A lightweight, readable view of the 12 modules (the full 5,112-node symbol graph is too dense to read). Click any box to expand it — no JavaScript required. For the module-dependency picture see diagrams/04_module_dependencies.svg; for a deeper per-file/per-function drill-down see tool-outputs/codeviz/vvah-codeviz.html.
CLI / core ▸in Operator command · .env credentials · config pathout A dispatched run · run_manifest.json
package: cli.py · models.py · manifest.py
The front door. Parses the command, loads credentials, checks Python, resolves config, and hands off to the orchestrator. Also defines the shared data contracts (models.py) every stage speaks.
What actually happens here
main() in cli.py is a hand-rolled dispatcher (not argparse subcommands) on args[0]: setup/init, doctor, estimate, gc, remediate, and anything matching VALIDATE_COMMANDS (validate/s11) each get their own handler; a bare scan (or no recognised keyword) falls through to orchestrator.main(). Every invocation is wrapped in manifest.capture(), which records the config hash, resolved roles, and the target's git SHA into run_manifest.json for later audit. _check_python() enforces the version floor before anything else runs, and _load_dotenv() loads .env relative to the target repo if one is given.
How the LLM / model version is chosen
CLI makes no model calls and picks no model. It reads models.<role> = {id, via} straight out of the resolved Config object and passes the whole object, unmodified, to whichever module owns that stage — orchestrator for S0–S9, remediation_agent for S10, validation for S11. Its only model-adjacent job is calling configure_backends(cfg, ...) so credentials/TLS are wired before doctor's live probe.
Deterministic (non-LLM) work in this module
Python-version floor check · argparse-free command dispatch on args[0] · config path resolution (--config → ./config.yaml → packaged default) · .env discovery relative to --repo · run_manifest capture (config hash + git SHA). Zero AI calls in this module itself.
Depends on: orchestrator, config
Orchestrator ▸in CLI command · resolved Configout Sequenced stages · SQLite checkpoints · final reports
package: orchestrator/
The shift manager. Preflights the backends, runs the pipeline stage by stage, checkpoints each so runs can resume, drives batch clones, and owns the state store.
What actually happens here
entry.py owns the full scan argument surface (--repo/--repo-file, --stop-after, --resume, --remediate, --top, --auto-step1, etc.) and is the actual home of the 'scan' verb the CLI delegates to. For each stage it checks the SQLite checkpoint store first (orchestrator/checkpoints.py) — a completed stage under --resume is skipped and its stored artifact reloaded instead of recalled. Batch mode (--repo-file) clones each repo (optionally grouped by --group-by-app) into --workspace and runs a fresh, isolated context per target. After S9 it hands off to remediation_agent (S10) and validation (S11) when enabled, and optionally loads cmdb.csv to enrich findings with environment-aware severity before the final report is written.
How the LLM / model version is chosen
Orchestrator itself never calls a model for analysis — that's every individual stage's job. Its one model-adjacent action is probe_backends(cfg) during doctor/preflight: a small, real call to each backend named in config.yaml to confirm the credential and endpoint actually work, separate from and prior to the token spend of a real scan.
Deterministic (non-LLM) work in this module
Preflight backend/credential checks · SQLite checkpoint read/write per stage (resume support) · batch clone + group-by-app sequencing · CMDB CSV load and join · run-level manifest assembly. All control flow; the AI reasoning happens one layer down, inside pipeline/remediation_agent/validation.
Depends on: pipeline, backends, util, report, remediation_agent, validation
Pipeline (S0–S9) ▸in Target repo (+ optional static seed)out FinalReport → report.md + report.sarif
package: pipeline/stages/ + callgraph_engine/
The assembly line. Nine detection stages plus the tree-sitter call-graph engine that traces untrusted data to dangerous operations.
What actually happens here
Each stage consumes the previous stage's typed artifact and produces the next: S1 builds a ContextPackage (repo map + call graph), S2 turns it into a ThreatModel, S3 decomposes that into a prioritised TaskManifest of analysis chunks, S4 deep-dives each chunk into candidate Finding[], S5 deterministically gates them, S6 adversarially verifies survivors and assigns CVSS, S7 deduplicates, S8 chains related findings into attack paths, S9 renders the FinalReport to Markdown and parses it into SARIF. S0 (optional, off by default) runs first and seeds S1 with source→sink taint paths from a pure static pass — no model call.
How the LLM / model version is chosen
Every LLM stage reads its own role from config.yaml — models.preprocess/threatmodel/decompose/deepdive/verify/dedup/chain — each a {id, via} pair, e.g. the shipped default profile sets deepdive: {id: claude-sonnet-4-6, via: cli}. `via` selects the transport (cli/sdk/openai/deepagents) at call time in backends/llm.py; `id` is passed through as the literal model string, unvalidated by this module. S4 additionally runs N independent passes on temperature-capable backends (sdk/openai) and keeps only findings that recur across passes (majority-vote FP filtering) — a resampling strategy, not a different model choice.
Deterministic (non-LLM) work in this module
S0 tree-sitter call-graph engine (source→sink taint tracing, no model) · S1 static repo/file walk + call-graph build · S5 confidence/evidence gating against fixed thresholds (a finding can be dropped here with zero model involvement) · S7 structural/text-similarity dedup · S9 Markdown→SARIF 2.1.0 parser. Five of the nine stages have a hard deterministic core wrapped around the AI reasoning, not just AI end to end.
Depends on: models, backends, lang, rules, report, util
Remediation (S10) ▸in Verified findings (security-scan/)out Per-finding DTOs (+ applied diffs in fix mode)
package: remediation_agent/
The repair crew. Proposes a minimal fix per finding from a playbook, applies it under a deterministic policy gate, and writes a DTO.
What actually happens here
remediate.py walks the findings from a prior scan's security-scan/ output (or the ones just produced in the same run), selects up to step_remediate.top_n_findings (or --top on the CLI) by descending CVSS, and for each one builds a prompt from remediation_playbook.yaml plus the finding's evidence. The model's proposed patch is then run through policy_gate/ before anything touches disk — forbidden paths, allow/deny rules, and a kill-switch can revert the edit even after the model proposed it. Every finding gets a DTO (remediate_report.json) recording the proposal, the gate decision, and (in fix mode) the applied diff, under <repo>/security-remediation/.
How the LLM / model version is chosen
models.remediate: {id: claude-opus-4-8, via: deepagents, provider: anthropic} in the shipped default profile — a single role, no persona split (unlike validate). `provider` picks which DeepAgents endpoint (openai Chat Completions or anthropic Messages) the deepagents backend actually calls; changing profiles (sdk.yaml/full.yaml) changes both id and via for this one role independently of every other stage.
Deterministic (non-LLM) work in this module
Playbook lookup by CWE (remediation_playbook.yaml) selects a fix pattern before the model is asked to write anything · the policy gate (policy_gate/) is pure rule evaluation — no model in that loop — enforcing forbidden paths and the kill-switch, and can revert a model-proposed edit outright · DTO assembly and diff capture are deterministic bookkeeping.
Depends on: backends, report, orchestrator, util
Validation (S11) ▸in Remediation DTOsout Verdicts: validated / validation_failed / needs_review
package: validation/
The inspection panel. A read-only adversarial panel grades each fix; scoring is deterministic given the synthesised gates.
What actually happens here
launcher.py stages a pre-patched copy of the repo (--workspace, refused if non-empty — must be ephemeral), confirms the remediation was actually applied, then runs three read-only personas — security_architect, penetration_tester, cross_repo_analyzer — plus an orchestrator persona that synthesises their input into a gate consensus. That synthesis happens host-side under via:deepagents or in-session under via:cli/sdk depending on profile. The result is re-scored deterministically and written back into the DTO's validation block; if consensus can't be reliably persisted, the outcome fails closed to needs_review rather than defaulting to validated.
How the LLM / model version is chosen
models.validate.orchestrator: {id: claude-opus-5, via: deepagents, provider: anthropic} in the default profile; the three personas inherit orchestrator's via and provider and may only override id — VVAH enforces ONE VENDOR PER PANEL at startup, so a gpt-* persona under an anthropic orchestrator is refused (exit 2) rather than silently mixing vendors mid-panel.
Deterministic (non-LLM) work in this module
Repo staging + fix-applied confirmation check (did the diff actually land, independent of any model opinion) · post-panel deterministic scoring/consensus synthesis · fail-closed rule: unpersisted consensus → needs_review, by rule, not by model judgement.
Depends on: backends, report, util
Backends ▸in A model request {id, via} + promptout Model response (sandboxed tools)
package: backends/ + harness/
The switchboard. Routes each role to cli / sdk / openai / deepagents and enforces per-route tool limits.
What actually happens here
llm.py's resolve() reads {id, via, temperature, thinking_budget, betas} off whatever role object it's handed and dispatches to the matching backend module (backends/cli.py subprocess, sdk.py Anthropic SDK, oai.py OpenAI-compatible, or the deepagents/harness path). It doesn't decide which model to use — every other module already decided that in config.yaml — it executes that decision and normalises the differences between backends (e.g. via:cli silently drops temperature/thinking_budget since the CLI has no such flags).
How the LLM / model version is chosen
This module IS the model-selection mechanism for the rest of the codebase: `via` (cli/sdk/openai/deepagents) chosen per-role in config.yaml determines which of the four backend implementations actually receives the prompt; `id` is passed through verbatim as the model string for that backend's API. There is no fallback or auto-selection — an unrecognised `via` raises immediately.
Deterministic (non-LLM) work in this module
Per-route tool allowlists (Read/Glob/Grep everywhere; Bash granted ONLY to via:cli roles that explicitly list it in allowed_tools) · TLS/base_url/api_key wiring from config · the sandboxed local Read/Glob/Grep tool-loop used by sdk/openai roles (no native Bash there) — all deterministic guardrails wrapped around the model call, not part of the reasoning itself.
Depends on: util, report
Report ▸in Findings Markdown (+ cmdb.csv)out Enriched report.md + report.sarif (redacted)
package: report/
The print shop. Adds CVSS/CWE/CMDB context, hides secrets at the write boundary, and emits SARIF.
What actually happens here
Takes the Markdown the pipeline already produced (S9's FinalReport) and post-processes it: joins CMDB (cmdb.csv, application-profile aware) to adjust severity for environment context, attaches CWE reference detail, redacts sensitive values as the file is written (not before — so nothing sensitive is ever held un-redacted in the output artifact longer than necessary), and parses the enriched Markdown into SARIF 2.1.0 for tool ingestion.
How the LLM / model version is chosen
None. This module makes zero model calls — it is pure deterministic post-processing of text an earlier LLM stage already generated.
Deterministic (non-LLM) work in this module
CVSS vector scoring · CWE taxonomy lookup · CMDB-aware severity adjustment · secret/PII redaction at the write boundary (Luhn+IIN-gated card numbers, SSNs, credential-shaped strings) · Markdown→SARIF 2.1.0 emission. The entire module is deterministic — it exists specifically so nothing sensitive or miscalibrated reaches report.md/report.sarif un-checked.
Depends on: util
lang ▸in Repo filesout Language hints + tree-sitter call graph
package: lang/
Language awareness — per-language researcher hints and specialist bodies used by S4/S6/S8.
What actually happens here
Supplies the per-language framing that makes S4's deep-dive and S6's verification prompts language-aware instead of generic — e.g. what a dangerous sink looks like in Java vs. Go vs. JS/TS — and drives the tree-sitter-language-pack parser used by the call-graph engine.
How the LLM / model version is chosen
No model calls of its own. It supplies context that other stages' prompts include; the model choice for those stages belongs to `pipeline`, not to lang.
Deterministic (non-LLM) work in this module
tree-sitter-language-pack parser selection by file extension (Python/Java/C#/JS/TS/Go) · static per-language hint/specialist-body lookup tables consumed as prompt context, not generated at run time.
Depends on: pipeline
rules ▸in External corpora (Semgrep/CodeQL/FindSecBugs)out CWE knowledge base / rule packs
package: rules/
The security knowledge base — first-party CWE knowledge plus a compiler for external rule sets.
What actually happens here
A static reference layer: first-party CWE descriptions and a compiler that ingests external rule corpora (Semgrep, CodeQL, FindSecBugs rule packs) into a common internal format. S4/S6 prompts pull from this as grounding material so the model isn't reasoning about CWE categories from parametric memory alone.
How the LLM / model version is chosen
No model calls — this module produces reference data consumed by other stages' prompts, it never itself talks to a model.
Deterministic (non-LLM) work in this module
Corpus ingestion/compilation into a common rule-pack format · CWE ID → description lookup. Entirely deterministic; refreshed by re-running the compiler, not by any AI process.
Depends on: pipeline
util ▸in Pipeline events · model usageout Metrics · token counts · errors.jsonl · progress
package: util/
Shared plumbing — environment checks, token/metrics accounting, JSON extraction, prompts, progress, error log.
What actually happens here
The shared substrate every other module calls into: environment.py's run_checks()/summarize() power both `setup` and `doctor` (one engine, two callers, so their output never drifts apart); tokens.py/metrics.py bucket usage per stage against per-stage and per-finding cost caps; errlog.py appends non-fatal errors to *_errors.jsonl instead of aborting a whole run over one recoverable failure.
How the LLM / model version is chosen
No model calls — util is instrumentation and plumbing around every other module's model calls, not a caller itself.
Deterministic (non-LLM) work in this module
Token/cost accounting bucketed per stage against config-defined caps · shared credential/backend readiness checks (env.run_checks) · JSON extraction from raw LLM text output · progress reporting · non-fatal error log. All deterministic; this is the module that makes the AI stages auditable and boundable.
Depends on: report
injectors ▸in known_cves.json · design_controls.yamlout CVE[] · Control[] (optional context)
package: injectors/
Optional context loaders that steer the threat model (S2) and verification (S6).
What actually happens here
Purely optional: if known_cves.json is supplied, S2's threat model treats matching components as higher-likelihood targets; if design_controls.yaml is supplied, S6's verification downranks exploitability for findings that a documented compensating control already covers. Absent either file, these stages proceed on code evidence alone.
How the LLM / model version is chosen
No model calls — injectors only loads and validates operator-supplied files into typed objects that later prompts include as context.
Deterministic (non-LLM) work in this module
JSON/YAML parsing and schema validation into typed CVE[]/Control[] objects. Pure file I/O; the only AI involvement is downstream, in how S2/S6 weigh this context inside their own prompts.
Depends on: pipeline
config ▸in Profile + config.local.yaml + ${ENV}out A merged Config object
package: config/
The settings reader — resolves and deep-merges the profile, expands env placeholders, applies overlays.
What actually happens here
Resolves the profile in a fixed order (--config → ./config.yaml → packaged default.yaml), deep-merges an optional config.local.yaml on top, expands ${ENV} placeholders (so secrets never live in the YAML itself), and applies step1 overlays. Critically, it refuses a config.yaml found INSIDE the repo being scanned — falling back to the packaged default — since the scanned repo is untrusted input and a committed config must not be able to redirect model endpoints or credentials.
How the LLM / model version is chosen
config doesn't call a model — it's the module that PRODUCES every models.<role>: {id, via, provider, temperature, ...} object that every other module in this diagram reads. Changing which model version or backend a stage uses always means editing this layer (a profile YAML), never code.
Deterministic (non-LLM) work in this module
Profile resolution order · config.local.yaml deep-merge · ${ENV} placeholder expansion · step1 overlay application · the untrusted-input trust-boundary check (config found inside the scan target is refused, not merged). 100% deterministic — this module has no AI surface at all.
Depends on: (all)