High-Level Design

The five components, how they fit together, trust boundaries, and quality mechanisms.

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

3. Run / deployment model

4. Trust boundaries & security posture (design-level)

5. Quality mechanisms

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).