Overview & Key Concepts

What VulnHunter is, the closed loop, the five components, and the glossary.

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:

  1. 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.
  2. A falsification engine — actively try to disprove every candidate; discard anything built on an unsupported assumption.
  3. 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.