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:
- Threat-model before analysing — focus effort on the real attack surface.
- Multi-agent voting — keep only findings that survive repeated, independent checks.
- Structured triage artifacts — emit machine-readable findings, fixes, and verdicts so the whole lifecycle is auditable and compressible.
The four phases
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.