Runbook — run a detection scan

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

← all docs

Runbook — run a detection scan

Owner: security analyst / operator · Frequency: per engagement/target · Last updated: 2026-08-14 · Last run: commands verified against samples/strix/README.md and AGENTS.md (not executed live — no Docker/LLM key in this sandbox).

[!warning] ⚠️ This runbook launches real exploitation attempts against the target. Only run it against systems you own or have explicit, written authorization to test.

Purpose

Start a Strix scan against a target and get results back — either interactively (the default) or headless (for scripts/CI).

Prerequisites

Procedure

Step 1 — Basic scan (local codebase)

strix --target ./app-directory

Expected result: the interactive TUI launches, showing the live agent tree as the root agent spawns specialists. If it fails: see Troubleshooting below.

Step 2 (alternative) — Headless / CI mode ⚠️

strix -n --target https://your-app.com --scan-mode quick --max-budget 10

Expected result: the CLI streams findings as they're discovered and prints the final report before exiting. Exit codes: 0 clean, 1 fatal error, 2 vulnerabilities found — a 0 only covers what was actually analyzed, so check run.json's status and llm_usage.cost vs. the budget before calling a run clean.

Step 3 (alternative) — API/spec-aware testing

# OpenAPI / Swagger file, paired with the live base URL
strix --target ./openapi.yaml --target https://api.your-app.com

# Postman collection (exported file, or pulled live by id)
strix --target ./collection.postman_collection.json --target https://api.your-app.com
export POSTMAN_API_KEY="PMAK-..."
strix --target "postman://<collection-uuid>?env=<environment-uuid>"

Expected result: Strix tests every declared endpoint from the spec instead of discovering them by crawling.

Step 4 (alternative) — Grey-box / authenticated / focused testing

strix --target https://your-app.com --instruction "Perform authenticated testing using credentials: user:pass"
strix --target api.your-app.com --instruction "Focus on business logic flaws and IDOR vulnerabilities"
strix --target api.your-app.com --instruction-file ./instruction.md

Step 5 — Resume an interrupted or budget-stopped scan

strix --resume <run-name>

Expected result: the agent tree is reconstituted exactly where it left off (../../modules/core.md — resume semantics), including any queued but undelivered inter-agent messages.

Step 6 — Browse results afterward

strix view              # most recent run
strix view <run-name>   # a specific run by name

Expected result: a local, read-only web dashboard opens (127.0.0.1, a private tokened link) — nothing leaves the machine.

Verification

Troubleshooting

Symptom Likely cause Fix
Scan ends with no finish_scan call / no report Root agent hit max_turns or budget before calling the lifecycle tool Re-run with a higher --max-turns/--max-budget, or --resume and let it continue.
"No LLM model configured" STRIX_LLM not set and no prior ~/.strix/cli-config.json Re-run setup-and-credentials.md.
Rate-limit error mid-scan Provider-side throttling The scan stops cleanly and logs a resume hint (strix --resume <run>) — wait, then resume.

Rollback

A scan that ran destructive actions against the target is not something Strix itself can undo — that's a target-side concern. On the Strix side, strix_runs/<run-name>/ can simply be deleted to discard results; the sandbox container is torn down automatically at the end of every scan (clean or crashed) via session_manager.cleanup().

Escalation

Issue Contact
Scan appears to be testing outside authorized scope Stop the scan immediately (Ctrl+C or kill the process); escalate to whoever granted authorization
Suspected false positive at scale See review-and-triage-findings.md

History

Date Change
2026-08-14 Runbook authored against usestrix/strix commit 8ca0c4a9.