Visa Vulnerability Agentic Harness — Architecture Explainer

Agentic SAST pipeline · generated 2026-08-14

Reading level:

1 · What VVAH Is

The Visa Vulnerability Agentic Harness (VVAH) is an open-source tool that reads a software codebase and, using frontier AI models, automatically finds security vulnerabilities, proposes fixes, and then checks those fixes — producing an auditable report a human can review.

Explain-it-simply

Think of VVAH as an assembly line of AI security specialists. The code enters one end. Station by station, different specialists inspect it: one maps the building's doors and windows, one imagines how a burglar would break in, others examine locks, crypto, and access rules. A sceptic then tries to disprove each claimed weakness. Confirmed issues are written up; a repair crew drafts fixes; and a final inspector tries to break each repair before it is trusted. Every station is an AI "skill" that can be swapped or re-tuned without rebuilding the line.

VVAH grew out of Project Glasswing, Anthropic's initiative for AI-assisted vulnerability research. Its guiding insight: the bottleneck in AI security work is not finding possible issues — models surface many — but triaging them fast enough to act. VVAH is engineered around that constraint. Its headline metric is Mean Time to Adapt (MTTA): elapsed time from an AI-discovered weakness to a validated fix.

Three ideas that drive quality

  • Threat-model first. Understand the app's real attack surface before analysing code, so effort is focused where it matters.
  • Multi-agent voting. Run analysis several times and keep only findings that survive a majority vote — this suppresses false positives.
  • Structured triage artifacts. Emit machine-readable findings (SARIF), fixes (DTOs), and verdicts so the whole lifecycle is compressed and auditable.
11pipeline stages (S0–S11)
4swappable model backends
226Python modules (~46k LOC)

Two safety facts newcomers must know

1. A default scan edits your code. The shipped default profile runs past detection into Stage 10 fix mode, which modifies source files in the target repo. Use --stop-after s9 for detection only.

2. Data egress. Any role using a model backend sends prompt data (your code) to that provider's endpoint. Only scan code you are authorised to process.

2 · Who Should Read What

This explainer is layered so different newcomers can enter at the right depth.

ReaderStart withThen
Non-technical (PM, analyst, manager) §1 What VVAH Is · §3 The Pipeline, step by step The "Explain-it-simply" boxes and the context diagram in §4
Security analyst §3 Pipeline · §5 Remediation & Validation Per-module Markdown docs; inputs (CVE/controls/CMDB)
Junior developer §4 Data Flow · §6 Module Map Low-Level Design + per-file Markdown reference
Reviewer / architect §6 Module Map · §7 Backends HLD / LLD documents and the CodeGraph module graph

3 · The Pipeline, Step by Step

VVAH works in four phases spanning eleven stages. Detection (S0–S9) never changes your code; remediation and validation (S10–S11) can.

Phase 1 — Discovery & Modelling (S1–S3)

Survey the building, then think like an attacker and draw up a hunting plan.

Technically: S1 explores the repo and builds a call graph (ContextPackage); S2 produces a STRIDE/OWASP threat model; S3 decomposes the work into prioritised analysis "chunks" (TaskManifest).

Phase 2 — Deep Dive & Verification (S4–S6)

Specialists inspect each area; a sceptic then tries to disprove every claimed flaw.

Technically: S4 runs specialist "lenses" per chunk (optionally N times + vote); S5 applies deterministic confidence/evidence gates; S6 runs adversarial verification and assigns CVSS.

Phase 3 — Synthesis & Reporting (S7–S9)

Merge duplicates, connect issues into attack chains, and write the report.

Technically: S7 deduplicates (deterministic + semantic); S8 builds exploit chains and re-ranks into a FinalReport; S9 emits SARIF 2.1.0.

Phase 4 — Remediation & Validation (S10–S11)

A repair crew drafts a minimal fix per issue; an inspector panel tries to break each fix before it is trusted.

Technically: S10 proposes (and in fix mode applies) a patch and writes a per-finding DTO; S11 runs an adversarial panel (security-architect + penetration-tester, plus a cross-repo analyzer when needed) that scores each fix against weighted gates and records a verdict.

Every stage checkpoints to a SQLite state DB kept outside the scanned repo, so --resume reuses completed work.

3b · Interactive Pipeline Explorer

Click any stage to see what it takes in, what it produces, and which AI skill (if any) runs it. Use the Simple / Technical switch at the top to change the depth of every description on this page.

4 · Data Flow

The two diagrams below trace what actually moves through the system. Each arrow is labelled with the data artifact handed to the next stage — this is the single most useful mental model for a newcomer.

Context diagram (who talks to VVAH)

Context VVAH — Context Diagram (DFD Level 0) op Security Operator (authorized) vvah VVAH Agentic SAST Harness op->vvah scan/remediate/validate cmd + config prov Model Provider (Anthropic / OpenAI / gateway) vvah->prov prompt data (egress) tgt Target Codebase (owned / authorized) vvah->tgt fixes (S10 fix mode) arts Findings, SARIF, Fixes, Verdicts vvah->arts reports prov->vvah model reasoning tgt->vvah source, CVE, controls, CMDB arts->op review

Detection data flow (S0 → S9)

VVAH_DFD VVAH — Detection Data-Flow (S0→S9)  ·  data artifact on each arrow repo Target repo (+ CVE/controls/cmdb) s0 S0 Seed repo->s0 source/sink seed s1 S1 Preprocess s0->s1 callgraph seed s2 S2 ThreatModel s1->s2 ContextPackage s3 S3 Decompose s2->s3 ThreatModel s4 S4 DeepDive s3->s4 TaskManifest (chunks) s5 S5 Prefilter s4->s5 Finding[] (+vote) s6 S6 Verify s5->s6 gated Finding[] s7 S7 Dedup s6->s7 TRUE/FP + CVSS s8 S8 Chain s7->s8 canonical Finding[] s9 S9 SARIF s8->s9 FinalReport (md) out report.md + report.sarif s9->out parse md → SARIF

Explain-it-simply

Think of a document moving through an office. It starts as loose pages (raw code), someone files it into a labelled folder (a map), a manager marks the risky bits (threat model), a to-do list is stapled on (chunks), specialists add sticky notes (findings), a checker crosses out the wrong ones, and finally it's bound into a report. Each desk only ever hands the next desk a tidier version of the same document.

Key artifacts, in order: seed → ContextPackage → ThreatModel → TaskManifest → Finding[] → verified findings + CVSS → canonical findings → FinalReport → report.md + report.sarif.

5 · System Architecture (HLD)

The high-level design: inputs on the left, the CLI and orchestrator driving the pipeline, model backends off to the side, and structured artifacts out the bottom.

VVAH_Architecture VVAH — System Architecture (High-Level Design) cluster_in Inputs (untrusted target + operator context) cluster_pipe Detection Pipeline  (S0–S9) cluster_out Outputs repo Target repo / batch CSV cli CLI  (cli.py) setup · doctor · estimate · scan · remediate · validate · gc repo->cli ctx known_cves.json design_controls.yaml cmdb.csv ctx->cli hints validator_hints.yaml remediation_policy/playbook hints->cli orch Orchestrator scan · batch · preflight · checkpoints · SQLite state store cli->orch s0 S0 static seed (tree-sitter callgraph) orch->s0 report Report / enrich CVSS · CWE · redaction · SARIF orch->report state / manifest s19 S1 preprocess → S2 threatmodel → S3 decompose S4 deepdive → S5 prefilter → S6 verify S7 dedup → S8 chain → S9 SARIF s0->s19 post Post-scan agents S10 Remediation · S11 Validation panel s19->post backends Backends (LLM transport) cli · sdk · openai · deepagents s19->backends model calls s19->report post->backends post->report dtos remediation DTOs validation verdicts post->dtos md report.md report->md sarif report.sarif (2.1.0) report->sarif

The seven layers

LayerPackageResponsibility
Entrycli.pyCommands: setup · doctor · estimate · scan · remediate · validate · gc
Controlorchestrator/Drives the run, batch cloning, preflight, checkpoints, SQLite state store
Analysispipeline/The S0–S9 detection stages + tree-sitter call-graph engine
Post-scanremediation_agent/, validation/S10 fixes and S11 adversarial validation
Transportbackends/LLM dispatch across cli · sdk · openai · deepagents
Reportingreport/CVSS/CWE enrichment, CMDB scoring, secret redaction, SARIF
Supportmodels.py, config/, lang/, rules/, util/, injectors/Data contracts, config, language hints, rule packs, utilities, context loaders

Explain-it-simply

The orchestrator is the shift manager; the pipeline is the assembly line; the backends are the phone lines to the AI specialists; and report is the print shop that formats and redacts the final paperwork.

5b · Technology Stack

What the harness is actually built from, and why each piece is there.

Explain-it-simply

The whole thing is a Python program. It reads code with a fast parser (tree-sitter), makes phone calls to AI models through several connectors, keeps a little notebook (a SQLite file) so it can pause and resume, and writes its results in standard security formats other tools understand.

LayerTechnologyWhy it's used
Language / runtimePython ≥ 3.11The whole harness. Installed as one command, vvaharness (via pip or pipx).
Static analysistree-sitter + tree-sitter-language-packFast, language-aware parsing that builds the call graph and traces untrusted data (Python, Java, C#, JS/TS, Go).
AI transport — AnthropicAnthropic Python SDK · Claude Agent SDK · claude CLIThree ways to talk to Claude: raw API, the tool-using Agent SDK (used for applying fixes), and the local CLI (the detection default).
AI transport — othersOpenAI-compatible Chat Completions · DeepAgents / LangGraphLets any OpenAI-compatible model run detection, and powers the post-scan remediation/validation agents.
State & resumeSQLitePer-stage checkpoints kept outside the scanned repo, so runs resume with --resume and prune with gc.
Data contractsPydantic (models.py)Typed objects (Finding, ThreatModel, FinalReport…) passed between stages — the pipeline's "type system".
ConfigYAML profiles + .envFour shipped profiles; secrets via environment variables, never in the config file.
Output standardsSARIF 2.1.0 · CVSS 3.1 · CWEIndustry formats: machine-readable findings (SARIF), severity scores (CVSS), and the weakness taxonomy (CWE).
Security toolingLuhn/IIN & SSN redaction · policy gatesMasks secrets/PII at the write boundary; deterministic gates constrain what the fix agent may edit.

This documentation set was itself built with two local code-intelligence tools — CodeGraph and Graphify — plus Graphviz for the diagrams (see §9).

6 · Remediation & Validation

Phase 4 is where VVAH goes beyond detection. It is also the part that edits code, so it is deliberately gated.

RemVal VVAH — Remediation (S10) & Validation (S11) Flow find Verified findings (security-scan/) sel Select top-N by CVSS find->sel rem S10 Remediation Agent playbook → minimal fix sel->rem gate Policy gate (deny/allow, forbidden paths, diff post-gate, kill-switch) rem->gate gate->rem revert forbidden dto DTO per finding remediate_report.json (+ diff.patch, triage.json) gate->dto disc S11 discover (no model spend) dto->disc panel S11 Adversarial Panel security-architect + penetration-tester (+cross-repo-analyzer) disc->panel synth Gate synthesis (host consensus) panel->synth verd Verdict validated / validation_failed / needs_review synth->verd

Remediation (S10)

For each verified finding, the Remediation Agent selects a fix strategy from a per-CWE/language/framework playbook, proposes a minimal patch, and writes a per-finding DTO (remediate_report.json + diff + triage). A deterministic policy gate enforces allow/deny CWE maps and forbidden-path globs, reverts edits to forbidden paths, and honours an emergency kill-switch. Bash is intentionally never granted — a prompt-injected agent with a shell would be RCE on the scanner host.

Validation (S11)

A read-only adversarial panel grades each fix: security-architect checks root-cause coverage, penetration-tester tries to bypass the fix (armed with per-CWE bypass cheatsheets), and a cross-repo-analyzer joins only when a fix spans 2+ repos. Per-gate results are synthesised by a conservative majority rule and re-scored deterministically into a verdict: validated, validation_failed, or needs_review. If consensus can't be persisted, it fails closed to needs_review.

Explain-it-simply

The repair crew fixes a lock, then a separate inspection team tries to pick it. The inspectors can look but never touch. If two of them agree it's broken — or if they can't reach a clear conclusion — the repair is sent back rather than trusted. "When unsure, don't ship" is built in.

7 · Module Map (LLD entry point)

This dependency graph is generated directly from the code by CodeGraph (calls + imports + references, aggregated to the package level, weight ≥ 3). It is the fastest way to see how the codebase actually hangs together.

Modules VVAH - Module Dependency Graph (CodeGraph: calls+imports+refs, weight>=3) vvaharness core (cli/models) vvaharness/backends backends vvaharness->vvaharness/backends 5 vvaharness/orchestrator orchestrator vvaharness->vvaharness/orchestrator 8 vvaharness/remediation_agent remediation_agent vvaharness->vvaharness/remediation_agent 4 vvaharness/report report vvaharness->vvaharness/report 3 vvaharness/backends->vvaharness/remediation_agent 5 vvaharness/backends->vvaharness/report 25 vvaharness/util util vvaharness/backends->vvaharness/util 39 vvaharness/config config vvaharness/injectors injectors vvaharness/injectors->vvaharness 4 vvaharness/lang lang vvaharness/pipeline pipeline vvaharness/lang->vvaharness/pipeline 20 vvaharness/lang->vvaharness/util 6 vvaharness/orchestrator->vvaharness 18 vvaharness/orchestrator->vvaharness/backends 22 vvaharness/orchestrator->vvaharness/config 4 vvaharness/orchestrator->vvaharness/injectors 6 vvaharness/orchestrator->vvaharness/remediation_agent 11 vvaharness/orchestrator->vvaharness/report 11 vvaharness/orchestrator->vvaharness/util 47 vvaharness/pipeline->vvaharness 180 vvaharness/pipeline->vvaharness/backends 46 vvaharness/pipeline->vvaharness/lang 25 vvaharness/pipeline->vvaharness/remediation_agent 4 vvaharness/pipeline->vvaharness/report 24 vvaharness/rules rules vvaharness/pipeline->vvaharness/rules 12 vvaharness/pipeline->vvaharness/util 69 vvaharness/remediation_agent->vvaharness/backends 23 vvaharness/remediation_agent->vvaharness/config 3 vvaharness/remediation_agent->vvaharness/orchestrator 14 vvaharness/remediation_agent->vvaharness/report 20 vvaharness/remediation_agent->vvaharness/util 19 vvaharness/report->vvaharness/util 7 vvaharness/rules->vvaharness/backends 7 vvaharness/rules->vvaharness/pipeline 15 vvaharness/rules->vvaharness/util 3 vvaharness/util->vvaharness 7 vvaharness/util->vvaharness/remediation_agent 4 vvaharness/util->vvaharness/report 12 vvaharness/validation validation vvaharness/util->vvaharness/validation 6 vvaharness/validation->vvaharness/backends 45 vvaharness/validation->vvaharness/config 3 vvaharness/validation->vvaharness/orchestrator 7 vvaharness/validation->vvaharness/pipeline 6 vvaharness/validation->vvaharness/remediation_agent 5 vvaharness/validation->vvaharness/report 14 vvaharness/validation->vvaharness/util 4

Explain-it-simply

This is an org chart for the code. The boxes are departments; an arrow means "this department relies on that one". The busiest box in the middle — pipeline — is the department everyone supports, just like operations in a real company.

The pipeline package is the hub. It leans on models.py for data contracts, backends for model calls, lang/rules for language and rule knowledge, report for output, and util for plumbing. orchestrator sits above the pipeline; validation and remediation_agent depend on backends and report. For per-file detail see the Markdown module docs under docs/modules/.

7b · Module Flow Explorer (click a box)

The codebase in one screen. Each box is a module; arrows show the direction of flow. Click any box to expand its input, output, responsibility, and dependencies. Boxes are grouped by layer, top to bottom, following how a run actually moves. (Expansion is built with native HTML, so it works even where scripts are disabled.)

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)

8 · Backends — one line, four transports

Every AI-driven stage is a configuration switch. A role picks {id, via} and the dispatcher (backends/llm.py) routes on via:. Swapping a model or provider is config-only — no code change.

Backends VVAH — Backend Routing (backends/llm.py dispatches on via:) disp llm.py dispatcher (reads role {id, via}) cli via: cli claude_cli.py (subprocess, native tools) disp->cli sdk via: sdk sdk.py (Anthropic SDK) + localtools sandbox disp->sdk oai via: openai oai.py (Chat Completions) + localtools sandbox disp->oai da via: deepagents harness/deepagents (LangGraph) disp->da det Detection S1–S9 det->cli det->sdk det->oai det->da rejected s10 S10 remediate (fix: Edit/Write) s10->cli s10->sdk s10->oai report-only s10->da s11 S11 validate (read-only panel) s11->cli s11->sdk s11->oai → deepagents s11->da
via:TransportUsed forNotes
clilocal claude CLIDetection default (S1–S9)Native tools; Bash only if explicitly listed
sdkAnthropic Python SDKDetection; S10 fixSandboxed Read/Glob/Grep; enables S4 voting; mTLS
openaiOpenAI-compatibleDetection; report-only remediationCannot edit files; validation is routed to deepagents
deepagentsDeepAgents / LangGraphS10 / S11 defaultRepo-confined FS for fixes; read-only agents for validation

Guardrail: deepagents is rejected for detection roles; a mixed-vendor validation panel is refused at startup before any spend.

Explain-it-simply

Same job, different phone line. Whether you dial the local assistant, the cloud service, or the specialist agency, the request is the same — the switchboard just decides who picks up and what they're allowed to touch (some lines can only read; only the repair line can write).

8b · DeepAgents — the S10/S11 runtime, in detail

Two of the eleven stages — S10 Remediate and S11 Validate — run on a different engine from the rest of the pipeline: DeepAgents, a runtime built on LangGraph. This section explains what that means and exactly what it is and isn't allowed to do.

Explain-it-simply

S1–S9 use a lighter-weight assistant that answers one question at a time. S10 and S11 need something closer to a project worker: an agent that can plan several steps, use tools in a loop, and — for the repair crew (S10) only — actually make an edit. DeepAgents is the engine that runs that worker safely: it decides which "who" (Anthropic or OpenAI) answers each request, keeps a hard cap on how long the worker can loop, and — critically — hands the repair crew a different, more permissive toolbelt than it hands the inspection panel. The repair crew (S10) can read and write files but never gets a shell. The inspection panel (S11) can only read — it never gets a pen.

Where it lives

Package: vvaharness/backends/harness/deepagents/ (client.py, options.py, limits.py, tools.py) plus vvaharness/backends/harness/registry.py, which is a separate dispatch layer from the via: router (backends/llm.py) that S1–S9 use. registry.get_harness(via) maps "cli"/"sdk" to a shared ClaudeHarness and "deepagents" to DeepAgentHarness — a session-oriented, streaming abstraction (run_oneshot / run_streaming), not the single-prompt prompt()/agentic() calls S1–S9 make.

How the model is actually chosen

options.py::build_model(model_id, env, provider) is the exact routing logic: if provider == "anthropic", or provider is unset and "claude" appears in model_id, it constructs a ChatAnthropic (langchain-anthropic); otherwise a ChatOpenAI (langchain-openai). This is what the provider: key in models.remediate / models.validate.orchestrator actually controls — it is not decorative. Validation's one-vendor-per-panel rule exists because every persona shares the orchestrator's via/provider; a persona pinned to a different vendor's model id is refused at startup (exit 2) before any spend.

S10 vs. S11 — same engine, different leash

S10 RemediateS11 Validate
Working directoryThe real target repo (cwd=repo) — edits land on diskA staged, pre-patched copy, removed on completion
ToolsRead/Glob/Grep + Write/Edit; Bash explicitly excluded (disallowed_tools=("Bash",))Read/Glob/Grep only, plus five deterministic read-only "fact tools" (DiffTouched, ChangedLines, DiffImpactMap, PatternScan, TestInventory)
Can it edit code?Yes — this is the only place in the whole pipeline that writes to the target repoNo — structurally incapable of it; there is no Write/Edit/Bash tool in its toolset at all
Loop budgetlimits.py::RECURSION_HEADROOM = 900 — extra LangGraph "supersteps" allowed beyond max_turns, so a long-but-legitimate tool loop isn't truncated mid-task. Shared by both stages.

Why it's a lazy import

registry.py::_make_deepagents() imports DeepAgentHarness inside the function body, not at module load. The deepagents package requires Python ≥ 3.11; a repo running 3.10 can still use via: cli/via: sdk for every other stage without ever hitting that requirement — the import only fires if a role actually selects via: deepagents.

In one sentence: DeepAgents is not "an LLM" — it's the LangGraph-based agent runtime that gives S10 and S11 multi-step, tool-using sessions, with the model vendor chosen per-role by provider, a shared loop-budget, and a toolset that is deliberately asymmetric — write access for the repair crew, read-only for the inspectors.

Full write-up with source references: LLD §9 — DeepAgents runtime mechanics · backends module doc · remediation_agent module doc · validation module doc.

9 · Graph Intelligence (how this was built)

The diagrams and module analysis on this page were produced by running two local, no-API-key code-intelligence tools over the repository. Their raw outputs ship alongside this page under tool-outputs/.

ToolWhat it producedOutput
CodeGraphSQLite knowledge graph — 5,992 nodes, 15,323 edges (228 classes, 2,846 functions, 276 methods across 336 files)tool-outputs/codegraph/ (+ module dependency JSON that powers §7)
GraphifyKnowledge graph — 5,112 nodes, 12,150 edges, 200 communities; interactive HTML + reporttool-outputs/graphify/graph.html, GRAPH_REPORT.md, graph.json

Readable interactive views (open these)

FileWhat it gives you
diagrams/module-graph.htmlThe 12-module flow; click a box to expand input/output/role.
tool-outputs/codeviz/vvah-codeviz.htmlFull drill-down: module → file → function, each with a plain note.
tool-outputs/codeviz/vvah-stage-explorer.htmlPipeline S0–S11 → implementing files → functions.
tool-outputs/graphify/labeled-clusters.htmlGraphify's 200 clusters, each given a human name (module + representative symbols) — the readable version of the raw "Community N" export.

Serena (LSP-based symbol tools) and grepai (semantic search) are designed to run inside your own AI client with local language servers / an embedding provider; a copy-paste setup guide is in docs/tools/graph-intelligence.md.