Design · Visa Vulnerability Agentic Harness (VVAH)

High-Level Design (HLD)

↩ architecture.html · generated 2026-08-14

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 (which models.<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.

flowchart TB IN["Inputs<br/>repo · CVE · controls · CMDB"] --> CLI["CLI (cli.py)"] CLI --> ORCH["Orchestrator<br/>scan · batch · preflight · state store"] ORCH --> PIPE["Detection Pipeline S0–S9"] PIPE --> POST["Post-scan agents<br/>S10 Remediate · S11 Validate"] PIPE <--> BK["Backends<br/>cli · sdk · openai · deepagents"] POST <--> BK PIPE --> REP["Report / enrich<br/>CVSS · CWE · redact · SARIF"] POST --> REP REP --> OUT["report.md · report.sarif · DTOs · verdicts"] ORCH -. state/manifest .-> REP

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

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)

5. Quality mechanisms

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.