# mcp-api-pentest

[![Python](https://img.shields.io/badge/python-3.10+-blue.svg)](https://python.org)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![PyPI](https://img.shields.io/pypi/v/mcp-api-pentest)](https://pypi.org/project/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
- **Intelligent retry**: Detects 429 responses and retries with exponential backoff
- **Multiple auth schemes**: Bearer, Basic, API Key (header/query), Cookie
- **Stealth mode**: Random delay between requests to evade WAF detection patterns
- **User-Agent rotation**: Rotates through a pool of realistic browser User-Agents
- **OpenAPI 3.x + YAML**: Parses Swagger 2.0, OpenAPI 3.x in JSON or YAML format
- **Markdown reports**: Automatic generation of security audit reports with evidence
- **Mock API sandbox**: 9 intentionally vulnerable endpoints for safe testing
- **CLI entry point**: Run from the terminal with `mcp-api-pentest --target https://api.example.com`

---

## Try it now (no AI client needed)

```bash
# 1. Start the mock API in the background
uv run mock_api.py &
sleep 2

# 2. Run a quick IDOR test
uv run python -c "
import anyio, json
from mcp_api_pentest.idor_detector.access_analyzer import analyze_access_control
async def test():
    r = await analyze_access_control(
        url='http://localhost:8080/api/v1/facturas/1001',
        privileged_token='admin_secret_token_2026',
        unprivileged_token='user_atacante_token_xyz',
        delay_seconds=0,
    )
    print(json.loads(r)['idor_alert'])
result = anyio.run(test)
"
```

## Example prompts for your AI

After connecting the MCP server to Claude Desktop, Cursor, or Claude Code, paste these into your AI assistant:

**Basic IDOR scan:**
> Audit the API at http://localhost:8080. Use the admin token 'admin_secret_token_2026' and the attacker token 'user_atacante_token_xyz'. Detect IDOR in all invoice endpoints.

**Chained attack:**
> Create an invoice with the victim token 'user_victima_token_abc', capture its ID, then try to read and delete it with the attacker token 'user_atacante_token_xyz'.

**Full audit with report:**
> Run a complete access control audit on http://localhost:8080. Test all endpoints with the three tokens: admin, victim, and attacker. Generate a findings report.

---

## 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
- `GET /api/v1/spec.yaml` — returns OpenAPI 3.x spec in YAML format

---

## Running Tests

```bash
# Run all tests (141 tests, all passing)
uv run pytest

# Run with verbose output
uv run pytest -v

# Run tests for a specific module
uv run pytest src/mcp_api_pentest/idor_detector/tests/
```

**Code quality checks:**

```bash
# Lint
uv run ruff check .

# Type checking
uv run mypy src/mcp_api_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.

```
src/mcp_api_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