Component: vulnhunter-fix/ — the fixer (/vulnhunter-fix)
Role. The repair crew. Turns each confirmed finding into a tested fix and a reviewable PR — test-first, operator-gated, scoped to the finding.
Kind. Prompt + Python.
SKILL.md+ a prompt library, avulnhunter_fixhelper package (incl. a code-graph builder), 30-plus gate scripts, JSON schemas, and PR/issue templates. ~39 production Python files (~6.8k LOC) + 31 test files.
Part 1
VulnHunter finds the bugs; VulnHunter-Fix fixes them properly. "Properly" means it refuses to call a fix done until a test proves it works: it first writes a test that fails because the bug is present (RED), then changes the code until that test passes (GREEN), then confirms the original exploit is blocked and nothing else broke. Every pull request it opens shows the exploit, the test, and the fix — so a reviewer can trust it at a glance. It stops and asks you before moving between phases; it never touches code outside the finding.
Explain-it-simply. A mechanic who won't hand back your car until the warning light they're fixing is reproduced on the diagnostic, then goes out — and who shows you the before/after readout with the receipt.
Data-flow (this component)
flowchart LR IN[(labelled issues /<br/>results dir)] --> PA[Parse+Cluster] PA --> PL[Plan<br/>tier by severity/CWE] PL --> TDD[Implement<br/>RED→GREEN→confirm] TDD --> VF[Verify<br/>re-run matrix] VF --> DL[Deliver<br/>6 gates → PR]
Part 2 — Technical detail
The skill runs unattended within a phase but pauses at every phase boundary for an operator
Approve/Pause (no fast-path). Mode is auto-detected by scripts/detect_mode.sh:
in-place (inside a checkout, no args — fix vulnhunter-labelled issues on per-finding git
worktrees under <repo>/.vulnhunter-fix/, one PR per cluster) or fork (pass target +
results path — fork into fork_org, work under ./work/, one PR per finding to the fork).
Model routing (config.json → models.routing): opus for Critical / complex CWEs
(CWE-287/295/327/330/345/502/611) at High+ / multi-file; sonnet for High / injection-family
(CWE-22/78/79/89/94/352/434/918); haiku for Low-Med single-file simple CWEs.
Directory map
| Path | Purpose |
|---|---|
SKILL.md |
Orchestrates parse → plan → implement → verify → deliver, with phase-boundary gates. |
config.json |
GitHub org/host, branch prefix, PR draft/labels, verification retries/timeout, model routing, modes. |
prompts/ |
The phase prompts: parse*, plan*, implement, agent_fix, reviewer_test, verify, sweep, deliver, tier_judgment, and CWE-family worker_agent_{authz,crypto,injection,config,resource,common}. |
references/ |
The rulebook: cwe-fix-patterns.md, remediation-rigor.md, fix-completeness-rubric.md, approved-crypto/key YAMLs, and JSON schemas (finding, fix_plan, result, triage). |
scripts/ |
30-plus deterministic validators + gates: run-gates.py, check-{scope,severity-mask,idempotency,body-completeness}.py, anti-merge-check.py, validate-*.py, detect_mode.sh, setup_worktree.sh, build_graph.py. |
vulnhunter_fix/ |
Python package: delivery.py + the graph/ code-graph builder. |
vulnhunter_fix/graph/ |
build.py (wrap Graphify AST → GraphDocument, content-hash cache), query.py (GraphQuery), schema.py, config.py, fallback.py (grep degrade). |
templates/ |
pr_body*.md, commit_msg.md, issue_body.md, residual_risk_section.md. |
The TDD gate (the heart of it)
Per finding: exploit demo → failing security test (RED) → implement fix (GREEN) → confirm
exploit blocked → regression check → commit. No source file is edited until RED evidence
exists on disk. verification.max_retries / max_repair_attempts bound the loop.
The six delivery gates (before gh pr create)
Severity-mask · body-completeness · scope · idempotency · anti-merge · verification-table —
all run by scripts/run-gates.py. If any fails, no PR opens.
Code-graph helper
graph/build.py runs AST-only Graphify extraction, refusing to run if cloud-LLM env vars
are set (check_backend_isolation) and degrading to fallback.py grep mode at low confidence.
Sequential by default on macOS (sandbox blocks the parallel semaphore syscall);
GRAPHIFY_PARALLEL overrides. See LLD §4.
Part 3 — Inputs, outputs, model selection & deterministic calls
What happens here. The fixer turns confirmed findings into tested code changes. Unlike the scanner, it is a hybrid: LLM reasoning (plan the fix, write the test, write the fix) is bracketed by deterministic Python at every boundary — mode detection, language detection, schema validation, the six delivery gates, and the code-graph build all run as ordinary scripts, not model calls.
Inputs. In-place mode: vulnhunter-labelled GitHub issues on origin. Fork mode: a prior
*_VULNHUNT_RESULTS_* results directory plus a target repo. Also: config.json (org/host,
routing, gate settings), the target checkout, and the reference rulebook under references/
(CWE fix patterns, approved-crypto/key YAMLs, JSON schemas).
Outputs. One reviewable pull request per unit of delivery (a cluster in-place, a single
finding in fork mode), each carrying the exploit, the RED→GREEN test, and the fix. Intermediate
artifacts: fix_plan.json, worker result.json, triage sidecars, and validated PR/issue bodies.
How the model version is chosen. Two separate mechanisms — don't conflate them. (A) The
Step-0/0b interactive gate, in SKILL.md itself: the skill reads its own running model from the
session system prompt. Opus 4.x → proceed; Sonnet or Haiku 4.x → stop, with a verbatim message
telling the user to run /model claude-opus-4-8 and re-invoke — no other tool calls happen
first. This gate applies only in interactive mode; headless invocations skip it because "the
executor" runs a fixed Opus model under the hood regardless. (B) Per-finding worker routing —
this is the component with real, deterministic routing of which model implements each fix.
config.json → models.routing maps each finding to a tier by
severity + CWE prefix + multi-file flag: opus for Critical, complex CWEs
(auth/crypto/deser — CWE-287/295/327/330/345/502/611) at High+, or multi-file changes; sonnet for
High / injection-family (CWE-22/78/79/89/94/352/434/918); haiku for Low-Med single-file simple
CWEs (CWE-117/200/312/319/532/693/1021). Default sonnet; override forces one model. Separately,
a completeness tier is decided by scripts/compute-completeness-tier.py, which walks signals
conservative-first (WORKAROUND → MITIGATION → FULL) and never silently returns FULL — only
when no deterministic signal matches does it return LLM_REVIEW, escalating to a bounded LLM
prompt (prompts/tier_judgment.md) whose output is then re-validated deterministically by
scripts/parse-tier-judgment.py against references/result-schema.json.
Deterministic (non-LLM) calls. (1) Mode & language detection — scripts/detect_mode.sh,
scripts/language-detect.py (heuristic: manifest files, then suffix majority-vote) to pick the
right repo-type adapter. (2) Code graph — scripts/build_graph.py / vulnhunter_fix/graph/
runs Graphify AST extraction (no cloud LLM; refuses if cloud-LLM env vars are set) with a
content-hash cache and a grep fallback. (3) git — worktree create/reset, branch, commit
(setup_worktree.sh, worktree-reset.py). (4) GitHub CLI (gh) — PR creation. (5) pytest /
the project's test runner — to run the RED (fail) and GREEN (pass) tests. (6) Schema validation
— jsonschema (Draft 2020-12) over finding/fix-plan/result/triage schemas. (7) The six delivery
gates — scripts/run-gates.py orchestrates check-*.py / validate-*.py / anti-merge-check.py
(severity-mask, body-completeness, scope, idempotency, anti-merge, verification-table); each is a
stateless script that returns pass/fail. A PR opens only if all gates pass.
See also: Scanner · Verifier · LLD · module index.