/vuln-scan

name: vuln-scan
description: >-
  Static source-code vulnerability scan. Reads a target directory (and
  THREAT_MODEL.md if present), spawns parallel review subagents per focus
  area, and writes VULN-FINDINGS.json + .md for /triage to consume. Read-only
  — no building, running, or network. For execution-verified crashes, use
  vuln-pipeline instead. Use when asked to "scan for vulns", "review this code
  for security issues", "find bugs in <dir>", or as the step between
  /threat-model and /triage.
argument-hint: "<target-dir> [--focus <area>] [--single] [--extra <file>] [--no-score]"
allowed-tools:
  - Read
  - Glob
  - Grep
  - Write
  - Bash(python3 .claude/skills/_lib/checkpoint.py:*)
  - Task
  - Bash(rg:*)
  - Bash(grep:*)
  - Bash(ls:*)
  - Bash(wc:*)
  - Bash(head:*)
  - Bash(file:*)

/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 a human builds a PoC out of band; no execution pipeline is vendored in this repository (Ouroboros adaptation).

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

Arguments

• `<target-dir>` (required) — directory to scan. Relative or absolute.

This is a read target, not the report destination. Run from the harness checkout root with `CHECKPOINT_ROOT` unset or equal to that root; keep that working directory and publication root even for an external target.

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

Step 1 — Scope

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`, then `docs/security/THREAT_MODEL.md` (Ouroboros adaptation). 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.

Step 2 — Fan out

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.

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,
    bypassSecuri