Metadata-Version: 2.4
Name: security-pentest-planner
Version: 1.3.0
Summary: Generate pentest action plans from OpenAPI — CLI, Python API, MCP, and agent skills
Author-email: Saulo Filho <saulofilho@users.noreply.github.com>
License: MIT
Project-URL: Homepage, https://saulofilho.github.io/security-pentest-planner-python/
Project-URL: Repository, https://github.com/saulofilho/security-pentest-planner-python
Project-URL: Documentation, https://github.com/saulofilho/security-pentest-planner-python/blob/main/docs/CLAUDE_SETUP.md
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Information Technology
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Security
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pyyaml>=6.0
Provides-Extra: mcp
Requires-Dist: mcp>=2.0.0; extra == "mcp"
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: mcp>=2.0.0; extra == "dev"
Dynamic: license-file

# security-pentest-planner

[![PyPI version](https://badge.fury.io/py/security-pentest-planner.svg)](https://badge.fury.io/py/security-pentest-planner)
[![Python Versions](https://img.shields.io/pypi/pyversions/security-pentest-planner.svg)](https://pypi.org/project/security-pentest-planner/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

**Site:** [saulofilho.github.io/security-pentest-planner-python](https://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](https://github.com/obra/superpowers): authorized scope → engagement → contract risks → deterministic plan → remediations → selective RFCs.

**What is new in 1.3.0:** [CHANGELOG.md](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](https://claude.ai/directory/manage):** yes — **Pro, Max, Team, or Enterprise** ([docs](https://claude.com/docs/directory/publish)). Free accounts cannot submit.
- **PyPI, GitHub, Pages, local plugin install, self-hosted marketplace:** **no**.

Details: **[docs/PUBLISH.md](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)

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

## CLI

```bash
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):

```bash
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](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`](https://docs.astral.sh/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

```python
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):

```python
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`):

```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:

```yaml
# .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](docs/PUBLISH.md)** (PyPI, Pages, Directory, Cursor, Codex, Gemini, Partners vs Connectors).

## Development

```bash
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](LICENSE).
