Runbook: Setup & Credentials

docs / process / runbooks / setup-and-credentials

← all docs

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

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

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.