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/)
llm.pyis the single dispatcher: every stage importsprompt()/agentic()from here;resolve()reads the role's{id, via}.localtools.pyimplements read-only Read/Glob/Grep jailed to the target repo (no Bash) forsdk/openai.agent_sdk.pyis the Claude Agent SDK backend for the mutating remediation role, with path confinement (_within_root) and redaction hooks.harness/is the post-scan abstraction: a neutralHarnesscontract (harness/base.py,harness/contract/) with two implementations —claude/(Agent SDK) anddeepagents/(LangGraph).registry.get_harnessmapsvia:→ factory. The contract defines permission policy (contract/permissions/), tool policy, effort, and message types so the two runtimes are interchangeable.
4. State store & checkpoints (orchestrator/store.py, orchestrator/checkpoints.py)
store.py— SQLite state store.connect/_migratemanage the schema;register_runrecords a run;save_callgraph/load_callgraphpersist the S1 call graph (as_graph_rowsof q-nodes) so later stages read it back without re-computing;reset_run/delete_runsupport re-runs andgc.checkpoints.py— per-stage save/load with schema validation (_validate_schema,_schema_for), a run-id derivation (run_id_for), and pruning (prune_checkpoints). S0–S4 checkpoint individually; S5–S7 share the S7 checkpoint; S8/S9 are separate.
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
util/tokens.py— process-wide token counter bucketed by phase (_bucket).util/metrics.py— buildsScanMetrics(kept out of the orchestrator hot path).util/status.py— per-stage spinner / structured event emission.util/scan_progress.py— optional per-file[progress]stream (S0–S9).util/errlog.py— structured non-fatal error log, counts by stage.manifest.py— run manifest with scrubbed argv, git SHA, config SHA-256, roles.
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.