x-api-pentest

name	x-api-pentest
description	Use when the user provides an OpenAPI or Swagger spec and asks to find security issues, pentest the API, audit endpoints for OWASP API Top 10, or check for BOLA, BFLA, mass assignment, injection, or SSRF vulnerabilities in a running HTTP API
disable-model-invocation	true

x-api-pentest — API Security Pentest from OpenAPI/Swagger

Black-box dynamic security testing of a live HTTP API using its OpenAPI/Swagger spec as the attack surface map. Orchestrates Schemathesis, RESTler, Nuclei, sqlmap, and interactsh, with Claude reasoning over findings to catch business-logic flaws.

Bootstrap

MANDATORY first step — do this BEFORE anything else: 0. Pin capabilities for the session per ../x-shared/capability-loading.md. Use the security_tools block (schemathesis, nuclei, sqlmap, spectral, interactsh) to skip lanes whose CLIs are unavailable rather than failing mid-step.

1. Read config.json to load tool paths, default flags, safety gates (safety.require_target_confirmation, safety.allowed_target_patterns, safety.denied_target_patterns, rate caps, per-oracle toggles).
2. Read gotchas.md — known failure patterns and the Noise Filters section (patterns that must NOT be emitted as findings).
3. Read references/safe-execution.md — target allowlist, sandboxing, credential isolation.
4. Confirm explicit authorization. If safety.require_target_confirmation is true, ASK: "Confirm you are authorized to test <target_url>. Type the URL to proceed."
5. Memory recall (only when mcp.basic_memory pinned in the bootstrap-active set): one mcp__basic-memory__search_notes({ query: "<target host/API name> api vulnerabilities", page_size: 5 }) call — keep the query purely topical per § Memory Reflex (no skill-name or repo-name tokens) — surface prior confirmed vuln classes / target gotchas / noise-filter lessons as leads for oracle reasoning, not verdicts, per ../x-shared/mcp-toolbox.md § Memory Reflex. Skip silently when not pinned.

Safe Execution Environment

This skill issues live HTTP requests including blind re-verification of each finding. Unsandboxed against the wrong target = production incident. Before proceeding:

• Target must match safety.allowed_target_patterns (localhost, RFC1918, *.staging.*, *.test.*, *.local). Override requires allow_unsafe_target=true + user confirmation.
• Prefer an egress-isolated container (Docker Compose with internal: true, cap_drop: ALL, no-new-privileges). Template in references/safe-execution.md.
• Credentials only via environment variables. Never read tokens from committed files.

Scope

DOES: dynamic black-box testing, OWASP API Top 10 (2023), BOLA / BFLA / mass assignment / SSRF / injection / rate-limit / business logic, markdown + SARIF output.

DOES NOT: static code review (→ ck-security, code-review), secret/dependency scanning (→ security-scan), network/infra pentest, social engineering, unauthorized testing.

How this differs from existing skills

• vs Transience api-security — Transience is bug-bounty / recon-driven. This skill is OpenAPI/Swagger-spec driven — hand it a spec, it systematically pentests every documented endpoint.
• vs HexStrike AI MCP — HexStrike is the tool execution layer (~150 wrapped CLIs). This skill is the orchestration layer and calls HexStrike when config.integrations.prefer_hexstrike: true, else direct CLI.
• vs Pwnkit — Pwnkit is general-purpose autonomous pentesting. This skill is API-only and dev-loop oriented. The blind-verification pattern in step 4 is borrowed from Pwnkit.
• vs OWASP Claude Skill — that skill is reference-only documentation. This skill actively tests.

See references/related-skills.md for full comparison.

Step-File Architecture

This skill uses sequential steps. Load ONE step file at a time. Complete each before proceeding.

Critical Rules

• Load ONE step file at a time — multiple causes phase merging and skipped checkpoints.
• Read the entire step file before acting — partial reads miss the gate at the bottom.
• Follow steps in order — step 4 requires step 2 credentials; step 5 requires step 3+4 outputs.
• Halt at every checkpoint for human input — auto-proceeding past consent gates is a security failure, not productivity.
• No active scans without explicit target confirmation — the consent gate at the end of step 1 is non-negotiable.

Workflow

1. steps/step-01-recon.md — spec lint, attack surface, role mapping, consent gate
2. steps/step-02-auth-baseline.md — validate 2 user tokens + admin token
3. steps/step-03-automated-sweep.md — parallel Schemathesis + RESTler (opt-in) + Nuclei
4. steps/step-04-targeted-tests.md — BOLA/BFLA, mass assignment, SSRF, velocity, business logic, LLM injection
5. steps/step-05-synthesize.md — dedupe, severity, chain-impact reasoning
6. steps/step-06-report.md — markdown + SARIF, handoff

Start with step 1 now.

Severity

This skill extends the canonical x-skills severity scale (../x-shared/severity-guide.md — CRITICAL / HIGH / MEDIUM / LOW) with an additional Info tier for non-actionable findings (informational / advisory only — never blocks merge). Casing follows CVSS-lite convention (Title-case: Critical / High / Medium / Low / Info) inside this skill's outputs because findings flow into SARIF (references/sarif-schema.md) and CVSS reporting tools that expect Title-case labels. When findings cross over into a generic x-skills review pipeline, map: Title-case → UPPER-case, Info → LOW.

Detail: references/owasp-api-top10-2023.md.

References

Loaded ONLY when needed by a step:

• references/owasp-api-top10-2023.md — risk catalog with detection oracles
• references/tool-invocations.md — exact CLI invocations with auth handling
• references/auth-recipes.md — OAuth2/JWT/API-key/refresh patterns
• references/bola-bfla-playbook.md — two-user matrix algorithm
• references/sarif-schema.md — SARIF 2.1.0 output format
• references/related-skills.md — when to use this vs Transience / HexStrike / Pwnkit / OWASP
• references/safe-execution.md — target allowlist, sandboxing, creds (read during bootstrap)
• references/llm-injection-patterns.md — Oracle G payload library (loaded by step-04 only if LLM endpoints detected)

Dependencies

• External tools — schemathesis, nuclei, sqlmap, spectral, interactsh-client (docker optional for RESTler). Step 1 fails fast with install instructions.
• superpowers:verification-before-completion — every Critical/High finding needs a curl repro before claiming complete.

Red Flags — STOP and reconsider

• Active scans without explicit target confirmation
• Target not matching safety.allowed_target_patterns without allow_unsafe_target=true
• Skipping step 2 (BOLA needs 2 users)
• "No findings" without showing tool exit codes
• Treating tool outputs independently — must dedupe + chain
• Output without curl reproductions
• Raising sqlmap risk above default (1) without explicit approval
• Hitting *.gov / *.mil or any denied pattern
• Emitting findings matching Noise Filters in gotchas.md

Gotchas

See gotchas.md — update when you encounter new ones.

Task: {{ARGUMENTS}}