Data Flow (DFD)
This document traces what data moves through VulnHunter, at three levels of zoom. The labelled artifact on each arrow is the most useful thing to memorise as a newcomer.
Rendered images:
03_context_dfd.svg(L0),02_dataflow_loop.svg(L1),06_hunt_phases.svg(Hunt internals).
Data enters as code plus a target scope. It is progressively refined: raw code becomes an inventory of entry points; the inventory becomes candidate findings; candidates become confirmed findings (the ones that survived disproof); confirmed findings become a report with proofs; the report becomes fixes-under-test; and fixes become independent verdicts. Nothing skips ahead — each step consumes the previous step's artifact.
Level 0 — Context diagram
flowchart LR OP([Engineer / developer]) -->|/vulnhunt · /vulnhunter-fix · /verify| VH[VulnHunter] TGT[(Target codebase)] -->|source, read-only by default| VH VH -->|prompt data egress| PROV([Model provider<br/>Anthropic API / Bedrock]) PROV -->|model reasoning| VH VH -->|findings, PoCs, verdicts| ART[[Artifacts]] VH <-->|issues · PRs · forks| GH([GitHub]) VH -. fix mode: edits on a branch/worktree only .-> TGT ART -->|review| OP
External entities: the operator, the target codebase, the model provider (data egress happens here), and GitHub. Note the dashed arrow back to the target — only the fixer writes, and only onto a git branch/worktree, never the scanner.
Level 1 — The Hunt → Fix → Verify loop
flowchart LR R[(code checkout)] -->|Phase1 recon| INV[Input inventory + partitions] INV -->|Phase2 hunt INJ/NAV/LOG| CAND[Candidate findings] CAND -->|Phase2b disprove| CONF[Confirmed findings] CONF -->|Phase3 reproduce| POC[PoCs + exploit tests + fix strategies] POC -->|Phase3d sweep + Phase4| RPT[[report README.md · VULN-NNN]] RPT -->|/vulnhunter-fix parse+plan| TDD[RED test → GREEN fix] TDD -->|verify + 6 gates| PR[[reviewable PR]] PR -->|/vulnhunt-fix-verify| VERD[[per-finding verdict]] VERD -.needs_review.-> TDD
Artifact reference
| Artifact | Produced by | Consumed by | Shape |
|---|---|---|---|
| Input inventory + partitions | /vulnhunt Phase 1 |
Phase 2 | entry points, file scope, prod/dev reachability |
| Candidate findings | Phase 2 (class agents) | Phase 2b | source→sink trace + hypothesis |
| Confirmed findings | Phase 2b (disprove) | Phase 3 | candidates that survived falsification |
| PoCs + exploit tests + fix strategies | Phase 3 | Phase 3d, Phase 4 | runnable/static proof + proposed fix |
| Sweep table | Phase 3d | Phase 4 | every instance of each root-cause pattern |
report README.md |
Phase 4 | /vulnhunter-fix, humans |
ranked VULN-NNN findings + code smells |
| Reviewable PR | /vulnhunter-fix Deliver |
reviewers, /verify |
exploit + RED→GREEN test + fix |
verify_disposition.json |
/vulnhunt-fix-verify Emit |
operator, runtime | per-finding verdict |
scan_manifest.json |
vulnhunter-agent |
your automation | schema-validated run record |
Level 2 — Two internal flows
/vulnhunt phases (the scanner)
The orchestrator dispatches a subagent per phase and only checks that each output file exists — it never reads findings into its own context.
flowchart LR P1[Recon] -->|partitions| P2[Hunt<br/>3×class + sink] P2 -->|candidates| P2B[Disprove] P2B -->|confirmed| P3[Reproduce+Test] P3 -->|root causes| P3D[Sweep] P3D -->|all instances| P4[Report] P2B -.zero findings = valid.-> P4
Files touched: phase{1..4}*.md drive each subagent; results accumulate under the
*_VULNHUNT_RESULTS_* directory (phase1_output.md, results/, phase2b_output.md,
poc/, exploit_tests/, phase3_output.md, phase3d_output.md, final README.md).
vulnhunter-agent runtime (headless)
flowchart LR URL[(repo URL)] --> CFG[load_config<br/>TOML + VULNHUNT_* env] CFG --> TOK[make_token_manager<br/>api_key / bedrock_oauth / bedrock_sigv4] TOK --> CLONE[clone target] CLONE --> RUN[runner.run_vulnhunt<br/>Agent SDK runs /vulnhunt] RUN --> MAN[(scan_manifest.json<br/>schema-validated)] MAN --> PUB[publish results<br/>optional] PUB --> ISS[extract→dedup→render→post issues<br/>optional]
Cross-cutting data handling
- Read-only by default. The scanner and verifier never write to the target; the fixer writes only on a branch/worktree and is scoped to the finding.
- Trusted roots. The verifier reads only the supplied repo + pre-cloned
additional_repos; cross-repo references that don't resolve are recorded as unverifiable, not fetched. - Schema-validated contracts.
scan_manifest.schema.json(runtime → your automation) andverify_disposition.schema.json(verifier output), plus finding/fix-plan/result/triage schemas inside the fixer, are validated before write. - Secret handling in the runtime. Auth material is resolved at a single chokepoint
(
build_settings.py) and can be read from a broker token directory; URLs are redacted in logs (_url.py).