Low-Level Design

Cross-cutting internals: orchestrator pattern, TDD gate, code-graph helper, verifier envelope, auth chokepoint.

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:

  1. 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).
  2. Dispatch a general-purpose subagent with the relevant phases/phaseN_*.md prompt and an output path.
  3. Verify the output file exists (via Glob) — it does not read the analysis back in.
  4. 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:

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.