diff --git a/README.md b/README.md index 1f861177..77c5e0ae 100644 --- a/README.md +++ b/README.md @@ -172,18 +172,9 @@ strix view my-run-name strix view --host 0.0.0.0 --port 8080 --no-open ``` -`strix view` starts a lightweight local server (bound to `127.0.0.1` on a random port) and opens your browser to a private, tokened link. Nothing leaves your machine: the dashboard reads the run's files straight off disk, with no cloud account or upload required. The UI ships prebuilt with Strix, so there is no extra install and no JS build step. +The dashboard shows the findings, a live map of the agent team, and past runs, and it can steer a running scan. Nothing leaves your machine, and the UI ships prebuilt. `strix view` binds to `127.0.0.1` and prints a tokened link that grants access to the run, so share it carefully. -Use `--host 0.0.0.0` to make the viewer reachable from other machines. Replace `0.0.0.0` in the printed URL with the server's reachable IP or hostname. The token in that URL grants access to the selected run's scan data, history, and steering, so only share it with trusted users and restrict the port with your firewall. Requests without the token-derived session cannot read run data. - -### What's in the dashboard - -- **Overview**: run status, target, and a severity breakdown of everything found so far. -- **Vulnerabilities**: each validated finding with its severity, details, and reproduction steps. -- **Agent graph**: a live map of the multi-agent team, showing which agent is doing what. -- **Steering**: send instructions to a live scan from the browser to redirect the agents mid-run. -- **History**: browse past runs on this machine and jump between them. -- **Reports**: generate a shareable report and email it to yourself or your team. +See the [viewer documentation](https://docs.strix.ai/usage/viewer) for the options and for reaching the viewer from another machine. --- @@ -209,18 +200,9 @@ having to discover them by crawling. Pair the spec with the live base URL so the agent knows where to send traffic: ```bash -# OpenAPI / Swagger file (.json / .yaml) +# OpenAPI / Swagger file, Postman export, or a live collection by id strix --target ./openapi.yaml --target https://api.your-app.com - -# Postman collection export -strix --target ./collection.postman_collection.json --target https://api.your-app.com - -# Postman collection pulled live by id (no manual export) -export POSTMAN_API_KEY="PMAK-..." -strix --target postman:// - -# ...with a Postman environment to resolve {{baseUrl}} / token variables -strix --target "postman://?env=" +strix --target postman:// --target https://api.your-app.com ``` @@ -235,20 +217,10 @@ strix -t https://github.com/org/app -t https://your-app.com # Targets from a file, one target per non-empty, non-comment line strix --target-list ./targets.txt - -# White-box source-aware scan (local repository) -strix --target ./app-directory --scan-mode standard - -# Focused testing with custom instructions -strix --target api.your-app.com --instruction "Focus on business logic flaws and IDOR vulnerabilities" - -# Provide detailed instructions through file (e.g., rules of engagement, scope, exclusions) -strix --target api.your-app.com --instruction-file ./instruction.md - -# Force PR diff-scope against a specific base branch -strix -n --target ./ --scan-mode quick --scope-mode diff --diff-base origin/main ``` +See the [CLI reference](https://docs.strix.ai/usage/cli) for every option, including scan modes, diff scope, instruction files, and budgets. + ### Headless Mode Run Strix programmatically without interactive UI using the `-n/--non-interactive` flag - perfect for servers and automated jobs. The CLI prints real-time vulnerability findings and the final report before exiting. Exits with non-zero code when vulnerabilities are found. @@ -287,9 +259,9 @@ jobs: ``` > [!TIP] -> In CI pull request runs, Strix automatically scopes quick reviews to changed files. -> If diff-scope cannot resolve, ensure checkout uses full history (`fetch-depth: 0`) or pass -> `--diff-base` explicitly. +> In CI pull request runs, Strix automatically scopes quick reviews to changed files, which is why the +> checkout above fetches full history. See the +> [CI/CD documentation](https://docs.strix.ai/integrations/github-actions) for the details. ### Configuration @@ -300,24 +272,20 @@ export LLM_API_KEY="your-api-key" # Optional export LLM_API_BASE="your-api-base-url" # if using a local model, e.g. Ollama, LMStudio export PERPLEXITY_API_KEY="your-api-key" # for search capabilities -export STRIX_REASONING_EFFORT="high" # control thinking effort (default: high, quick scan: medium) ``` > [!NOTE] > Strix automatically saves your configuration to `~/.strix/cli-config.json`, so you don't have to re-enter it on every run. +> See the [configuration reference](https://docs.strix.ai/advanced/configuration) for every environment variable. #### Sign in with a ChatGPT subscription Instead of a metered API key, you can run Strix on your ChatGPT Plus/Pro subscription: ```bash -strix auth login chatgpt # sign in with your ChatGPT account - +strix auth login chatgpt # sign in with your ChatGPT account export STRIX_LLM="chatgpt/gpt-5.4" # chatgpt/ runs on the subscription -strix --target ./app-directory - -strix auth status # show the active sign-in -strix auth logout # forget the sign-in +strix auth status # show the active sign-in, or logout to forget it ``` #### Use the managed platform: `strix cloud` @@ -333,20 +301,14 @@ strix cloud vulns list --severity critical Every [REST API](https://docs.app.strix.ai) operation has a matching `strix cloud ` command. Run `strix cloud` to list the resources, and add `help` to a resource to list its verbs. Output is JSON when stdout is not a terminal or when you pass `--json`. Binary downloads are the exception: redirect the raw bytes, or combine `--output FILE --json` for download metadata. -See the [platform documentation](https://docs.app.strix.ai) for scopes, workspaces, billing, and source-upload options. +See the [cloud CLI documentation](https://docs.strix.ai/cloud/cli) for scopes, workspaces, billing, and source-upload options. #### Connect your own MCP servers -Strix can connect to Model Context Protocol (MCP) servers you list and expose their tools to the agent during a run. Create `~/.strix/mcp-servers.json` with a JSON list of servers. Each entry is either a local `stdio` server that Strix launches as a subprocess, or a remote `http` server: +Strix can connect to Model Context Protocol (MCP) servers you list and expose their tools to the agent during a run. Create `~/.strix/mcp-servers.json` with a JSON list of local `stdio` servers or remote `http` servers: ```json [ - { - "name": "local_fs", - "transport": "stdio", - "command": "npx", - "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/project"] - }, { "name": "github", "transport": "http", @@ -357,14 +319,14 @@ Strix can connect to Model Context Protocol (MCP) servers you list and expose th ] ``` -Each server's tools are namespaced by `name` (for example `local_fs_read_file`). Omit `allowed_tools` to expose every tool the server offers, or set it to a list to restrict which tools the agent can call. The file is optional, and a server that fails to connect is skipped without failing the run. You can point Strix at a different file with `STRIX_MCP_CONFIG`. +Each server's tools are namespaced by `name`, for example `github_list_issues`. See the [MCP documentation](https://docs.strix.ai/integrations/mcp) for the full schema, tool filtering, and `stdio` servers. **Recommended models for best results:** - [Z.ai GLM-5.3 on OpenRouter](https://openrouter.ai/z-ai/glm-5.3) - `openrouter/z-ai/glm-5.3` (the default pick) - [OpenAI GPT-5.4](https://openai.com/api/) - `openai/gpt-5.4` -- [Anthropic Claude Sonnet 4.6](https://claude.com/platform/api) - `anthropic/claude-sonnet-4-6` -- [Google Gemini 3 Pro Preview](https://cloud.google.com/vertex-ai) - `vertex_ai/gemini-3-pro-preview` +- [Anthropic Claude Opus 5](https://claude.com/platform/api) - `anthropic/claude-opus-5` +- [Google Gemini 3.1 Pro Preview](https://cloud.google.com/vertex-ai) - `vertex_ai/gemini-3.1-pro-preview` - [DeepSeek V4 Pro](https://platform.deepseek.com) - `deepseek/deepseek-v4-pro` - [Moonshot Kimi K3](https://platform.kimi.ai) - `moonshot/kimi-k3` diff --git a/docs/cloud/cli.mdx b/docs/cloud/cli.mdx new file mode 100644 index 00000000..d0f84292 --- /dev/null +++ b/docs/cloud/cli.mdx @@ -0,0 +1,103 @@ +--- +title: "Cloud CLI" +description: "Drive app.strix.ai from the terminal with strix cloud" +--- + +The `strix cloud` commands drive the managed platform ([app.strix.ai](https://app.strix.ai)) from the terminal. You do not need Docker or an LLM key. + +## Sign In + +Sign in once with the browser device flow. The sign-in creates your account and workspace on first use, and it stores a personal API token in `~/.strix/platform-auth.json`. + +```bash +strix cloud login # browser approval, then workspace and scope profile +strix cloud login --workspace "My Team" # select a workspace by name or ID +strix cloud whoami # local account and workspace status +strix cloud session # verify the remote session and consent ceiling +strix cloud logout # revoke remotely, then remove the local token +``` + +A browser sign-in creates one reusable credential for each CLI installation. A second sign-in on the same installation replaces the secret instead of adding another key. `strix cloud logout` revokes the server session before it deletes the local token. Use `--local-only` when you cannot reach the server. + +## Scopes + +The default **Recommended** preset covers normal scan work, local source uploads, workspace switching, and user-approved credit top-ups. It excludes credential creation, so request `tokens:write` when you need it. + +```bash +strix cloud login --scopes scans:read scans:write uploads:write billing:read +strix cloud login --scope-profile minimal # also accepts recommended or full +strix cloud session scopes # granted scopes and the login ceiling +strix cloud session scopes set minimal # narrow without another browser sign-in +``` + +A workspace switch keeps the credential and its expiry, preserves the server-side scope preference, and caps access by the target role. A switch can never exceed the login consent ceiling. Each process pins the workspace it started with, so a concurrent switch fails safely instead of sending a stale command to another organization. + +## Commands + +Every operation of the [REST API](https://docs.app.strix.ai) has a matching command in the form `strix cloud `. + +```bash +strix cloud # list all resources +strix cloud scans # run the safe default (scans list) +strix cloud scans help # list the verbs of a resource +strix cloud domains add --domain example.com --asset-type web_app +strix cloud scans start --engagement-type live_test --domain-ids --wait +strix cloud vulns list --severity critical +strix cloud credits # credit balance +``` + +Write commands take request fields as flags. Every write command also accepts one JSON object with `--data`: + +```bash +strix cloud scans start --data '{"engagement_type":"code_review"}' # literal JSON +strix cloud scans start --data @request.json # read a file +cat request.json | strix cloud scans start --data - # read standard input +``` + +`--token` and `STRIX_API_TOKEN` are stateless overrides for a single command, and they never replace the stored sign-in. Pair a CLI-session override with `--workspace-id` or `STRIX_WORKSPACE_ID`. + +## Workspaces And Account Setup + +```bash +strix cloud workspaces list # numbered list; workspace is also accepted +strix cloud workspaces create --name "My Team" # needs admin and organizations:write +strix cloud workspaces use 2 # switch by list number, exact name, or ID +strix cloud billing topup --credits 20 --yes # approve an agent payment after HTTP 402 +strix cloud billing subscribe --plan strix_cloud # opens the hosted checkout page +strix cloud billing portal # opens the billing portal +strix cloud integrations install github # opens the app installation page +strix cloud domains verify # prints the DNS record to add +``` + +The last four commands end at a person. Strix creates the link, opens the browser for an interactive terminal, and always prints the URL. The user enters the card, approves the installation, or adds the DNS record. Pass `--no-browser` to print the URL only. + +## Output And Exit Codes + +The commands work for people and for agents. Terminal output favors names, branches, lifecycle states, and numbered selectors. Redirected output, and `--json`, preserve the complete machine-readable record. + +- Human lists keep the selectors that follow-up commands need, and they omit internal organization and user IDs. A selector that is too long for the compact table is repeated losslessly in a copyable block. +- Paginated lists print the next `--page` or `--offset`. Detail views keep useful prose within a safe terminal bound, so use `--json` for the complete record. +- Token lists separate API keys from named CLI device sessions. +- Binary downloads are the exception to JSON output. Redirect the raw bytes on purpose, or use `--output FILE --json` to write the file and receive structured download metadata. +- There are no prompts when stdin is not a terminal. + +Exit codes: `0` success, `1` error, `2` invalid usage, `4` authentication or plan limit, `5` payment required. + +## Credits And Plan Limits + +Non-Enterprise scans consume the deterministic estimate shown for their scope. A source-only code review at the default `ultra` tier currently starts at 60 credits. Enterprise scans are plan-included and do not consume the credit wallet. + +Report downloads need Enterprise, schedules need Pro, and billing writes need an admin token. A plan block exits `4`. An insufficient credit wallet exits `5` without the creation of a scan and without a charge. + +## Local Source Scans + +See [Scan Local Source](/cloud/overview#scan-local-source) for the upload approval flow, the exclusion rules, and the size limits. + +## Tab Completion + +Enable native tab completion once for each shell session: + +```bash +source <(strix completions zsh) # use bash instead of zsh when appropriate +strix completions fish | source +``` diff --git a/docs/docs.json b/docs/docs.json index 7573a0cd..e51d98af 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -25,7 +25,8 @@ "pages": [ "usage/cli", "usage/scan-modes", - "usage/instructions" + "usage/instructions", + "usage/viewer" ] }, { @@ -77,7 +78,8 @@ { "group": "Strix Cloud", "pages": [ - "cloud/overview" + "cloud/overview", + "cloud/cli" ] } ] diff --git a/docs/usage/viewer.mdx b/docs/usage/viewer.mdx new file mode 100644 index 00000000..147bbd0d --- /dev/null +++ b/docs/usage/viewer.mdx @@ -0,0 +1,49 @@ +--- +title: "Local Web Viewer" +description: "Browse a run in a local dashboard with strix view" +--- + +Every scan writes its results to disk as it runs. `strix view` serves those files in a local dashboard, for a live run or a finished one. + +```bash +strix view # the most recent run +strix view my-run-name # a specific run under ./strix_runs +strix view --host 0.0.0.0 --port 8080 --no-open +``` + +The UI ships prebuilt with Strix, so there is no extra install and no JavaScript build step. The dashboard reads the run files straight off disk. Nothing leaves your machine, and you do not need a cloud account. + +## Options + + + Run name under `./strix_runs`. Defaults to the most recent run. + + + + Host to bind to. Use `0.0.0.0` to reach the viewer from other machines. + + + + Port to serve on. The default selects an available ephemeral port. + + + + Do not open the browser automatically. + + +## What Is In The Dashboard + +- **Overview** — run status, target, and a severity breakdown of everything found so far. +- **Vulnerabilities** — each validated finding with its severity, details, and reproduction steps. +- **Agent graph** — a live map of the multi-agent team, and what each agent is doing. +- **Steering** — send instructions to a live scan to redirect the agents during the run. +- **History** — browse past runs on this machine and move between them. +- **Reports** — generate a shareable report and send it by email. + +## Sharing The Link + + + The token in the printed URL grants access to the run data, the history, and the steering of a live scan. Share it only with trusted users. + + +To reach the viewer from another machine, start it with `--host 0.0.0.0` and replace `0.0.0.0` in the printed URL with a reachable IP address or hostname. Restrict the port with your firewall. A request without the token-derived session cannot read run data.