Runbook: Run a Detection Scan (S0–S9)

docs / process / runbooks / run-a-detection-scan

← all docs

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

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 s9 unless you intend remediation to run in the same invocation — the shipped default.yaml profile has step_remediate.enabled on, so a bare vvaharness scan --repo ... --application-id ... edits source files (S10 fix mode) in addition to detecting. If you only want detection, --stop-after s9 is 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

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.