phy-xss-audit — XSS 漏洞静态扫描器

对源代码执行跨 10 类规则的扫描，覆盖服务端渲染、客户端 DOM 操作及框架特有模式，识别 跨站脚本（XSS） 漏洞。映射至 OWASP A03:2021 — 注入 和 CWE-79。

快速开始

# 扫描整个项目
python3 ~/.claude/skills/phy-xss-audit/scripts/xss_audit.py .

# 扫描单个文件
python3 ~/.claude/skills/phy-xss-audit/scripts/xss_audit.py src/components/Post.tsx

# CI 模式 — 发现任意 CRITICAL 或 HIGH 级别问题即退出状态码 1
python3 ~/.claude/skills/phy-xss-audit/scripts/xss_audit.py . --ci

# JSON 输出（适用于 SARIF 流水线）
python3 ~/.claude/skills/phy-xss-audit/scripts/xss_audit.py . --format json

# GitHub Actions 注解格式输出
python3 ~/.claude/skills/phy-xss-audit/scripts/xss_audit.py . --format github

# 仅运行某一项检查
python3 ~/.claude/skills/phy-xss-audit/scripts/xss_audit.py . --check XV003

10 类检查项

通过 / 部分通过 / 不通过判定标准

XV001 — innerHTML / outerHTML 中使用用户数据

• 不通过（HIGH）：存在 element.innerHTML = 或 .html()（jQuery）赋值操作，且用户可控数据（如 req.query、req.body、request.GET、location.search 等）在 ±20 行范围内流入，且附近无 DOMPurify.sanitize() 防护。
• 通过：赋值前已使用 DOMPurify.sanitize(input) 进行净化，或数据来源为内部/静态内容。

XV002 — document.write() 中使用用户数据

• 不通过（HIGH）：在邻近代码行中，document.write() 或 document.writeln() 调用传入了用户可控数据。
• 通过：document.write() 仅输出开发者控制的静态字符串（无任何用户输入路径）。

XV003 — eval() / setTimeout(string) 中使用用户数据

• 不通过（CRITICAL）：出现 eval(userVar)、setTimeout(userVar + "...") 或 new Function(...) 等调用，且参数中直接包含用户数据；测试/规格文件（*.test.js / *.spec.ts）中的此类调用被跳过。
• 通过：eval() 仅用于静态字符串（如 JSON Schema），或用户数据通过安全的 JSON.parse() 传入。

XV004 — dangerouslySetInnerHTML 未配合 DOMPurify 使用

• 不通过（HIGH）：React 组件中使用 dangerouslySetInnerHTML={{ __html: ... }}，但该值在 ±5 行范围内未被 DOMPurify.sanitize() 包裹。
• 通过：该值为 DOMPurify.sanitize(html) 的返回结果 —— 即代码中在 ±5 行内出现 DOMPurify.sanitize( 模式。

XV005 — Django mark_safe() / autoescape off

• 不通过（CRITICAL）：出现 mark_safe(user_data) 调用，且用户可控数据在 ±10 行范围内流入；同时，模板中任意位置出现 {% autoescape off %} 均触发告警。
• 通过：mark_safe() 仅包裹开发者定义的静态 HTML 字符串，或数据已先经 bleach.clean() 净化。

XV006 — Jinja2 | safe 过滤器或 Markup() 绕过

• 不通过（CRITICAL）：模板变量通过 | safe 过滤器或被 Markup() 包裹，且用户可控数据在 ±10 行范围内流入。
• 通过：| safe 仅用于开发者控制的内容（例如：无用户输入参与的静态站点生成器输出）。

XV007 — PHP echo/print 未调用 htmlspecialchars

• 不通过（HIGH）：出现 echo $_GET['key'] 或 echo $var 等输出语句，且同一行未调用 htmlspecialchars() / htmlentities() / strip_tags() / filter_input() 等函数进行转义。
• 通过：所有用户输入在输出前均被 htmlspecialchars($var, ENT_QUOTES, 'UTF-8') 包裹。

XV008 — ERB raw / html_safe 未配合 sanitize 使用

• 不通过（HIGH）：ERB 模板中出现 <%== user_var %>、user_var.html_safe 或 raw user_var，且用户输入在 ±10 行范围内流入，且附近无 sanitize() 或 strip_tags() 防护。
• 通过：输出使用 h(var) / escape_html()，或用户值被 sanitize() 显式包裹。

XV009 — Vue v-html 中绑定动态表达式

• 不通过（HIGH）：出现 v-html="someVar"，且该值为动态计算所得，且周围 10 行内未见 DOMPurify.sanitize() 调用。
• 通过：该值在绑定至 v-html 前已通过 DOMPurify.sanitize(rawHtml) 计算得出。

XV010 — Angular bypassSecurityTrust / Go template.HTML 类型转换

• 不通过（HIGH）：Angular 中调用 bypassSecurityTrustHtml(userVar) 或 bypassSecurityTrustScript(userVar)，且用户数据在邻近范围内流入；Go 中对用户可控输入执行 template.HTML(userStr) 或 template.JS(userStr) 类型转换。
• 通过：Angular — 未调用任何 bypass 方法，改用标准 [innerHTML] 绑定；Go — 交由 html/template 自动处理转义（绝不将用户字符串强制转换为 template.HTML 类型）。

覆盖的 XSS 类型

支持的语言与框架

污染源模式（用户可控数据）

若某变量上下 ±15–20 行内出现以下任一模式，则该变量被判定为“用户可控”：

req.query / req.body / req.params / req.headers       (Node.js/Express)
request.GET / request.POST / request.args / request.json  (Django/Flask)
params[ / query_params[ / @query_params               (Rails/FastAPI)
$_GET[ / $_POST[ / $_REQUEST[ / $_COOKIE[             (PHP)
location.search / location.hash / URLSearchParams(    (Browser DOM)
c.Query( / c.Param( / r.URL.Query(                    (Go Gin/stdlib)

净化防护模式（自动抑制告警）

以下模式若出现在危险目标（sink）附近，将自动抑制该处告警：

CI 集成

# GitHub Actions
- name: XSS audit
  run: python3 scripts/xss_audit.py . --format github --ci

# GitLab CI
xss-audit:
  script:
    - python3 scripts/xss_audit.py . --ci
  allow_failure: false

# Pre-commit hook
#!/bin/sh
python3 ~/.claude/skills/phy-xss-audit/scripts/xss_audit.py . --ci

示例输出

======================================================================
  phy-xss-audit — XSS 漏洞扫描报告
======================================================================
  总数：3  |  CRITICAL：1  |  HIGH：2
======================================================================

🔴 [XV005] CRITICAL — Django mark_safe() / autoescape off (CWE-79)
   文件 ：app/views.py:47
   代码 ：return mark_safe(request.GET.get('content', ''))
   修复 ：切勿对用户输入调用 mark_safe()。应先使用 bleach.clean() 净化。

🟠 [XV001] HIGH — innerHTML / outerHTML 中使用用户数据 (CWE-79)
   文件 ：src/components/Comment.tsx:23
   代码 ：el.innerHTML = comment.body
   修复 ：在 innerHTML 赋值前使用 DOMPurify.sanitize(userInput) 进行净化。

🟠 [XV004] HIGH — dangerouslySetInnerHTML 未配合 DOMPurify 使用 (CWE-79)
   文件 ：src/components/Post.jsx:61
   代码 ：dangerouslySetInnerHTML={{ __html: post.content }}
   修复 ：dangerouslySetInnerHTML={{ __html: DOMPurify.sanitize(post.content) }}

OWASP 覆盖情况

本能力覆盖 OWASP A03:2021 — 注入（XSS 向量）。

本技能加入后，phy- suite 的 OWASP Top 10 覆盖情况：

• A01 — phy-path-traversal-audit ✅
• A02 — phy-crypto-audit ✅
• A03 — phy-xss-audit ✅ ← 当前技能
• A04 — phy-cors-audit ✅
• A05 — phy-security-headers ✅
• A06 — phy-dep-upgrade ✅
• A07 — phy-session-audit ✅
• A08 — phy-deserialization-audit ✅
• A09 — phy-otel-audit ✅（可观测性/日志）
• A10 — phy-ssrf-audit ✅

已实现完整的 OWASP Top 10 覆盖。

配套技能

技术说明

• 零外部依赖 — 完全基于 Python 3 标准库（re、pathlib、argparse、json）
• 自动跳过目录：.git/、node_modules/、__pycache__/、dist/、build/、.venv/
• 编码处理：优先尝试 utf-8，失败则回退至 latin-1
• XV003（eval）：跳过文件名匹配 *.test.js / *.spec.ts 的文件，以降低测试工具误报率
• 邻近窗口（Proximity window）：用户输入必须位于危险目标（sink）的 ±10–20 行范围内（各检查项可独立配置）
• 误报抑制：当检测到上述“净化防护模式”在危险目标附近时，自动抑制告警

作者

Canlah AI — 在不损害品牌前提下高效开展效果营销。

• GitHub：github.com/PHY041
• 全部技能：clawhub.ai/PHY041