Component: vulnhunt/ — the scanner (/vulnhunt)
Role. The hunting crew. Finds exploitable defects by tracing attacker-controlled inputs forward to dangerous sinks and disproving weak candidates. Prompt-only; never edits the target.
Kind. Prompt-only Claude Code skill —
SKILL.md+ 11 phase files. No Python package.
Part 1
This is the hunter. Give it a codebase and it produces a short, high-confidence list of proven vulnerabilities — each with a working demonstration and a suggested fix. It gets to "short and high-confidence" by working like an attacker (start at the doors, follow the data) and then arguing against itself before it will report anything.
Explain-it-simply. A detective that lists every way into the building, follows each intruder's path to see if they can reach the vault, then makes a sceptical colleague try to poke holes in every theory. Only theories that survive get written up — with proof.
Data-flow (this component)
flowchart LR R[(code)] --> P1[Phase1 Recon<br/>input inventory] P1 --> P2[Phase2 Hunt<br/>INJ · NAV · LOG + sink] P2 --> P2B[Phase2b Disprove] P2B --> P3[Phase3 Reproduce+Test] P3 --> P3D[Phase3d Sweep] P3D --> P4[Phase4 Report] P2B -.zero findings = valid.-> P4
The top-level skill is an orchestrator: it spawns a subagent per phase and only checks that each output file exists — it never reads the analysis itself. That discipline is what keeps the methodology systematic instead of improvised.
Part 2 — Technical detail
SKILL.md binds VULNHUNT_DIR/VULNHUNT_BRANCH/repo URL, runs mandatory first actions
(model check on Opus; dependency install in bash-enabled mode, else read-only), then drives
the phases and compiles the report. It encodes the Operating Principles (report what the
gates confirm; follow the data; prove it; fix the class not the payload; production code only)
and the Investigation Discipline (forward tracing through dispatch boundaries; audit all
outbound parameters; exhaust all paths; follow stores and response taint; transitive caller
search; read production source not mocks). Scope excludes tests/build/vendored/generated/docs,
with a deliberate exception for security-relevant infrastructure config.
File map (quick scan)
| File | Lines | Purpose |
|---|---|---|
SKILL.md |
~230 | Orchestrator: metadata binding, first actions, phase dispatch, report compile, stopping rules. |
phases/phase1_recon.md |
519 | Recon subagent — build the input inventory, partition the codebase, mark prod/dev reachability. |
phases/phase2_hunt.md |
260 | Orchestrator's dispatch procedure for the parallel class agents. |
phases/phase2_shared.md |
380 | Reference every class agent reads first (cached across the dispatch). |
phases/phase2_class_inj.md |
168 | Injection class reference (SQLi, command, code, template, path). |
phases/phase2_class_nav.md |
223 | Navigation & access-control reference (authz, IDOR, SSRF, open redirect). |
phases/phase2_class_log.md |
137 | Logic & crypto reference. |
phases/phase2b_verify.md |
283 | Falsification pass — try to disprove each candidate. |
phases/phase3_reproduce_test.md |
262 | Write PoCs + executable exploit tests. |
phases/phase3c_fixes.md |
67 | Fix-strategy generation (descriptions, not applied edits). |
phases/phase3d_sweep.md |
134 | Grep every instance of each confirmed root-cause pattern. |
phases/phase4_report.md |
187 | Final report format; count-checks so no finding is dropped or collapsed. |
Key behaviours
- Two invocation paths. Path A (agent-driven) reads a pre-resolved metadata block; path B (interactive) resolves target/mode itself and offers a read-only vs bash-enabled menu.
- Read-only vs bash-enabled. Read-only writes static PoCs (exploit tests written, not run); bash-enabled installs deps and runs the exploit tests — trusted code only.
- Count discipline in Phase 4. Instance counts must reconcile against the sweep table, and
every exploit-test PASS becomes exactly one
VULN-NNNrow — the report explicitly guards against collapsing multiple sink locations into one finding. - Zero findings is valid — if every candidate is eliminated, it reports "no exploitable vulnerabilities found", lists code smells, and stops.
Outputs (under *_VULNHUNT_RESULTS_*/)
phase1_output.md, results/ (per class agent), phase2b_output.md, poc/,
exploit_tests/, phase3_output.md, phase3d_output.md, and the final README.md.
Part 3 — Inputs, outputs, model selection & deterministic calls
What happens here. The scanner reads a codebase and produces a proven list of exploitable
findings. It does this as an LLM-reasoning process: each phase is a subagent that reads code and
reasons, using search tools for navigation. There is no built-in static-analysis engine —
unlike a classic SAST tool, /vulnhunt has no tree-sitter/AST pass of its own; the "analysis" is
the model's reasoning over what Grep/Glob/Read surface.
Inputs. A target code checkout (the working directory, or a path given at invocation); the mode
(read-only vs bash-enabled); and, under agent-driven runs, a "Pre-resolved scan metadata" block
(results dir, branch, repo URL). Optionally, in bash mode, the target's own dependency manifests
(package.json, requirements.txt, go.mod, pom.xml, build.sbt) so deps can be installed.
Outputs. A *_VULNHUNT_RESULTS_* directory: per-phase markdown (phase1_output.md, results/,
phase2b_output.md, phase3_output.md, phase3d_output.md), poc/, exploit_tests/, and the
final report README.md. It writes nothing to the target's own source.
How the model version is chosen. There is no per-phase model routing — every subagent
inherits the active Claude Code session model. The only model logic is a check, not a choice:
SKILL.md Step 0 inspects the running model and, if it is not Opus 4.7 or higher, stops and
asks the user to /model opus before continuing (skipped on agent-driven runs, where the runtime
sets the model). So model selection lives outside the skill — in the CLI/agent that launched it.
Deterministic (non-LLM) calls. (1) Grep / Glob / Read — text search and file reads used for
navigation and for verifying output files exist (the orchestrator's sync signal). (2) In
bash-enabled mode only: deterministic dependency install (npm install / pip install -r /
go mod download / mvn dependency:resolve / sbt update) and exploit-test execution (the
project's own test runner) to actually run PoCs. (3) /cost after each phase for spend reporting.
No schema validators, no code-graph engine, no git writes. In read-only mode there are no
external process calls at all — PoCs are written but not run.
See also: HLD · Data Flow · Fixer · module index.