Capital One VulnHunter

An AI security tool that finds real security bugs in computer code, fixes them, and checks the fixes. It aims for a few proven bugs, not a long list of maybes.

Reading level:

πŸ‘‰ New to this, or English is not your first language? Keep Simple selected β€” every section is written in short, plain sentences with the key words explained below.

What it is

VulnHunter is an AI tool that finds and fixes security bugs in computer code. It works in three simple steps:

  1. πŸ”ŽFind. It reads the code like an attacker. It looks at every place where data from outside can come in. It follows that data to see if it can reach a dangerous action. Then it double-checks each result and removes the weak ones. What is left is a short list of real bugs, each with a working example of the attack.
  2. πŸ› οΈFix. For each real bug, it writes a fix and a test that proves the fix works. Then it makes a "pull request" β€” a proposed code change a human can review.
  3. βœ…Check. A separate part re-reads the fixed code and says, for each bug, whether it is truly fixed. It trusts only the code, not what anyone says.

Why this matters: many tools list hundreds of "maybe" bugs and waste people's time. VulnHunter is built to report only bugs it can prove β€” fewer results, but real ones.

VulnHunter is a suite of three Claude Code skills plus two Python runtimes, optimised for Claude Opus. Detection is attacker-first and forward: enumerate user-controllable inputs, trace each to dangerous sinks, then run a falsification pass that discards candidates resting on unsupported assumptions. Only findings backed by an executable PoC survive. Remediation is test-driven; verification is a separate read-only agent.

βœ… VulnHunter does remediate. The suite has three parts: the scanner (/vulnhunt) finds bugs and is read-only; the fixer (/vulnhunter-fix) writes the actual code fix and opens a pull request; the verifier (/vulnhunt-fix-verify) checks it. So "the scanner never edits your code" and "VulnHunter fixes code" are both true β€” different parts do different jobs.
⚠️ Only the fixer changes code, and only on a git branch, gated by an operator. All parts send code to a model provider; scan only repositories you're authorized to analyze.

πŸ“– Words to know

Plain meanings for the words used on this page. Hover is not needed β€” the meaning is written next to each word everywhere it appears.

InputAny data that comes from outside the program β€” a web form, a file, a URL, a message.
SinkA place in the code where data is used in a dangerous way β€” running a command, a database query, opening a file.
Vulnerability / bugA weakness an attacker can use to do something they should not.
Exploit / PoCA small working example that shows the bug is real. PoC = "proof of concept".
False positiveA warning that looks like a bug but is not real. VulnHunter is built to avoid these.
SkillOne tool inside VulnHunter that does one job. There are three: find, fix, check.
AgentAn AI worker that reads code and reasons. VulnHunter splits work across many agents.
Read-onlyCan look at the code but cannot change it.
Pull request (PR)A proposed code change on GitHub that a person reviews before it is accepted.
Claude Code / Claude OpusThe AI system VulnHunter runs on. You bring your own access to it.

The closed loop: Hunt β†’ Fix β†’ Verify

Three skills form a complete, automated remediation loop.

  1. 🟠 Hunt β€” /vulnhunt
    Finds real, exploitable bugs and writes up each one with proof. Orchestrator that dispatches a subagent per phase (Recon β†’ Hunt β†’ Disprove β†’ Reproduce β†’ Sweep β†’ Report). Reads code only; documents fix strategies.
    In: a code checkout β†’ Out: a *_VULNHUNT_RESULTS_* dir (report, PoCs, exploit tests).
  2. 🟒 Fix β€” /vulnhunter-fix
    Fixes each bug test-first and opens a pull request you can review. Per finding: exploit demo β†’ failing test (RED) β†’ fix (GREEN) β†’ confirm blocked β†’ regression check β†’ PR through six mechanical gates. Operator-gated at every phase boundary.
    In: labelled issues / results dir β†’ Out: a reviewable PR (exploit + test + fix).
  3. 🟣 Verify β€” /vulnhunt-fix-verify
    A separate inspector checks each fix from the code alone β€” no trusting anyone's word. Strictly read-only (Read/Write/Edit/Glob/Grep/Agent β€” no Bash, no network). Reads only trusted roots; emits a per-finding verdict JSON.
    In: repo Β· report Β· fixed=VULN-… Β· out β†’ Out: verify_disposition.json.

The five components

HUNT vulnhunt/

Finds the bugs. Made only of written instructions β€” nothing to install.

Prompt-only (SKILL.md + 11 phases). Orchestrator/subagent split keeps findings out of the driver's context.

FIX vulnhunter-fix/

Writes the fix, proves it with a test, and opens a pull request.

Prompt + Python. 39 prod py files, 30+ gate scripts, model routing by severity/CWE, code-graph helper.

VERIFY vulnhunt-fix-verify/

Checks each fix by reading the code only. Cannot change anything.

Prompt-only (SKILL + 4 phases). No Bash / no network; caller pre-creates out; trusted-roots only.

RUNTIME vulnhunter-agent/

Runs the scanner by itself and creates GitHub tickets for the bugs.

~13k LOC. Auth chokepoint (api_key / bedrock_oauth / bedrock_sigv4); schema-validated manifest.

RUNTIME harness/ (for developers)

Scans many projects at once and measures how well the scanner works.

Shells out to claude -p /vulnhunt; clone→scan→LLM-judge→tally.

β†’ Open the clickable component graph (from CodeGraph: 180 files, 4,538 nodes, 10,362 edges).

Inside /vulnhunt β€” the phases

The scanner never analyses code itself. It spawns a fresh subagent for each phase and only checks the output file exists β€” which forces a systematic method.

Phase 1 Β· Recon β€” map every way in

List every place an outsider can push data into the program, and split the code into chunks to work on.

Build the input inventory, partition the codebase into subgraphs, mark production vs test/dev reachability. β†’ phase1_output.md.

Phase 2 Β· Hunt β€” parallel specialists

For each chunk, three specialists (injection, access-control, logic/crypto) follow the data forward, plus one that starts from dangerous operations.

Per production partition: INJ + NAV + LOG class agents + 1 sink-driven. Minimum agents = (3 Γ— partitions) + 1. Shared reference cached via phase2_shared.md.

Phase 2b Β· Disprove β€” the falsification engine

A sceptic tries to prove each claimed bug is actually wrong. About half get thrown out here.

Adversarial pass over each candidate; eliminates those resting on unsupported assumptions or mitigated by controls. This is the precision filter.

Phase 3 Β· Reproduce, Test & Fix

Write a working demonstration and a test for each surviving bug, plus a fix idea.

PoCs + executable exploit tests + fix strategies (descriptions, not applied edits). β†’ poc/, exploit_tests/, phase3_output.md.

Phase 3d Β· Sweep β€” find every other instance

Search the whole codebase for the same mistake, so one fix covers all of them.

Grep each confirmed root-cause pattern across the repo. β†’ phase3d_output.md.

Phase 4 Β· Report

Assemble the final report β€” one entry per confirmed bug, with proofs. Finding nothing is a valid result.

Orchestrator compiles the README; count-checks reconcile the sweep table so no finding is dropped or collapsed. Code smells go in a separate section.

Automation & scale

vulnhunter-agent β€” headless runtime

Runs a scan by itself β€” with no person watching β€” for example every night or after each code change. It saves a record of what happened and creates one GitHub ticket for each real bug it found. All the settings (which AI, which keys, which GitHub) come from one settings file, so the same setup works in any environment.

Clones the target, runs /vulnhunt via the Claude Agent SDK, writes a schema-validated scan_manifest.json, and optionally publishes results + files deduplicated issues. Auth is a single chokepoint: api_key (default), bedrock_oauth, or bedrock_sigv4. Use it as a base image you extend β€” wrap, don't fork; build against the manifest.

harness β€” batch & benchmark (dev-only)

A practice area for the scanner. One mode runs it over a whole list of code projects at once. The other mode runs it on projects where the real bugs are already known, then counts how many the scanner caught β€” so the team can measure how well it works.

Batch scanning from REPO_LIST.txt (resumable) and an accuracy benchmark (clone β†’ scan β†’ LLM-judge β†’ tally) against ground_truth/<repo>.json.

Technology stack

Runtime hostClaude Code CLI on Claude Opus (you supply model access).
SkillsPrompt-only Markdown (SKILL.md + phase files). Installed via install.sh.
LanguagesPython 3.12+ for the runtime agent & harness; jsonschema, Claude Agent SDK.
Code intelligenceGraphify AST extraction (dist graphifyy) with a grep fallback.
Model accessAnthropic API (default) or Amazon Bedrock (OAuth proxy / SigV4).
ExternalGitHub (issues Β· PRs Β· forks) via gh / tokens.
ContractsJSON-Schema-validated manifest & verdict + finding/fix/result schemas.
LicenseApache-2.0. Source: github.com/capitalone/VulnHunter.

Diagrams

Click any diagram to zoom.

System architecture
System architecture (HLD)
Hunt Fix Verify data flow
Data flow through Hunt β†’ Fix β†’ Verify (DFD L1)
Vulnhunt phases
The /vulnhunt internal phase pipeline
Component dependency graph
Component dependency graph (from CodeGraph)
Agent runtime
Headless runtime pipeline
Context diagram
Context diagram (DFD L0)

Docs & readable graphs

πŸ“˜ Onboarding docs

Start Here Β· Overview Β· HLD Β· LLD Β· Data Flow Β· Modules

🧩 Deterministic vs. LLM

What's a model call vs. ordinary code, per component β€” and why there's no LangChain/LangGraph/DeepAgents here.

βš™οΈ Operate it (samples)

Samples index · Process SOP · Scan→Fix→Verify runbook

🧭 Skill & phase explorer

Hunt→Fix→Verify + runtimes, each box → phases → files. Best entry point.

πŸ”¬ Code drill-down

module β†’ file β†’ function with plain-English notes.

πŸ” vs. the Visa harness

File-by-file equivalence check against the sibling Visa project β€” what matches, what's genuinely missing.