Data Flow (DFD)

Context diagram, the Hunt→Fix→Verify loop, and the two internal flows, at three levels of zoom.

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