Start Here — Capital One VulnHunter Onboarding Guide
Welcome. This documentation set explains VulnHunter — Capital One's open-source, agentic AI security tool that finds exploitable security defects in source code, proves them with executable proof-of-concepts, fixes them under test, and independently verifies the fixes.
It is written for three audiences. Every module document is split into a plain-English first half (with a diagram) and a technical second half (with per-file detail), so you can read at the depth you need.
Pick your path
| You are… | Read, in order |
|---|---|
| Non-technical (PM, analyst, manager) | architecture.html → Overview → the opening section of any module doc |
| Security analyst | Overview → Data Flow → /vulnhunt scanner → Fix & Verify |
| Junior developer | HLD → Data Flow → module docs → LLD |
| Reviewer / architect | HLD → LLD → Graph Intelligence → Visa file-equivalence check |
What's in this folder
Capital One - VulnHunter/
├── architecture.html ← interactive explainer (START HERE, non-technical friendly)
├── docs/
│ ├── 00_START_HERE.md ← this file
│ ├── 01_overview.md ← what VulnHunter is, key concepts, glossary
│ ├── design/
│ │ ├── HLD.md ← High-Level Design (components + how they fit)
│ │ ├── LLD.md ← Low-Level Design (cross-cutting internals)
│ │ ├── data-flow.md ← DFD levels 0/1/2 + narrative
│ │ └── deterministic-vs-llm.md ← which parts are model calls vs ordinary code, per component
│ ├── modules/ ← one doc per component (non-technical + technical + per-file)
│ └── tools/graph-intelligence.md ← how the graphs were built + Serena/grepai setup
├── diagrams/ ← rendered SVG + PNG (architecture, DFDs, component graph …)
├── tool-outputs/ ← real CodeGraph & Graphify exports + readable HTML views
├── tools/codeviz/ ← reusable, dependency-free code-graph tool (any Python repo)
├── scratchpad/modtables/ ← per-component file/LOC/docstring inventory (working notes)
├── samples/ ← process doc + runbooks for operating the harness
└── CapOne vulnhunter/ ← the Obsidian vault (long-term knowledge base)
The one-paragraph summary
VulnHunter is a closed loop of three Claude Code skills. /vulnhunt (Hunt) reasons
like an attacker: it enumerates every user-controllable input, traces each forward to
dangerous sinks, then runs a falsification engine that tries to disprove each
candidate — so what survives is real and exploitable, backed by a runnable proof-of-concept.
/vulnhunter-fix (Fix) remediates each finding test-first: it writes a failing security
test (RED), implements the fix (GREEN), confirms the exploit is blocked, and opens a
reviewable PR. /vulnhunt-fix-verify (Verify) is a completely separate, read-only
agent that independently confirms whether each fix actually holds. Two runtimes wrap the
loop for automation: vulnhunter-agent/ runs it headless (CI, a fleet worker) and files
GitHub issues; harness/ drives it across many repos and benchmarks detection accuracy.
⚠️ The scanner never edits your code.
/vulnhuntis read-only by default and writes fixes as strategies, not applied edits. Only/vulnhunter-fixchanges code — and only on a git branch/worktree, gated by an operator at every phase boundary. All three skills send code to a model provider; only scan repositories you are authorized to analyze.
What makes it different (vs. traditional SAST)
- Attacker-first, forward analysis. Conventional scanners start at dangerous sinks and search backward for a hypothetical attacker — which floods teams with false positives. VulnHunter starts at real attacker-accessible entry points and reasons forward.
- A falsification engine. After finding a candidate, it actively tries to prove itself wrong, discarding anything that rests on unsupported assumptions.
- Evidence-backed remediation. Every surviving finding ships with an exploit path, a PoC, and a targeted fix — proven by test, not taken on faith.
Diagram index
diagrams/01_architecture.svg— system architecture (HLD)diagrams/02_dataflow_loop.svg— Hunt→Fix→Verify data flow (DFD L1)diagrams/03_context_dfd.svg— context diagram (DFD L0)diagrams/04_module_dependencies.svg— component dependency graph (from CodeGraph)diagrams/05_agent_runtime.svg— headless runtime pipelinediagrams/06_hunt_phases.svg— the/vulnhuntinternal phasesdiagrams/module-graph.html— clickable component flow
Requirements at a glance
Built and optimized for Claude Opus running in Claude Code — you supply your own
model access. Python 3.12+ is needed only for the runtime agent and the benchmarking harness;
the three skills are prompt-only (installed with ./install.sh into ~/.claude/skills/).
Apache-2.0 licensed. See Overview for concepts and the
HLD for the component picture.