x-api-pentest

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."

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}}