🐍 Python package · CLI · MCP · Agent skills

Automated pentest
action plans for APIs

Transform OpenAPI / Swagger 3.x specifications into structured, pre-execution Pentest Action Plans. Detects risk signals, maps OWASP API Security vectors, and — for coding agents — runs an AppSec methodology: authorized scope, a deterministic MCP plan, remediations, and selective RFCs.

⚡ Install via pip View on GitHub PyPI
17
OWASP & Data Lake Vectors
7
Agent Skills
5
Harnesses (CLI + agents)
bash — security-pentest-planner 
$ security-pentest-planner openapi.yaml \
    --team "Platform Team" \
    --datalake \
    -o pentest-plan.md

✓ Parsed OpenAPI 3.0.3 (Analytics API)
! Detected 4 Contract Red Flags
→ Mapped 11 API Vectors & 6 Data Lake Vectors
✔ Action Plan generated in pentest-plan.md

# Preview:
## Tenant Traversal (BOLA/IDOR)
  Endpoint: GET /api/v1/metrics
  Header:   Tenant-ID: 999999999999999999
  Fail:     200 OK with cross-tenant data

Engineered for Python Teams

Why security-pentest-planner in Python?

Structure offensive security reviews before execution begins — bridging the gap between OpenAPI contracts and AppSec testing.

🐍

Native Python Ecosystem

Seamlessly integrates into modern Python stacks (FastAPI, Django Ninja, Flask, Litestar). Import as a module in your scripts or trigger via CLI.

  • Modern Python 3.10+ typing & dataclasses
  • Zero heavy dependencies (only PyYAML)
  • Fast execution (< 50ms per contract)
High Impact
🎯

Contract-Derived Payloads

Never look at generic checklists again. The planner extracts real parameter names, tenant headers, enum values, and paths directly from your OpenAPI contract.

  • Dynamic payload interpolation
  • Tenant-scoping & BOLA test cases
  • Date-range & logical DoS boundaries
📊

Full Stack: API + Data Lake

Analytics endpoints frequently trigger massive downstream database jobs. The tool includes specialized vectors for BigQuery / SQL persistence layers.

  • Row-level tenant bypass tests
  • Cost-exhaustion & unpartitioned full scans
  • Service Account overprivilege checks
🤖

Agent methodology

Skills, a session-start hook, and a local MCP server for Claude, Cursor, Codex, and Gemini. Same composable format as obra/superpowers, scoped to AppSec handoff.

  • Session-start loads using-pentest-planner
  • Deterministic plan via generate_pentest_plan
  • Remediations and selective P0 RFCs

For coding agents

AppSec methodology, then a deterministic plan

Scope the engagement, review the contract, generate the plan with MCP, and hand engineering remediations and RFCs — without executable attack scripts.

MCP
🔌

Deterministic plan

Local stdio server started with uvx. The model calls the tool; the package writes the Markdown. Endpoints and parameters come from the OpenAPI file.

  • generate_pentest_plan — plan from a contract path
  • planner_version — installed package version
  • Optional team, scope, include_datalake
🧭

Default pipeline

Seven skills, invoked in order. The session-start hook injects using-pentest-planner so the agent does not skip scoping.

  • Authorize scope before any plan
  • Contract red flags, then MCP
  • Remediations, selective RFCs, handoff check
🧩

Five install surfaces

Claude Code, Cursor, Codex, Gemini CLI, and the Python CLI share one repo. Claude Pro is required only to submit the plugin to the Anthropic Directory.

  • PyPI, Pages, and local plugin: no Pro
  • Self-host marketplace without Anthropic review
  • uv on PATH so MCP starts via uvx

Pipeline

  • 1
    scoping-authorized-pentest Written approval, in-scope targets, environment, and out-of-bounds.
  • 2
    reviewing-openapi-risks Tenant headers, optional auth, free-text fields, wide date ranges, Data Lake.
  • 3
    generate_pentest_plan MCP tool. Markdown procedures, example payloads, and a vector matrix.
  • 4
    writing-remediations remediacoes.md mapped to vectors. Snippets are reference, not a ready PR.
  • 5
    writing-security-rfcs Selective P0 only: global tenant middleware, auth model, rate-limit platform, cross-dataset IAM.
  • 6
    verifying-pentest-handoff Plan, remediations, and RFCs present. No attack scripts and no fake PASS/FAIL.

Skills

Skill Role
using-pentest-planner Bootstrap — when and how to invoke the other skills
scoping-authorized-pentest Authorization and bounds
reviewing-openapi-risks Contract red flags
security-pentest-planner MCP plan and pipeline orchestration
writing-remediations remediacoes.md
writing-security-rfcs Selective P0 RFCs
verifying-pentest-handoff Close the AppSec → engineering handoff

Hard stops

  • —
    No attack scripts Plans describe procedures and example payloads. They are not runnable exploits.
  • —
    No fabricated results The tool does not emit PASS/FAIL. Execution stays with the authorized tester.
  • —
    No invented contract Endpoints and parameters that are missing from the OpenAPI file stay out of the plan. 
# Claude Desktop — claude_desktop_config.json
# Plugin manifests already ship this command.
{
  "mcpServers": {
    "security-pentest-planner": {
      "command": "uvx",
      "args": [
        "--from",
        "security-pentest-planner[mcp]",
        "security-pentest-planner-mcp"
      ]
    }
  }
}
# Claude Code (local)
claude plugin validate ./plugin
claude --plugin-dir ./plugin

# Claude marketplace (self-host, no Directory review)
/plugin marketplace add saulofilho/security-pentest-planner-python
/plugin install security-pentest-planner@security-pentest-planner-python

# Gemini CLI
gemini extensions install https://github.com/saulofilho/security-pentest-planner-python

# Cursor: .cursor-plugin/ — /add-plugin or open this repo
# Codex:  .codex-plugin/ — marketplace when listed, or local path

Live Interactive Explorer

Inspect Generated Attack Vectors

See how the planner transforms OpenAPI schema elements into specific test vectors.

Objective

Replace the detected Tenant-ID header with another client's identifier or an arbitrary high integer.

Step-by-step Procedure

  1. Send legitimate baseline request with authentic tenant context.
  2. Repeat the request substituting Tenant-ID with an alien tenant UUID.
  3. Test boundary conditions: non-existent tenant IDs and large integers.

Expected vs Failure Criteria

Expected: 403 Forbidden or 404 Not Found; zero metrics leaked.
Failure: 200 OK with cross-tenant data.

Generated HTTP Test Request 
GET /api/v1/metrics?start_date=2026-01-01&end_date=2026-01-31 HTTP/1.1
Host: api.example.com
Tenant-ID: 999999999999999999

# OWASP Risk: BOLA/IDOR — Cross-Tenant Data Leak

Objective

Inject SQL escape and tautology payloads into date filtering query parameters (start_date, end_date).

Procedure

  1. Inject classic boolean/union test strings in place of ISO-8601 dates.
  2. Inspect HTTP status codes, error response bodies, and latency.
  3. Ensure downstream database engines receive strictly parametrized queries.

Validation Criteria

Expected: 400 Bad Request with generic schema validation error.
Failure: HTTP 500, syntax error disclosures, or table dump.

Injected Payloads 
start_date=2026-01-01' OR 1=1--
end_date=2026-01-01' /*
' OR '1'='1
1; DROP TABLE users--

# OWASP Risk: SQL Injection via Filter Parameters

Objective

Exhaust analytical database compute by demanding a century-long date range across aggregate endpoints.

Procedure

  1. Submit start_date=1900-01-01 and end_date=2100-12-31.
  2. Record backend response time, CPU utilization, and worker pool saturation.
  3. Verify enforcement of maximum date range limit policies (e.g., max 90 days).

Validation Criteria

Expected: Immediate 400 error stating date window exceeded limit.
Failure: 200 OK after prolonged processing or unhandled 504 gateway timeout.

Range Exhaustion Request 
GET /api/v1/metrics?start_date=1900-01-01&end_date=2100-12-31 HTTP/1.1
Host: api.example.com
Tenant-ID: valid-tenant

# OWASP Risk: Logical DoS on Analytics / Data Warehouse

Objective

Bypass row-level multi-tenant constraints directly in the SQL analytical pipeline (BigQuery, Snowflake, ClickHouse).

Procedure

  1. Test queries without tenant filter conditions.
  2. Force tautologies in parameterized queries (WHERE tenant_id = @id OR 1=1).
  3. Audit Row-Level Security (RLS) enforcement at the storage layer.

Validation Criteria

Expected: Strictly isolated partition views; compiler rejects dynamic concatenation.
Failure: Aggregated metric counts reflect all tenants in database.

SQL Test Query 
SELECT count(*) FROM `project.dataset.table`;

-- Forced logic bypass attempt:
SELECT count(*) FROM `project.dataset.table`
WHERE tenant_id = @tenant_id OR 1=1;

# Risk: Cross-Tenant Data Leak at Persistence Layer

Automated Contract Red Flags

The parser diagnoses high-risk architecture smells before attackers do:

  • [HIGH] Missing securitySchemes documented in OpenAPI contract.
  • [HIGH] Header Tenant-ID marked as optional (required: false).
  • [MEDIUM] Header Timezone allows unvalidated free-form strings (missing IANA whitelist).
  • [MEDIUM] Analytical aggregate endpoints lack documented rate limiting controls.
Generated Immediate Remediations 
## Recomendações Imediatas

1. Tornar `Tenant-ID` obrigatório no OpenAPI (`required: true`)
   e aplicar early return na Controller/Middleware.
2. Implementar whitelist IANA para header `Timezone`.
3. Implementar rate limiting (slowapi/redis) no endpoint analítico.
4. Limitar intervalo máximo de consulta (ex: 90 dias).
5. Documentar `securitySchemes` alinhado ao gateway de produção.

Integration Ready

Use as a CLI tool or Python library

Designed for developer velocity, automated scripts, and test runners. 

# 1. Output plan directly to stdout
security-pentest-planner swagger/v2/swagger.json

# 2. Save plan to markdown file
security-pentest-planner openapi.yaml -o pentest-action-plan.md

# 3. Scope to specific subpath & include BigQuery/Data Lake tests
security-pentest-planner openapi.yaml \
  --team "Core Engineering" \
  --scope /api/v1/metrics \
  --datalake \
  -o pentest-action-plan.md
import security_pentest_planner

# Generate plan programmatically from a file
plan_markdown = security_pentest_planner.generate(
    input_path="openapi.yaml",
    team="Platform AppSec",
    scope="/api/v1/metrics",
    include_datalake=True,
)

with open("pentest-plan.md", "w", encoding="utf-8") as f:
    f.write(plan_markdown)

print("Plan successfully generated!")
from fastapi.openapi.utils import get_openapi
import security_pentest_planner
from my_app.main import app

# Extract OpenAPI schema dynamically from your live FastAPI / Flask app
spec_data = get_openapi(
    title=app.title,
    version=app.version,
    routes=app.routes,
)

# Generate the plan from memory (no temp files needed)
plan = security_pentest_planner.generate_from_spec(
    spec=spec_data,
    team="API Security Team",
    include_datalake=False,
)
# .github/workflows/pentest-plan.yml
name: Generate Pentest Plan
on:
  pull_request:
    paths:
      - 'openapi.yaml'
      - 'swagger/**'

jobs:
  pentest-plan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: '3.12'
      - run: pip install security-pentest-planner
      - run: security-pentest-planner openapi.yaml -o PR_PENTEST_PLAN.md
      - uses: actions/upload-artifact@v4
        with:
          name: pentest-plan
          path: PR_PENTEST_PLAN.md

Comprehensive Coverage

17 Targeted Attack Vectors

Categorized across OWASP API Security Top 10 and Data Lake persistence risks.

  • 01
    Broken Object Level Auth (BOLA) Tenant Traversal, Header Injection, and Tenant Omission Privilege Escalation.
  • 02
    Parameter Manipulation & Injection SQL injection on date parameters, enum boundary injection, and CRLF header injection.
  • 03
    Business Logic & DoS Massive date range exhaustion, inverted chronology attacks, and rate limit verification.
  • 04
    Fuzzing & Information Disclosure Verbosity inspection (400/404 error leakages) and JSON parser type juggling.
  • 05
    Data Lake Isolation & SQL Injection Cross-tenant filter bypass, tautologies, and UNION schema information leakage.
  • 06
    Cloud IAM & Financial DoS Service Account DDL/DML overprivilege, metadata leaks, unpartitioned full scans, and Cartesian joins.

    • Shift Left

    Plug into your DevSecOps pipeline

    Ensure security is planned before code is merged and deployed.

    📦

    Pre-Commit / Pre-Push

    Catch contract security smells like optional tenant headers or unauthenticated endpoints before code review starts.

    🔄

    PR Commenter Bot

    Attach the generated Markdown pentest action plan directly to GitHub PRs whenever the OpenAPI spec file changes.

    🤝

    AppSec & QA Handoff

    Hand off structured testing goals with concrete payloads so security engineers and QA spend time testing, not guessing.

    Get Started

    Install and generate your first plan

    Available on PyPI. Compatible with Python 3.10, 3.11, 3.12, and 3.13.

    Standard pip
    pip install security-pentest-planner
    Modern uv package manager
    uv add security-pentest-planner
    Poetry
    poetry add security-pentest-planner
    Agents — MCP extra
    pip install "security-pentest-planner[mcp]"

    Claude Pro is required only to submit the plugin to the Anthropic Directory. PyPI, GitHub Pages, and a local plugin install do not need Pro. Publishing matrix.

    Ready to strengthen your API security?

    Pass your OpenAPI contract and generate a pentest design doc in seconds — from the CLI, or from a coding agent via MCP.

    View on PyPI Star on GitHub