Runbook: Run a Detection Scan (S0–S9)
Owner: Analyst / CI job owner | Frequency: On demand, or scheduled per repo Last Updated: 2026-08-14 | Last Run: —
Purpose
Run the read-only detection pipeline against a target codebase and produce report.md /
report.sarif. This is the safe, non-editing half of VVAH — use --stop-after s9 to
guarantee no source changes and no remediation-stage model spend.
Prerequisites
- [ ]
vvaharness doctor --config config.yamlexits 0 (seesetup-and-credentials.md) - [ ]
config.yamlpresent outside the target repo - [ ] Target repo path (or a
--repo-fileCSV/TXT for batch mode) - [ ] Optional context files ready if you have them:
known_cves.json,design_controls.yaml,cmdb.csv
Procedure
Step 1: Scope check (no spend)
vvaharness estimate --repo /path/to/target
Expected result: file count, byte count, and a rough input-token estimate.
If it fails: no such path: <repo> means the path is wrong — this command does not
touch the network at all, so any failure is local.
Step 2: (Optional) Exact-scope check without full cost
vvaharness scan --repo /path/to/target --config config.yaml --stop-after s3
Expected result: run stops cleanly after S3 (decompose); checkpoints for S0–S3 written to the state DB; no findings yet, no code touched. If it fails: see Troubleshooting — most failures here are config/credential, not scan logic.
Step 3: Run the full detection scan
vvaharness scan --repo /path/to/target \
--application-id <app-id> \
--config config.yaml \
--stop-after s9
Expected result: exit 0; /path/to/target/security-scan/report.md,
report.sarif, and (if any non-fatal errors occurred) errors.jsonl are written.
run_manifest.json is written to your current working directory.
If it fails: re-run with --resume (see Step 4) rather than starting over — completed
stages are checkpointed in the state DB.
⚠️ Do not omit
--stop-after s9unless you intend remediation to run in the same invocation — the shippeddefault.yamlprofile hasstep_remediate.enabledon, so a barevvaharness scan --repo ... --application-id ...edits source files (S10 fix mode) in addition to detecting. If you only want detection,--stop-after s9is mandatory.
Step 4: Resume an interrupted scan
vvaharness scan --repo /path/to/target --config config.yaml --stop-after s9 --resume
Expected result: stages already checkpointed for this repo/run are skipped; the scan picks up from the first incomplete stage. If it fails: if resume repeatedly fails at the same stage, evict the run and start clean (see Rollback).
Step 5 (optional): Batch mode — many repos in one invocation
vvaharness scan --repo-file repos.csv \
--config config.yaml \
--stop-after s9 \
--workspace ./batch-workspace \
--group-by-app
repos.csv header: AppID,RepoName[,Path] (or a .txt with
application_id,repository_name,path per line). --group-by-app clones every repo sharing
an AppID under {workspace}/{app_id}/ and produces one report per application instead
of one per repo. Add --keep-clones to retain the clones after scanning (implied by
--stop-after clone).
Expected result: one security-scan/ output per repo (or per app, with --group-by-app).
If it fails: check the CSV header exactly matches AppID,RepoName[,Path]; a missing
Path column is derived from batch.git_base_url in config — confirm that's set if you omit Path.
Verification
- [ ]
security-scan/report.mdexists and lists findings ranked by CVSS (or states none found) - [ ]
security-scan/report.sarifvalidates as SARIF 2.1.0 (importable into your SAST tracker) - [ ]
security-scan/errors.jsonl, if present, has no entries indicating a stage was skipped unexpectedly - [ ] Target repo's working tree is unchanged (
git statusin the target — confirms--stop-after s9held)
Troubleshooting
| Symptom | Likely Cause | Fix |
|---|---|---|
| Scan exits non-zero immediately, no stages run | doctor-class credential/config issue |
Run vvaharness doctor --config config.yaml; fix blocking items first. |
| Target's files were modified after a scan you thought was detection-only | --stop-after s9 was omitted and the profile has step_remediate.enabled: true |
Always pass --stop-after s9 for detection-only runs; revert the target repo from git and re-run correctly. |
config.yaml seems ignored, defaults used |
Config file located inside the target repo | Move it outside the target (untrusted-input protection — see process-operate-vvah.md Exceptions). |
Cost/time far exceeds estimate's projection |
Large binary/vendored files not excluded | Add an exclude overlay via --step1-config (or rely on --auto-step1 in the default profile) to skip vendored/generated directories. |
| Scan hangs or times out on one stage | Backend rate-limit or network issue | Ctrl-C (safe — exits 130, no partial writes to report.md), then re-run with --resume. |
| Batch run: one repo fails, rest should continue | Expected behavior — each entry gets a fresh context | Check that repo's errors.jsonl / exit status individually; other repos' reports are unaffected. |
Rollback
Detection scans don't modify the target repo (with --stop-after s9), so there is nothing
to roll back in the target. To discard a run's checkpoints and force a clean re-scan:
vvaharness gc --run /path/to/target
Escalation
| Situation | Contact | Method |
|---|---|---|
| Scan reports findings that look wrong/incomplete for a well-known repo | AppSec tool owner | Share report.md + run_manifest.json (records config hash + git SHA) |
| Repeated backend failures across multiple repos | Operator / platform team | Likely a shared credential or gateway outage — check doctor first |
History
| Date | Run By | Notes |
|---|---|---|
| 2026-08-14 | — | Runbook authored against harness commit 3d972f67; flags verified against orchestrator/entry.py. |