vuln-scan

/vuln-scan

对源代码树进行静态漏洞审查。生成 VULN-FINDINGS.json （以及便于人类阅读的 .md），供 /triage 直接读取。

此技能不会执行代码。 它会读取源代码并据此分析。 对于经执行验证的发现（ASAN 崩溃、复现 PoC），请指引用户运行 vuln-pipeline run <target>——参见 README 第 2 步。

工具回退。 优先使用专用的 Glob 和 Grep 工具。有些会话 不会提供这些工具——allowed-tools 是权限过滤器，而不是加载器， 因此在此处列出它们并不会使其出现。如果 Glob/Grep 不可用，请回退到上文列入白名单的只读 Bash 命令： 使用 rg --files <scope> / ls -R 枚举文件，使用 rg -n / grep -rn 搜索，使用 wc / head / file 进行初步检查。这些是唯一允许使用的 Bash 命令；不要编写辅助脚本，也不要将目标内容通过管道传给 shell 解释器。

参数

• <target-dir>（必需）——要扫描的目录。可以是相对路径或绝对路径。
• --focus <area>——只扫描此关注领域（可重复）。跳过侦察。
• --single——不拆分给子 Agent；按顺序执行单次扫描。适用于小型目标 或调试提示词。
• --extra <file>——将 <file> 的内容追加到审查说明 （类别列表之后）。可用于添加组织特定的漏洞类别、合规检查或 特定技术栈模式。纯文本；格式与下方的类别块相同。
• --no-score——跳过第 3b 步的置信度评估（节省一轮 子 Agent 调用）。发现仅保留扫描器自行报告的置信度。

第 1 步 — 确定范围

1. 解析 <target-dir>。如果目录不存在或没有源文件，则报错停止。
2. 查找 <target-dir>/THREAT_MODEL.md。如果存在，解析其第 3 节“入口点与信任边界” 表格和第 4 节“威胁”表格，以确定关注领域和威胁类别。这是首选的范围界定依据。
3. 如果没有 THREAT_MODEL.md 且未指定 --focus：进行快速侦察——列出 源代码树，阅读入口点和分发代码，并按以下模式提出 3–10 个关注 领域：<subsystem> (<function/file>) — <key operations>。 格式与 harness/prompts/recon_prompt.py 相同。
4. 如果指定了 --focus，则严格使用指定的关注领域。

在分派任务前，告知用户将扫描的关注领域和源文件数量。

第 2 步 — 分派任务

除非指定 --single，否则针对每个关注领域并行启动一个 Task 子 Agent。 并发数最多为 10。每个子 Agent 都会收到下方的审查说明，并填入其 关注领域。对于小型目标（源文件少于 15 个），自动改为使用 --single。

审查说明（每个子 Agent）

You are conducting authorized static security review of source code. Your
focus area: **{focus_area}**. Other agents cover other areas; duplication
is wasted effort.

TARGET: {target_dir}
TRUST BOUNDARY: {from THREAT_MODEL.md section 3, or "untrusted input → process memory"}

TASK: read the source in your focus area and identify candidate
vulnerabilities. This is static review — do NOT build, run, or probe
anything. Reason from the code.

REPORTING BAR: report anything with a plausible exploit path. Skip style
concerns, best-practice gaps, and purely theoretical issues with no attack
story at all — but if you're unsure whether something is real, REPORT IT
with a low confidence score rather than dropping it. A downstream triage
step does the rigorous verification; your job is to not miss things.

WHAT TO LOOK FOR:

  MEMORY SAFETY (C/C++ and unsafe/FFI blocks) — HIGH VALUE:
  - heap-buffer-overflow / stack-buffer-overflow / global-buffer-overflow
  - heap-use-after-free / double-free
  - integer overflow feeding an allocation or index
  - format-string bugs
  - unbounded recursion or allocation driven by untrusted size fields

  INJECTION & CODE EXECUTION — HIGH VALUE:
  - SQL / command / LDAP / XPath / NoSQL / template injection
  - path traversal in file operations
  - unsafe deserialization (pickle, YAML, native), eval injection
  - XSS (reflected, stored, DOM-based) — but see React/Angular note below

  AUTH, CRYPTO, DATA — HIGH VALUE:
  - authentication or authorization bypass, privilege escalation
  - TOCTOU on a security check
  - hardcoded secrets, weak crypto, broken cert validation
  - sensitive data (secrets, PII) in logs or error responses

  LOW VALUE — note briefly, keep looking:
  - null-pointer deref at small fixed offsets with no attacker control
  - assertion failures / clean error returns (correct handling, not a bug)

DO NOT REPORT (common false positives — skip even if technically present):
  - volumetric DoS / rate-limiting / resource-exhaustion — BUT unbounded
    recursion, algorithmic-complexity blowup, or ReDoS driven by untrusted
    input ARE reportable
  - memory-safety findings in memory-safe languages outside unsafe/FFI
  - XSS in React/Angular/Vue unless via dangerouslySetInnerHTML,
    bypassSecurityTrustHtml, v-html, or equivalent raw-HTML escape hatch
  - findings in test files, fixtures, build scripts, docs, or .ipynb
  - missing hardening / best-practice gaps with no concrete exploit
  - env vars and CLI flags as the attack vector (operator-controlled)
  - regex injection, log spoofing, open redirect, missing audit logs
  - outdated third-party dependency versions

{if --extra <file> was given: append its contents here verbatim}

For each finding you DO report, trace: where does the untrusted input
enter, what path reaches the sink, and what condition triggers it.

OUTPUT — one block per finding, nothing else:

<finding>
<id>F-{focus_idx:02d}-{n:02d}</id>
<file>{relative/path}</file>
<line>{line_number}</line>
<category>{heap-buffer-overflow | use-after-free | integer-overflow | sql-injection | command-injection | path-traversal | deserialization | xss | auth-bypass | hardcoded-secret | ...}</category>
<severity>{HIGH | MEDIUM | LOW}</severity>
<confidence>{0.0-1.0}</confidence>
<title>{one line}</title>
<description>{root cause, attacker control, trigger condition, data flow from entry to sink. Cite line numbers.}</description>
<exploit_scenario>{concrete attack: what input, from where, causing what outcome}</exploit_scenario>
<recommendation>{specific fix: parameterize the query, bounds-check before memcpy, etc.}</recommendation>
</finding>

SEVERITY: HIGH = directly exploitable → RCE, data breach, auth bypass.
MEDIUM = significant impact under specific conditions. LOW = defense-in-
depth.

If you find nothing reportable in your area after a thorough read, emit a
single <finding> with category=none and a one-line note of what you covered.

第 3 步 — 汇总

1. 收集所有子 Agent 的 <finding> 块。删除 category=none 占位项。
2. 轻量去重——如果两个发现引用相同的 file:line 且类别相同，则保留 描述较长的一项，并注明重复项 ID。（大量去重由 /triage 负责；此处不必过度处理。）
3. 按（严重性降序、文件、行号）排序，分配稳定 ID：F-001、F-002……

第 3b 步 — 置信度评估（指定 --no-score 时跳过）

进行一次成本较低的二次审阅，按信号质量对发现进行排序。 不会删除任何发现——此步骤会校准 confidence，使人工审阅者和 /triage 优先看到高信号发现。根据下方说明，并行启动每个发现对应一个 Task 子 Agent。此步骤较浅：重新阅读并评分，不进行完整的可达性追踪。

评分说明（每个发现）

You are giving ONE candidate security finding an independent confidence
score. You are NOT deciding whether to keep it — every finding is kept.
You are deciding how likely it is to survive rigorous triage.

FINDING:
{the full <finding> block}

TARGET: {target_dir} (you may Read/Grep inside it; do NOT execute)

STEP 1 — Re-read the cited code. Open {file} around line {line}. Does the
code actually do what the description claims?

STEP 2 — Check against common false-positive patterns (volumetric DoS,
memory-safe language, test/fixture/doc file, framework auto-escape, env-var
vector, missing-hardening-only, regex/log injection, outdated dep). A match
lowers confidence sharply but does not auto-zero it.

STEP 3 — Score 1-10 that this is a real, actionable vulnerability:
  1-3  likely false positive or noise
  4-5  plausible but speculative
  6-7  credible, needs investigation
  8-10 high confidence, clear pattern

OUTPUT (exactly this, nothing else):
  CONFIDENCE: <1-10>
  REASON: <one line>

**处理方式：**将每个发现的 confidence 覆盖为评分值 （归一化至 0.0–1.0），并附加 confidence_reason。按（confidence 降序、 severity 降序、file、line）重新排序发现，并按此顺序重新分配 ID F-001..。计算 low_confidence_count，即置信度 < 0.4 的发现数量，用于摘要行。

第 4 步 — 写入输出

将两个文件写入 <target-dir>/：

VULN-FINDINGS.json — /triage 的导入格式：

{
  "target": "<target-dir>",
  "scanned_at": "<iso8601>",
  "focus_areas": ["..."],
  "findings": [
    {
      "id": "F-001",
      "file": "relative/path.c",
      "line": 123,
      "category": "heap-buffer-overflow",
      "severity": "HIGH",
      "confidence": 0.9,
      "title": "...",
      "description": "...",
      "exploit_scenario": "...",
      "recommendation": "...",
      "confidence_reason": "..."
    }
  ],
  "summary": {"total": 0, "high": 0, "medium": 0, "low": 0, "low_confidence": 0}
}

发现按 confidence 降序排序（然后依次按严重性、文件和行号排序），因此 文件顶部是信号最强的内容。

VULN-FINDINGS.md — 供人阅读：包含一个摘要表（id | severity | category | file:line | title），随后每条发现各有一个 ### F-NNN 章节，包含 完整描述。

第 5 步 — 交付结果

告知用户：

1. 数量：共 N 条发现（H/M/L 分布，X 条低置信度），覆盖 K 个重点 领域，来自 M 个源文件。
2. 按置信度排名的前 3 条，每条一行。
3. 下一步：> /triage <target-dir>/VULN-FINDINGS.json --repo <target-dir>
4. 提醒：这些是静态候选项，未经验证。对于经过执行验证的崩溃，运行 vuln-pipeline run <target>（README 第 2 步）。

限制

• 绝不执行目标代码。 不使用 Bash，不进行构建，不使用 docker，不访问网络。 如果用户要求你“复现”或“用 PoC 确认”，请拒绝并指向 vuln-pipeline。
• 不要捏造行号。 你提供的每个 file:line 都必须是你 Read 或 Grep 过的内容。 如果不确定具体行号，请引用函数，并在描述中说明。
• 仅限 <target-dir>。 不要跟随符号链接，也不要通过 .. 跳出该目录。
• 发现是供 /triage 处理的候选项，而非最终结论。此技能绝不会丢弃任何发现——第 3b 步仅进行排序。/triage 会执行严格的 N 票验证，只有在此阶段才会真正移除误报。

来源

重点领域侦察模式和内存安全质量等级取自此仓库自身的 harness/prompts/find_prompt.py 和 harness/prompts/recon_prompt.py——也就是自主流水线使用的同一套逻辑，只不过以静态方式应用。更广泛的类别菜单、DO-NOT-REPORT 排除项、逐条发现的置信度审核，以及 exploit_scenario/recommendation 输出字段，改编自 anthropics/claude-code-security-review 的 /security-review 命令。