High-Level Design (HLD)
Companion diagram:
diagrams/01_architecture.svg. Interactive version:architecture.html— click any module box in §7 "Module Flow" there for a full paragraph per module: what actually happens, exactly how its LLM model/version is chosen (whichmodels.<role>config key,id/via/provider), and which parts of it are deterministic (no model call) vs. AI-driven.
Visa Vulnerability Agentic Harness (VVAH) is a command-line application. You run one command (vvaharness) and hand it a
codebase. Internally it behaves like a factory: a shift manager (the orchestrator)
feeds the code into an assembly line (the pipeline) of AI stages, using phone lines
to AI specialists (the backends). A print shop (the report layer) formats and
redacts the results into paperwork you can act on. Everything is coordinated so a run can
pause and resume, and so nothing sensitive leaks into the final documents.
1. Components and responsibilities
| # | Component | Package | Responsibility |
|---|---|---|---|
| 1 | Entry / CLI | cli.py, __main__.py |
Parse commands, load .env, check Python floor, resolve --config, dispatch. |
| 2 | Orchestrator | orchestrator/ |
Single-repo and batch drivers, preflight backend checks, checkpointing, SQLite state store, CMDB load, finding enrichment. |
| 3 | Detection pipeline | pipeline/stages/ |
The S0–S9 analysis stages plus the tree-sitter call-graph engine. |
| 4 | Remediation agent | remediation_agent/ |
Stage 10 — propose/apply a minimal fix per finding; policy gate; per-finding DTOs. |
| 5 | Validation | validation/ |
Stage 11 — adversarial panel, deterministic scoring, verdict write-back. |
| 6 | Backends | backends/ |
Two dispatch layers: llm.py routes S1–S9's single-call prompt()/agentic() on via:; backends/harness/ is the session-oriented abstraction S10/S11 use, including the DeepAgents/LangGraph runtime (§6). |
| 7 | Report | report/ |
CVSS/CWE enrichment, CMDB-aware scoring, secret/PII redaction, SARIF emission. |
| 8 | Support libs | models.py, config/, lang/, rules/, util/, injectors/, manifest.py, agentdoc.py |
Data contracts, config loading, language hints, rule packs, utilities, optional context loaders, run manifest, agent-instruction docs. |
2. Technology stack
- Language / runtime: Python ≥ 3.11.
- Static analysis:
tree-sitter+tree-sitter-language-pack(Python/Java/C#/ JS/TS/Go parsers) for the S0/S1 call-graph and taint seeding. - AI transports: Anthropic Python SDK, Claude Agent SDK,
claudeCLI subprocess, OpenAI-compatible Chat Completions, and DeepAgents/LangGraph. - State: SQLite (checkpoints/resume), kept outside the scanned repo.
- Output formats: Markdown + SARIF 2.1.0; CVSS 3.1; CWE taxonomy.
3. Run / deployment model
VVAH is installed as a single command (pip install . or pipx install .) and runs
locally or in CI. A run resolves config in this order: --config → ./config.yaml →
packaged default.yaml, with an optional config.local.yaml deep-merge. Four shipped
profiles trade off backends and credentials:
| Profile | Backends | Use when |
|---|---|---|
default.yaml |
S0 local; S1–S9 cli; S10/S11 deepagents (Anthropic) |
The built-in default (mixed backend). |
sdk.yaml |
all roles sdk |
You want S4 majority voting on one API key. |
full.yaml |
mixed cli + sdk + openai |
Template for spreading roles across backends. |
taint.yaml |
S0 on; S1–S9 cli; S10/S11 disabled |
Taint-first source→sink scanning. |
State lives in $VVAHARNESS_STATE_DIR/vvaharness.db (default ~/.vvaharness/state/).
--resume reuses completed stages; gc prunes old runs.
4. Trust boundaries & security posture (design-level)
- The scanned repo is untrusted input. A
config.yamlor.envlocated inside the target is refused (falls back to packaged default) so a committed config cannot redirect model endpoints or credentials. - No
Bashin post-scan agents. The remediation/validation tool set is Read/Glob/Grep(/Edit/Write) — a shell is intentionally never granted, because a prompt-injected agent with a host shell would be RCE on the scanner. - Redaction at the write boundary. Card numbers (Luhn+IIN gated), SSNs, and credential material are masked as reports are written to MD/SARIF.
- Least privilege by backend. OpenAI-compatible detection/remediation is sandboxed to read-only tools; fix mode requires a write-capable backend; validation agents are read-only and write only their own artifacts.
- Elevated privilege warning. VVAH must only be run by authorised operators against trusted repositories.
5. Quality mechanisms
- Deterministic + AI hybrid at every stage: deterministic gates (S5), deterministic dedup pass (S7), deterministic SARIF (S9), deterministic scoring (S11) bracket the AI reasoning.
- Majority voting (S4) on temperature-capable backends.
- Adversarial verification (S6) and adversarial validation (S11).
- Checkpointing for reproducibility and cost control;
run_manifest.jsonrecords tool version, roles, config hashes, and target git SHA for auditability.
6. DeepAgents — the S10/S11 runtime
S10 (Remediate) and S11 (Validate) run on a different engine from S1–S9. Where detection calls a model once per question, remediation and validation need an agent that plans several steps and uses tools in a loop — so those two stages run on DeepAgents, a runtime built on LangGraph.
In plain terms: think of S1–S9 as consulting a specialist who answers one question at a time, and S10/S11 as handing the job to a project worker who can take several actions in sequence. DeepAgents is the engine running that worker — it picks which vendor (Anthropic or OpenAI) answers each request, caps how long the worker may loop, and — this is the important part — gives the repair crew (S10) a different, more permissive toolset than it gives the inspection panel (S11): S10 can read and write files (never a shell); S11 can only read.
This is a second, separate dispatch layer from the via: router (backends/llm.py)
that S1–S9 use — backends/harness/registry.py maps via: cli/via: sdk to a shared
Claude-session harness and via: deepagents to the LangGraph-based harness, and only S10/S11
roles are ever routed here. See LLD §9 for the exact
model-routing logic, the S10-vs-S11 permission table, and the loop-budget mechanism.
See LLD for cross-cutting internals and data-flow for the artifact-by-artifact flow.