Start Here — Visa Vulnerability Agentic Harness (VVAH) Onboarding Guide
Welcome. This documentation set explains the Visa Vulnerability Agentic Harness (VVAH) — an open-source tool that uses frontier AI models to find security vulnerabilities in code, propose fixes, and validate those fixes.
It is written for three audiences. Every module document is split into a plain-English first half (with a data-flow diagram) and a technical second half (with per-file detail), so you can read at the depth you need.
Pick your path
| You are… | Read, in order |
|---|---|
| Non-technical (PM, analyst, manager) | architecture.html → Overview → the opening plain-English paragraph of any module doc |
| Security analyst | Overview → Data Flow → Remediation & Validation modules |
| Junior developer | HLD → Data Flow → module docs → LLD |
| Reviewer / architect | HLD → LLD → Graph Intelligence |
| Operator / hands-on user (want to run it, not just understand it) | Process & Runbooks index → Setup & Credentials → Run a Detection Scan |
What's in this folder
Visa-Vulnerablity Agentic Harness/
├── architecture.html ← interactive explainer (START HERE, non-technical friendly)
├── docs/
│ ├── 00_START_HERE.md ← this file
│ ├── 01_overview.md ← what VVAH is, key concepts, glossary
│ ├── design/
│ │ ├── HLD.md / HLD.html ← High-Level Design (HTML is a styled, rendered copy)
│ │ ├── LLD.md / LLD.html ← Low-Level Design (cross-cutting internals)
│ │ └── data-flow.md / data-flow.html ← DFD levels 0/1/2 + narrative
│ ├── modules/ ← one doc per package (non-technical + technical + per-file)
│ │ └── (backends / remediation_agent / validation also ship as .html — see below)
│ ├── tools/graph-intelligence.md ← how the graphs were built + Serena/grepai setup
│ └── process/ ← HOW TO OPERATE VVAH: SOP + runbooks (new)
│ ├── process-operate-vvah.md ← end-to-end SOP: RACI, flow, exceptions, metrics
│ ├── process-optimization.md ← current-state waste analysis + recommendations
│ └── runbooks/ ← setup, run-a-scan, remediate-and-validate
├── diagrams/ ← rendered SVG + PNG (architecture, DFDs, module graph …)
├── tool-outputs/ ← real CodeGraph & Graphify graph exports
└── samples/ ← a runnable copy of the harness, used by the runbooks above
Want to run it, not just read about it? Start at
docs/process/00_process-and-runbooks-index.md —
every command there is verified against the working copy in ../samples/.
The one-paragraph summary
VVAH runs an 11-stage pipeline across four phases. Detection (S0–S9) maps the attack surface, threat-models the app, decomposes the work, deep-dives with specialist AI "lenses", verifies findings adversarially, deduplicates, chains exploits, and emits a Markdown + SARIF report. Remediation (S10) proposes and can apply a minimal fix per finding; Validation (S11) runs an adversarial panel that grades each fix. Every AI stage is a swappable skill routed to one of four backends by config alone.
⚠️ A plain
vvaharness scanedits your code (Stage 10 fix mode) and sends code to a model provider. Use--stop-after s9for read-only detection, and only scan repos you are authorised to process.
Rendered HTML copies
HLD.md, LLD.md, data-flow.md, modules/backends.md, modules/remediation_agent.md,
and modules/validation.md also ship as standalone, styled .html files (diagrams render
live via Mermaid) — open the .html if you'd rather read in a browser than a Markdown
viewer. The .md is always the source of truth; regenerate the .html after editing with
python tools/gen_design_html.py.
Diagram index
diagrams/01_architecture.svg— system architecture (HLD)diagrams/02_dataflow_pipeline.svg— detection data flow (DFD L1)diagrams/03_context_dfd.svg— context diagram (DFD L0)diagrams/04_module_dependencies.svg— module dependency graph (from CodeGraph)diagrams/05_backend_routing.svg— backend routingdiagrams/06_remediate_validate.svg— S10/S11 flow