Skip to main content

security-pentest-planner

PyPI version Python Versions License: MIT

Site: saulofilho.github.io/security-pentest-planner-python

Generates pentest action plans from OpenAPI/Swagger as a CLI, a Python library, and an agent plugin (skills + MCP) in the style of obra/superpowers: authorized scope → engagement → contract risks → deterministic plan → remediations → selective RFCs.

What is new in 1.3.0: CHANGELOG.md — an engagement record (surface, happy path, what-if questions, chain, decision) before the vector plan.

Do you need Claude Pro?

  • Submit to the Directory: yes — Pro, Max, Team, or Enterprise (docs). Free accounts cannot submit.
  • PyPI, GitHub, Pages, local plugin install, self-hosted marketplace: no.

Details: docs/PUBLISH.md.

What it does

  • Parses OpenAPI 3.x (YAML/JSON)
  • Detects risk signals (tenant headers, dates, enums, free-form timezones, Data Lake)
  • Selects OWASP API vectors via taxonomy
  • Emits a Markdown design/action plan (procedures, payloads as examples, matrix, remediations hints)
  • Engagement record before any test: surface, happy path, what-if questions, chain, and the next observation
  • MCP server: engagement tools plus generate_pentest_plan (pip install "security-pentest-planner[mcp]")
  • Agent skill pipeline: scope → engagement → contract risks → plan → remediations → selective RFCs → handoff
  • Session-start hook injects using-pentest-planner

What it does NOT do

  • Executable attack scripts
  • PASS/FAIL test results
  • Merge-ready implementation PRs

Installation (Python)

pip install security-pentest-planner
# MCP for agents:
pip install "security-pentest-planner[mcp]"

CLI

security-pentest-planner openapi.yaml -o pentest-action-plan.md
security-pentest-planner openapi.yaml --team "Platform" --scope /api/v1/metrics --datalake -o plan.md

Engagement record (stops before any test):

security-pentest-planner engagement open engagement.json \
  --title "Game store" \
  --authorization "ticket-18" \
  --in-scope "lab store" \
  --out-of-bounds "production,other customers" \
  --environment lab

security-pentest-planner engagement seed engagement.json --openapi openapi.yaml
security-pentest-planner engagement show engagement.json

Install by harness (skills + MCP)

Harness Install
Claude Code (local) claude plugin validate ./plugin then claude --plugin-dir ./plugin
Claude marketplace (self-host) /plugin marketplace add saulofilho/security-pentest-planner-python → /plugin install security-pentest-planner@security-pentest-planner-python
Claude Directory After listing — see docs/MARKETPLACE.md (Pro+ to submit)
Cursor .cursor-plugin/ present — /add-plugin from marketplace when listed, or open this repo
Codex .codex-plugin/ — install from OpenAI plugin marketplace when listed, or local path
Gemini CLI gemini extensions install https://github.com/saulofilho/security-pentest-planner-python

Requires uv on PATH so the plugin can start MCP via uvx.

Skills (methodology)

Skill Role
using-pentest-planner Bootstrap — when/how to invoke skills
scoping-authorized-pentest Authorization + bounds
planning-engagement Surface, happy path, what-if questions, chain, decision
reviewing-openapi-risks Contract red-flags
security-pentest-planner MCP plan + pipeline
writing-remediations remediacoes.md
writing-security-rfcs Selective P0 RFCs
verifying-pentest-handoff Close AppSec → eng handoff

Session-start hook injects using-pentest-planner (same idea as Superpowers).

Programmatic usage

import security_pentest_planner

plan = security_pentest_planner.generate(
    input_path="openapi.yaml",
    team="Platform Team",
    scope="/api/v1/metrics",
    include_datalake=True,
)

From an in-memory spec (FastAPI, Flask, or any dict):

from fastapi.openapi.utils import get_openapi
import security_pentest_planner
from my_app.main import app

spec = get_openapi(title=app.title, version=app.version, routes=app.routes)
plan = security_pentest_planner.generate_from_spec(
    spec=spec,
    team="API Security Team",
    include_datalake=False,
)

MCP

Stdio server: security-pentest-planner-mcp (the plugin manifests already start it with uvx).

Tool Role
open_engagement Create the JSON with authorization, in-scope items, and out-of-bounds items
add_surface / add_flow / add_e_se Surface, happy path, and one what-if question
link_chain / decide / show_engagement Order, what to observe next, Markdown
seed_surface Surfaces from OpenAPI, without questions
suggest_questions / accept_questions Catalog suggestions and an explicit accept
generate_pentest_plan Markdown plan from an OpenAPI path (team, scope, include_datalake, optional output_path)
planner_version Installed package version

Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "security-pentest-planner": {
      "command": "uvx",
      "args": [
        "--from",
        "security-pentest-planner[mcp]",
        "security-pentest-planner-mcp"
      ]
    }
  }
}

CI

Example workflow that uploads the plan when the contract changes:

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

Publish everywhere

See docs/PUBLISH.md (PyPI, Pages, Directory, Cursor, Codex, Gemini, Partners vs Connectors).

Development

git clone https://github.com/saulofilho/security-pentest-planner-python.git
cd security-pentest-planner-python
pytest -v
python3 scripts/validate_plugin.py

License

MIT — see LICENSE.

Metadata

Release files for security-pentest-planner 1.3.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for security-pentest-planner 1.3.0
File Size Uploaded Provenance Actions
security_pentest_planner-1.3.0.tar.gz 34.1 kB Without provenance Details for security_pentest_planner-1.3.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for security-pentest-planner 1.3.0
File Interpreter ABI Platform Actions
security_pentest_planner-1.3.0-py3-none-any.whl Python 3 none any Details for security_pentest_planner-1.3.0-py3-none-any.whl

Total release size: 68.6 kB

Release files / security_pentest_planner-1.3.0.tar.gz

Download URL security_pentest_planner-1.3.0.tar.gz
Size 34.1 kB
Tags Source
SHA-256 checksum
How to use checksums
42fdfbdade7a404fb005b2965b563cacbb9f35509cc73d0a54c7c55327b98815
BLAKE2b-256 checksum
How to use checksums
0c59e1c5d87196e8042765f6364da14cd2fbda4e844f2faef8134efd951ca381
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.13.16

Release files / security_pentest_planner-1.3.0-py3-none-any.whl

Download URL security_pentest_planner-1.3.0-py3-none-any.whl
Size 34.4 kB
Tags Python 3
SHA-256 checksum
How to use checksums
029d76b5aef19362ddd0ac09dd5877057a1ec694abbf459f8c061f609c78591b
BLAKE2b-256 checksum
How to use checksums
9303443d9e96f817f5b55aedd6412081a1720711efd818957bc6d78ec8ac5a0d
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.13.16

Security for security-pentest-planner 1.3.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

1.3.0 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page