security-pentest-planner
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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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.