From 9acdad382d8343196e87bd59c6ec1b2aa0a79dd2 Mon Sep 17 00:00:00 2001 From: Alex Schapiro Date: Tue, 28 Jul 2026 03:58:58 +0000 Subject: [PATCH] =?UTF-8?q?feat:=20agent-ready=20=E2=80=94=20installable?= =?UTF-8?q?=20SKILL.md=20skills,=20AGENTS.md,=20coding-agents=20docs?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- AGENTS.md | 39 +++++++++++++ README.md | 12 ++++ docs/docs.json | 3 +- docs/integrations/coding-agents.mdx | 52 +++++++++++++++++ skills/strix-ci-setup/SKILL.md | 74 +++++++++++++++++++++++++ skills/strix-fix-findings/SKILL.md | 52 +++++++++++++++++ skills/strix-pentest/SKILL.md | 86 +++++++++++++++++++++++++++++ 7 files changed, 317 insertions(+), 1 deletion(-) create mode 100644 AGENTS.md create mode 100644 docs/integrations/coding-agents.mdx create mode 100644 skills/strix-ci-setup/SKILL.md create mode 100644 skills/strix-fix-findings/SKILL.md create mode 100644 skills/strix-pentest/SKILL.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 000000000..234cdc90a --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,39 @@ +# Strix — Agent Guide + +Strix is an open-source autonomous AI pentesting tool. This file is for AI coding agents that want to **use** Strix (run security scans) or **contribute** to it. + +## Using Strix from an agent + +Install the agent skills for step-by-step workflows: + +```bash +npx skills add usestrix/strix +``` + +- `strix-pentest` — run a headless pentest against code, URLs, domains, or IPs and read results +- `strix-fix-findings` — remediate findings and re-run Strix to verify +- `strix-ci-setup` — add diff-scoped PR scanning to CI/CD + +Quick reference (details in the skills and https://docs.strix.ai): + +```bash +curl -sSL https://strix.ai/install | bash # install +export STRIX_LLM="openai/gpt-5.4" # any LiteLLM model id +export LLM_API_KEY="" +strix -n -t ./ --scan-mode quick --max-budget 10 # headless scan; always use -n +``` + +- Requires Docker running. Scans take minutes (`quick`) to hours (`deep`) — run in the background. +- Exit codes (headless): `0` clean, `1` fatal error, `2` vulnerabilities found. +- Artifacts in `strix_runs//`: `penetration_test_report.md`, `vulnerabilities/*.md`, `vulnerabilities.json`, `findings.sarif` (SARIF 2.1.0), `run.json`. +- Docs index for LLMs: https://docs.strix.ai/llms.txt (full: https://docs.strix.ai/llms-full.txt). +- Only scan targets the user is authorized to test. + +## Contributing to this repo + +- Python 3.12+, managed with `uv`. Install dev deps: `make dev-install`. +- Lint/format/type-check/security, all in one: `make check-all` (ruff, mypy, bandit). +- Tests: `uv run pytest`. +- Run from source: `uv run strix --target `. +- Layout: `strix/agents` (agent graph + prompts), `strix/tools` (proxy, browser, terminal, scanners), `strix/runtime` (Docker sandbox), `strix/report` (findings, SARIF), `strix/skills` (internal knowledge packs the pentest agents load — different from the consumer skills in `skills/`), `strix/interface` (CLI/TUI), `containers/` (sandbox image). +- Pre-commit hooks: `make pre-commit` (or `uv run pre-commit install`). diff --git a/README.md b/README.md index 982a635de..f8d67d48b 100644 --- a/README.md +++ b/README.md @@ -94,6 +94,18 @@ strix --target ./app-directory --- +## 🤖 Use Strix from Your Coding Agent + +Strix is agent-ready. Give Claude Code, Cursor, Codex, or any [SKILL.md-compatible](https://agentskills.io) agent the ability to run pentests, fix findings, and set up CI scanning: + +```bash +npx skills add usestrix/strix +``` + +This installs three skills: **strix-pentest** (run headless scans and read results), **strix-fix-findings** (remediate + re-scan to verify), and **strix-ci-setup** (diff-scoped PR scanning in CI). Agents can also read [`AGENTS.md`](AGENTS.md) for a quick reference and [docs.strix.ai/llms.txt](https://docs.strix.ai/llms.txt) for the full docs index. + +--- + ## ☁️ Strix Platform Try the Strix full-stack penetration testing platform at **[app.strix.ai](https://app.strix.ai)** - sign up for free, connect your repos and domains, and launch a pentest in minutes. diff --git a/docs/docs.json b/docs/docs.json index 23cf23867..de23c1586 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -46,7 +46,8 @@ "group": "Integrations", "pages": [ "integrations/github-actions", - "integrations/ci-cd" + "integrations/ci-cd", + "integrations/coding-agents" ] }, { diff --git a/docs/integrations/coding-agents.mdx b/docs/integrations/coding-agents.mdx new file mode 100644 index 000000000..66dc4da64 --- /dev/null +++ b/docs/integrations/coding-agents.mdx @@ -0,0 +1,52 @@ +--- +title: "Coding Agents" +description: "Use Strix from Claude Code, Cursor, Codex, and other AI agents" +--- + +Strix is built to be driven by AI coding agents. Install the official agent skills and your agent knows how to run pentests, remediate findings, and wire Strix into CI. + +## Install the Skills + +Works with any agent that supports the open [SKILL.md standard](https://agentskills.io) — Claude Code, Cursor, Codex, Gemini CLI, OpenCode, and dozens more: + +```bash +npx skills add usestrix/strix +``` + +| Skill | What your agent learns | +|-------|------------------------| +| `strix-pentest` | Run headless scans against code, URLs, domains, or IPs with budget caps, and read the results | +| `strix-fix-findings` | Triage findings, fix root causes, and re-run Strix to verify each fix | +| `strix-ci-setup` | Add diff-scoped PR security scanning to GitHub Actions or any CI | + +Install a single skill with `npx skills add usestrix/strix --skill strix-pentest`, or use one without installing: + +```bash +npx skills use usestrix/strix@strix-pentest | claude +``` + +## Agent-Friendly Interfaces + +Everything an agent needs is machine-readable: + +- **Headless CLI** — `strix -n` runs without the TUI and exits with `0` (clean), `1` (error), or `2` (vulnerabilities found). +- **Structured results** — every run writes `vulnerabilities.json`, `vulnerabilities.csv`, `findings.sarif` (SARIF 2.1.0), and per-finding Markdown under `strix_runs//`. +- **Budget controls** — `--max-budget` and `--max-turns` give agents hard cost/time caps. +- **`AGENTS.md`** — the [repository's agent guide](https://github.com/usestrix/strix/blob/main/AGENTS.md) with a quick reference. +- **`llms.txt`** — this documentation is indexed at [docs.strix.ai/llms.txt](https://docs.strix.ai/llms.txt) and fully exported 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. + +## Example Prompts + +Once the skills are installed, prompts like these just work: + +```text +Pentest this repo with Strix (quick mode, $10 budget) and summarize the findings. +``` + +```text +Fix all critical and high findings from the last Strix run, then re-scan to verify. +``` + +```text +Add Strix security scanning to our GitHub Actions so every PR gets tested. +``` diff --git a/skills/strix-ci-setup/SKILL.md b/skills/strix-ci-setup/SKILL.md new file mode 100644 index 000000000..b7006c9e9 --- /dev/null +++ b/skills/strix-ci-setup/SKILL.md @@ -0,0 +1,74 @@ +--- +name: strix-ci-setup +description: Wire Strix security scanning into CI/CD — GitHub Actions, GitLab CI, or any pipeline — so every pull request gets a diff-scoped AI pentest that blocks vulnerable code. Use when the user asks to add security scanning, pentesting, or Strix to their CI pipeline or PR workflow. +license: Apache-2.0 +metadata: + author: usestrix + homepage: https://docs.strix.ai +--- + +# Set up Strix in CI/CD + +Run a diff-scoped Strix scan on every PR: only changed files are tested, `quick` mode keeps it fast, and exit code `2` fails the build when validated vulnerabilities are found. + +## GitHub Actions + +Create `.github/workflows/security.yml`: + +```yaml +name: Security Scan + +on: + pull_request: + +jobs: + strix-scan: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + with: + fetch-depth: 0 # required for diff-scope resolution + + - name: Install Strix + run: curl -sSL https://strix.ai/install | bash + + - name: Run Security Scan + env: + STRIX_LLM: ${{ secrets.STRIX_LLM }} + LLM_API_KEY: ${{ secrets.LLM_API_KEY }} + run: strix -n -t ./ --scan-mode quick --max-budget 10 +``` + +Then tell the user to add two repository secrets: `STRIX_LLM` (model id, e.g. `openai/gpt-5.4`) and `LLM_API_KEY` (the provider key). Do not create these values yourself. + +Notes: +- In CI/headless runs Strix automatically scopes to the PR's changed files (`--scope-mode auto`). If diff resolution fails, keep `fetch-depth: 0` or pass `--diff-base origin/main`. +- Exit codes: `0` pass, `2` vulnerabilities found (fails the job), `1` setup error. +- The runner needs Docker (default GitHub-hosted Ubuntu runners have it). + +### Optional: upload findings to GitHub code scanning + +Strix writes SARIF 2.1.0 to `strix_runs//findings.sarif`: + +```yaml + - name: Upload SARIF + if: always() + uses: github/codeql-action/upload-sarif@v3 + with: + sarif_file: strix_runs +``` + +## Other CI systems + +Any pipeline works the same way — install, set the two env vars, run headless: + +```bash +curl -sSL https://strix.ai/install | bash +strix -n -t ./ --scan-mode quick --scope-mode diff --diff-base origin/main --max-budget 10 +``` + +Gate the pipeline on the exit code. Schedule `standard` scans nightly and `deep` scans for release candidates. + +## Hosted alternative + +If the user prefers zero CI setup, the managed platform at https://app.strix.ai reviews every PR via the GitHub/GitLab/Bitbucket app with no workflow file or LLM key required. diff --git a/skills/strix-fix-findings/SKILL.md b/skills/strix-fix-findings/SKILL.md new file mode 100644 index 000000000..9c83cc441 --- /dev/null +++ b/skills/strix-fix-findings/SKILL.md @@ -0,0 +1,52 @@ +--- +name: strix-fix-findings +description: Triage and remediate vulnerabilities found by a Strix pentest, then re-run Strix to verify each fix. Use after a Strix scan reports findings, or when the user asks to fix security issues from a strix_runs report, vulnerabilities.json, or findings.sarif. +license: Apache-2.0 +metadata: + author: usestrix + homepage: https://docs.strix.ai +--- + +# Fix Strix findings and verify + +Turn validated Strix findings into minimal, correct fixes — and prove they work by re-scanning. + +## 1. Triage + +Read the artifacts in `strix_runs//`: + +- `vulnerabilities/*.md` — one finding per file: description, severity, PoC steps or script, affected code locations, remediation guidance. +- `vulnerabilities.json` — the same findings as JSON (ids, severity, CWE/CVE, `code_locations` with `fix_before`/`fix_after` suggestions when available). + +Order work by severity: critical → high → medium → low. Every Strix finding was validated with a working proof-of-concept, so do not dismiss findings as false positives without re-testing the PoC yourself. + +## 2. Fix + +For each finding: + +1. Reproduce it with the PoC from the finding file when feasible. +2. Fix the root cause, not the specific payload (e.g. parameterize all queries, don't blocklist one string; enforce authorization in the handler, don't hide the endpoint). +3. Prefer the framework's built-in defense (ORM parameterization, template auto-escaping, CSRF middleware, centralized authz) over ad-hoc sanitization. +4. Keep the diff minimal and apply the repo's existing patterns. Finding files often include `fix_before`/`fix_after` snippets — use them as a starting point, not verbatim. + +Common finding classes and expected fixes: injection → parameterization/escaping at the sink; IDOR/broken access control → object-level authorization checks; SSRF → allowlist + block internal ranges; XSS → context-aware output encoding + CSP; secrets exposure → rotate the secret AND remove it from code/history; auth issues → fix the server-side check (never client-side). + +## 3. Verify by re-running Strix + +After fixing, re-run Strix scoped to the fixed area and confirm the finding is gone: + +```bash +# Re-test just the changed files (fast) +strix -n -t ./ --scan-mode quick --scope-mode diff --diff-base origin/main --max-budget 5 + +# Or re-test with the original finding as focus +strix -n -t ./ --instruction "Verify the SQL injection in app/api/search.py is fixed. Original PoC: " --max-budget 5 +``` + +- Exit code `0` = clean; `2` = findings remain (read the new `strix_runs//vulnerabilities/` and iterate). +- Also re-run the PoC manually when it is a simple request/script — fastest signal. +- Run the project's own test suite to make sure the fix doesn't break behavior. + +## 4. Report + +Summarize per finding: severity, root cause, fix applied (file:line), verification result (re-scan clean / PoC no longer reproduces). Never include live secrets in the report; if a secret leaked, state that rotation is required. diff --git a/skills/strix-pentest/SKILL.md b/skills/strix-pentest/SKILL.md new file mode 100644 index 000000000..9217dd05c --- /dev/null +++ b/skills/strix-pentest/SKILL.md @@ -0,0 +1,86 @@ +--- +name: strix-pentest +description: Run an autonomous AI penetration test with the Strix CLI against a local codebase, repository, URL, domain, or IP — headlessly, with cost/turn budgets — and read the validated findings (Markdown, JSON, CSV, SARIF) from the run directory. Use when the user asks to pentest, security-scan, or find vulnerabilities in an app, API, website, or repo with Strix. +license: Apache-2.0 +metadata: + author: usestrix + homepage: https://docs.strix.ai +--- + +# Run a Strix pentest + +Strix runs autonomous AI pentesting agents in an isolated Docker sandbox. They dynamically exploit the target and only report findings validated with a working proof-of-concept. + +## Prerequisites + +1. **Docker running** — check with `docker info`. The first scan pulls the sandbox image automatically. +2. **Strix installed** — check with `strix --version`. Install if missing: + ```bash + curl -sSL https://strix.ai/install | bash # or: pipx install strix-agent + ``` +3. **LLM configured** — two environment variables: + ```bash + export STRIX_LLM="openai/gpt-5.4" # any LiteLLM model id (openai/..., anthropic/..., openrouter/...) + export LLM_API_KEY="" + ``` + Ask the user for these if unset. Never hardcode or commit keys. + +## Running a scan + +Always use `-n` (non-interactive/headless) when you run Strix — the default TUI blocks agents. Always set `--max-budget` unless the user says otherwise. + +```bash +# Local code (white-box) +strix -n -t ./ --scan-mode standard --max-budget 10 + +# Deployed app / API (black-box) +strix -n -t https://staging.example.com --max-budget 20 + +# Repo + deployed app together (best coverage) +strix -n -t https://github.com/org/app -t https://staging.example.com + +# Focused testing with credentials or scope hints +strix -n -t https://app.example.com \ + --instruction "Use credentials user@example.com:pass123. Focus on IDOR and auth bypass." + +# Large monorepo: bind-mount instead of copying +strix -n --mount ./huge-monorepo +``` + +Key flags: + +| Flag | Meaning | +|---|---| +| `-t, --target` | URL, repo URL, local path, domain, or IP. Repeatable. | +| `-n, --non-interactive` | Headless, exits on completion. Required for agents. | +| `-m, --scan-mode` | `quick` (minutes) / `standard` (~30 min) / `deep` (hours, default). | +| `--instruction` / `--instruction-file` | Credentials, focus areas, scope rules. | +| `--max-budget USD` | Hard LLM spend cap; scan wraps up cleanly at the limit. | +| `--max-turns N` | Per-agent turn cap (default 500). | +| `--resume RUN_NAME` | Resume a prior run from `strix_runs/`. | + +Scans take minutes (`quick`) to hours (`deep`). Run them in the background and poll for completion rather than blocking. + +## Exit codes (headless) + +- `0` — scan completed, no vulnerabilities +- `1` — fatal error (missing env vars, Docker down, bad config) +- `2` — vulnerabilities found + +## Reading results + +Artifacts land in `strix_runs//`: + +| File | Contents | +|---|---| +| `penetration_test_report.md` | Executive report — read this first. | +| `vulnerabilities/*.md` | One file per validated finding, with PoC and remediation. | +| `vulnerabilities.json` / `vulnerabilities.csv` | All findings as structured JSON / CSV index. | +| `findings.sarif` | SARIF 2.1.0 for GitHub code scanning / ASPM ingestion. | +| `run.json` | Run metadata, status, targets, usage/cost. | + +Summarize findings by severity (critical/high/medium/low/info) and include the PoC evidence when reporting to the user. To fix the findings, use the `strix-fix-findings` skill. + +## Safety + +Only scan targets the user owns or is authorized to test. If the target looks like third-party infrastructure, confirm authorization first.