Zap MCP Server

🚀 ZAP MCP 服务器

ZAP MCP 服务器是一款强大的模型上下文协议（MCP）服务器，它将 OWASP ZAP（Zed 攻击代理）与 AI 助手和 MCP 客户端集成在一起。通过自动化漏洞扫描，实现由 AI 驱动的安全测试。

🚀 快速开始

🐳 Docker/Podman（推荐）

使用容器实现最快启动：

# 1. 克隆仓库
git clone https://github.com/LisBerndt/zap-custom-mcp.git
cd zap-custom-mcp

# 2. 启动（自动检测 Docker/Podman）
# Linux/Mac：
./build.sh && ./start.sh

# Windows：
build.bat
start.bat

# 3. 等待（约 90 秒）后连接：
# http://localhost:8082/mcp

📖 有关详细的设置说明和本地主机扫描，请参阅：

• DOCKER.md - 完整的 Docker 指南
• PODMAN.md - 完整的 Podman 指南

✅ 自动 URL 转换：服务器会自动检测 Docker/Podman 环境，并将 localhost/127.0.0.1 URL 转换为适当的主机网关。你可以直接使用 localhost URL，无需手动映射！

💻 本地安装

1. 启动服务器

推荐方法（作为包）：

python -m zap_custom_mcp

替代方法：

# 作为特定模块
python -m zap_custom_mcp.http_server

# 直接执行（旧方法，可能存在导入问题）
python zap_custom_mcp/http_server.py

💡 最佳实践：始终使用 python -m zap_custom_mcp 以获得最可靠的执行效果。

服务器将自动执行以下操作：

• ✅ 检查 ZAP 是否正在运行
• ✅ 如果需要，通过 PATH 启动 ZAP
• ✅ 创建/加载会话
• ✅ 启动 MCP 服务器

⏱️ 重要提示：服务器启动后大约需要 90 秒才能完全运行。这包括：

• ZAP 初始化和启动
• 会话创建
• MCP 服务器初始化
• 所有组件准备就绪

2. 连接你的 MCP 客户端

连接到：http://localhost:8082/mcp

MCP 配置示例

对于 Cursor IDE，将以下内容添加到你的 mcp.json 中：

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

对于其他 MCP 客户端，使用相同的 URL 端点。

3. 可用工具

工具	描述
start_active_scan	运行主动安全扫描（蜘蛛 + 主动）
start_complete_scan	运行完整扫描（AJAX + 蜘蛛 + 主动 + 被动）
start_passive_scan	运行被动安全分析
start_ajax_scan	为现代 Web 应用程序运行 AJAX 蜘蛛
get_scan_status	获取实时扫描状态
cancel_scan	取消正在运行的扫描
list_scans	列出所有活动扫描
create_new_session	创建新的 ZAP 会话

✨ 主要特性

• 🔍 多种扫描类型：主动、被动、AJAX 蜘蛛和完整扫描
• ⚡ 异步处理：后台扫描执行，实时更新状态
• 🐳 Docker 支持：使用 Docker Compose 轻松部署
• 🤖 AI 集成：与兼容 MCP 的 AI 助手无缝集成
• 📊 丰富的报告：详细的漏洞报告，包含风险评分
• 🔄 会话管理：灵活的会话处理策略
• 🛡️ 生产就绪：强大的错误处理和日志记录
• 🔄 自动 URL 转换：自动将 localhost URL 映射到容器主机网关

📦 安装指南

包结构

本项目使用了合适的 Python 包结构 (zap_custom_mcp/)，具有以下优点：

• ✅ 清晰的导入 - 适当的模块组织
• ✅ Docker 兼容性 - 在容器中无缝工作
• ✅ 可发布到 PyPI - 可以作为正式的 Python 包发布

执行方法：

• python -m zap_custom_mcp（推荐）
• python -m zap_custom_mcp.http_server（替代方法）

选项 1：本地安装

1. 克隆仓库

git clone https://github.com/LisBerndt/zap-custom-mcp.git
cd zap-custom-mcp

2. 安装 OWASP ZAP

• 从 OWASP ZAP 下载页面 下载
• 确保 zap.bat 可通过 PATH 访问
• 测试：where zap.bat（Windows）或 which zap.sh（Linux/Mac）

3. 安装 Python 依赖项

pip install -r requirements.txt

4. Linux 特定说明

• 安装 Java（推荐 OpenJDK 11+）：

# Debian/Ubuntu
sudo apt-get update && sudo apt-get install -y default-jre

# Fedora
sudo dnf install -y java-11-openjdk

• 安装 OWASP ZAP：

# Debian/Ubuntu（从官方仓库）
sudo apt-get update && sudo apt-get install -y zaproxy

# 如果你的发行版仓库中没有，从 ZAP 网站下载：
# https://www.zaproxy.org/download/

• 验证 ZAP 是否在 PATH 中（Linux/Mac）：

which zap.sh || echo "zap.sh not found in PATH"

选项 2：Docker/Podman 部署（推荐）

🐳 Docker/Podman 是最简单、最可靠的方法！

# 1. 克隆仓库
git clone https://github.com/LisBerndt/zap-custom-mcp.git
cd zap-custom-mcp

# 2. 构建并启动容器（自动检测 Docker/Podman）
# Linux/Mac：
./build.sh
./start.sh

# Windows：
build.bat
start.bat

# 3. 检查状态
docker-compose ps  # 或 podman-compose ps

📖 有关详细的 Docker/Podman 设置和本地主机扫描说明，请参阅：

• DOCKER.md - 完整的 Docker 设置指南
• PODMAN.md - 完整的 Podman 设置指南

✅ 自动 URL 转换：服务器会自动检测 Docker/Podman 环境，并将 localhost/127.0.0.1 URL 转换为适当的主机网关：

• Docker：localhost:3000 → host.docker.internal:3000
• Podman：localhost:3000 → host.containers.internal:3000
• 本地：URL 保持不变

这意味着你可以直接使用 localhost URL - 在容器中运行时，它们将自动转换！

📚 详细文档

⚙️ 配置

服务器使用环境变量进行配置。关键设置如下：

变量	默认值	描述
ZAP_BASE	http://127.0.0.1:8080	ZAP API 端口 - 通过修改 URL 更改端口
ZAP_MCP_PORT	8082	MCP 服务器端口 - MCP 客户端连接的端口
ZAP_MCP_HOST	127.0.0.1	MCP 服务器主机（使用 0.0.0.0 表示所有接口）
ZAP_AUTOSTART	true	如果 ZAP 未运行，则自动启动
ZAP_LOG_LEVEL	INFO	日志记录级别

自定义端口配置

使用 .env 文件（推荐）：

# 复制示例文件
cp env.example .env

# 编辑 .env 文件
ZAP_PORT=8081
ZAP_MCP_PORT=8083
ZAP_BASE=http://127.0.0.1:8081

使用环境变量：

# 设置自定义端口
export ZAP_PORT=8081
export ZAP_MCP_PORT=8083
export ZAP_BASE="http://127.0.0.1:8081"

# 然后启动容器
./start.sh

📖 有关完整的配置详细信息，请参阅：

• DOCKER.md - Docker 配置选项
• PODMAN.md - Podman 配置选项

💻 使用示例

开发工作流集成

本地开发测试

{
  "tool": "start_passive_scan",
  "arguments": {
    "url": "http://localhost:3000",
    "timeout_seconds": 60
  }
}

预提交安全检查

{
  "tool": "start_active_scan",
  "arguments": {
    "url": "http://localhost:8080",
    "ascan_max_wait_seconds": 300,
    "spider_max_wait_seconds": 120
  }
}

本地主机扫描示例

✅ 自动 URL 转换：服务器会自动检测 Docker/Podman 环境，并转换 localhost/127.0.0.1 URL：

{
  "tool": "start_complete_scan",
  "arguments": {
    "url": "http://localhost:3000",
    "include_findings": true
  }
}

自动执行的操作：

• Docker：http://localhost:3000 → http://host.docker.internal:3000
• Podman：http://localhost:3000 → http://host.containers.internal:3000
• 本地：http://localhost:3000 → http://localhost:3000（不变）

📖 有关 Docker/Podman 本地主机扫描示例，请参阅：

• DOCKER.md - Docker 本地主机示例
• PODMAN.md - Podman 本地主机示例

基本安全扫描

💡 示例目标：OWASP Juice Shop - 一个专门为安全测试和培训设计的易受攻击的 Web 应用程序。

{
  "tool": "start_complete_scan",
  "arguments": {
    "url": "https://juice-shop.herokuapp.com/#/",
    "include_findings": true,
    "include_evidence": false
  }
}

快速被动扫描

💡 适用场景：无需主动测试的快速安全评估。

{
  "tool": "start_passive_scan",
  "arguments": {
    "url": "https://juice-shop.herokuapp.com/#/",
    "timeout_seconds": 300
  }
}

AJAX 蜘蛛扫描

💡 适用场景：具有 JavaScript/AJAX 内容的现代 Web 应用程序。

{
  "tool": "start_ajax_scan",
  "arguments": {
    "url": "https://juice-shop.herokuapp.com/#/",
    "maxDuration": 5,
    "maxCrawlDepth": 5,
    "numberOfBrowsers": 1,
    "browserId": "firefox-headless"
  }
}

注意：AJAX 扫描要求容器中安装 Firefox（默认包含）。Firefox 以无头模式运行，无需任何显示服务器。

自定义主动扫描

💡 高级配置：自定义超时和扫描策略，以进行全面测试。

{
  "tool": "start_active_scan",
  "arguments": {
    "url": "https://juice-shop.herokuapp.com/#/",
    "ascan_max_wait_seconds": 3600,
    "spider_max_wait_seconds": 900,
    "scanPolicyName": "Default Policy"
  }
}

🔄 左移安全集成

开发工作流

1. 本地开发

• 在开发过程中测试本地主机应用程序
• 立即获得安全问题反馈
• 在提交代码之前修复漏洞

2. 预提交钩子

• 将安全扫描集成到 git 预提交钩子中
• 防止不安全的代码进入仓库
• 自动化安全验证

3. CI/CD 管道集成

• 将安全测试添加到构建管道中
• 自动扫描暂存环境
• 为每个部署生成安全报告

4. AI 辅助安全

• 使用 AI 助手解释扫描结果
• 获取修复漏洞的建议
• 通过 AI 指导学习安全最佳实践

对开发团队的好处

• ⚡ 更快的反馈 - 几分钟内发现问题，而不是几周
• 💰 降低成本 - 尽早修复问题，成本更低
• 🎯 开发者教育 - 通过实践测试学习安全知识
• 🛡️ 主动安全 - 从一开始就构建安全的应用程序
• 📊 持续改进 - 定期进行安全评估

🐳 容器部署

✅ 自动 URL 转换：服务器会自动检测 Docker/Podman 环境，并将 localhost/127.0.0.1 URL 转换为适当的主机网关。你可以直接使用 localhost URL！

📖 有关完整的容器设置和使用说明，请参阅：

• DOCKER.md - 完整的 Docker 设置指南，包含自动 URL 转换
• PODMAN.md - 完整的 Podman 设置指南，包含自动 URL 转换

快速容器命令：

# 启动容器（自动检测 Docker/Podman）
# Linux/Mac：
./start.sh

# Windows：
start.bat

# 跟踪日志
docker-compose logs -f    # Docker
podman-compose logs -f    # Podman

# 停止容器
docker-compose down       # Docker
podman-compose down       # Podman

📊 扫描结果

扫描返回结构化结果，包括：

{
  "scan_id": "abc12345",
  "target": "https://juice-shop.herokuapp.com/#/",
  "alerts": {
    "High": 2,
    "Medium": 5,
    "Low": 12,
    "Informational": 8
  },
  "totalAlerts": 27,
  "riskScore": 31,
  "vulnerabilityNames": [
    { "name": "SQL Injection", "risk": "High", "count": 1 },
    { "name": "XSS", "risk": "Medium", "count": 3 }
  ],
  "durations": {
    "ajax": 45.2,
    "spider": 120.5,
    "ascan": 1800.0,
    "pscan": 30.1
  }
}

🔧 技术细节

服务器启动时间过长

服务器大约需要 90 秒才能完全运行。这是正常现象，包括：

• ZAP 启动和初始化
• 会话创建
• MCP 服务器初始化

在尝试连接之前，请 等待启动过程完成。

ZAP 无法启动

# 检查 ZAP 是否在 PATH 中
where zap.bat  # Windows
which zap.sh   # Linux/Mac

# 检查 Java 安装情况
java -version

# 启用调试日志记录
set ZAP_LOG_LEVEL=DEBUG
python -m zap_custom_mcp

连接问题

# 检查 ZAP 是否正在运行
curl http://localhost:8080/JSON/core/view/version/

# 检查 MCP 服务器
curl http://localhost:8082/mcp

# 检查防火墙设置

MCP 客户端连接问题

如果你的 MCP 客户端无法连接：

1. 确保服务器已运行至少 90 秒
2. 验证 URL 是否正确：http://localhost:8082/mcp
3. 检查是否有防火墙阻止端口 8082
4. 对于 Cursor IDE，确保你的 mcp.json 配置正确

📄 许可证

本项目采用 MIT 许可证 - 有关详细信息，请参阅 LICENSE 文件。

🙏 致谢

• OWASP ZAP - 出色的安全测试工具
• 模型上下文协议 - 使 AI 集成成为可能的协议
• 主权工程 - SEC-05 队列，启发了自由技术和自我主权应用程序的发展

特别感谢

本项目受到了 主权工程社区 的启发，他们致力于为自我主权的未来构建工具。SEC-05 队列对自由技术、抗审查性和无许可访问的执着追求，与使安全测试工具更易于访问和去中心化的目标完美契合。

"为自我主权的未来构建应用程序和服务。" — 主权工程

📞 支持

• 📖 文档
• 🐛 问题跟踪器
• 💬 讨论区

---

为自我主权的工程师用心编码 - 勇往直前！