Start Here

Pick your reading path by role; folder map; the one-paragraph summary.

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. /vulnhunt is read-only by default and writes fixes as strategies, not applied edits. Only /vulnhunter-fix changes 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)

Diagram index

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.