VulnHunter — Skill & Phase Explorer

The closed loop Hunt → Fix → Verify plus its two automation runtimes. Expand any box to see its phases/stages and the files that implement them. Works without JavaScript.

HUNT find exploitable defects FIX test-driven remediation VERIFY independent read-only check RUNTIME run it headless / at scale

HUNT /vulnhunt — the scanner (prompt-only skill)

An orchestrator that never analyses code itself — it dispatches a subagent per phase and verifies each output file. Attacker-first: start at every user-controllable input, trace forward to dangerous sinks, then try to disprove each candidate. Never edits the target; fixes are documented, not applied.

In: a code checkout (read-only by default) → Out: a *_VULNHUNT_RESULTS_* dir with report README.md, PoCs, exploit tests.
Phase 1 · Recon — build the input inventory

Enumerate every attacker-controllable entry point (HTTP handlers, CLI, queue consumers, gRPC, file uploads), partition the codebase into subgraphs, and mark production vs test/dev reachability.

Out: phase1_output.md — input inventory + partition table.

phases/phase1_recon.md

Phase 2 · Hunt — parallel class-group trace agents

For each production partition, spawn one agent per vulnerability class — INJ (injection), NAV (navigation & access control), LOG (logic & crypto) — plus one sink-driven audit agent. Each traces inputs forward to sinks. Minimum agents = (3 × partitions) + 1.

Out: one result file per agent under results/.
Phase 2b · Verify — adversarial disprove (falsification engine)

A pass that actively tries to disprove each candidate — flawed assumptions, missing preconditions, mitigating controls. Roughly half of candidates are eliminated here. This is what keeps false positives low.

Out: phase2b_output.md — confirmed findings only.

phases/phase2b_verify.md

Phase 3 · Reproduce, Test & Fix

For each surviving finding: write a PoC, an executable exploit test, and a fix strategy (description, not an applied edit). Read-only mode writes static PoCs; bash-enabled mode runs them.

Out: poc/, exploit_tests/, phase3_output.md (VULN-NNN table).
Phase 3d · Sweep — find every other instance

Grep each confirmed root-cause pattern across the whole codebase so a single fix covers all instances, not just the one that was traced.

Out: phase3d_output.md — sweep table + per-instance triage.

phases/phase3d_sweep.md

Phase 4 · Report — orchestrator compiles the final report

The orchestrator assembles the input inventory with dispositions, one VULN-NNN per sink location, PoCs, fix strategies, the sweep table, and a separate Code Quality (code smells) section. Zero findings is a valid outcome.

phases/phase4_report.md → results dir README.md

FIX /vulnhunter-fix — the fixer (prompt + Python helpers)

Developer-led, test-driven remediation. Unattended within a phase, but pauses at every phase boundary for an operator Approve/Pause. Never edits a source file until RED evidence exists on disk.

In: vulnhunter-labelled GitHub issues (in-place) or a results dir (fork mode) → Out: a reviewable PR with exploit + test + fix.
1 · Parse — extract & cluster findings

Pull findings from issues or the results dir and cluster related ones so one PR fixes a whole root cause.

prompts/parse.md · prompts/parse_issues.md · scripts/issue_intake.py · scripts/cluster_score.py

2 · Plan — decide fix order & approach per cluster

Route each cluster to a model tier by severity/CWE (see config.json → models.routing) and pick the remediation approach.

prompts/plan.md · prompts/plan_fork.md · prompts/tier_judgment.md · scripts/parse-tier-judgment.py

3 · Implement (TDD gate) — RED → GREEN → confirm

Exploit demo → failing security test (RED) → implement fix (GREEN) → confirm exploit blocked → regression check → commit. Worker agents are CWE-family specialised.

prompts/implement.md · prompts/agent_fix.md · prompts/worker_agent_{authz,crypto,injection,config,resource,common}.md

4 · Verify — re-run the full RED→GREEN matrix

Independent reviewer test pass per cluster; schema-validated results with a repair loop.

prompts/verify.md · prompts/reviewer_test.md · scripts/validate-*.py

5 · Deliver — six mechanical gates before gh pr create

Severity-mask, body-completeness, scope, idempotency, anti-merge, and verification-table gates all run before any PR opens.

prompts/deliver.md · scripts/run-gates.py · scripts/check-*.py · templates/pr_body*.md · vulnhunter_fix/delivery.py

graph/ — the code-graph helper package

Wraps Graphify AST extraction (dist graphifyy) into the fixer's own schema, with a content-hash cache and a grep fallback when AST extraction can't run.

vulnhunter_fix/graph/{build,query,schema,config,fallback}.py · scripts/build_graph.py

VERIFY /vulnhunt-fix-verify — independent verifier (prompt-only)

A separate, strictly read-only agent — Read/Write/Edit/Glob/Grep/Agent, no Bash, no network. The developer's word is a claim, not evidence; only the code is evidence. The caller must pre-create the out directory.

In: repo= report= fixed=VULN-… out= → Out: per-finding verdict JSON.
Phase 0 · Preflight — validate args & trusted roots

Reject missing/non-absolute args; establish the trusted roots (repo + additional_repos).

phases/phase0_preflight.md → out/phase0_state.json

Phase 1 · Extract — pull the claimed-fixed findings

Read the prior report and extract only the fixed= findings.

phases/phase1_extract.md → out/extracted_findings.md

Phase 2 · Verify — inspect the checkout, reach a verdict

Statically confirm whether each finding is actually remediated in the supplied code.

phases/phase2_verify.md → out/disposition_VULN-NNN.json (one per id)

Phase 4 · Emit — write the verdict JSON

Combine dispositions into the final artifact. (Phase 3 is intentionally reserved for future exploit-test replay.)

phases/phase4_emit.md → out/verify_disposition.json

RUNTIME vulnhunter-agent/ — headless runtime

Runs /vulnhunt unattended via the Claude Agent SDK: clone → scan → publish → file GitHub issues; also a --mode=verify path. All hosts/credentials/paths come from TOML + VULNHUNT_* env — nothing sensitive is hardcoded.

Auth chokepoint — one place decides how to reach Claude

Three interchangeable token managers behind one get_valid_token(): api_key (default), bedrock_oauth, bedrock_sigv4.

agent/auth.py · agent/token_client.py · agent/build_settings.py · agent/config.py

Scan → manifest

Drives the SDK, streams events, retries on 429, then writes a schema-validated manifest — the stable integration contract.

agent/runner.py · agent/_stream_events.py · agent/manifest.py · scan_manifest.schema.json

Publish & Issues

Optionally push results to a separate repo and post one deduplicated GitHub issue per confirmed finding (or a clean-scan receipt).

agent/publish.py · agent/issues*.py (fetch/extract/dedup/render/remote_report)

Verify mode & audit

Orchestrates /vulnhunt-fix-verify and posts verdicts; optional JSONL lifecycle audit.

agent/verify*.py · agent/audit.py · verify_disposition.schema.json

RUNTIME harness/ — batch & benchmark (dev-only)

Workstation-scale tooling that shells out to claude -p /vulnhunt …. Not part of the shipped product.

Batch scanning — many repos from a URL list

Clone + scan every repo in REPO_LIST.txt, resumable, with status/collect commands.

local_harness/batch/run.py · local_harness/scan.py · local_harness/clone.py

Benchmark — measure detection accuracy

Clone → scan → LLM-judge against a known-vulnerable corpus → tally metrics. Bring your own ground_truth/<repo>.json.

local_harness/benchmark/{run,judge,tally,analyze_misses,finding_history}.py

Generated for new-joiner onboarding · counts from CodeGraph & Graphify (see tool-outputs/). Source: github.com/capitalone/VulnHunter (Apache-2.0).