mirror of
https://github.com/usestrix/strix.git
synced 2026-10-01 02:03:55 +00:00
1d05637b68
Three issues raised in review on #1217, all real: - The STRIX_MAX_AGENTS check read agent_count() and then spawned, so two parents racing for the last slot both passed before either child registered and the graph overshot the cap. The coordinator now hands out slots atomically (try_reserve_agent_slot / release_agent_slot), counting outstanding reservations alongside live agents under the same lock. The slot is released once the spawner has registered the child or failed. Depth stays a plain check — a parent's depth cannot change mid-spawn. - _trim_parent_history kept the newest item whole when that item alone exceeded the budget ("and kept"), so the cap bounded nothing on the child's first request and could overflow the provider context window. An oversized newest item is now rendered as a truncated text message. No tool-call pairing can break: nothing else survives that trim. - --reasoning-effort exported STRIX_REASONING_EFFORT, which persist_current() then wrote into cli-config.json, turning a documented per-run flag into the default for every later run. Env vars can now be marked run-scoped and are skipped when persisting. Tests cover the concurrent reservation, slot release, the oversized-item trim, and the persist exemption. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
172 lines
7.7 KiB
Text
172 lines
7.7 KiB
Text
---
|
|
title: "CLI Reference"
|
|
description: "Command-line options for Strix"
|
|
---
|
|
|
|
## Basic Usage
|
|
|
|
```bash
|
|
strix (--target <target> | --target-list <path>) [options]
|
|
```
|
|
|
|
## Options
|
|
|
|
<ParamField path="--target, -t" type="string">
|
|
Target to test. Accepts URLs, repositories, local directories, domains, IP addresses, API spec files (OpenAPI/Swagger `.json`/`.yaml`, a Postman collection export), or a live Postman collection by id (`postman://<collection-uuid>`). Can be specified multiple times. Fresh runs require at least one target source: `--target` or `--target-list`.
|
|
|
|
When the target is an API spec, Strix copies it into the agent's workspace and authorizes the base URLs it declares (including those resolved from a Postman environment) as in-scope hosts - so the agent reads the contract and tests the full declared surface instead of discovering endpoints by crawling. Pair the spec with the deployed base URL (e.g. `--target ./openapi.yaml --target https://api.example.com`) so the agent has a reachable host to attack.
|
|
|
|
<Note>
|
|
A local directory is mounted into the sandbox live and **writable**, so the agent edits your real files (`.git` excepted). Commit or stash first.
|
|
</Note>
|
|
|
|
<Note>
|
|
Fetching a Postman collection by id requires `POSTMAN_API_KEY`. Add `?env=<environment-uuid>` to also pull a Postman environment, which resolves `{{baseUrl}}` / token variables the collection references (e.g. `postman://<collection-uuid>?env=<environment-uid>`).
|
|
</Note>
|
|
</ParamField>
|
|
|
|
<ParamField path="--target-list" type="string">
|
|
Path to a file containing targets, one per non-empty, non-comment line. Lines starting with `#` are ignored. Can be specified multiple times and combined with `--target`.
|
|
</ParamField>
|
|
|
|
<ParamField path="--instruction" type="string">
|
|
Custom instructions for the scan. Use for credentials, focus areas, or specific testing approaches.
|
|
</ParamField>
|
|
|
|
<ParamField path="--instruction-file" type="string">
|
|
Path to a file containing detailed instructions.
|
|
</ParamField>
|
|
|
|
<ParamField path="--workspace-file" type="string">
|
|
Path to a file on your machine to place into the sandbox workspace before the
|
|
scan starts. Repeat the option for more files. Write `PATH:DEST` to choose the
|
|
destination inside `/workspace`. `DEST` defaults to the file name. See
|
|
[Workspace files](/usage/instructions#workspace-files).
|
|
</ParamField>
|
|
|
|
<ParamField path="--scan-mode, -m" type="string" default="deep">
|
|
Scan depth: `quick`, `standard`, or `deep`.
|
|
</ParamField>
|
|
|
|
<ParamField path="--reasoning-effort" type="string">
|
|
Model reasoning effort for this run: `none`, `minimal`, `low`, `medium`,
|
|
`high`, `xhigh`, or `max`. Higher = more thinking tokens = higher cost and
|
|
(usually) deeper analysis. Overrides `STRIX_REASONING_EFFORT` and the config
|
|
file for this run. Defaults to the configured value (`high`). Not written back
|
|
to the config file, so it never changes what later runs do.
|
|
</ParamField>
|
|
|
|
<ParamField path="--scope-mode" type="string" default="auto">
|
|
Code scope mode: `auto` (enable PR diff-scope in CI/headless runs), `diff` (force changed-files scope), or `full` (disable diff-scope).
|
|
</ParamField>
|
|
|
|
<ParamField path="--diff-base" type="string">
|
|
Target branch or commit to compare against (e.g., `origin/main`). Defaults to the repository's default branch.
|
|
</ParamField>
|
|
|
|
<ParamField path="--non-interactive, -n" type="boolean">
|
|
Run in headless mode without TUI. Ideal for CI/CD.
|
|
</ParamField>
|
|
|
|
<ParamField path="--config" type="string">
|
|
Path to a custom config file (JSON) to use instead of `~/.strix/cli-config.json`.
|
|
</ParamField>
|
|
|
|
<ParamField path="--max-budget" type="number">
|
|
Maximum LLM spend in USD for the whole scan, counted cumulatively across the
|
|
root agent and every child agent. The budget is checked after each model
|
|
response.
|
|
|
|
In non-interactive mode (`-n`), once the running cost reaches the threshold,
|
|
the scan stops cleanly with a `stopped` status (not a failure) and the sandbox
|
|
is torn down. Sub-agents are stopped early, at 90% of the budget, reserving
|
|
the final slice for the root agent to wind down and produce the final report.
|
|
|
|
In interactive mode, reaching the budget pauses the scan instead of ending
|
|
it: every agent parks, and sending any message resumes the scan with the cap
|
|
extended by the original budget amount. There is no sub-agent reserve in
|
|
interactive mode.
|
|
|
|
As the budget is approached, graduated wrap-up warnings are surfaced to
|
|
**every** agent so they can finish their work and call their lifecycle tool
|
|
before the hard stop. The bands sit just below each role's own stop point: the
|
|
root is warned at **70%, 85% and 95%** (it stops at 100%), while sub-agents are
|
|
warned at **75%, 80% and 85%** (they stop at the 90% reserve). In interactive
|
|
mode every agent uses the **70%, 85% and 95%** bands. Percentages shown in the
|
|
warnings are the real cumulative spend against the full budget.
|
|
|
|
Must be greater than `0`. Omit the flag for no limit.
|
|
|
|
**Limitations**
|
|
|
|
- The check fires *after* a response is returned, so the final spend can
|
|
slightly overshoot the limit by any calls already in flight when the
|
|
threshold is crossed (most relevant with several child agents running
|
|
concurrently).
|
|
- Cost is a best-effort estimate derived from token usage and model pricing;
|
|
providers that do not expose priced usage may under-count.
|
|
- For LiteLLM-routed models, Strix enables streaming success callbacks to
|
|
capture provider-reported cost. Message content remains excluded, but
|
|
third-party LiteLLM callbacks configured in the same process can receive
|
|
other streaming metadata such as model names, request IDs, and token
|
|
counts.
|
|
</ParamField>
|
|
|
|
<ParamField path="--max-turns" type="integer" default="500">
|
|
Maximum number of turns (one model response plus its tool round) allotted to
|
|
**each** agent, applied per run. When an agent reaches this limit it is
|
|
force-stopped.
|
|
|
|
As the limit is approached, graduated wrap-up warnings (at 70%, 85% and 95%)
|
|
are injected into that agent's next model turn so it can prioritise its
|
|
remaining work and call its lifecycle tool (`finish_scan` for the root agent,
|
|
`agent_finish` for sub-agents) before the hard stop.
|
|
|
|
Must be greater than `0`.
|
|
</ParamField>
|
|
|
|
## Examples
|
|
|
|
```bash
|
|
# Basic scan
|
|
strix --target https://example.com
|
|
|
|
# Authenticated testing
|
|
strix --target https://app.com --instruction "Use credentials: user:pass"
|
|
|
|
# Focused testing
|
|
strix --target api.example.com --instruction "Focus on IDOR and auth bypass"
|
|
|
|
# CI/CD mode
|
|
strix -n --target ./ --scan-mode quick
|
|
|
|
# Cap cost and per-agent turns
|
|
strix --target https://example.com --max-budget 25 --max-turns 300
|
|
|
|
# Force diff-scope against a specific base ref
|
|
strix -n --target ./ --scan-mode quick --scope-mode diff --diff-base origin/main
|
|
|
|
# Multi-target white-box testing
|
|
strix -t https://github.com/org/app -t https://staging.example.com
|
|
|
|
# API spec + live target (OpenAPI/Swagger file or Postman collection)
|
|
strix -t ./openapi.yaml -t https://api.example.com
|
|
|
|
# Postman collection pulled live by id (+ optional environment)
|
|
strix -t "postman://<collection-uuid>?env=<environment-uuid>"
|
|
|
|
# Targets from a file
|
|
strix --target-list ./targets.txt
|
|
|
|
# Extra files placed in the sandbox workspace
|
|
strix --target ./my-project --workspace-file ./wordlist.txt
|
|
strix --target https://app.com --workspace-file ./openapi.yaml:specs/openapi.yaml
|
|
```
|
|
|
|
## Exit Codes
|
|
|
|
| Code | Meaning |
|
|
|------|---------|
|
|
| 0 | Scan completed successfully (interactive mode always exits `0`; in headless mode, `0` means no vulnerabilities were found) |
|
|
| 1 | A fatal error occurred before or during the scan (e.g. missing environment variables, Docker unavailable, invalid config file, diff-scope resolution failure, or an unhandled error) |
|
|
| 2 | Vulnerabilities found (headless mode only) |
|