High-Level Design (HLD)
Companion diagram:
diagrams/01_architecture.svg. Interactive version:architecture.html.
VulnHunter is not a server or a daemon — it is a set of skills that run inside Claude Code on your machine (or a CI worker), driven by a Claude Opus model you provide. Think of Claude Code as the factory floor and the three skills as three specialist crews that share it: a hunting crew that finds exploitable defects, a repair crew that fixes them under test, and an inspection crew that independently signs off each repair. Two optional runtimes turn the lights on automatically: one runs a single scan headless and files the paperwork (GitHub issues); the other runs many scans in a batch and grades how well the hunter did.
flowchart TB IN["Inputs<br/>code checkout · labelled issues"] --> CC["Claude Code CLI<br/>(subagents · tool allow-list)"] CC --> HUNT["/vulnhunt (Hunt)<br/>recon→hunt→disprove→PoC→sweep→report"] HUNT --> FIX["/vulnhunter-fix (Fix)<br/>parse→plan→RED→GREEN→verify→deliver"] FIX --> VERIFY["/vulnhunt-fix-verify (Verify)<br/>read-only per-finding verdict"] CC <--> PROV["Model provider<br/>Anthropic API / Bedrock"] AGENT["vulnhunter-agent<br/>headless runtime"] -.drives.-> HUNT HARNESS["harness<br/>batch + benchmark"] -.drives at scale.-> HUNT HUNT --> OUT1["results dir<br/>report · PoCs · tests"] FIX --> OUT2["reviewable PR"] VERIFY --> OUT3["verdict JSON"] AGENT --> OUT4["GitHub issues · scan_manifest.json"]
1. Components and responsibilities
| # | Component | Path | Responsibility |
|---|---|---|---|
| 1 | Scanner (/vulnhunt) |
vulnhunt/ |
Prompt-only orchestrator. Dispatches a subagent per phase (Recon → Hunt → Disprove → Reproduce → Sweep → Report). Reads code with Grep/Glob/Read; never edits the target. |
| 2 | Fixer (/vulnhunter-fix) |
vulnhunter-fix/ |
Test-driven remediation. Parses & clusters findings, plans, runs RED→GREEN per finding, verifies, and delivers a PR through six mechanical gates. Ships a Python helper package + a code-graph builder. |
| 3 | Verifier (/vulnhunt-fix-verify) |
vulnhunt-fix-verify/ |
Read-only, independent verification. Reads a prior scan + a "fixed" claim and emits a per-finding verdict. No Bash, no network. |
| 4 | Runtime agent | vulnhunter-agent/ |
Config-driven headless wrapper: clone → run /vulnhunt via the Claude Agent SDK → publish results → file GitHub issues; also a --mode=verify path. |
| 5 | Harness (dev-only) | harness/ |
Workstation-scale batch scanning + an accuracy benchmark (clone → scan → LLM-judge → tally). Shells out to claude -p /vulnhunt. |
Supporting assets inside these subtrees: phase files (phases/), prompt libraries and
reference rules (prompts/, references/), gate scripts (scripts/), JSON schemas
(scan_manifest.schema.json, verify_disposition.schema.json, finding/fix-plan/result
schemas), and PR/issue templates (templates/).
2. Technology stack
- Runtime host: the Claude Code CLI, authenticated, running on Claude Opus (the falsification discipline depends on frontier-class reasoning; you supply model access).
- Language / packages: Python 3.12+ for the runtime agent and harness (the three
skills themselves are prompt-only — Markdown, no package). Helper deps:
jsonschema(fixer), the Claude Agent SDK (agent). - Code intelligence: the fixer builds a lightweight code graph via Graphify AST
extraction (dist
graphifyy), with a grep fallback when AST mode can't run. - External services: GitHub (
ghCLI / tokens) for issues, PRs, forks; the model provider — direct Anthropic API by default, or Amazon Bedrock (OAuth-proxy or SigV4). - Contracts: JSON-Schema-validated manifests and dispositions.
3. Run / deployment model
- Install the skills with
./install.sh, which copies (not symlinks) them into~/.claude/skills/— symlinks breakfind/globinside subagents. Re-run after edits. - Interactive:
claude --model opus --add-dir ~/.claude/skills/<skill> …then invoke the slash command./vulnhuntis read-only by default; a menu offers a bash-enabled mode that installs deps and runs exploit tests (trusted code only). - Headless:
python -m agent <repo-url>loads config (TOML +VULNHUNT_*env), selects an auth mode, clones, runs the scanner via the Agent SDK, writes a schema-validatedscan_manifest.json, and optionally publishes results + files issues. Designed to be used as a base image you extend (FROM) with your own config/credentials — wrap, don't fork; build against the manifest, not the internals. - At scale:
harness/batch-scans aREPO_LIST.txt(resumable) and benchmarks accuracy againstground_truth/<repo>.json.
4. Trust boundaries & security posture (design-level)
- The scanned repo is untrusted input. VulnHunter reasons about attacker-controlled data; it treats the target as adversarial, not as a source of instructions.
- The scanner is read-only.
/vulnhuntdocuments fix strategies; it does not modify the target. Only/vulnhunter-fixwrites code — and only on a git branch/worktree, with an operator Approve/Pause at every phase boundary and a "never touch untargeted code" rule. - The verifier is sandboxed by tool envelope.
/vulnhunt-fix-verifyruns under Read/Write/Edit/Glob/Grep/Agent with no Bash and no network — it cannot run shell commands, clone, or fetch. It reads only within the trusted roots (the supplied repo plus any pre-clonedadditional_repos); anything outside is recorded as unverifiable and the run continues rather than halting. The caller must pre-create theoutdirectory. - Developer claims are evidence-free. The verifier treats "I fixed it" as a claim to be checked against the code, and developer comments as claims, never as instructions.
- Secrets never hardcoded. The runtime pulls every host, credential, and path from config
or env; an auth chokepoint (
build_settings.py) is the single place that knows how to authenticate. Tokens can be consumed from a broker directory rather than embedded. - Authorized use only. All three skills egress code to a model provider; run only against repositories you are explicitly authorized to analyze. (Note the upstream cyber-safeguard disclaimer: dual-use vulnerability discovery may require enrolment in Anthropic's Cyber Verification Program on first-party platforms.)
5. Quality mechanisms
- Orchestrator/worker split. The scanner's top level does no analysis — it dispatches subagents and checks output files exist. Keeping findings out of the orchestrator's context forces the systematic methodology instead of improvised reasoning.
- Falsification before reporting. Phase 2b actively tries to disprove candidates.
- Executable proof. Every finding has a PoC; every fix has a RED→GREEN test.
- Deterministic gates bracket the AI. Six mechanical delivery gates and 30-plus validator scripts constrain the fixer; JSON schemas validate every machine-readable artifact.
- Independent verification. A completely separate read-only agent re-checks fixes, so remediation is proven, not trusted.
- Benchmarking. The harness measures detection accuracy against a known-vulnerable corpus so methodology changes can be evaluated, not guessed.
See LLD for cross-cutting internals, data-flow for the artifact-by-artifact flow, and Deterministic Tools vs. LLM Reasoning for exactly which parts of each component are model calls vs ordinary code (including why there is no LangChain/LangGraph/DeepAgents anywhere in this codebase).