Visa Vulnerability Agentic Harness (VVAH) — Overview & Key Concepts

docs / 01_overview

← all docs

Visa Vulnerability Agentic Harness (VVAH) — Overview & Key Concepts

Read this first. Imagine an assembly line staffed by AI security specialists. A codebase enters one end. Station by station, specialists inspect it: one maps every door and window, one thinks like a burglar, others examine the locks, the cryptography, and who is allowed where. A professional sceptic then tries to prove each claimed weakness is wrong. Whatever survives is written up. A repair crew drafts the smallest possible fix for each real issue, and a final inspection panel tries to break every repair before anyone trusts it.

That is VVAH. Each "station" is an AI skill that can be re-tuned or replaced without rebuilding the line, and each can be pointed at a different AI model by changing a config file — no code changes.

Why it exists. Modern AI can suggest a lot of possible vulnerabilities. The hard part is triage — deciding fast which suggestions are real and worth acting on. VVAH is built around that bottleneck. Its headline measure of success is Mean Time to Adapt (MTTA): how long it takes to go from an AI-discovered weakness to a validated fix.

Three design choices that make findings trustworthy:

  1. Threat-model before analysing — focus effort on the real attack surface.
  2. Multi-agent voting — keep only findings that survive repeated, independent checks.
  3. Structured triage artifacts — emit machine-readable findings, fixes, and verdicts so the whole lifecycle is auditable and compressible.

The four phases

flowchart LR subgraph P1["Phase 1 · Discovery & Modelling"] S1[S1 Preprocess] --> S2[S2 Threat Model] --> S3[S3 Decompose] end subgraph P2["Phase 2 · Deep Dive & Verification"] S4[S4 Deep Dive] --> S5[S5 Pre-filter] --> S6[S6 Verify] end subgraph P3["Phase 3 · Synthesis & Reporting"] S7[S7 Dedup] --> S8[S8 Chain] --> S9[S9 SARIF] end subgraph P4["Phase 4 · Remediation & Validation"] S10[S10 Remediate] --> S11[S11 Validate] end S0[S0 Static Seed<br/>optional] --> S1 S3 --> S4 --> S7 --> S10

Detection (S0–S9) never changes your code. Remediation and validation (S10–S11) can — and are on by default in the shipped profile.

Key concepts and glossary

Term Plain meaning
Agentic SAST Static Application Security Testing driven by autonomous AI "agents" that read code with tools, not just pattern-match.
Stage (S0–S11) One step of the pipeline. Each has a clear input and output.
Skill The reusable AI capability that powers an LLM-driven stage (e.g. "threat modeler").
Role A named model slot in config (e.g. preprocess, verify) with an {id, via} — the model and the backend it uses.
Backend (via:) How a model call is transported: cli, sdk, openai, or deepagents.
ContextPackage The structured map of the repo (files + call graph) produced by S1.
ThreatModel Assets, trust boundaries, and ranked threats produced by S2.
TaskManifest / chunk The prioritised list of code areas to analyse, produced by S3.
Finding A candidate vulnerability with evidence, CWE, and (after S6) a CVSS score.
CWE / CVSS Standard taxonomy of weakness types / standard severity score (0–10).
SARIF An industry-standard JSON format for static-analysis results (v2.1.0 here).
DTO "Data Transfer Object" — the per-finding remediation record (remediate_report.json) that carries the proposed fix and its status.
Taint analysis Tracking untrusted data ("source") to a dangerous operation ("sink").
Source / Sink / Sanitizer Where untrusted data enters / where it's dangerous / what neutralises it.
Lens / specialist A focused analysis persona: crypto, access-control, logic-bug, batch-ETL, IaC (deserialization is opt-in).
Majority-vote FP filtering Running analysis N times and keeping only findings that recur, to cut false positives.
MTTA Mean Time to Adapt — discovery → validated fix. VVAH's primary metric.
Policy gate / kill-switch Deterministic rules that constrain what the remediation agent may edit, with an emergency off-switch.
Verdict Validation outcome: validated, validation_failed, or needs_review.

Inputs and outputs at a glance

Inputs: the target repo (or a CSV of many repos), plus optional context — known_cves.json (raises threat likelihood), design_controls.yaml (downranks exploitability), cmdb.csv (environment-aware scoring), and operator files (validator_hints.yaml, remediation_policy.yaml, remediation_playbook.yaml).

Outputs (per target, under security-scan/): report.md, report.sarif (2.1.0), and errors.jsonl. With remediation on, per-finding DTOs appear under security-remediation/, and run_manifest.json is written to the working directory.

Commands you'll meet

Command What it does
vvaharness setup Inspects credentials and recommends a profile; can install agent instructions.
vvaharness doctor Checks credentials and backends are ready.
vvaharness estimate Rough scope/cost — spends nothing.
vvaharness scan Runs the pipeline (⚠ default runs all 11 stages and edits source).
vvaharness remediate Stage 10 only — propose/apply fixes for a prior scan.
vvaharness validate Stage 11 only — grade the fixes with the adversarial panel.
vvaharness gc Prune old checkpoint/resume state.

See HLD for the component picture, data-flow for what moves between stages, and the module docs for per-file detail.