Runbook: Setup & Credentials
Owner: Operator (platform/DevOps) | Frequency: Once per environment, then as-needed on credential rotation Last Updated: 2026-08-14 | Last Run: —
Purpose
Get Visa Vulnerability Agentic Harness (VVAH) installed and provably ready to run — the
gate every other runbook depends on. Use this whenever scan/remediate/validate fails
with a credential or backend error, not just on first install.
Prerequisites
- [ ] Python ≥ 3.11 available (
python3 --version) - [ ] Working copy of the harness at
samples/visa-vulnerability-agentic-harness/(see../../../samples/README.mdif missing) - [ ] At least one model credential: Anthropic API key (
sdk/deepagentsbackend), a logged-inclaudeCLI (clibackend), or an OpenAI-compatible endpoint + key (openaibackend) - [ ] Write access to
$VVAHARNESS_STATE_DIR(default~/.vvaharness/state/)
Procedure
Step 1: Create the environment and install
cd samples/visa-vulnerability-agentic-harness
python3 -m venv .venv && source .venv/bin/activate
pip install -e ".[sdk,validation]"
Expected result: pip finishes with no errors; vvaharness --help prints the command list.
If it fails: Python < 3.11 is the most common cause — vvaharness itself checks this at
startup and prints ERROR: ... naming the required floor before anything else runs.
Step 2: Provide credentials
cp .env.example .env
$EDITOR .env
Expected result: .env has the key(s) for your chosen backend(s) filled in
(e.g. ANTHROPIC_API_KEY=, OPENAI_API_KEY=, OPENAI_BASE_URL=).
If it fails: if you don't know which keys you need yet, run Step 3 first — setup tells
you exactly what's missing.
Step 3: Run guided setup
vvaharness setup
Expected result: a checklist of AI-agent install, keys, deps, gateway, and config, ending in either:
Ready ✓ → vvaharness scan --repo /path/to/target
or a count of blocking issues with what to fix.
If it fails: fix the specific blocking item(s) printed (missing key, unreachable gateway,
missing extra) and re-run. setup also offers to install agent instruction files and, if
remediation rule defaults can't be resolved from the installed wheel, will interactively
prompt for an inputs directory — point it at inputs/ in this same folder.
Step 4: Choose a profile
cp vvaharness/config/profiles/sdk.yaml config.yaml # or default.yaml / full.yaml / taint.yaml
Expected result: config.yaml exists in your working directory (outside any target
repo you plan to scan — see the Troubleshooting row on this below).
If it fails: N/A — this is a file copy. Pick based on the table below.
| Profile | Use when |
|---|---|
default.yaml |
Standard run: S0 local, S1–S9 via cli, S10/S11 via deepagents (Anthropic). |
sdk.yaml |
You want S4 majority voting on a single Anthropic API key. |
full.yaml |
Template for spreading roles across cli + sdk + openai. |
taint.yaml |
Taint-first source→sink scanning (S0 on; S10/S11 disabled). |
Step 5: Live readiness probe
vvaharness doctor --config config.yaml
Expected result:
N ok · 0 warning(s) · 0 blocking issue(s)
followed by exit code 0. This is the same static checks as setup plus a live backend
connectivity probe that actually spends a trivial amount of budget to confirm the endpoint answers.
If it fails: exit code 1 with n_blocking > 0 — read the per-check line it printed
(each is name: detail) and fix that specific item; re-run doctor until clean. Do not
proceed to scan on a non-zero doctor exit.
Verification
- [ ]
vvaharness doctor --config config.yamlexits 0 - [ ]
vvaharness estimate --repo <any small test repo>prints a scope estimate with no errors
Troubleshooting
| Symptom | Likely Cause | Fix |
|---|---|---|
ERROR: <python version message> at any command |
Interpreter below the required floor | Install/activate Python ≥ 3.11; recreate the venv. |
setup/doctor reports a missing extra (e.g. validation) |
pip install -e . without the extras VVAH needs for your profile |
pip install -e ".[sdk,validation]" (add extras as doctor names them). |
doctor blocking issue naming a key/endpoint |
.env incomplete or not loaded |
Confirm .env is in the directory you're running from (VVAH auto-loads ./.env); re-check the exact variable name doctor printed. |
config.yaml silently ignored, packaged default used instead |
Config file placed inside the target repo being scanned | This is intentional (untrusted-input protection) — move config.yaml outside the target and pass --config explicitly. |
remediate/setup prompts for "Path to the VVAH inputs directory" |
Remediation rule defaults not resolvable from the installed package | Point it at inputs/ in samples/visa-vulnerability-agentic-harness/ (contains the example policy/playbook/CVE files). |
doctor probe step is skipped |
A blocking issue exists above it | doctor intentionally skips the (budget-spending) live probe until static blocking issues are cleared — fix those first. |
Rollback
Setup has no destructive steps to roll back. To start clean: deactivate && rm -rf .venv
and repeat Step 1. Credential changes are just .env edits — no un-do needed beyond restoring
the previous file if you kept a backup.
Escalation
| Situation | Contact | Method |
|---|---|---|
| Credential rotation needed, no access to the vault/secret store | Operator / platform team | Standard credential-request process |
doctor fails against a model endpoint that other tools reach fine |
AppSec tool owner | Flag as a possible VVAH/backend config issue, include the exact doctor output |
| Unclear which profile to use for a new use case | AppSec tool owner | Share the target's size/language and whether fix mode should be on |
History
| Date | Run By | Notes |
|---|---|---|
| 2026-08-14 | — | Runbook authored against harness commit 3d972f67; flags verified directly from cli.py/util/environment source, not from memory. |