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
