mcp-api-pentest 0.2.0__tar.gz

mcp_api_pentest-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 mcp-api-logic-pentest
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

mcp_api_pentest-0.2.0/MANIFEST.in

@@ -0,0 +1,2 @@
+include README.md
+include LICENSE

mcp_api_pentest-0.2.0/PKG-INFO

@@ -0,0 +1,288 @@
+Metadata-Version: 2.4
+Name: mcp-api-pentest
+Version: 0.2.0
+Summary: MCP server for autonomous API logic penetration testing — OWASP API Top 10 / BOLA-IDOR detection via LLM-driven analysis
+Author-email: Jose Nieto <josenieto@github.com>
+License: MIT
+Project-URL: Homepage, https://github.com/josenieto/mcp-api-logic-pentest
+Project-URL: Repository, https://github.com/josenieto/mcp-api-logic-pentest
+Project-URL: Issues, https://github.com/josenieto/mcp-api-logic-pentest/issues
+Keywords: mcp,pentest,api-security,owasp,bola,idor,security-audit
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Information Technology
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Security
+Classifier: Topic :: Software Development :: Testing
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: fastapi>=0.139.2
+Requires-Dist: fastmcp>=3.4.4
+Requires-Dist: httpx>=0.28.1
+Requires-Dist: uvicorn>=0.51.0
+Dynamic: license-file
+
+# mcp-api-pentest
+
+An MCP server that lets AI assistants (Claude Desktop, Cursor, Claude Code) perform automated security audits on your APIs. It detects **BOLA/IDOR** vulnerabilities — the #1 risk in the OWASP API Top 10 — where one user can access another user's data.
+
+> Think of it as giving your AI the ability to act like a penetration tester, running requests with different user tokens and comparing the results to find broken authorization logic.
+
+---
+
+## Quickstart in 3 minutes
+
+```bash
+# 1. Clone and install
+git clone https://github.com/josenieto/mcp-api-pentest
+cd mcp-api-pentest
+uv sync
+
+# 2. Start the mock API (a vulnerable API for safe testing)
+uv run mock_api.py
+
+# 3. Start the MCP server
+uv run app.py
+```
+
+That's it. The server is now running and waiting for an AI client to connect.
+
+---
+
+## What it does
+
+The project acts as a bridge between an AI and your API:
+
+```
+AI (Claude/Cursor)  ←→  MCP Server  ←→  API Target
+                           |
+                     Generates REPORTE_PENTEST.md
+```
+
+**Example attack flow the AI can run:**
+
+1. **Create** an invoice with Token A → `POST /api/v1/invoices`
+2. **Read** the same invoice with Token B → `GET /api/v1/invoices/42`
+3. **Detect** the IDOR → both tokens return 200 OK with 94% similar content
+4. **Save** the finding → "BOLA/IDOR in invoices endpoint — CRITICAL"
+5. **Generate** a report → `REPORTE_PENTEST.md`
+
+All of this happens without writing a single line of code — the AI drives the audit through MCP tools.
+
+---
+
+## Features
+
+- **IDOR detection**: Compares API responses with privileged vs unprivileged tokens
+- **Chained attacks**: Create a resource, capture its ID, then attack it with a different user
+- **Multi-session state**: Cache dynamic values across requests for complex attack flows
+- **Smart truncation**: Handles massive JSON responses without flooding the AI's context window
+- **Rate limiting**: Passive delays to avoid being blocked by WAFs
+- **Markdown reports**: Automatic generation of security audit reports with evidence
+- **Mock API sandbox**: 7 intentionally vulnerable endpoints for safe testing
+- **CLI entry point**: Run from the terminal with `mcp-api-pentest --target https://api.example.com`
+
+---
+
+## Installation
+
+### From source (recommended for now)
+
+```bash
+git clone https://github.com/josenieto/mcp-api-pentest
+cd mcp-api-pentest
+uv sync
+```
+
+### Requirements
+
+- Python 3.10 or newer
+- [uv](https://github.com/astral-sh/uv) package manager
+
+---
+
+## How to Use
+
+### Option 1: CLI mode (terminal)
+
+Start the MCP server directly:
+
+```bash
+uv run app.py
+```
+
+With options:
+
+```bash
+mcp-api-pentest \
+  --swagger spec.json \
+  --target https://api.example.com \
+  --token-admin "admin123" \
+  --token-victim "victim456" \
+  --token-attacker "attacker789" \
+  --output report.md \
+  --delay 1.0
+```
+
+### Option 2: Connect an AI client
+
+Add this to your MCP client configuration:
+
+**Claude Desktop** (`claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "api-logic-pentest": {
+      "command": "uv",
+      "args": ["run", "app.py"],
+      "cwd": "/path/to/mcp-api-pentest"
+    }
+  }
+}
+```
+
+**Cursor** (`.cursor/mcp.json`):
+
+```json
+{
+  "mcpServers": {
+    "api-logic-pentest": {
+      "command": "uv",
+      "args": ["run", "app.py"],
+      "cwd": "/path/to/mcp-api-pentest"
+    }
+  }
+}
+```
+
+**Claude Code** (`~/.claude/mcp.json`):
+
+```json
+{
+  "mcpServers": {
+    "api-logic-pentest": {
+      "command": "uv",
+      "args": ["run", "app.py"],
+      "cwd": "/path/to/mcp-api-pentest"
+    }
+  }
+}
+```
+
+### Option 3: Sandbox mode (test locally)
+
+```bash
+# Starts a vulnerable mock API on port 8080
+uv run mock_api.py
+```
+
+The mock API includes 3 test users with tokens:
+
+| User | Token | Role |
+|------|-------|------|
+| Admin | `admin_secret_token_2026` | admin |
+| Victim | `user_victima_token_abc` | user |
+| Attacker | `user_atacante_token_xyz` | user |
+
+**Vulnerable endpoints** (intentionally broken for testing):
+
+- `GET /api/v1/facturas/{id}` — IDOR (no ownership validation)
+- `POST /api/v1/invoices` — creates invoice, captures ID for chained attacks
+- `DELETE /api/v1/invoices/{id}` — deletes without ownership check
+- `GET /api/v1/users/{id}/profile` — reads profile without ownership check
+- `PUT /api/v1/users/{id}/profile` — mass assignment without ownership (escalate role to admin)
+- `GET /api/v1/items` — pagination without bounds validation
+- `POST /api/v1/items` — creates item for chained attacks
+- `DELETE /api/v1/items/{id}` — deletes without ownership check
+
+---
+
+## Running Tests
+
+```bash
+# Run all tests (102 tests, all passing)
+uv run pytest
+
+# Run with verbose output
+uv run pytest -v
+
+# Run tests for a specific module
+uv run pytest mcp_api_logic_pentest/idor_detector/tests/
+```
+
+**Code quality checks:**
+
+```bash
+# Lint
+uv run ruff check .
+
+# Type checking
+uv run mypy mcp_api_logic_pentest/ --ignore-missing-imports
+```
+
+---
+
+## Available MCP Tools
+
+The AI can use 11 tools to audit APIs:
+
+| Tool | What it does |
+|------|-------------|
+| `parse_api_spec` | Reads an OpenAPI/Swagger file and extracts routes |
+| `execute_security_request` | Sends HTTP requests with auth headers and rate limiting |
+| `analyze_access_control` | Compares responses from two tokens to detect IDOR |
+| `capture_context` | Stores a dynamic value (like a created ID) in memory |
+| `get_context` | Retrieves a previously stored value |
+| `list_context` | Lists all stored key-value pairs |
+| `clear_context` | Resets the session cache |
+| `extract_json_value` | Extracts a field from a JSON response using dot-notation |
+| `save_security_finding` | Records a security finding to the audit report |
+| `generate_report` | Returns the full Markdown audit report |
+| `export_report_json` | Exports all findings as structured JSON |
+
+---
+
+## Architecture
+
+This project follows a **Modular Monolith by Features** design.
+
+```
+mcp_api_logic_pentest/
+├── config/               → Global settings and logger
+├── shared/               → Reusable utilities (JSON truncation)
+├── spec_analyzer/        → OpenAPI/Swagger file parsing
+├── http_client/          → HTTP communication with auth providers
+├── idor_detector/        → Multi-session authorization comparison
+├── audit_context/        → In-memory state for chained attacks
+├── report_generator/     → Security finding reports (Markdown + JSON)
+├── orchestration/        → Cross-module attack flow coordinator
+└── adapters/             → Entry points: MCP server and CLI
+```
+
+Each module is self-contained with its own tests. New detection patterns (like Mass Assignment or Rate Limit testing) are added as new modules without touching existing code.
+
+See `docs/adr/ADR-001-modular-monolith-by-features.md` for the full architecture decision.
+
+---
+
+## Contributing
+
+1. Create a branch from `integration/master`
+2. Write your changes **plus tests** (we follow RED/GREEN/REFACTOR)
+3. Push — CI runs lint, type check, and tests automatically
+4. When CI passes, the merge happens automatically
+
+
+---
+
+## License
+
+MIT

mcp_api_pentest-0.2.0/README.md

@@ -0,0 +1,257 @@
+# mcp-api-pentest
+
+An MCP server that lets AI assistants (Claude Desktop, Cursor, Claude Code) perform automated security audits on your APIs. It detects **BOLA/IDOR** vulnerabilities — the #1 risk in the OWASP API Top 10 — where one user can access another user's data.
+
+> Think of it as giving your AI the ability to act like a penetration tester, running requests with different user tokens and comparing the results to find broken authorization logic.
+
+---
+
+## Quickstart in 3 minutes
+
+```bash
+# 1. Clone and install
+git clone https://github.com/josenieto/mcp-api-pentest
+cd mcp-api-pentest
+uv sync
+
+# 2. Start the mock API (a vulnerable API for safe testing)
+uv run mock_api.py
+
+# 3. Start the MCP server
+uv run app.py
+```
+
+That's it. The server is now running and waiting for an AI client to connect.
+
+---
+
+## What it does
+
+The project acts as a bridge between an AI and your API:
+
+```
+AI (Claude/Cursor)  ←→  MCP Server  ←→  API Target
+                           |
+                     Generates REPORTE_PENTEST.md
+```
+
+**Example attack flow the AI can run:**
+
+1. **Create** an invoice with Token A → `POST /api/v1/invoices`
+2. **Read** the same invoice with Token B → `GET /api/v1/invoices/42`
+3. **Detect** the IDOR → both tokens return 200 OK with 94% similar content
+4. **Save** the finding → "BOLA/IDOR in invoices endpoint — CRITICAL"
+5. **Generate** a report → `REPORTE_PENTEST.md`
+
+All of this happens without writing a single line of code — the AI drives the audit through MCP tools.
+
+---
+
+## Features
+
+- **IDOR detection**: Compares API responses with privileged vs unprivileged tokens
+- **Chained attacks**: Create a resource, capture its ID, then attack it with a different user
+- **Multi-session state**: Cache dynamic values across requests for complex attack flows
+- **Smart truncation**: Handles massive JSON responses without flooding the AI's context window
+- **Rate limiting**: Passive delays to avoid being blocked by WAFs
+- **Markdown reports**: Automatic generation of security audit reports with evidence
+- **Mock API sandbox**: 7 intentionally vulnerable endpoints for safe testing
+- **CLI entry point**: Run from the terminal with `mcp-api-pentest --target https://api.example.com`
+
+---
+
+## Installation
+
+### From source (recommended for now)
+
+```bash
+git clone https://github.com/josenieto/mcp-api-pentest
+cd mcp-api-pentest
+uv sync
+```
+
+### Requirements
+
+- Python 3.10 or newer
+- [uv](https://github.com/astral-sh/uv) package manager
+
+---
+
+## How to Use
+
+### Option 1: CLI mode (terminal)
+
+Start the MCP server directly:
+
+```bash
+uv run app.py
+```
+
+With options:
+
+```bash
+mcp-api-pentest \
+  --swagger spec.json \
+  --target https://api.example.com \
+  --token-admin "admin123" \
+  --token-victim "victim456" \
+  --token-attacker "attacker789" \
+  --output report.md \
+  --delay 1.0
+```
+
+### Option 2: Connect an AI client
+
+Add this to your MCP client configuration:
+
+**Claude Desktop** (`claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "api-logic-pentest": {
+      "command": "uv",
+      "args": ["run", "app.py"],
+      "cwd": "/path/to/mcp-api-pentest"
+    }
+  }
+}
+```
+
+**Cursor** (`.cursor/mcp.json`):
+
+```json
+{
+  "mcpServers": {
+    "api-logic-pentest": {
+      "command": "uv",
+      "args": ["run", "app.py"],
+      "cwd": "/path/to/mcp-api-pentest"
+    }
+  }
+}
+```
+
+**Claude Code** (`~/.claude/mcp.json`):
+
+```json
+{
+  "mcpServers": {
+    "api-logic-pentest": {
+      "command": "uv",
+      "args": ["run", "app.py"],
+      "cwd": "/path/to/mcp-api-pentest"
+    }
+  }
+}
+```
+
+### Option 3: Sandbox mode (test locally)
+
+```bash
+# Starts a vulnerable mock API on port 8080
+uv run mock_api.py
+```
+
+The mock API includes 3 test users with tokens:
+
+| User | Token | Role |
+|------|-------|------|
+| Admin | `admin_secret_token_2026` | admin |
+| Victim | `user_victima_token_abc` | user |
+| Attacker | `user_atacante_token_xyz` | user |
+
+**Vulnerable endpoints** (intentionally broken for testing):
+
+- `GET /api/v1/facturas/{id}` — IDOR (no ownership validation)
+- `POST /api/v1/invoices` — creates invoice, captures ID for chained attacks
+- `DELETE /api/v1/invoices/{id}` — deletes without ownership check
+- `GET /api/v1/users/{id}/profile` — reads profile without ownership check
+- `PUT /api/v1/users/{id}/profile` — mass assignment without ownership (escalate role to admin)
+- `GET /api/v1/items` — pagination without bounds validation
+- `POST /api/v1/items` — creates item for chained attacks
+- `DELETE /api/v1/items/{id}` — deletes without ownership check
+
+---
+
+## Running Tests
+
+```bash
+# Run all tests (102 tests, all passing)
+uv run pytest
+
+# Run with verbose output
+uv run pytest -v
+
+# Run tests for a specific module
+uv run pytest mcp_api_logic_pentest/idor_detector/tests/
+```
+
+**Code quality checks:**
+
+```bash
+# Lint
+uv run ruff check .
+
+# Type checking
+uv run mypy mcp_api_logic_pentest/ --ignore-missing-imports
+```
+
+---
+
+## Available MCP Tools
+
+The AI can use 11 tools to audit APIs:
+
+| Tool | What it does |
+|------|-------------|
+| `parse_api_spec` | Reads an OpenAPI/Swagger file and extracts routes |
+| `execute_security_request` | Sends HTTP requests with auth headers and rate limiting |
+| `analyze_access_control` | Compares responses from two tokens to detect IDOR |
+| `capture_context` | Stores a dynamic value (like a created ID) in memory |
+| `get_context` | Retrieves a previously stored value |
+| `list_context` | Lists all stored key-value pairs |
+| `clear_context` | Resets the session cache |
+| `extract_json_value` | Extracts a field from a JSON response using dot-notation |
+| `save_security_finding` | Records a security finding to the audit report |
+| `generate_report` | Returns the full Markdown audit report |
+| `export_report_json` | Exports all findings as structured JSON |
+
+---
+
+## Architecture
+
+This project follows a **Modular Monolith by Features** design.
+
+```
+mcp_api_logic_pentest/
+├── config/               → Global settings and logger
+├── shared/               → Reusable utilities (JSON truncation)
+├── spec_analyzer/        → OpenAPI/Swagger file parsing
+├── http_client/          → HTTP communication with auth providers
+├── idor_detector/        → Multi-session authorization comparison
+├── audit_context/        → In-memory state for chained attacks
+├── report_generator/     → Security finding reports (Markdown + JSON)
+├── orchestration/        → Cross-module attack flow coordinator
+└── adapters/             → Entry points: MCP server and CLI
+```
+
+Each module is self-contained with its own tests. New detection patterns (like Mass Assignment or Rate Limit testing) are added as new modules without touching existing code.
+
+See `docs/adr/ADR-001-modular-monolith-by-features.md` for the full architecture decision.
+
+---
+
+## Contributing
+
+1. Create a branch from `integration/master`
+2. Write your changes **plus tests** (we follow RED/GREEN/REFACTOR)
+3. Push — CI runs lint, type check, and tests automatically
+4. When CI passes, the merge happens automatically
+
+
+---
+
+## License
+
+MIT

mcp_api_pentest-0.2.0/mcp_api_logic_pentest/adapters/cli.py

@@ -0,0 +1,65 @@
+"""CLI entry point for mcp-api-logic-pentest."""
+import argparse
+import sys
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="mcp-api-pentest",
+        description="MCP server for autonomous API logic penetration testing",
+    )
+    parser.add_argument(
+        "--swagger", "-s",
+        help="Path to OpenAPI/Swagger spec file (JSON or YAML)",
+    )
+    parser.add_argument(
+        "--target", "-t",
+        help="Base URL of the API to audit",
+    )
+    parser.add_argument(
+        "--output", "-o",
+        default="REPORTE_PENTEST.md",
+        help="Output report path (default: REPORTE_PENTEST.md)",
+    )
+    parser.add_argument(
+        "--delay",
+        type=float,
+        default=0.5,
+        help="Delay in seconds between requests (default: 0.5)",
+    )
+    parser.add_argument(
+        "--token-admin",
+        help="Admin-level authentication token for multi-session audits",
+    )
+    parser.add_argument(
+        "--token-victim",
+        help="Victim-level authentication token for multi-session audits",
+    )
+    parser.add_argument(
+        "--token-attacker",
+        help="Attacker-level authentication token for multi-session audits",
+    )
+    parser.add_argument(
+        "--config",
+        help="Path to YAML configuration file",
+    )
+    parser.add_argument(
+        "--mock",
+        action="store_true",
+        help="Launch the mock API sandbox instead of the MCP server",
+    )
+    return parser
+
+
+def main() -> None:
+    args = build_parser().parse_args()
+
+    if args.mock:
+        print("Starting mock API sandbox...")
+        import subprocess
+        subprocess.run([sys.executable, "mock_api.py"])
+        return
+
+    print("Starting MCP API Logic Pentest server...")
+    from mcp_api_logic_pentest.adapters.mcp_server import mcp
+    mcp.run()

mcp_api_pentest-0.2.0/mcp_api_logic_pentest/adapters/mcp_server.py

@@ -0,0 +1,50 @@
+from fastmcp import FastMCP
+
+from mcp_api_logic_pentest.audit_context.attack_context import (
+    capture_context,
+    clear_context,
+    extract_json_value,
+    get_context,
+    list_context,
+)
+from mcp_api_logic_pentest.http_client.http_client import execute_security_request
+from mcp_api_logic_pentest.idor_detector.access_analyzer import analyze_access_control
+from mcp_api_logic_pentest.report_generator.reporter import (
+    export_report_json,
+    generate_report,
+    save_security_finding,
+)
+from mcp_api_logic_pentest.spec_analyzer.spec_parser import parse_api_spec
+
+mcp = FastMCP("mcp-api-logic-pentest")
+
+# ---------------------------------------------------------------------------
+# Fase 1 + 4: HTTP client and spec parsing
+# ---------------------------------------------------------------------------
+
+mcp.tool()(parse_api_spec)
+mcp.tool()(execute_security_request)
+
+# ---------------------------------------------------------------------------
+# Fase 2: Multi-session IDOR detection
+# ---------------------------------------------------------------------------
+
+mcp.tool()(analyze_access_control)
+
+# ---------------------------------------------------------------------------
+# Fase 3: State management for chained attacks
+# ---------------------------------------------------------------------------
+
+mcp.tool()(capture_context)
+mcp.tool()(get_context)
+mcp.tool()(list_context)
+mcp.tool()(clear_context)
+mcp.tool()(extract_json_value)
+
+# ---------------------------------------------------------------------------
+# Fase 5b: Report generation
+# ---------------------------------------------------------------------------
+
+mcp.tool()(save_security_finding)
+mcp.tool()(generate_report)
+mcp.tool()(export_report_json)