Design · Visa Vulnerability Agentic Harness (VVAH)

Low-Level Design (LLD)

↩ architecture.html · generated 2026-08-14

Low-Level Design (LLD)

This document covers the cross-cutting internals — the mechanisms that many stages share. Per-module and per-file internals live in the module docs.

Companion: diagrams/04_module_dependencies.svg (generated from CodeGraph), 05_backend_routing.svg.

1. Data contracts (vvaharness/models.py, ~1,850 LOC)

A single Pydantic module defines the objects passed between stages. This is the "type system" of the pipeline — read it first when tracing data.

Core contracts: CVE, Control, AppProfile, Asset, TrustBoundary, Threat, ThreatModel, EntryPoint, Sink, ModuleInfo, ContextPackage, Chunk, TaskManifest, Finding, Severity, Chain, RankedFinding, DroppedFinding, ScanMetrics, FinalReport.

Taint sub-model (populated by the call-graph engine): TaintSymbolRef, TaintTransferEdge, TaintEvidencePath, CFGNode, CFG, ConditionTaintEdge, ReflectionFact, ReflectionTaintEdge, FrameworkMarkerFact, RouteTaintFact, ResponseDataflowFact, FrameworkTaintEdge. (The CFG/ConditionTaintEdge types are reserved schema for future branch-sensitive analysis; the current scanner does not populate a branch CFG.)

Helpers coerce loose model output into typed contracts (_coerce_enum, _coerce_int, _coerce_confidence) and render Markdown safely (_md_cell, _demote_md_headings).

2. Config resolution (vvaharness/config/__init__.py)

Config.load resolves the active file (--config → ./config.yaml → packaged default), deep-merges an optional config.local.yaml, and expands ${ENV:-default} placeholders (_expand_env, _expand). Merge semantics support replace/append (_replace_merge, _append_merge). Per-scan step1 exclusion overlays are applied by apply_step1_overlay. is_network_path guards remote-config trust rules. The overlay is announced on every command and its SHA-256 is recorded in the manifest.

3. Backend dispatch (vvaharness/backends/)

flowchart TB step[Any pipeline stage] -->|"prompt() / agentic()"| llm["llm.py<br/>dispatcher (resolve on via:)"] llm --> cli["claude_cli.py"] llm --> sdk["sdk.py (Anthropic SDK)"] llm --> oai["oai.py (OpenAI-compat)"] sdk -->|S10 fix| asdk["agent_sdk.py (Edit/Write)"] cli & sdk & oai --> lt["localtools.py<br/>sandboxed Read/Glob/Grep"] reg["harness/registry.py"] --> claudeH["harness/claude (Agent SDK)"] reg --> daH["harness/deepagents (LangGraph)"]

4. State store & checkpoints (orchestrator/store.py, orchestrator/checkpoints.py)

5. Redaction (report/redact.py)

Applied at the MD/SARIF write boundary. Card numbers are Luhn+IIN gated (_luhn, _cc_network); SSNs area/group/serial gated (_ssn_valid); values after strong credential keywords are always masked, while prose-ambiguous keywords are left alone (_bearer_credential). redact_counts/redact_tree support auditing what was masked.

6. Scoring engine (validation/scoring/, validation/io/_host_score.py)

Validation verdicts are deterministic given the synthesised gates. Personas emit per-gate reports; synthesis/_consensus.py applies a conservative majority (_most_conservative_status) to produce host-owned gates; scoring/_engine.py scores them against scoring/_configs.py weights/thresholds; io/_host_score.py re-scores from the persisted synthesized_gates.json. Absent/unparseable gates ⇒ UNVERIFIABLE ⇒ needs_review (fail-closed). Backend split: under deepagents the host synthesises; under cli/sdk the in-session orchestrator synthesises and the host persists it.

7. Permission & sandbox model

Route Tools Enforcement
detection sdk/openai Read/Glob/Grep localtools.py jail (no Bash)
detection cli native + allowlist Bash only if explicitly listed (no shipped profile does)
S10 deepagents fix Read/Glob/Grep/Edit/Write repo-confined virtual FS, traversal-safe
S10 sdk fix Edit/Write via Agent SDK Agent SDK permission gate denies Bash
S11 all read-only contract/permissions deny-by-default write gate

8. Observability & accounting

9. DeepAgents runtime mechanics

Expands on §3's harness/deepagents/ bullet. This is the LangGraph-based implementation of the Harness contract, used only by S10 (Remediate) and S11 (Validate) roles whose via: deepagents.

Model routing — harness/deepagents/options.py::build_model(model_id, env, provider): provider == "anthropic", or provider unset and "claude" appears in model_id → ChatAnthropic (langchain-anthropic); otherwise → ChatOpenAI (langchain-openai). This is the literal mechanism behind the provider: key in models.remediate / models.validate.orchestrator — it is read here, not merely documentation. Validation's one-vendor-per-panel rule follows directly: every persona inherits the orchestrator's via/provider, so a persona id from a different vendor fails this same routing check and validation refuses to start (exit 2).

Session execution — harness/deepagents/client.py::DeepAgentHarness implements run_oneshot/run_streaming against a compiled LangGraph state graph (built by options.py::build_oneshot_options/build_streaming_agent). run_streaming uses graph.astream(..., stream_mode="updates", subgraphs=True) so each persona's internal tool steps surface with a namespace tag, which translate.py converts into typed HarnessMessages for the caller.

Loop budget — harness/deepagents/limits.py::RECURSION_HEADROOM = 900: extra LangGraph supersteps permitted beyond the role's configured max_turns, so a long-but-legitimate tool loop is captured (a partial-state snapshot is taken and a terminal result yielded) rather than truncated mid-task on GraphRecursionError. limits.py is deliberately free of deepagents imports so the budget constant is usable even on Python 3.10.

S10 vs. S11 — the permission asymmetry, mechanically:

S10 Remediate (remediation_agent/plugin_runner) S11 Validate (validation/tools/deep_tools.py)
cwd passed to the harness the real target repo a staged, pre-patched copy (removed on completion)
tools built generic Read/Glob/Grep/Edit/Write reader/writer set, minus Bash (tools = tuple(t for t in _tools(cfg) if t != "Bash"), disallowed_tools=("Bash",)) generic Read/Glob/Grep readers (deepagents/tools.py::build_tools) plus five deterministic read-only fact tools operating on diff.patch: DiffTouched, ChangedLines, DiffImpactMap, PatternScan, TestInventory
Can it write to disk? Yes — the only place in the pipeline that mutates the target repo No — no Write/Edit/Bash tool exists in its toolset; this is a structural guarantee, not a runtime check

Why the lazy import — harness/registry.py::_make_deepagents() imports DeepAgentHarness inside the function body. deepagents (the PyPI package) requires Python ≥ 3.11; importing it eagerly at module load would break every via: cli/via: sdk caller on Python 3.10, even though they never touch this backend. The import only executes when a role's via actually resolves to "deepagents".

For how each stage uses these, jump to the module docs.