Visa Vulnerability Agentic Harness (VVAH) — Interactive Module Graph

A clean, self-contained view of the 12 modules and how a run flows through them. Click any box to expand its input, output and details.

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.

1 · Entry
CLI / core ▸in Operator command · .env credentials · config pathout A dispatched run · run_manifest.jsonclick to expand

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.

InputOperator command · .env credentials · config path
OutputA dispatched run · run_manifest.json
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

▼
2 · Control
Orchestrator ▸in CLI command · resolved Configout Sequenced stages · SQLite checkpoints · final reportsclick to expand

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.

InputCLI command · resolved Config
OutputSequenced stages · SQLite checkpoints · final reports
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

▼
3 · Analysis
Pipeline (S0–S9) ▸in Target repo (+ optional static seed)out FinalReport → report.md + report.sarifclick to expand

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.

InputTarget repo (+ optional static seed)
OutputFinalReport → report.md + report.sarif
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

▼
4 · Post-scan
Remediation (S10) ▸in Verified findings (security-scan/)out Per-finding DTOs (+ applied diffs in fix mode)click to expand

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.

InputVerified findings (security-scan/)
OutputPer-finding DTOs (+ applied diffs in fix mode)
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_reviewclick to expand

package: validation/

The inspection panel. A read-only adversarial panel grades each fix; scoring is deterministic given the synthesised gates.

InputRemediation DTOs
OutputVerdicts: validated / validation_failed / needs_review
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

▼
5 · Transport
Backends ▸in A model request {id, via} + promptout Model response (sandboxed tools)click to expand

package: backends/ + harness/

The switchboard. Routes each role to cli / sdk / openai / deepagents and enforces per-route tool limits.

InputA model request {id, via} + prompt
OutputModel response (sandboxed tools)
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

▼
6 · Reporting
Report ▸in Findings Markdown (+ cmdb.csv)out Enriched report.md + report.sarif (redacted)click to expand

package: report/

The print shop. Adds CVSS/CWE/CMDB context, hides secrets at the write boundary, and emits SARIF.

InputFindings Markdown (+ cmdb.csv)
OutputEnriched report.md + report.sarif (redacted)
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

▼
7 · Support
lang ▸in Repo filesout Language hints + tree-sitter call graphclick to expand

package: lang/

Language awareness — per-language researcher hints and specialist bodies used by S4/S6/S8.

InputRepo files
OutputLanguage hints + tree-sitter call graph
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 packsclick to expand

package: rules/

The security knowledge base — first-party CWE knowledge plus a compiler for external rule sets.

InputExternal corpora (Semgrep/CodeQL/FindSecBugs)
OutputCWE knowledge base / rule packs
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 · progressclick to expand

package: util/

Shared plumbing — environment checks, token/metrics accounting, JSON extraction, prompts, progress, error log.

InputPipeline events · model usage
OutputMetrics · token counts · errors.jsonl · progress
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)click to expand

package: injectors/

Optional context loaders that steer the threat model (S2) and verification (S6).

Inputknown_cves.json · design_controls.yaml
OutputCVE[] · Control[] (optional context)
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 objectclick to expand

package: config/

The settings reader — resolves and deep-merges the profile, expands env placeholders, applies overlays.

InputProfile + config.local.yaml + ${ENV}
OutputA merged Config object
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)