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
- [ ]
setup-and-credentials.mdcompleted. - [ ] Written authorization to test the intended target.
- [ ] A budget ceiling in mind (
--max-budget-usd/ CLI's--max-budget), since scans spend LLM tokens per turn.
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
- [ ]
strix_runs/<run-name>/run.jsonexists and itsstatusfield reflects the actual outcome (completed, not silentlyrunning). - [ ] If findings were expected,
strix_runs/<run-name>/vulnerabilities.jsonis non-empty andpenetration_test_report.mdreads coherently.
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. |