Capital One VulnHunter — Overview & Key Concepts
Imagine hiring a team of AI security specialists and giving them one rule: think like the attacker. You hand them a codebase. First they walk the building and list every door, window, and mail slot — every place an outsider can push data in. Then, for each entry, they follow that data step by step to see whether it can reach something dangerous (a database query, a shell command, a file path, an outbound request). When a specialist claims "this one is exploitable," a professional sceptic steps in and tries hard to prove them wrong. Only the claims that survive that cross-examination are written up — each with a working demonstration of the attack.
That is /vulnhunt, the scanner. Two more specialists complete the loop: a repair
crew (/vulnhunter-fix) that fixes each confirmed issue test-first and opens a pull
request, and an independent inspector (/vulnhunt-fix-verify) that re-checks each fix
without trusting anyone's word — only the code.
Why it exists. Modern AI can suggest a huge number of possible vulnerabilities. The hard, expensive part is triage — deciding quickly which suggestions are real and worth a developer's time. Traditional scanners optimise for recall and drown teams in false positives. VulnHunter optimises for precision: it would rather report three real, proven bugs than three hundred maybes.
Three design choices that make findings trustworthy:
- Attacker-first, forward tracing — start at real entry points, follow the data to a sink; don't start at a scary-looking sink and guess backward.
- A falsification engine — actively try to disprove every candidate; discard anything built on an unsupported assumption.
- Executable proof — every reported finding carries a proof-of-concept, and every fix carries a failing-then-passing security test.
The closed loop
flowchart LR
subgraph HUNT["/vulnhunt · HUNT (read-only)"]
R[Recon] --> H[Hunt<br/>INJ·NAV·LOG] --> D[Disprove] --> P[Reproduce] --> S[Sweep] --> RPT[Report]
end
subgraph FIX["/vulnhunter-fix · FIX (edits on a branch)"]
PA[Parse] --> PL[Plan] --> TDD[RED→GREEN] --> VF[Verify] --> DL[Deliver PR]
end
subgraph VERIFY["/vulnhunt-fix-verify · VERIFY (read-only)"]
EX[Extract] --> VR[Verify] --> EM[Verdict]
end
RPT --> PA
DL --> EX
EM -.needs_review.-> PA
The scanner (Hunt) never changes your code. The fixer (Fix) changes code only on a git branch/worktree and pauses for operator approval at every phase boundary. The verifier is strictly read-only.
The five components
| Component | Kind | One-line role |
|---|---|---|
vulnhunt/ |
Prompt-only skill | The scanner: /vulnhunt. Orchestrator that dispatches a subagent per phase. |
vulnhunter-fix/ |
Prompt + Python | The fixer: /vulnhunter-fix. Test-driven remediation → reviewable PR. |
vulnhunt-fix-verify/ |
Prompt-only skill | The verifier: /vulnhunt-fix-verify. Read-only, independent per-finding verdict. |
vulnhunter-agent/ |
Python runtime | Headless automation: clone → scan → publish → file GitHub issues (+ verify mode). |
harness/ |
Python (dev-only) | Batch-scan many repos and benchmark detection accuracy. |
Key concepts and glossary
| Term | Plain meaning |
|---|---|
| Agentic SAST | Static Application Security Testing driven by autonomous AI "agents" that read code with tools (Grep/Glob/Read) and reason, rather than just pattern-matching. |
| Skill | A Claude Code capability defined by a SKILL.md (+ phase files). VulnHunter ships three: /vulnhunt, /vulnhunter-fix, /vulnhunt-fix-verify. |
| Orchestrator | The top-level skill logic that dispatches subagents and verifies their output files — it does no analysis itself, to keep its context lean and the methodology systematic. |
| Phase | One step of a skill (e.g. Recon, Hunt, Disprove). Each has a clear input and an output file. |
| Subagent | A fresh Claude agent spawned for one phase/partition, with its own context and tool envelope. |
| Source / Sink / Sanitizer | Where untrusted data enters / where it becomes dangerous / what neutralises it. |
| Forward tracing | Following data from an entry point toward sinks (VulnHunter's direction), vs. "sink-first" backward search. |
| Falsification engine (Phase 2b) | The adversarial pass that tries to disprove each candidate; roughly half are eliminated. |
| Partition / class group | Recon splits the repo into partitions; each is hunted by three class agents — INJ (injection), NAV (navigation & access control), LOG (logic & crypto) — plus a sink-driven agent. |
| PoC | Proof-of-concept: a runnable (or static) demonstration that a finding is exploitable. |
| VULN-NNN | The identifier for one confirmed finding (one per sink location) in the report. |
| Sweep (Phase 3d) | Grep every instance of a confirmed root-cause pattern so one fix covers all of them. |
| Code smell | A weak/theoretical candidate that didn't survive the gates — reported separately, not as a vulnerability. |
| TDD gate (RED→GREEN) | The fixer writes a failing security test (RED) before any code edit, then implements the fix (GREEN). No fix is "done" without it. |
| Cluster | A group of related findings the fixer remediates together in one PR (in-place mode). |
| Delivery gate | One of six mechanical checks (severity-mask, body-completeness, scope, idempotency, anti-merge, verification-table) that must pass before a PR opens. |
| Verdict | The verifier's outcome per finding: e.g. validated / needs_review. |
| CWE / CVSS | Standard taxonomy of weakness types / standard severity score. Used to route fixes to model tiers. |
| Auth mode | How the runtime reaches Claude: api_key (default), bedrock_oauth, or bedrock_sigv4. |
| scan_manifest.json | The schema-validated record the runtime writes after a scan — the stable integration contract for your own automation. |
Inputs and outputs at a glance
Inputs: a target code checkout (read-only for the scanner). The fixer additionally consumes
vulnhunter-labelled GitHub issues (in-place mode) or a prior results directory (fork mode).
The runtime takes a repo URL plus a TOML config + VULNHUNT_* env vars.
Outputs: the scanner writes a *_VULNHUNT_RESULTS_* directory (report README.md, PoCs,
exploit tests). The fixer opens a reviewable PR (exploit + test + fix). The verifier writes
verify_disposition.json. The runtime adds scan_manifest.json and one deduplicated GitHub
issue per confirmed finding.
Commands you'll meet
| Command | What it does |
|---|---|
/vulnhunt |
Run the scanner (read-only by default; bash-enabled mode can run exploit tests). |
/vulnhunter-fix |
Remediate findings test-first and open a PR (in-place or fork mode). |
/vulnhunt-fix-verify repo=… report=… fixed=VULN-… out=… |
Independently verify claimed-fixed findings (read-only). |
python -m agent <repo-url> |
Headless: clone, scan, publish, file issues. |
python -m local_harness.batch.run scan |
Batch-scan every repo in REPO_LIST.txt. |
python -m local_harness.benchmark.run |
Benchmark detection accuracy against a known-vulnerable corpus. |
See HLD for the component picture, data-flow for what moves between phases, and the module docs for per-file detail.