vuln-scan

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

/vuln-scan

/vuln-scan

Static vulnerability review of a source tree. Produces
VULN-FINDINGS.json
(+ a human-readable
.md
) that
/triage
ingests directly.
This skill does not execute code. It reads source and reasons about it. For execution-verified findings (ASAN crashes, reproducing PoCs), point the user at
vuln-pipeline run <target>
— see README Step 2.
Tool fallbacks. Prefer the dedicated Glob and Grep tools. Some sessions do not provision them —
allowed-tools
is a permission filter, not a loader, so listing them here does not make them appear. When Glob/Grep are unavailable, fall back to the read-only Bash commands whitelisted above:
rg --files <scope>
/
ls -R
for enumeration,
rg -n
/
grep -rn
for search,
wc
/
head
/
file
for sniffing. These are the ONLY permitted Bash commands; do not write helper scripts or pipe target content into a shell interpreter.
针对源代码树的静态漏洞审查工具。生成
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解释器。

Arguments

参数

  • <target-dir>
    (required) — directory to scan. Relative or absolute.
  • --focus <area>
    — scan only this focus area (repeatable). Skips recon.
  • --single
    — no subagent fan-out; one sequential pass. Use on tiny targets or when debugging the prompt.
  • --extra <file>
    — append the contents of
    <file>
    to the review brief (after the category list). Use to add org-specific vulnerability classes, compliance checks, or stack-specific patterns. Plain text; same shape as the category blocks below.
  • --no-score
    — skip the Step 3b confidence pass (saves a round of subagents). Findings keep the scanner's self-reported confidence only.
  • <target-dir>
    (必填)——待扫描的目录,支持相对路径或绝对路径。
  • --focus <area>
    ——仅扫描指定重点领域(可重复使用该参数),跳过侦察步骤。
  • --single
    ——不生成子代理,仅执行单次顺序扫描。适用于小型目标或调试提示时使用。
  • --extra <file>
    ——将
    <file>
    的内容追加到审查简报中(位于分类列表之后)。用于添加组织特定的漏洞类别、合规检查或技术栈特定的检测模式。仅支持纯文本格式,需与下方分类块格式一致。
  • --no-score
    ——跳过第3b步的可信度验证环节(减少一轮子代理调用)。检测结果仅保留扫描器自行报告的可信度评分。

Step 1 — Scope

步骤1——范围确定

  1. Resolve
    <target-dir>
    . If it doesn't exist or has no source files, stop with an error.
  2. Look for
    <target-dir>/THREAT_MODEL.md
    . If present, parse its section 3 "Entry points & trust boundaries" table and section 4 "Threats" table for focus areas and threat classes. This is the preferred scoping input.
  3. If no THREAT_MODEL.md and no
    --focus
    : do a quick recon — list the source tree, read entry points and dispatch code, and propose 3-10 focus areas using the pattern
    <subsystem> (<function/file>) — <key operations>
    . Same shape as
    harness/prompts/recon_prompt.py
    .
  4. If
    --focus
    was given, use exactly those.
Tell the user the focus areas you'll scan and the source-file count before fanning out.
  1. 解析
    <target-dir>
    。若目录不存在或无源代码文件,则终止并返回错误。
  2. 查找
    <target-dir>/THREAT_MODEL.md
    。若存在,则解析其第3节“入口点与信任边界”表格和第4节“威胁”表格,提取重点领域和威胁类别。这是首选的范围输入依据。
  3. 若不存在THREAT_MODEL.md且未指定
    --focus
    :执行快速侦察——列出源代码树,读取入口点和调度代码,按照
    <子系统>(<功能/文件>)——<核心操作>
    的格式,提出3-10个重点领域。格式与
    harness/prompts/recon_prompt.py
    一致。
  4. 若已指定
    --focus
    ,则严格使用这些指定领域。
在生成子代理之前,告知用户将扫描的重点领域以及源代码文件数量。

Step 2 — Fan out

步骤2——并行扫描

Unless
--single
, spawn one Task subagent per focus area in parallel. Cap at 10 concurrent. Each subagent gets the review brief below with its focus area filled in. On tiny targets (<15 source files), fall through to
--single
automatically.
除非指定
--single
,否则为每个重点领域生成一个Task子代理并行执行。并发数上限为10。每个子代理将收到下方的审查简报,并填充对应的重点领域。对于小型目标(少于15个源代码文件),将自动启用
--single
模式。

Review brief (per subagent)

子代理审查简报

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.
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.

Step 3 — Collate

步骤3——结果整理

  1. Collect
    <finding>
    blocks from all subagents. Drop
    category=none
    placeholders.
  2. Light dedupe — if two findings cite the same
    file:line
    with the same category, keep the one with the longer description and note the duplicate id. (Heavy dedupe is
    /triage
    's job; don't over-engineer here.)
  3. Assign stable ids
    F-001
    ,
    F-002
    , ... in (severity desc, file, line) order.
  1. 收集所有子代理返回的
    <finding>
    块。移除
    category=none
    的占位项。
  2. 轻度去重——若两个检测结果引用相同的
    file:line
    且类别相同,则保留描述更详细的那一个,并标注重复ID。(深度去重是/triage工具的职责,此处无需过度设计。)
  3. 按照(严重程度降序、文件路径、行号)的顺序,分配稳定的ID:
    F-001
    F-002
    ……

Step 3b — Confidence pass (skip if
--no-score
)

步骤3b——可信度验证环节(若指定
--no-score
则跳过)

A cheap second-opinion read that ranks findings by signal quality. Nothing is dropped — this pass calibrates
confidence
so humans and
/triage
see high-signal findings first. Spawn one Task subagent per finding in parallel with the brief below. Shallow: re-read and score, not a full reachability trace.
这是一次低成本的二次审核,用于按信号质量排序检测结果。不会丢弃任何结果——此环节仅校准
confidence
值,以便人工和/triage工具优先查看高信号结果。为每个检测结果并行生成一个Task子代理,并使用下方的简报。仅进行浅层审核:重新读取并评分,不进行完整的可达性追踪。

Scoring brief (per finding)

评分简报(每个检测结果)

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>
Resolve: overwrite each finding's
confidence
with the score (normalized to 0.0-1.0) and attach
confidence_reason
. Re-sort findings by (
confidence
desc,
severity
desc,
file
,
line
) and reassign ids
F-001..
in that order. Compute
low_confidence_count
= findings with confidence < 0.4, for the summary line.
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
字段。按照(可信度降序、严重程度降序、文件路径、行号)重新排序检测结果,并重新分配ID
F-001..
。计算
low_confidence_count
=可信度<0.4的检测结果数量,用于摘要行。

Step 4 — Write output

步骤4——生成输出文件

Write both files to
<target-dir>/
:
VULN-FINDINGS.json
— the
/triage
ingest shape:
json
{
  "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}
}
Findings are sorted by
confidence
desc (then severity, file, line), so the top of the file is the highest-signal material.
VULN-FINDINGS.md
— human-readable: a summary table (id | severity | category | file:line | title), then one
### F-NNN
section per finding with the full description.
两个文件写入
<target-dir>/
VULN-FINDINGS.json
——/triage工具的导入格式:
json
{
  "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 | 严重程度 | 类别 | 文件:行号 | 标题),然后每个检测结果对应一个
### F-NNN
章节,包含完整描述。

Step 5 — Hand back

步骤5——结果交付

Tell the user:
  1. Counts: N findings (H/M/L split, X low-confidence), across K focus areas, from M source files.
  2. Top 3 by confidence, one line each.
  3. Next step:
    > /triage <target-dir>/VULN-FINDINGS.json --repo <target-dir>
  4. Remind: these are static candidates, not verified. For execution-verified crashes,
    vuln-pipeline run <target>
    (README Step 2).
告知用户:
  1. 统计信息:共N个检测结果(高/中/低严重程度分布,X个低可信度结果),覆盖K个重点领域,来自M个源代码文件。
  2. 可信度排名前三的检测结果,各用一句话描述。
  3. 下一步操作:
    > /triage <target-dir>/VULN-FINDINGS.json --repo <target-dir>
  4. 提醒:这些是静态候选结果,未经过验证。如需执行验证的崩溃测试,请使用
    vuln-pipeline run <target>
    (README第2步)。

Constraints

约束条件

  • Never execute target code. No Bash, no builds, no
    docker
    , no network. If the user asks you to "reproduce" or "confirm with a PoC," decline and point at
    vuln-pipeline
    .
  • Don't fabricate line numbers. Every
    file:line
    you emit must be something you Read or Grep'd. If unsure of the exact line, cite the function and say so in the description.
  • Stay in
    <target-dir>
    .
    Don't follow symlinks or
    ..
    out of it.
  • Findings are candidates for
    /triage
    , not final verdicts. This skill never drops a finding — Step 3b only ranks.
    /triage
    does the rigorous N-vote verification and is where false positives actually get removed.
  • 绝不要执行目标代码。禁止使用Bash、构建、
    docker
    或网络请求。若用户要求“复现”或“用PoC验证”,请拒绝并引导至
    vuln-pipeline
  • 不要伪造行号。所有输出的
    file:line
    必须是你已读取或Grep过的内容。若不确定确切行号,请引用函数名并在描述中说明。
  • 仅在
    <target-dir>
    内操作
    。请勿跟随符号链接或通过
    ..
    跳出目标目录。
  • 检测结果是/triage工具的候选项,而非最终结论。本技能绝不丢弃任何检测结果——第3b步仅进行排序。/triage工具会执行严格的多轮验证,真正移除误报。

Provenance

来源说明

The focus-area recon pattern and memory-safety quality tiers are lifted from this repo's own
harness/prompts/find_prompt.py
and
harness/prompts/recon_prompt.py
— the same logic the autonomous pipeline uses, applied statically. The broader category menu, DO-NOT-REPORT exclusions, per-finding confidence pass, and
exploit_scenario
/
recommendation
output fields are adapted from
anthropics/claude-code-security-review
's
/security-review
command.
重点领域侦察模式和内存安全质量分级来自本仓库的
harness/prompts/find_prompt.py
harness/prompts/recon_prompt.py
——与自动流水线使用的逻辑相同,此处应用于静态扫描。更广泛的类别菜单、禁止报告的排除项、每个检测结果的可信度验证环节,以及
exploit_scenario
/
recommendation
输出字段,均改编自
anthropics/claude-code-security-review
/security-review
命令。