Component: vulnhunt/ — the scanner

The hunting crew: attacker-first forward tracing, phase-by-phase, prompt-only.

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

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.