Recipes

Copy-paste recipes for the most common pwnkit scenarios. Every recipe assumes you have an OPENROUTER_API_KEY (or equivalent) exported. See Getting Started if you don’t.

Scan my REST API (OpenAPI)

Point pwnkit at your OpenAPI 3.x / Swagger 2.0 document and it will seed the recon phase with every endpoint, parameter, and auth requirement — skipping the crawl entirely.

npx pwnkit-cli scan \
  --target https://api.example.com \
  --api-spec ./openapi.yaml \
  --mode web \
  --depth deep

If your API requires authentication, add --auth (see Scan authenticated APIs below).

Scan a WordPress site for CVEs

Enable the Docker executor so the agent has wpscan, nmap, and friends available, and turn on web search so it can look up plugin CVEs as it goes. By default this uses the prebuilt GHCR image; only force raw Kali if you are debugging tool parity.

export PWNKIT_FEATURE_DOCKER_EXECUTOR=1
export PWNKIT_FEATURE_WEB_SEARCH=1
export PWNKIT_FEATURE_DYNAMIC_PLAYBOOKS=1

npx pwnkit-cli scan \
  --target https://blog.example.com \
  --mode web \
  --depth deep \
  --verbose

Raw Kali fallback:

export PWNKIT_FEATURE_DOCKER_EXECUTOR=1
export PWNKIT_DOCKER_IMAGE=kalilinux/kali-rolling
export PWNKIT_DOCKER_BOOTSTRAP_TOOLS=1

Audit an npm package for security issues

# Default audit (latest version)
npx pwnkit-cli audit express

# Pin a specific version
npx pwnkit-cli audit express --version 4.18.2

# Deep audit with the Claude Code CLI runtime
npx pwnkit-cli audit left-pad --depth deep --runtime claude

The package is installed in a sandbox, scanned with semgrep, then reviewed by an AI agent that traces data flow and hunts for supply-chain issues.

Run a full pentest with maximum accuracy

Turn on every false-positive reduction feature and let EGATS do a thorough tree search. Slower, but produces client-ready findings.

export PWNKIT_FEATURE_CONSENSUS_VERIFY=1
export PWNKIT_FEATURE_REACHABILITY_GATE=1
export PWNKIT_FEATURE_POV_GATE=1
export PWNKIT_FEATURE_TRIAGE_MEMORIES=1
export PWNKIT_FEATURE_MULTIMODAL=1
export PWNKIT_FEATURE_DOCKER_EXECUTOR=1

npx pwnkit-cli scan \
  --target https://example.com \
  --mode web \
  --depth deep \
  --egats \
  --runtime claude

See Configuration — Feature flags for what each flag does.

Best-of-N racing for hard targets

When a single linear attack plan keeps getting stuck, spawn 5 parallel strategies and let the fastest one win.

npx pwnkit-cli scan \
  --target https://hard-target.example.com \
  --mode web \
  --race \
  --depth deep

Export findings to GitHub Issues

Push every confirmed finding to a GitHub repo as a labelled issue with evidence and reproduction steps.

export GITHUB_TOKEN="ghp_..."

npx pwnkit-cli scan \
  --target https://example.com \
  --mode web \
  --export github:myorg/security-findings

Each finding becomes an issue labelled by severity (sev:critical, sev:high, …) and category (cat:xss, cat:ssrf, …) so you can triage from the GitHub UI.

Generate an HTML, Markdown, or PDF report

# HTML (auto-opens in browser and saves to a temp file)
npx pwnkit-cli scan \
  --target https://example.com \
  --mode web \
  --depth deep \
  --format html

# Markdown (printed to stdout; redirect to a file)
npx pwnkit-cli scan \
  --target https://example.com \
  --mode web \
  --depth deep \
  --format md > example-pentest.md

# PDF (auto-opens in your default viewer and saves to a temp file)
npx pwnkit-cli scan \
  --target https://example.com \
  --mode web \
  --depth deep \
  --format pdf

Both formats include an executive summary, a severity breakdown, per-finding evidence blocks with request/response pairs, and reproduction steps. Works for audit and review too.

Scan authenticated APIs (bearer token)

# Inline
npx pwnkit-cli scan \
  --target https://api.example.com \
  --api-spec ./openapi.yaml \
  --auth '{"type":"bearer","token":"eyJhbGciOi..."}'

# From a file (avoids leaking the token to shell history)
cat > auth.json <<'EOF'
{"type":"bearer","token":"eyJhbGciOi..."}
EOF

npx pwnkit-cli scan \
  --target https://api.example.com \
  --api-spec ./openapi.yaml \
  --auth ./auth.json

Other auth types:

# Session cookie
--auth '{"type":"cookie","value":"session=abc123; csrf=def456"}'

# HTTP Basic
--auth '{"type":"basic","username":"admin","password":"hunter2"}'

# Custom header (API key)
--auth '{"type":"header","name":"X-API-Key","value":"sk_live_..."}'

Track learned false positives across runs

After a scan, mark noisy findings as false positives and pwnkit will remember the pattern for next time.

# Mark a single finding as FP (auto-creates a memory)
pwnkit-cli triage mark-fp NF-042 --reason "test fixture echo endpoint, not reachable in prod"

# Add a memory from an existing finding without suppressing it
pwnkit-cli triage memory add --finding NF-017 --reason "intentional CORS config for public API"

# List what pwnkit has learned
pwnkit-cli triage memory list

# Remove a memory that's no longer accurate
pwnkit-cli triage memory remove <memory-id>

Enable memory injection into the verify pipeline with PWNKIT_FEATURE_TRIAGE_MEMORIES=1.