mcp-api-pentest 0.3.1

MCP server for autonomous API logic penetration testing — OWASP API Top 10 / BOLA-IDOR detection via LLM-driven analysis

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

# 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

---

Installation

From source (recommended for now)

git clone https://github.com/josenieto/mcp-api-pentest
cd mcp-api-pentest
uv sync

Requirements

• Python 3.10 or newer
• uv package manager

---

How to Use

Option 1: CLI mode (terminal)

Start the MCP server directly:

uv run app.py

With options:

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

{
  "mcpServers": {
    "api-logic-pentest": {
      "command": "uv",
      "args": ["run", "app.py"],
      "cwd": "/path/to/mcp-api-pentest"
    }
  }
}

Cursor (.cursor/mcp.json):

{
  "mcpServers": {
    "api-logic-pentest": {
      "command": "uv",
      "args": ["run", "app.py"],
      "cwd": "/path/to/mcp-api-pentest"
    }
  }
}

Claude Code (~/.claude/mcp.json):

{
  "mcpServers": {
    "api-logic-pentest": {
      "command": "uv",
      "args": ["run", "app.py"],
      "cwd": "/path/to/mcp-api-pentest"
    }
  }
}

Option 3: Sandbox mode (test locally)

# 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

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

# 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