Reduce OSS docs diff to STE fixes

2026-08-16 17:27:26 +02:00 · 2026-08-14 19:32:17 +00:00
parent 5e8a773f3e
commit cb3fa2db51
10 changed files with 50 additions and 65 deletions
@@ -3,13 +3,13 @@ title: "Skills"
 description: "Specialized knowledge packages that enhance agent capabilities"
 ---

-Skills are structured knowledge packages that give Strix agents specialized knowledge about vulnerability types, technologies, and testing methods.
+Skills are structured knowledge packages that give Strix agents deep expertise in specific vulnerability types, technologies, and testing methods.

 ## The Idea

 LLMs have broad but shallow security knowledge. They know _about_ SQL injection but lack the nuanced techniques that experienced pentesters use, such as parser quirks, bypass methods, validation tricks, and chain attacks.

-Skills inject specialized knowledge into the agent's context. This knowledge helps the agent specialize in the current task.
+Skills inject this deep, specialized knowledge directly into the agent's context, transforming it from a generalist into a specialist for the task at hand.

 ## How They Work

@@ -141,4 +141,4 @@ Community contributions are welcome. Create a `.md` file in the appropriate cate
 1. **Real-world techniques:** Methods that work in practice
 2. **Practical payloads:** Working examples with variations
 3. **Validation steps:** How to confirm without false positives
-4. **Context awareness:** Version and environment-specific behavior
+4. **Context awareness:** Version/environment-specific behavior
@@ -24,10 +24,10 @@ Skip the setup. Run Strix in the cloud at [app.strix.ai](https://app.strix.ai).

 ## What You Get

- **Penetration test reports:** Review validated findings and proofs of concept
+- **Penetration test reports:** Validated findings with PoCs
 - **Shareable dashboards:** Collaborate with your team
 - **CI/CD integration:** Block risky changes automatically
- **Continuous monitoring:** Find new vulnerabilities quickly
+- **Continuous monitoring:** Catch new vulnerabilities quickly

 ## Getting Started

@@ -64,7 +64,7 @@ Skills are specialized knowledge packages that enhance agent capabilities. They
 2. **Fork and branch:** Create a branch from `main`
 3. **Make changes:** Follow the existing code style
 4. **Write tests:** Add coverage for new features
-5. **Run checks:** Run `make check-all`
+5. **Run checks:** `make check-all` should pass
 6. **Submit a pull request:** Link to the issue and provide context

 ### Code Style
@@ -26,21 +26,21 @@ Strix agents are autonomous and act like real hackers. They run your code dynami

 ## Use Cases

- **Application Security Testing:** Detect and validate critical application vulnerabilities
- **Rapid Penetration Testing:** Complete penetration tests in hours, not weeks
- **Bug Bounty Automation:** Automate research and generate PoCs for faster reports
+- **Application Security Testing:** Detect and validate critical vulnerabilities in your applications
+- **Rapid Penetration Testing:** Get penetration tests done in hours, not weeks
+- **Bug Bounty Automation:** Automate research and generate PoCs for faster reporting
 - **CI/CD Integration:** Block vulnerabilities before they reach production

 ## Key Capabilities

- **Security toolkit:** Browser automation, HTTP proxy, terminal, and Python runtime
- **Finding validation:** Proofs of concept help reduce false positives
+- **Full hacker toolkit:** Browser automation, HTTP proxy, terminal, Python runtime
+- **Real validation:** PoCs, not false positives
 - **Multi-agent orchestration:** Specialized agents collaborate on complex targets
- **Developer-focused CLI:** Use the interactive TUI or headless mode
+- **Developer-first CLI:** Interactive TUI or headless mode for automation

 ## Security Tools

-Strix agents include a complete security toolkit:
+Strix agents include a comprehensive toolkit:

 | Tool | Purpose |
 |------|---------|
@@ -65,10 +65,10 @@ Strix agents include a complete security toolkit:

 ## Multi-Agent Architecture

-Strix uses a graph of specialized agents for complete security testing:
+Strix uses a graph of specialized agents for comprehensive security testing:

- **Distributed Workflows:** Specialized agents test different attacks and assets
- **Scalable Testing:** Parallel execution provides broad coverage
+- **Distributed Workflows:** Specialized agents for different attacks and assets
+- **Scalable Testing:** Parallel execution for fast comprehensive coverage
 - **Dynamic Coordination:** Agents collaborate and share discoveries

 ## Quick Example
@@ -85,6 +85,6 @@ jobs:
 All CI platforms require Docker access. Your runner must have Docker available.
 </Note>

-<Tip>
+<Note>
 If diff-scope fails in CI, full git history is required for merge-base and branch comparison. In GitHub Actions, use `fetch-depth: 0`.
-</Tip>
+</Note>
@@ -7,7 +7,7 @@ Strix is built to be driven by AI coding agents. Install the official agent skil

 ## Install the Skills

-These skills work with agents that support the open [SKILL.md standard](https://agentskills.io), including Claude Code, Cursor, Codex, Gemini CLI, and OpenCode:
+Works with any agent that supports the open [SKILL.md standard](https://agentskills.io), including Claude Code, Cursor, Codex, Gemini CLI, OpenCode, and dozens more:

 ```bash
 npx skills add usestrix/strix
@@ -15,8 +15,8 @@ npx skills add usestrix/strix

 | Skill | What your agent learns |
 |-------|------------------------|
-| `penetration-testing-with-strix` | Run headless scans against code, URLs, domains, or IP addresses with the self-hosted CLI or the managed cloud, apply budget caps, and read the results |
-| `managed-pentesting-with-strix` | Use the managed [app.strix.ai](https://app.strix.ai) platform through REST without local Docker or an LLM key |
+| `penetration-testing-with-strix` | Run headless scans against code, URLs, domains, or IPs: self-hosted CLI or managed cloud: with budget caps, and read the results |
+| `managed-pentesting-with-strix` | Drive the managed [app.strix.ai](https://app.strix.ai) platform over REST: no local Docker or LLM key needed |
 | `fix-security-vulnerabilities-with-strix` | Triage findings, fix root causes, and re-run Strix to verify each fix |
 | `ci-security-scanning-with-strix` | Add PR security scanning to GitHub Actions or any CI (self-hosted CLI or managed app) |

@@ -26,12 +26,12 @@ Install a single skill with `npx skills add usestrix/strix --skill penetration-t
 npx skills use usestrix/strix@penetration-testing-with-strix | claude
 ```

-## Two Ways to Run Strix
+## Two ways to run: self-hosted or managed

-Both options provide machine-readable results. Choose the option that fits your environment.
+Both use the same engine and produce the same validated findings and SARIF. Agents can pick per situation or combine them.

- **Open-source CLI (self-hosted):** Runs locally in a Docker sandbox with your LLM key. This option is free, local, and air-gap capable.
- **Managed cloud:** Runs on Strix infrastructure through the [app.strix.ai REST API](https://docs.app.strix.ai). This option needs no Docker, LLM key, or local installation. The Enterprise plan adds dashboards, scheduling, pull request reviews, and PDF or DOCX reports.
+- **Open-source CLI (self-hosted):** Runs locally in a Docker sandbox with your LLM key. It is free, fully local, and air-gap capable. It suits local development loops and full control.
+- **Managed cloud:** Runs on Strix infrastructure through the [app.strix.ai REST API](https://docs.app.strix.ai). It needs no Docker, LLM key, or local installation. The Enterprise plan adds dashboards, scheduling, pull request reviews, and PDF or DOCX reports. It suits sandboxed or CI environments and teams.

 Create a managed API token under **Settings > API Access**. The `managed-pentesting-with-strix` skill documents the full flow.

@@ -40,23 +40,8 @@ Create a managed API token under **Settings > API Access**. The `managed-pentest
 Everything an agent needs is machine-readable:

 - **Headless CLI:** `strix -n` runs without the TUI. It exits with `0` for a clean scan, `1` for an error, or `2` for vulnerabilities.
- **REST API:** The managed platform exposes a documented [OpenAPI](https://docs.app.strix.ai/openapi.json) at `https://app.strix.ai/api/v1`.
-  The API supports:
-  - scans
-  - vulnerabilities
-  - assets
-  - pull request reviews
-  - schedules
-  - webhooks
-
-  The API uses bearer tokens and scopes.
- **Structured results:** Each self-hosted run writes these files under `strix_runs/<run-name>/`:
-  - `vulnerabilities.json`
-  - `vulnerabilities.csv`
-  - `findings.sarif` in SARIF 2.1.0 format
-  - Per-finding Markdown files
-
-  The cloud exposes the same data as JSON and provides SARIF export.
+- **REST API:** The managed platform exposes a documented [OpenAPI](https://docs.app.strix.ai/openapi.json) at `https://app.strix.ai/api/v1`. It supports scans, vulnerabilities, assets, pull request reviews, schedules, and webhooks. The API uses bearer tokens and scopes.
+- **Structured results:** Each self-hosted run writes `vulnerabilities.json`, `vulnerabilities.csv`, and `findings.sarif` in SARIF 2.1.0 format. It also writes per-finding Markdown under `strix_runs/<run-name>/`. The cloud exposes the same data as JSON and provides SARIF export.
 - **Budget controls:** `--max-budget` and `--max-turns` set cost and turn limits.
 - **`AGENTS.md`:** The [repository's agent guide](https://github.com/usestrix/strix/blob/main/AGENTS.md) provides a quick reference.
 - **`llms.txt`:** The index is available at [docs.strix.ai/llms.txt](https://docs.strix.ai/llms.txt). The full export is available at [docs.strix.ai/llms-full.txt](https://docs.strix.ai/llms-full.txt). Every page is also available as Markdown by appending `.md` to its URL.
@@ -5,7 +5,7 @@ description: "Run Strix with self-hosted LLMs for privacy and air-gapped testing

 Running Strix with local models allows for completely offline, privacy-first security assessments. Data never leaves your machine, making this ideal for sensitive internal networks or air-gapped environments.

-## Privacy Versus Performance
+## Privacy vs Performance

 | Feature | Local Models | Cloud Models (GPT-5/Claude 4.5) |
 |---------|--------------|--------------------------------|
@@ -15,9 +15,9 @@ Running Strix with local models allows for completely offline, privacy-first sec
 | **Setup** | Complex (GPU required) | Instant |

 <Warning>
-**Compatibility Note**: Strix requires advanced agent capabilities, including tool use, multi-step planning, and self-correction. Most local models under 70B parameters struggle with these tasks.
+**Compatibility Note**: Strix relies on advanced agentic capabilities (tool use, multi-step planning, self-correction). Most local models, especially those under 70B parameters, struggle with these complex tasks.

-Critical assessments often require capable cloud models, such as Claude 4.5 Sonnet or GPT-5. Local models suit assessments where privacy has priority.
+For critical assessments, use state-of-the-art cloud models such as **Claude 4.5 Sonnet** or **GPT-5**. Use local models only when privacy is the absolute priority.
 </Warning>

 ## Ollama
@@ -39,7 +39,7 @@ Critical assessments often require capable cloud models, such as Claude 4.5 Sonn

 ### Recommended Models

-We recommend these models for a good balance of reasoning and tool use:
+We recommend these models for the best balance of reasoning and tool use:
 - **Qwen3 VL** (`ollama pull qwen3-vl`)
 - **DeepSeek V3.1** (`ollama pull deepseek-v3.1`)
 - **Devstral 2** (`ollama pull devstral-2`)
@@ -72,7 +72,7 @@ verification against a real endpoint.

 ## Tool calling must return structured `tool_calls`

-Strix requires a **native** function or tool call during each working turn. If the inference server returns plain assistant text, Strix cannot execute the call. The agent then requests another tool call and stops after its recovery attempts end.
+Strix is entirely tool-driven. Every working turn must be a **native** function or tool call. If the inference server returns the call as plain assistant text, Strix never sees a call it can execute. The agent makes no real progress and gives up after its recovery attempts end.

 This is almost always an **inference-server configuration** problem, not a model or Strix problem. Common symptoms are the model printing a call as text such as:

@@ -82,19 +82,19 @@ exec_command(cmd="nmap ...", timeout=180)
 {"action": "exec_command", "params": {"cmd": "nmap ..."}}
 ```

-Configure the inference server to parse tool tokens into structured `tool_calls`. A configured endpoint returns a structured call or rejects the request. It does not return the call as text.
+The fix belongs on the inference server. It must be configured to parse the model's tool tokens into structured `tool_calls`. A correctly configured endpoint either returns a structured call or rejects the request outright. It never leaks the call as text.

 ### Fixes by server

 **llama.cpp (`llama-server`)**
- Run with `--jinja` and a tool-use chat template that matches the model. Recent builds enable `--jinja` by default. Upgrade if yours does not.
- For thinking models, align or disable reasoning with `--reasoning-format` or `-rea off`.
- Set a low temperature, such as `--temp 0.2`, to improve tool-call reliability.
+- Run with `--jinja` and a correct tool-use chat template (`--chat-template` or `--chat-template-file` matching the model). Recent builds enable `--jinja` by default. Upgrade if yours does not.
+- For thinking models, align or disable reasoning (`--reasoning-format` or `-rea off`) so it does not break tool-call parsing.
+- A low temperature, such as `--temp 0.2`, improves tool-call reliability.

 **Ollama**
- Use a recent Ollama version and a model whose template supports tools. Ollama returns `tools param requires --jinja flag` when the template lacks tool support.
- For reasoning models such as qwen3, disable **thinking** mode. Thinking mode can move tool calls into `content` instead of `tool_calls`. Disable it in Ollama with a non-thinking model or `think: false` in the model parameters or `Modelfile`.
- Raise **`num_ctx`** to a value between 16k and 32k, or higher. Strix sends a large system prompt and many tool schemas. A small context can truncate the tool definitions and stop valid calls. A short test prompt can look fine while a real scan fails.
+- Use a recent Ollama and a model whose template wires tools. Modern Ollama returns `tools param requires --jinja flag` if the template lacks tool support.
+- For reasoning models such as qwen3, disable the model's **thinking** mode. Thinking left on can push the tool call into `content` instead of the structured `tool_calls` field. Turn it off on the Ollama side with a non-thinking model variant, `think: false` in the model's parameters, or `Modelfile`.
+- Raise **`num_ctx`** to at least 16k to 32k. Strix sends a large system prompt plus many tool schemas. At Ollama's small default context, the tool definitions can be truncated from the prompt. The model can then stop emitting valid calls. A short test prompt can look fine while a real scan fails. Set this explicitly instead of inferring it from a quick check.

 **vLLM**
 - Start with `--enable-auto-tool-choice`, a matching `--tool-call-parser` (`hermes`, `qwen3_xml`, or `llama3_json`), and a matching `--reasoning-parser` for reasoning models.
@@ -3,7 +3,7 @@ title: "HTTP Proxy"
 description: "Caido-powered proxy for request interception and replay"
 ---

-Strix includes [Caido](https://caido.io), a modern HTTP proxy for security testing. Strix routes browser traffic through Caido, so the agent can inspect and modify requests and responses.
+Strix includes [Caido](https://caido.io), a modern HTTP proxy built for security testing. All browser traffic flows through Caido, giving the agent full control over requests and responses.

 ## Capabilities

@@ -70,7 +70,7 @@ asyncio.run(main())
 | `view_sitemap_entry()` | Inspect one sitemap entry + its related requests |
 | `scope_rules()`        | Manage proxy scope (allowlist/denylist)    |

-For one-off requests, use shell tools such as `curl`.
+For one-off arbitrary requests, use shell tools such as `curl`.
 The sandbox routes traffic through Caido with the `HTTP_PROXY` variable.
 Caido then adds each request to `list_requests` for replay through `repeat_request`.

@@ -105,7 +105,7 @@ asyncio.run(main())

 ## Human-in-the-Loop

-Strix exposes the Caido proxy to the host machine during automated scans. The TUI displays the Caido URL in the sidebar. Click the URL to copy it, then open it in Caido Desktop.
+Strix exposes the Caido proxy to your host machine, so you can interact with it alongside the automated scan. When the sandbox starts, the Caido URL is displayed in the TUI sidebar. Click the URL to copy it, then open it in Caido Desktop.

 ### Accessing Caido

@@ -116,13 +116,13 @@ Strix exposes the Caido proxy to the host machine during automated scans. The TU

 ### What You Can Do

- **Inspect traffic:** Browse HTTP/HTTPS requests that the agent makes
- **Replay requests:** Resend captured requests after you modify them
- **Intercept and modify:** Pause requests, edit them, and forward them
- **Explore the sitemap:** Review the attack surface that the agent discovered
- **Manual testing:** Use Caido tools to test reported findings or unexplored areas
+- **Inspect traffic:** Browse all HTTP/HTTPS requests the agent is making in real time
+- **Replay requests:** Take any captured request and resend it with your own modifications
+- **Intercept and modify:** Pause requests mid-flight, edit them, then forward
+- **Explore the sitemap:** See the full attack surface the agent has discovered
+- **Manual testing:** Use Caido's tools to test findings the agent reports, or explore areas it has not reached

-Strix supports collaborative testing. The agent performs automated work while you investigate important areas.
+Strix is a collaborative tool, not only a fully automated scanner. The agent handles the heavy lifting while you focus on the interesting parts.

 ## Scope

@@ -3,7 +3,7 @@ title: "Sandbox Tools"
 description: "Pre-installed security tools in the Strix container"
 ---

-Strix runs inside a Kali Linux-based Docker container with a complete set of security tools. The agent can use these tools through the [terminal](/tools/terminal).
+Strix runs inside a Kali Linux-based Docker container with a comprehensive set of security tools pre-installed. The agent can use any of these tools through the [terminal](/tools/terminal).

 ## Reconnaissance

@@ -3,7 +3,7 @@ title: "Scan Modes"
 description: "Choose the right scan depth for your use case"
 ---

-Strix offers three scan modes to balance speed and coverage.
+Strix offers three scan modes to balance speed and thoroughness.

 ## Quick