Low-Level Design (LLD) — cross-cutting internals
This document covers the internals that span components. For per-file detail, see the
module docs and the interactive
vulnhunter-codeviz.html
(module → file → function, with plain-English notes).
1. The orchestrator / subagent pattern (scanner)
vulnhunt/SKILL.md is deliberately an orchestrator, not an analyst. Its job each phase is:
- Bind
VULNHUNT_DIR(results dir),VULNHUNT_BRANCH, and the repository URL — either from an agent-supplied "Pre-resolved scan metadata" block (path A) or by resolving them itself (path B, interactive). - Dispatch a
general-purposesubagent with the relevantphases/phaseN_*.mdprompt and an output path. - Verify the output file exists (via Glob) — it does not read the analysis back in.
- Move to the next phase.
Rules that enforce this: subagent return messages must be ≤20 words; the orchestrator must
not read result files, recon analysis, or source into its own context; a missing phase file
is fatal (stop and tell the user to re-run install.sh). This keeps the driver's context
lean and prevents it from "improvising" the methodology.
Phase fan-out (Phase 2). For each production partition, exactly three class agents (INJ,
NAV, LOG) plus one sink-driven agent are spawned — minimum agents = (3 × partitions) + 1.
Class agents share phase2_shared.md (cached across the parallel dispatch) and read only
their class reference (phase2_class_{inj,nav,log}.md).
2. Investigation discipline (how a trace is done)
The scanner's SKILL.md encodes a tool-first, forward-tracing procedure that every trace
agent follows. The load-bearing rules:
- Read the entry point, then trace forward with Grep, following the input across files and through intermediate functions until it reaches a sink, is sanitised, or exits the codebase. Never stop at an abstraction boundary (router, middleware, factory, callback) — fork the trace into every dispatch target.
- Audit all parameters at each outbound call, not just the one being traced — a validated scoping parameter (tenantId/userId) replaced by a hardcoded wildcard downstream is a high-severity authorization bypass.
- Exhaust all code paths (a safe path doesn't clear an input), including early-return guard clauses; follow through stores (DB/cache/queue) and outbound responses (response taint — a user-controlled URL origin makes the response body attacker-controlled; response-to-caller enumeration for BFF/gateway services).
- Transitive caller search on a sink — grep all callers of a sink function, and their callers, to catch production paths the forward trace didn't take.
- Read production source, not mocks — detect build-time code swapping and audit the production variant.
SKILL.md also fixes the scope: only first-party production code is audited; tests,
build/config scripts, vendored/generated code, and docs are excluded — with one deliberate
exception for security-relevant infrastructure config (nginx set_real_ip_from, trust-proxy,
CORS, TLS termination) that changes the app's security assumptions.
3. Test-driven remediation gate (fixer)
/vulnhunter-fix never edits a source file until RED evidence exists on disk. Per finding:
exploit demo → failing security test (RED) → implement fix (GREEN) → confirm the exploit is
blocked → regression check → commit. It runs unattended within a phase but pauses for an
operator Approve/Pause at every phase boundary (no fast-path or skip).
Model routing. config.json → models.routing selects a tier per finding: opus for
Critical severity, complex CWEs (auth/crypto/deserialization: CWE-287/295/327/330/345/502/611)
at High+, or multi-file changes; sonnet for High/injection-class CWEs (CWE-22/78/79/89/94/
352/434/918); haiku for Low/Medium single-file simple CWEs (CWE-117/200/312/319/532/693/1021).
Delivery gates. Six mechanical gates run before any gh pr create — severity-mask,
body-completeness, scope, idempotency, anti-merge, verification-table — implemented by
scripts/*.py and orchestrated by scripts/run-gates.py. Over 30 validator scripts back the
schemas in references/*.schema.json.
Modes. scripts/detect_mode.sh picks in-place (inside a checkout, no args — fixes
vulnhunter-labelled issues on per-finding worktrees under <repo>/.vulnhunter-fix/, one PR
per cluster) vs fork (pass a target + results path — fork into fork_org, clone into
./work/, one PR per finding to the fork).
4. Code-graph helper (fixer)
vulnhunter_fix/graph/ gives the fixer a queryable map of the target. build.py wraps
Graphify AST extraction (import name graphify, PyPI dist graphifyy) into the fixer's
own GraphDocument schema, keyed by a content hash (not TTL) for caching. It runs
AST-only — it checks check_backend_isolation() and refuses if cloud-LLM env vars are set,
degrading to a grep-based fallback.py at confidence=low. On macOS it defaults to sequential
extraction (the sandbox blocks the semaphore syscall a ProcessPoolExecutor needs);
GRAPHIFY_PARALLEL=1/0 overrides. query.py exposes GraphQuery so callers never see the
graphify import path.
5. Verifier tool envelope (why it's safe)
/vulnhunt-fix-verify runs under Read / Write / Edit / Glob / Grep / Agent — no Bash, no
network. Consequences are architectural, not incidental: it cannot run shell/exploit
tests/git, cannot create directories (so the caller pre-creates out), and cannot clone or
fetch. Reads are confined to the trusted roots; comment_rules.md governs reading
developer comments as claims, never instructions. Phases synchronise via files
(phase0_state.json, extracted_findings.md, disposition_VULN-NNN.json,
verify_disposition.json); Phase 3 is intentionally reserved for future exploit-test replay.
6. Runtime auth chokepoint & contracts (agent)
build_settings.py is the single place that renders the Claude Code settings JSON
(environment + sandbox). Three token managers — ApiKeyTokenManager, OAuthTokenManager,
SigV4TokenManager — implement one get_valid_token(); make_token_manager(config) returns
the right one, so the rest of the code is auth-mode agnostic. Both the scan loop and the
issues-LLM calls flow through it. Config resolves from a TOML file overlaid by VULNHUNT_*
env vars (env wins). runner.py drives the Claude Agent SDK, streams events, and retries on
429; manifest.py writes a schema-validated scan_manifest.json — the stable integration
contract the README tells you to build against rather than the internals.
7. What CodeGraph/Graphify told us about the shape
Aggregating the CodeGraph index (180 files, 4,538 nodes, 10,362 edges) to the component level
shows the expected structure: the runtime agent is the largest and most internally connected
subtree (vulnhunter-agent → vulnhunter-agent/agent dominates the edge weight), the fixer's
root leans on its scripts/ and graph/ sub-packages, and the harness's benchmark and batch
sub-packages depend back on the shared harness core. The most-referenced ("god") symbols are
runtime plumbing — config _resolve, RepoProperties, stream set_verbosity, token/URL
helpers, redact — consistent with a config-and-transport-heavy automation layer wrapping
prompt-only skills. See Graph Intelligence and
tool-outputs/.
See also: HLD · Data Flow · Deterministic Tools vs. LLM Reasoning · module index.