星战科技xingzhan.cloud
返回市场
MCP-Zap-服务器

MCP-Zap-服务器

作者：dtkmn18 星标更新：2025-11-21
安装使用来源：spider==github.com

项目介绍

GitHub stars GitHub forks GitHub watchers GitHub repo size GitHub language count GitHub top language GitHub last commit GitHub Tag

重要 该项目仍在开发中，尚未准备好用于生产环境。它旨在教育目的，并展示模型上下文协议（MCP）与OWASP ZAP的能力。

注意 本项目未得到OWASP或OWASP ZAP项目的认可。它是独立实现的模型上下文协议（MCP），用于与OWASP ZAP一起使用。

MCP ZAP 服务器

这是一个Spring Boot应用程序，公开了OWASP ZAP作为MCP（模型上下文协议）服务器。它允许任何兼容MCP的AI代理（例如Claude Desktop、Cursor）编排ZAP操作——爬虫、主动扫描、导入OpenAPI规范以及生成报告。

📚 文档

📖 查看完整文档 - 完整指南、API参考和示例

快速链接

在Cursor上的演示

📺 观看演示视频 | YouTube链接

<a href="https://www.youtube.com/watch?v=9_9VqsL0lNw" target="_blank" rel="noopener noreferrer"> <img src="https://img.youtube.com/vi/9__9VqsL0lNw/0.jpg" alt="▶️ 观看演示"> </a>

目录

特性

  • MCP ZAP服务器：公开ZAP操作为MCP工具。消除了手动CLI调用和脆弱脚本。
  • OpenAPI集成：将远程OpenAPI规范导入ZAP并启动主动扫描
  • 报告生成：生成HTML/JSON报告并以编程方式获取内容
  • 容器化：通过docker-compose编排运行ZAP和MCP服务器
  • 安全：为ZAP（ZAP_API_KEY）和MCP服务器（MCP_API_KEY）配置API密钥

架构

flowchart LR
  subgraph "DOCKER COMPOSE"
    direction LR
    ZAP["OWASP ZAP (容器)"]
    MCPZAP["MCP ZAP Server"]
    MCPFile["MCP 文件系统服务器"]
    Client["MCP 客户端 (开放Web-UI)"]
    Juice["OWASP Juice-Shop"]
    Petstore["Swagger Petstore Server"]
  end

  MCPZAP <-->|HTTP/可流式传输 + MCPO| Client
  MCPFile <-->|STDIO + MCPO| Client
  MCPZAP -->|ZAP REST API| ZAP
  ZAP -->|扫描、警报、报告| MCPZAP

  ZAP -->|爬虫/主动扫描| Juice
  ZAP -->|导入API/主动扫描| Petstore

前提条件

  • 支持LLM工具调用（如gpt-4o、Claude 3、Llama 3、mistral、phi3）
  • Docker ≥ 20.10
  • Docker Compose ≥ 1.29
  • Java 21+（仅在Docker外构建Spring Boot MCP服务器时需要）

安全配置

生成API密钥

在启动服务之前，生成安全的API密钥：

# 生成ZAP API密钥
openssl rand -hex 32

# 生成MCP API密钥
openssl rand -hex 32

环境设置

  1. 复制示例环境文件：
cp .env.example .env
  1. 编辑.env并更新以下必需值：
# 必需：设置您的安全API密钥
ZAP_API_KEY=在这里填写您生成的ZAP API密钥
MCP_API_KEY=在这里填写您生成的MCP API密钥

# 必需：设置您的工作目录
LOCAL_ZAP_WORKPLACE_FOLDER=/到您的zap工作区的路径
  1. 重要：切勿将.env提交到版本控制中。它已经在.gitignore中。

安全功能

MCP ZAP服务器包括全面的安全功能，具有三种身份验证模式：

  • 🔐 灵活的身份验证：选择none、api-key或jwt模式
  • 🔑 API密钥身份验证：简单承载令牌，适用于可信环境
  • 🎫 JWT身份验证：现代基于令牌的身份验证，带有过期和刷新
  • 🛡️ URL验证：防止扫描内部资源和私有网络
  • ⏱️ 扫描限制：可配置超时和并发扫描限制
  • 📋 白名单/黑名单：对可扫描域进行细粒度控制

身份验证模式

MCP服务器支持三种身份验证模式，以平衡安全性和易用性：

🚫 模式1：无身份验证（none）

⚠️ 警告：仅限开发/测试

# .env
MCP_SECURITY_MODE=none

仅用于受信任网络上的本地开发。所有请求均无需身份验证即可访问。

CSRF保护：禁用以保持MCP协议兼容性（MCP端点不支持CSRF令牌）。

🔑 模式2：API密钥身份验证（api-key）

✅ 推荐用于：简单部署、内部网络

# .env
MCP_SECURITY_MODE=api-key
MCP_API_KEY=您的安全API密钥

简单的静态API密钥身份验证：

# 使用X-API-Key头
curl -H "X-API-Key: 您的mcp-api-key" http://localhost:7456/mcp

CSRF保护：禁用（设计如此）- 这是一个仅API服务器，使用基于令牌的身份验证，而不是会话cookie。CSRF攻击仅影响浏览器中的基于cookie的身份验证。详情见SECURITY.md。

优点：简单配置，无令牌过期，最小开销
使用场景：Docker Compose，内部网络，单租户部署

🎫 模式3：JWT身份验证（jwt）

✅ 推荐用于：生产，云部署，多租户

# .env
MCP_SECURITY_MODE=jwt
JWT_ENABLED=true
JWT_SECRET=您的256位秘密至少32个字符
MCP_API_KEY=您的初始API密钥

带有自动过期的基于令牌的身份验证：

# 1. 交换API密钥以获取JWT令牌
curl -X POST http://localhost:7456/auth/token \
  -H "Content-Type: application/json" \
  -d '{"apiKey": "您的mcp-api-key", "clientId": "您的客户端ID"}'

# 2. 使用访问令牌（有效期1小时）
curl -H "Authorization: Bearer 您的访问令牌" http://localhost:7456/mcp

# 3. 当过期时刷新（刷新令牌有效期7天）
curl -X POST http://localhost:7456/auth/refresh \
  -H "Content-Type: application/json" \
  -d '{"refreshToken": "您的刷新令牌"}'

CSRF保护：禁用（设计如此）- 仅API服务器，使用无状态JWT身份验证。详情见SECURITY.md以了解OWASP合规性解释。

优点：令牌过期（1小时访问，7天刷新），令牌撤销，审计轨迹
使用场景：生产部署，公共访问，合规性要求

注意：JWT模式向后兼容—迁移期间客户端仍可使用API密钥。

🔐 MCP安全合规性：此服务器遵循模型上下文协议安全最佳实践。详情及路线图见SECURITY.md。

📚 详细文档：

URL安全配置

默认情况下，服务器阻止扫描：

  • 本地主机和回环地址（127.0.0.0/8，::1）
  • 私有网络范围（10.0.0.0/8，172.16.0.0/12，192.168.0.0/16）
  • 链路本地地址（169.254.0.0/16）

要启用特定域名的扫描，请在.env中配置白名单：

# 仅允许特定域名（支持通配符）
ZAP_URL_WHITELIST=example.com,*.test.com,demo.org

警告：仅在隔离且安全的环境中启用ZAP_ALLOW_LOCALHOST=true或ZAP_ALLOW_PRIVATE_NETWORKS=true。

快速开始

开发（快速构建 - 2-3分钟）⚡

对于本地开发，使用JVM镜像进行快速迭代：

git clone https://github.com/dtkmn/mcp-zap-server.git
cd mcp-zap-server

# 设置环境变量
cp .env.example .env
# 编辑.env以包含您的API密钥和配置

# 创建工作区目录
mkdir -p $(grep LOCAL_ZAP_WORKPLACE_FOLDER .env | cut -d '=' -f2)/zap-wrk

# 启动服务（JVM - 快速构建）
./dev.sh
# 或手动：
docker compose -f docker-compose.yml -f docker-compose.dev.yml up -d --build

构建时间：约2-3分钟
启动时间：约3-5秒
用途：开发、测试、快速迭代

生产（原生镜像 - 20+分钟）🏭

对于闪电般快速启动的生产部署：

# 构建原生镜像（去喝杯咖啡☕）
./prod.sh
# 或手动：
docker compose -f docker-compose.yml -f docker-compose.prod.yml up -d --build

构建时间：约20-25分钟
启动时间：约0.6秒
用途：生产、云部署、无服务器

性能对比

指标JVM（开发）原生（生产）
构建时间2-3分钟20-25分钟
启动时间3-5秒0.6秒
内存约300MB约200MB
镜像大小383MB391MB
最佳用途开发生产
Docker-Compose

在浏览器中打开http://localhost:3000，您应该能看到Open Web-UI界面。

设置自定义OpenAI/Ollama API连接

Admin-Panel-Open-WebUI

设置MCP服务器连接

MCP-Tools-Config-Open-WebUI

完成后，您可以查看Prompt Examples部分，了解如何使用MCP ZAP服务器与您的AI代理一起使用。

查看所有服务的日志，运行：

   docker-compose logs -f

查看特定服务的日志，运行：

   docker-compose logs -f <服务名称>

服务概述

zap

  • 镜像：zaproxy/zap-stable
  • 目的：在8090端口上运行OWASP ZAP守护进程。
  • 配置：
    • 需要一个API密钥用于安全，通过ZAP_API_KEY环境变量配置。
    • 接受来自所有地址的请求。
    • 将主机目录${LOCAL_ZAP_WORKPLACE_FOLDER}映射到容器路径/zap/wrk。

open-webui

  • 镜像：ghcr.io/open-webui/open-webui
  • 目的：提供一个管理ZAP和MCP服务器的Web界面。
  • 配置：
    • 暴露3000端口。
    • 使用命名卷来持久化后端数据。

mcpo

  • 镜像：ghcr.io/open-webui/mcpo:main
  • 目的：公开任何MCP工具为OpenAPI兼容的HTTP服务器。仅由open-webui所需。https://github.com/open-webui/mcpo
  • 配置：
    • 在8000端口上运行。
    • 使用流式传输HTTP模式通过URLhttp://mcp-server:7456/mcp连接到MCP服务器。

mcp-server

  • 镜像：mcp-zap-server:latest
  • 目的：此仓库。作为MCP服务器公开ZAP操作，使用API密钥身份验证。
  • 配置：
    • 依赖于zap服务并通过配置的ZAP_API_KEY连接到它。
    • 需要MCP_API_KEY用于客户端身份验证（在.env文件中设置）。
    • 暴露7456端口用于流式传输HTTP连接。
    • 将主机目录${LOCAL_ZAP_WORKPLACE_FOLDER}映射到/zap/wrk以允许文件访问。
    • 支持可配置的扫描限制和URL验证策略。
  • 安全：
    • 所有端点（除健康检查外）都需要API密钥身份验证。
    • 通过X-API-Key头或Authorization: Bearer <token>包含API密钥。
    • 默认情况下，URL验证防止扫描内部/私有网络。

mcpo-filesystem

  • 镜像：ghcr.io/open-webui/mcpo:main
  • 目的：公开MCP文件系统服务器为OpenAPI兼容的HTTP端点。
  • 配置：
    • 依赖于open-webui
    • 暴露8001端口。

juice-shop

  • 镜像：bkimminich/juice-shop
  • 目的：提供一个故意不安全的Web应用程序，用于测试ZAP的扫描能力。
  • 配置：
    • 在3001端口上运行。

petstore

  • 镜像：swaggerapi/petstore3:unstable
  • 目的：运行Swagger Petstore示例API，以演示OpenAPI导入和扫描。
  • 配置：
    • 在3002端口上运行。

停止服务

要停止并删除所有容器，运行：

docker-compose down

手动构建

./gradlew clean build

与Claude Desktop、Cursor、Windsurf或任何兼容MCP的AI代理一起使用

可流式传输的HTTP模式

这是连接到MCP服务器的推荐模式。

重要：您必须包含API密钥用于身份验证。

{
  "mcpServers": {
    "zap-mcp-server": {
      "protocol": "mcp",
      "transport": "streamable-http",
      "url": "http://localhost:7456/mcp",
      "headers": {
        "X-API-Key": "您的mcp-api-key"
      }
    }
  }
}

或使用Bearer令牌：

{
  "mcpServers": {
    "zap-mcp-server": {
      "protocol": "mcp",
      "transport": "streamable-http",
      "url": "http://localhost:74