Start Here — Visa Vulnerability Agentic Harness (VVAH) Onboarding Guide

docs / 00_START_HERE

← all docs

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 scan edits your code (Stage 10 fix mode) and sends code to a model provider. Use --stop-after s9 for 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