🕷️ OWASP ZAP MCP Server

Drive the world's most popular web app scanner from your AI assistant.

Point Claude, Cursor, or any MCP client at OWASP ZAP and run real crawls, authenticated scans, and vulnerability triage — through 67 curated, safety-gated tools built straight from the official ZAP API.

✨ Why this exists

Talking to ZAP's raw REST API from an LLM is clumsy and risky: hundreds of endpoints, no guardrails, and it's easy to point an attack at the wrong host. This project gives your AI assistant a small, opinionated, safe surface:

🔐 Safe by design

• Cloud metadata endpoints (169.254.169.254) are always refused

• Optional scope allowlist + private-range blocking

• Control port bound to localhost by default

🔑 Real authenticated scanning

• Full workflow: context → auth method → indicators → user → forced-user

• scan_as_user for spider, AJAX spider, and active scan

• The thing most ZAP wrappers skip entirely

🧱 Reliable under load

• One pooled async client, bounded retries with backoff

• Typed errors + a uniform result envelope

• A single bad call can never crash the server

🚢 Production posture

• Fail-closed config, secrets never logged

• Pinned, non-root, health-gated containers

• Green CI on every push

🏗️ Architecture

flowchart LR
    A["🤖 LLM client<br/>(Claude · Cursor)"] -->|MCP / Streamable HTTP<br/>127.0.0.1:8000| B
    B["🕷️ zap-mcp-server<br/>Python 3.12 · 67 tools<br/>target policy · pooled client"] -->|internal docker net<br/>http://zap:8080| C
    C["🛡️ zap-daemon<br/>OWASP ZAP 2.17.0<br/>API restricted to private ranges"]
    B -.->|refuses metadata / out-of-scope| X["⛔ blocked targets"]

• The MCP server reaches ZAP over the internal Docker network.

• Both ports are published on 127.0.0.1 only — nothing is world-exposed.

• Every state-changing ZAP action requires the API key.

🚀 Quick start

# 1. Set your secret (never committed)
cp .env.example .env
#    edit .env -> ZAP_API_KEY=<long-random-value>

# 2. Launch (ZAP starts, becomes healthy, then the MCP server starts)
docker compose up -d --build

# 3. Confirm
docker compose ps                    # both services: healthy
docker compose logs -f mcp-server    # "Registered 67 MCP tools"

Then point your MCP client at it:

{
  "mcpServers": {
    "owasp-zap": { "url": "http://localhost:8000/mcp" }
  }
}

🔑 Authenticated scanning in 6 steps

The capability most ZAP wrappers skip — scan behind a login:

1. create_context ─────────────► scope it (include app, exclude /logout)
2. set_authentication_method ──► e.g. formBasedAuthentication
3. set_logged_in / out_indicator
4. new_user → set_user_credentials → set_user_enabled
5. set_forced_user (+ mode)  ──► keeps the session alive during scans
6. spider_scan_as_user → active_scan_as_user

Prefer repeatable runs? Drive the whole pipeline with a ZAP Automation Framework plan via zap_run_automation_plan.

🧰 The 67 tools

Tools marked 🎯 are gated by the target-authorization policy. Every tool returns a uniform envelope: {"status":"success",...} or {"status":"error","code":...,"retryable":...}.

All tool names are prefixed with zap_ (e.g. zap_active_scan).

🛡️ Security model

🧪 Development

python -m venv .venv && source .venv/bin/activate
pip install -r requirements-dev.txt
pytest -q          # policy, config, error envelope, tool behavior

CI runs py_compile + pytest on every push to main.

⚖️ Responsible use

Active scanning is an attack. In most jurisdictions, testing systems without permission is illegal. Before you scan:

• ✅ Confirm the target is in scope for an engagement you're authorized to run

• ✅ Pin scope with ZAP_TARGET_ALLOWLIST; consider ZAP_BLOCK_PRIVATE_TARGETS=true

• ✅ Use a long random ZAP_API_KEY; never commit .env

Cloud metadata endpoints are always refused and this cannot be overridden.

📄 License

MIT © Neeraj829784 — swap the LICENSE file for Apache-2.0 if you want an explicit patent grant.