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.
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.
| Reader | Start with | Then |
|---|---|---|
| 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)
Detection data flow (S0 → S9)
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.
The seven layers
| Layer | Package | Responsibility |
|---|---|---|
| Entry | cli.py | Commands: setup · doctor · estimate · scan · remediate · validate · gc |
| Control | orchestrator/ | Drives the run, batch cloning, preflight, checkpoints, SQLite state store |
| Analysis | pipeline/ | The S0–S9 detection stages + tree-sitter call-graph engine |
| Post-scan | remediation_agent/, validation/ | S10 fixes and S11 adversarial validation |
| Transport | backends/ | LLM dispatch across cli · sdk · openai · deepagents |
| Reporting | report/ | CVSS/CWE enrichment, CMDB scoring, secret redaction, SARIF |
| Support | models.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.
| Layer | Technology | Why it's used |
|---|---|---|
| Language / runtime | Python ≥ 3.11 | The whole harness. Installed as one command, vvaharness (via pip or pipx). |
| Static analysis | tree-sitter + tree-sitter-language-pack | Fast, language-aware parsing that builds the call graph and traces untrusted data (Python, Java, C#, JS/TS, Go). |
| AI transport — Anthropic | Anthropic Python SDK · Claude Agent SDK · claude CLI | Three 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 — others | OpenAI-compatible Chat Completions · DeepAgents / LangGraph | Lets any OpenAI-compatible model run detection, and powers the post-scan remediation/validation agents. |
| State & resume | SQLite | Per-stage checkpoints kept outside the scanned repo, so runs resume with --resume and prune with gc. |
| Data contracts | Pydantic (models.py) | Typed objects (Finding, ThreatModel, FinalReport…) passed between stages — the pipeline's "type system". |
| Config | YAML profiles + .env | Four shipped profiles; secrets via environment variables, never in the config file. |
| Output standards | SARIF 2.1.0 · CVSS 3.1 · CWE | Industry formats: machine-readable findings (SARIF), severity scores (CVSS), and the weakness taxonomy (CWE). |
| Security tooling | Luhn/IIN & SSN redaction · policy gates | Masks 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.
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.
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.)
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)
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.
via: | Transport | Used for | Notes |
|---|---|---|---|
cli | local claude CLI | Detection default (S1–S9) | Native tools; Bash only if explicitly listed |
sdk | Anthropic Python SDK | Detection; S10 fix | Sandboxed Read/Glob/Grep; enables S4 voting; mTLS |
openai | OpenAI-compatible | Detection; report-only remediation | Cannot edit files; validation is routed to deepagents |
deepagents | DeepAgents / LangGraph | S10 / S11 default | Repo-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 Remediate | S11 Validate | |
|---|---|---|
| Working directory | The real target repo (cwd=repo) — edits land on disk | A staged, pre-patched copy, removed on completion |
| Tools | Read/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 repo | No — structurally incapable of it; there is no Write/Edit/Bash tool in its toolset at all |
| Loop budget | limits.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/.
| Tool | What it produced | Output |
|---|---|---|
| CodeGraph | SQLite 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) |
| Graphify | Knowledge graph — 5,112 nodes, 12,150 edges, 200 communities; interactive HTML + report | tool-outputs/graphify/graph.html, GRAPH_REPORT.md, graph.json |
Readable interactive views (open these)
| File | What it gives you |
|---|---|
diagrams/module-graph.html | The 12-module flow; click a box to expand input/output/role. |
tool-outputs/codeviz/vvah-codeviz.html | Full drill-down: module → file → function, each with a plain note. |
tool-outputs/codeviz/vvah-stage-explorer.html | Pipeline S0–S11 → implementing files → functions. |
tool-outputs/graphify/labeled-clusters.html | Graphify'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.