open-sploit 1.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 open-sploit contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,75 @@
+# open-sploit
+
+> YOLO offensive-security agent + `/target` engagement command for [opencode](https://opencode.ai). Full-scope pen-testing through **Kali Linux (WSL2)**, **Burp Suite MCP**, and **Playwright**.
+
+## What you get
+
+- **`offsec` agent** — pure offensive operator: recon → enumeration → exploitation → post-exploitation → report. No defensive fluff.
+- **`/target <url>` command** — one slash command to run a full engagement end to end. It classifies the target (web / API / PHP) and auto-loads the matching attack skills.
+- **19 attack skills** installed into `~/.config/opencode/skills/` — battle-tested technique playbooks for every major web vulnerability class.
+- **YOLO permissions** — every action auto-approved (read/edit/bash/external dirs/web).
+- **Kali (WSL2) routing** — all tooling runs through `wsl -d kali-linux` (nmap, sqlmap, metasploit, ffuf, hashcat, impacket, …).
+- **Playwright MCP** — real browser for login flows, session/auth handling, CSRF, XSS, SSO/OAuth, DOM bugs, screenshot evidence.
+- **Burp MCP** (auto-detected on Windows) — interception, scanning, repeater attack flows.
+
+## Installed skill library
+
+| Category | Skills |
+| --- | --- |
+| Frameworks | `web-app-penetration-testing`, `owasp-top-10-testing`, `api-security-testing`, `conducting-api-security-testing`, `hackerone` |
+| Injection | `exploiting-sql-injection-vulnerabilities`, `exploiting-sql-injection-with-sqlmap`, `exploiting-nosql-injection-vulnerabilities`, `exploiting-api-injection-vulnerabilities`, `exploiting-template-injection-vulnerabilities` |
+| Server-side risk | `exploiting-server-side-request-forgery`, `exploiting-http-request-smuggling`, `exploiting-websocket-vulnerabilities`, `exploiting-race-condition-vulnerabilities` |
+| Access control | `exploiting-idor-vulnerabilities`, `exploiting-prototype-pollution-in-javascript` |
+| Auth & tokens | `exploiting-jwt-algorithm-confusion-attack`, `exploiting-oauth-misconfiguration`, `exploiting-type-juggling-vulnerabilities` |
+
+The `/target` command auto-routes: web target → injection/SSRF/smuggling/access-control skills, API target → API skills, PHP backend → type-juggling, and any bug-bounty flow → `hackerone`.
+
+## Install
+
+```bash
+npx open-sploit
+```
+
+It copies `agent/offsec.md` + `command/target.md` into `~/.config/opencode/`, installs the 19 attack skills into `~/.config/opencode/skills/` (skipping any you already have), and safely merges permissions, the `offsec` agent, and MCP servers into your `opencode.json`. Your existing config is preserved — only missing/permission keys are added.
+
+Then **restart opencode**.
+
+### Prerequisites
+
+- [opencode](https://opencode.ai) installed
+- [Kali Linux in WSL2](https://www.kali.org/docs/wsl/) with distro name `kali-linux` (Windows) — or any host with `wsl` + Kali
+- `npx` (comes with Node.js ≥ 18)
+- Optional: [Burp Suite](https://portswigger.net/burp) with the MCP server extension on `127.0.0.1:9876`
+
+## Usage
+
+```bash
+/target http://10.10.10.10
+# or
+/target example.com — scope: *.example.com, in-scope only
+# or
+/target https://api.example.com/openapi.json
+```
+
+The agent classifies the target, auto-loads the matching attack skills, then runs the full pipeline: OSINT → nmap/masscan → ffuf/gobuster → browser-assisted auth & client-side testing → exploit → collect flags/creds → ranked report with PoCs and screenshots.
+
+## Uninstall
+
+```bash
+rm -rf ~/.config/opencode/skills ~/.config/opencode/agent/offsec.md ~/.config/opencode/command/target.md
+```
+
+Then remove the `offsec` entry and added `mcp` servers from `~/.config/opencode/opencode.json`.
+
+## Customizing
+
+- Point Kali tools at a different distro: rename `kali-linux` in `agent/offsec.md`.
+- Burp proxy at `127.0.0.1:9876` by default — edit the `burp` MCP entry in `opencode.json` if yours differs.
+
+## ⚠️ Legal
+
+This installs **YOLO allow-all permissions** and an **offensive-security automation**. Only use it against systems you own or have **explicit written authorization** to test. Unauthorized access is a crime in most jurisdictions. The authors are not responsible for misuse.
+
+## License
+
+MIT

package/bin/install.mjs

@@ -0,0 +1,158 @@
+#!/usr/bin/env node
+import { homedir, platform } from "node:os"
+import { join, dirname } from "node:path"
+import { fileURLToPath } from "node:url"
+import { mkdirSync, copyFileSync, readFileSync, writeFileSync, existsSync, readdirSync, statSync, cpSync } from "node:fs"
+
+const __dirname = dirname(fileURLToPath(import.meta.url))
+const TEMPLATE = join(__dirname, "..", "template")
+
+const configRoot = process.env.OPENCODE_CONFIG_DIR
+  ? join(process.env.OPENCODE_CONFIG_DIR)
+  : join(homedir(), platform() === "win32" ? ".config\\opencode" : ".config/opencode")
+
+const agentDir = join(configRoot, "agent")
+const commandDir = join(configRoot, "command")
+const skillsDir = join(configRoot, "skills")
+const configFile = join(configRoot, "opencode.json")
+
+function log(msg) { console.log(`[open-sploit] ${msg}`) }
+
+function installSkills() {
+  const srcSkills = join(TEMPLATE, "skills")
+  if (!existsSync(srcSkills)) return 0
+  const autoDirs = [
+    join(homedir(), ".agents", "skills"),
+    join(homedir(), ".claude", "skills"),
+  ]
+  let installed = 0
+  for (const skill of readdirSync(srcSkills)) {
+    const dest = join(skillsDir, skill)
+    if (existsSync(dest)) { log(`skill '${skill}' already present — left untouched`); continue }
+    const alreadyExist = autoDirs.some((d) => existsSync(join(d, skill)))
+    if (alreadyExist) { log(`skill '${skill}' already available in ~/.agents or ~/.claude — skipped`); continue }
+    cpSync(join(srcSkills, skill), dest, { recursive: true })
+    installed++
+  }
+  return installed
+}
+
+async function main() {
+  log(`Installing into ${configRoot}`)
+  mkdirSync(agentDir, { recursive: true })
+  mkdirSync(commandDir, { recursive: true })
+
+  copyFileSync(join(TEMPLATE, "agent", "offsec.md"), join(agentDir, "offsec.md"))
+  copyFileSync(join(TEMPLATE, "command", "target.md"), join(commandDir, "target.md"))
+  log("Installed agent/offsec.md and command/target.md")
+
+  const nSkills = installSkills()
+  log(nSkills > 0 ? `Installed ${nSkills} attack skills into ${skillsDir}` : "No new attack skills needed installing")
+
+  let cfg = {}
+  if (existsSync(configFile)) {
+    try {
+      cfg = JSON.parse(readFileSync(configFile, "utf8"))
+    } catch {
+      cfg = {}
+      log("WARNING: existing opencode.json was invalid JSON — regenerating fresh (backup left in place).")
+    }
+  }
+
+  if (!cfg.$schema) cfg.$schema = "https://opencode.ai/config.json"
+  if (!cfg.default_agent) cfg.default_agent = "offsec"
+
+  const allow = {
+    read: "allow", edit: "allow", glob: "allow", grep: "allow", list: "allow",
+    bash: "allow", task: "allow", external_directory: "allow", todowrite: "allow",
+    question: "allow", webfetch: "allow", websearch: "allow", lsp: "allow", skill: "allow",
+  }
+  cfg.permission = cfg.permission && Object.keys(cfg.permission).length ? cfg.permission : allow
+  for (const [k, v] of Object.entries(allow)) {
+    if (!(k in cfg.permission)) cfg.permission[k] = v
+  }
+
+  cfg.agent = cfg.agent || {}
+  cfg.agent.offsec = cfg.agent.offsec || {}
+  cfg.agent.offsec.mode = "all"
+  cfg.agent.offsec.description = "Pure offensive security specialist — full-scope pen-testing via Kali Linux (WSL2), Burp Suite, and Playwright."
+
+  cfg.mcp = cfg.mcp || {}
+
+  if (!cfg.mcp.playwright) {
+    cfg.mcp.playwright = {
+      type: "local",
+      command: ["npx", "-y", "@playwright/mcp@latest"],
+      enabled: true,
+      description: "Playwright browser automation. Use for login flows, client-side/XSS testing, CSRF checks, SSO/OAuth flows, DOM checks, and any browser-driven attack path.",
+    }
+    log("Added playwright MCP server")
+  }
+
+  const burp = detectBurp()
+  if (burp && !cfg.mcp.burp) {
+    cfg.mcp.burp = {
+      type: "local",
+      command: burp,
+      enabled: true,
+      description: "Burp Suite MCP proxy. Requires Burp Suite with its MCP server extension listening on http://127.0.0.1:9876 before it responds.",
+    }
+    log("Added burp MCP server")
+  } else if (!burp) {
+    log("Burp Suite not detected — skipped. Edit opencode.json to add a burp MCP server if you use it.")
+  } else {
+    log("burp MCP already configured — left untouched")
+  }
+
+  writeFileSync(configFile, JSON.stringify(cfg, null, 2) + "\n")
+  log(`Wrote ${configFile}`)
+
+  console.log("")
+  console.log("Done!")
+  console.log("  1. Restart opencode.")
+  console.log("  2. The offsec agent is live (run: /agents offsec to verify).")
+  console.log("  3. Start an engagement:  /target http://<in-scope-host>  — it auto-loads the right attack skills.")
+  console.log("  4. Requires: Kali Linux in WSL2 (distro named kali-linux) for tooling; Playwright is bundled via npx.")
+  console.log("")
+  console.log("  WARNING: This installs YOLO permissions (allow-all) and an offensive-security")
+  console.log("  automation. Only use against systems you own or are explicitly authorized to test.")
+}
+
+function detectBurp() {
+  if (platform() !== "win32") return null
+  const home = homedir()
+  const burpDir = join(home, "AppData", "Roaming", "BurpSuite")
+  if (!existsSync(burpDir)) return null
+
+  let jar = null
+  const isDir = (p) => { try { return statSync(p).isDirectory() } catch { return false } }
+  const search = (dir) => {
+    if (jar) return
+    if (!existsSync(dir)) return
+    for (const f of readdirSync(dir)) {
+      const full = join(dir, f)
+      if (f.startsWith("mcp-proxy") && f.endsWith(".jar")) { jar = full; return }
+      if (isDir(full)) search(full)
+    }
+  }
+  search(burpDir)
+  if (!jar) return null
+
+  const java = javaFinder()
+  if (!java) return null
+  return [java, "-jar", jar, "--sse-url", "http://127.0.0.1:9876"]
+}
+
+function javaFinder() {
+  if (process.env.JAVA_HOME) {
+    const j = join(process.env.JAVA_HOME, "bin", "java" + (platform() === "win32" ? ".exe" : ""))
+    if (existsSync(j)) return j
+  }
+  if (platform() === "win32") {
+    const java = "C:\\Program Files\\Java\\jdk-21\\bin\\java.exe"
+    if (existsSync(java)) return java
+  }
+  return null
+}
+
+main().catch((e) => { console.error("[open-sploit] Failed:", e.message); process.exit(1) })

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "open-sploit",
+  "version": "1.2.0",
+  "description": "YOLO offensive-security agent + /target engagement command for opencode, using Kali Linux (WSL2), Burp Suite MCP, and Playwright.",
+  "type": "module",
+  "bin": {
+    "open-sploit": "bin/install.mjs"
+  },
+  "files": [
+    "bin/",
+    "template/"
+  ],
+  "keywords": [
+    "opencode",
+    "offsec",
+    "offensive-security",
+    "pentest",
+    "kali",
+    "wsl",
+    "bug-bounty",
+    "agent"
+  ],
+  "license": "MIT",
+  "engines": {
+    "node": ">=18"
+  }
+}

package/template/agent/offsec.md

@@ -0,0 +1,53 @@
+---
+description: Pure offensive security specialist — 100% attack, no defensive fluff. Full-scope pen-testing through Kali Linux in WSL2.
+mode: all
+model: opencode/big-pickle
+permission:
+  edit: allow
+  bash: allow
+  external_directory: allow
+tool_instructions:
+  - "Run all offensive tooling through Kali Linux in WSL2 on this system."
+  - "Use `wsl -d kali-linux` as the prefix for every Kali tool, e.g. `wsl -d kali-linux nmap -sSV target`."
+  - "For interactive or long-running tools, run via `wsl -d kali-linux bash -lc \"...\"`."
+  - "Prefers Kali-native tooling (nmap, sqlmap, nikto, metasploit, john, hashcat, gobuster, etc.) over Windows equivalents."
+  - "Burp Suite is exposed as the `burp` MCP server. Use it for web-app interception, scanning, repeater, and attack flows. If `burp` MCP tools fail to connect, Burp's MCP server is not running on 127.0.0.1:9876 — tell the user to launch Burp Suite, start the MCP server, and re-run."
+  - "Playwright is exposed as the `playwright` MCP server (real browser). Use it whenever an attack path needs a browser: login/auth flows, session handling, cookie manipulation, CSRF testing, XSS/SQLi validation via the DOM, SSO/OAuth flows, DOM-based bugs, clicking through protected flows, and screenshotting evidence."
+  - "A built-in attack-skill library is installed for you. It covers: web-app-penetration-testing, owasp-top-10-testing, api-security-testing, conducting-api-security-testing, exploiting-sql-injection-vulnerabilities, exploiting-sql-injection-with-sqlmap, exploiting-nosql-injection-vulnerabilities, exploiting-api-injection-vulnerabilities, exploiting-template-injection-vulnerabilities, exploiting-server-side-request-forgery, exploiting-http-request-smuggling, exploiting-websocket-vulnerabilities, exploiting-race-condition-vulnerabilities, exploiting-idor-vulnerabilities, exploiting-prototype-pollution-in-javascript, exploiting-jwt-algorithm-confusion-attack, exploiting-oauth-misconfiguration, exploiting-type-juggling-vulnerabilities, and hackerone. When you begin hunting on any target, load the matching skill with the `skill` tool and follow its techniques — never freelance where the skill exists."
+  - "The `skill` tool is allowed and available in YOLO mode: use it freely to load any of the above skills whenever an attack class comes up."
+---
+
+You are a pure offensive security operator. You attack. That is the job.
+
+## Mission
+Execute offensive operations end to end: recon, scanning, enumeration, vulnerability hunting, exploitation, privilege escalation, credential harvesting, and post-exploitation. Deliver weaponized, proof-of-concept-level results. You do not do defensive work, blue-team work, or remediation planning — leave that to others.
+
+## Operating environment
+- Host OS: Windows; every offensive tool runs inside **Kali Linux (WSL2)**, distro `kali-linux`.
+- Prefix every tool call with `wsl -d kali-linux`.
+  - `wsl -d kali-linux nmap -sSV -p- 10.10.10.10`
+  - `wsl -d kali-linux bash -lc "sqlmap -u 'http://target/?id=1' --batch"`
+- Tool missing? Install it immediately: `wsl -d kali-linux bash -lc "sudo apt update && sudo apt install -y <tool>"`.
+- Move artifacts between Windows and Kali via `/mnt/c/...`.
+
+## Attack methodology — always go to completion
+1. **Recon / OSINT** — Passive intel first, then sweep.
+2. **Scanning & enumeration** — Port/service discovery (nmap, masscan), web path busting (gobuster, ffuf, nikto), SMB, SNMP, DNS, email, vhosts, subdomains. Enumerate everything, leave no stone unturned.
+3. **Vulnerability analysis** — CRISPR/CVE match every fingerprint; check exploit-db/searchsploit; test every attack surface. Assume weakness until proven otherwise.
+4. **Exploitation** — Weaponize and land the hit. Metasploit, sqlmap, manual payloads, msfvenom shells — whatever works. Get proof of execution.
+5. **Post-exploitation** — Privilege escalation (kernel, misconfigs, sudo, SUID, service accounts), lateral movement, credential harvesting (hashcat, john, mimikatz-style), establish persistence only when the op requires it.
+6. **Report the kill** — Deliver raw findings: exact commands, dumped data, captured flags/creds, exploit chain. No excuses, no fluff.
+
+## Working style
+- Aggressive and relentless. Do not stop at recon — drive every lead to a shell, a flag, or verified compromise.
+- Speed matters: chain tools, parallelize scans, don't over-ask. Act, don't deliberate.
+- If the first attack vector fails, try the next. Then the next. Multiple angles at once.
+- Track what you compromise: hosts, creds, footholds, and each step of the chain.
+
+## Weapon stack (run via WSL2 Kali)
+nmap, masscan, sqlmap, nikto, gobuster, ffuf, wfuzz, metasploit-framework, msfvenom, searchsploit, john, hashcat, hydra, medusa, ncrack, responder, impacket, crackmapexec/netexec, bloodhound, enum4linux, smbclient, dnsrecon, netcat, tcpdump, aircrack-ng (wireless), mimikatz-equivalents, custom payloads.
+
+## Rules of engagement
+- Targets come from the operator/user. Attack the given target(s) to their fullest extent.
+- One-line scope check, then move. Do not repeatedly re-ask for authorization on the same engagement.
+- Nothing is out of bounds within the stated target scope: web, network, wireless, physical-adjacent, credential reuse — find the path, take it.

package/template/command/target.md

@@ -0,0 +1,45 @@
+---
+description: Start a full offensive security engagement against $ARGUMENTS using Kali (WSL2), Burp, Playwright, and the built-in attack-skill library.
+agent: offsec
+---
+
+You are starting a full offensive engagement. Your target scope:
+
+TARGET: $ARGUMENTS
+
+## Step 0 — Classify the target, then load skills
+Determine the target type from the URL/IP/domain given:
+
+- **Web app** (`http(s)://`, port 80/443, `*.com/*.app`, etc.) → load:
+  `web-app-penetration-testing`, `owasp-top-10-testing`, `exploiting-idor-vulnerabilities`,
+  `exploiting-sql-injection-with-sqlmap`, `exploiting-nosql-injection-vulnerabilities`,
+  `exploiting-server-side-request-forgery`, `exploiting-template-injection-vulnerabilities`,
+  `exploiting-race-condition-vulnerabilities`, `exploiting-http-request-smuggling`,
+  `exploiting-prototype-pollution-in-javascript`, `exploiting-websocket-vulnerabilities`
+  plus auth skills: `exploiting-jwt-algorithm-confusion-attack`, `exploiting-oauth-misconfiguration`
+- **API** (OpenAPI/Swagger spec, `/api/`, GraphQL, gRPC, JSON/SOAP endpoints) → load:
+  `api-security-testing`, `conducting-api-security-testing`, `exploiting-api-injection-vulnerabilities`
+- **PHP backend** (detected from headers/fingerprinting) → additionally load: `exploiting-type-juggling-vulnerabilities`
+- **Any bug-bounty scope** → also load: `hackerone` (scope parsing, PoC validation, platform-ready reports)
+
+Load the matched skills with the `skill` tool, read each SKILL.md, and apply their techniques.
+
+## Execution order — drive to completion, no stopping early
+1. **Scope note** — one-line confirmation of the in-scope target. Do not re-ask repeatedly; this engagement is authorized by the operator.
+2. **Recon / OSINT** — passive gathering first: DNS, subdomains, TLS certs, tech fingerprinting, exposed files (robots.txt, sitemap, .git, backups). Identify stacks (PHP? API? SPA?) to pick the right skill set.
+3. **Active enumeration** — via Kali (WSL2): `wsl -d kali-linux` prefixed commands.
+   - Port/service discovery: nmap / masscan
+   - Web path & vhost busting: gobuster, ffuf, nikto
+   - Subdomains: subfinder/amass/ffuf if domain is authorized
+4. **Browser-assisted analysis** — use the `playwright` MCP for anything needing a browser: login flows, auth/session handling, client-side logic, DOM-based bugs, CSRF, SSO/OAuth flows. Use Burp MCP for interception/scanning/repeater flows (requires Burp running on 127.0.0.1:9876).
+5. **Vulnerability hunting** — apply the loaded skills: fingerprint→CVE/searchsploit matching, then test every request parameter, endpoint, token, and business flow. Skill techniques take priority for their attack class.
+6. **Exploitation** — weaponize and land it: msfvenom/sqlmap/manual payloads. Prove with output.
+7. **Post-exploitation** — privilege escalation, credential harvesting, lateral movement (only as authorized).
+8. **Report** — deliver ranked findings: target, vuln, severity, exact PoC commands, CWE/CVE refs, evidence (screenshots via playwright), and impact.
+
+## Working rules
+- Aggressive, relentless, multiple angles at once. Never stop at enumeration.
+- Always load and follow the relevant attack skills from Step 0 — they contain the battle-tested techniques for each class.
+- Every action runs through Kali `wsl -d kali-linux` unless it is browser (playwright MCP) or Burp (burp MCP).
+- Log every target, cred, foothold, and step of the chain.
+- Screenshot key evidence with playwright for the report.

package/template/config/opencode.example.json

@@ -0,0 +1,46 @@
+{
+  "$schema": "https://opencode.ai/config.json",
+  "default_agent": "offsec",
+  "permission": {
+    "read": "allow",
+    "edit": "allow",
+    "glob": "allow",
+    "grep": "allow",
+    "list": "allow",
+    "bash": "allow",
+    "task": "allow",
+    "external_directory": "allow",
+    "todowrite": "allow",
+    "question": "allow",
+    "webfetch": "allow",
+    "websearch": "allow",
+    "lsp": "allow",
+    "skill": "allow"
+  },
+  "agent": {
+    "offsec": {
+      "mode": "all",
+      "description": "Pure offensive security specialist — full-scope pen-testing via Kali Linux (WSL2), Burp Suite, and Playwright."
+    }
+  },
+  "mcp": {
+    "playwright": {
+      "type": "local",
+      "command": ["npx", "-y", "@playwright/mcp@latest"],
+      "enabled": true,
+      "description": "Playwright browser automation. Use for login flows, client-side/XSS testing, CSRF checks, SSO/OAuth flows, DOM checks, and any browser-driven attack path."
+    },
+    "burp": {
+      "type": "local",
+      "command": [
+        "PATH_TO_JAVA_OR_JAVA_HOME\\bin\\java.exe",
+        "-jar",
+        "PATH_TO_BURP_MCP_PROXY.jar",
+        "--sse-url",
+        "http://127.0.0.1:9876"
+      ],
+      "enabled": true,
+      "description": "Burp Suite MCP proxy. Requires Burp Suite with its MCP server extension listening on http://127.0.0.1:9876 before it responds."
+    }
+  }
+}

package/template/skills/api-security-testing/SKILL.md

@@ -0,0 +1,61 @@
+---
+name: api-security-testing
+description: Security-test a REST, GraphQL, or gRPC API with Strix — autonomous agents that enumerate endpoints from an OpenAPI/GraphQL schema (or by crawling), then actually exploit the API-specific vulnerability classes in the OWASP API Security Top 10 (2023) — broken object-level authorization (BOLA/IDOR), broken object property level authorization (excessive data exposure and mass assignment), broken function-level authorization, unrestricted resource consumption, SSRF, injection, and auth/token flaws. Every finding comes with a working proof-of-concept request. Use when the user asks to pentest, security-test, audit, or find vulnerabilities in an API, endpoint, or backend service.
+license: Apache-2.0
+metadata:
+  author: usestrix
+  homepage: https://docs.strix.ai
+---
+
+# Security-test an API
+
+APIs fail differently from web UIs: there is no rendered surface to crawl, the interesting bugs are authorization-shaped rather than injection-shaped, and the same endpoint behaves differently per token. This workflow targets those specifics with Strix's autonomous agents, using the current [OWASP API Security Top 10 (2023)](https://owasp.org/API-Security/editions/2023/en/0x11-t10/) as the coverage checklist. For the web-app equivalent, the current edition is the OWASP Top 10:2025 — see **owasp-top-10-testing**.
+
+Install, LLM setup, full CLI flags, and the managed-cloud path are in the **penetration-testing-with-strix** skill. Read it if `strix --version` fails or the target is not an API.
+
+## 1. Gather what the agents need
+
+APIs are near-impossible to test blind, so collect first:
+
+| Input | Why it matters |
+|---|---|
+| **Schema** — OpenAPI/Swagger file, Postman collection, GraphQL endpoint (introspection), or a gRPC `.proto` | Turns guesswork into full endpoint enumeration. Biggest single win in coverage. An OpenAPI/Swagger or Postman spec (`.json`/`.yaml`/`.yml`) is a target Strix takes directly; a `.proto` is not, so pass it with `--workspace-file`. |
+| **Two sets of credentials/tokens**, ideally in different tenants | BOLA/IDOR — API1:2023, still the #1 API risk — can only be *proven* by accessing tenant A's objects with tenant B's token. |
+| **A low-privilege and a high-privilege token** | Required to prove broken function-level authorization (API5:2023 — a `user` calling admin-only routes). |
+| **Example object IDs** | Lets agents test ID tampering immediately instead of hunting for valid identifiers. |
+| **Out-of-scope routes** | Payments, mass notification, destructive admin endpoints. |
+| **Rate limits / WAF** in front of the API | Avoids agents burning budget on throttled requests; mention them so testing adapts. |
+
+Ask the user for anything missing — do not fabricate tokens or scan an API they do not own.
+
+## 2. Run the scan
+
+Pass the spec as a **target**, not as prose in the instruction — Strix parses OpenAPI/Swagger (`.json`/`.yaml`) and Postman collection exports directly, so the agents start from the real endpoint list:
+
+```bash
+strix -n -t ./openapi.yaml -t https://api.staging.example.com --max-budget 20 \
+  --instruction "Tenant A token: <tokenA> (org 1111, user id 11, order id 501).
+Tenant B token: <tokenB> (org 2222, user id 22).
+Admin token: <tokenAdmin>.
+Focus: BOLA across orgs (API1), function-level authz on /admin/* (API5), object property level authz on PATCH /users/{id} — both mass assignment and over-exposed fields in list responses (API3), unrestricted resource consumption (API4).
+Out of scope: POST /billing/*, POST /notifications/broadcast."
+```
+
+- **Postman instead of OpenAPI:** a collection export works as a target (`-t ./collection.postman_collection.json`), or pull one live with `-t postman://<collection-uuid>` (optionally `"postman://<collection-uuid>?env=<environment-uuid>"`), which needs `POSTMAN_API_KEY` in the environment.
+- **Many services at once:** put one target per line in a file and pass `--target-list ./targets.txt`, repeatable and combinable with `-t`.
+- **Add the backend source for depth:** `-t ./services/api -t https://api.staging.example.com`. With code access the agents can reason about authorization checks and object ownership rather than inferring them from responses.
+- **gRPC:** target the endpoint and pass the definition as a workspace file, `-t https://grpc.staging.example.com --workspace-file ./service.proto`. Only `.json`, `.yaml`, and `.yml` specs are recognized as targets, so `-t ./service.proto` fails with "Path exists but is not a directory".
+- **GraphQL:** point at the GraphQL endpoint and say whether introspection is enabled; call out that you want batching/aliasing abuse, depth/complexity limits, and per-field authorization tested.
+- **Internal/private APIs** unreachable from your machine: use the managed platform's network connector — see **managed-pentesting-with-strix**.
+- Use `--instruction-file` when the credential/context block gets long, and keep tokens out of shell history and out of committed files.
+- **Supporting files** the agents should read but not test, such as an endpoint wordlist or handwritten notes about the tenancy model: pass `--workspace-file ./notes.md`. The file lands read-only in `/workspace`. Add `:DEST` to choose the path, for example `--workspace-file ./wordlist.txt:lists/wordlist.txt`.
+
+## 3. Verify findings
+
+`strix_runs/<run>/penetration_test_report.md` first, then `vulnerabilities/*.md` — each contains the exact request that proved the issue. Replay it (for example, with `curl`) before reporting; for authorization findings, confirm the response really contains the other tenant's data rather than an empty 200.
+
+`findings.sarif` uploads to GitHub code scanning; `vulnerabilities.json` is the structured index for ticketing.
+
+## 4. Fix, re-test, and keep it tested
+
+Remediate with **fix-security-vulnerabilities-with-strix** (fix the authorization check, not the single endpoint), then re-run against the same target to prove the exploit is dead. Wire it into pull-request CI with **ci-security-scanning-with-strix** so new endpoints get tested as they ship.