Zap Mcp Server

Zap Mcp Server

安全 Python

🚀 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
  1. 安装 OWASP ZAP
  • 从 OWASP ZAP 下载页面 下载
  • 确保 zap.bat 可通过 PATH 访问
  • 测试：where zap.bat（Windows）或 which zap.sh（Linux/Mac）
  1. 安装 Python 依赖项
pip install -r requirements.txt
  1. 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. 本地开发
  • 在开发过程中测试本地主机应用程序
  • 立即获得安全问题反馈
  • 在提交代码之前修复漏洞
  1. 预提交钩子
  • 将安全扫描集成到 git 预提交钩子中
  • 防止不安全的代码进入仓库
  • 自动化安全验证
  1. CI/CD 管道集成
  • 将安全测试添加到构建管道中
  • 自动扫描暂存环境
  • 为每个部署生成安全报告
  1. 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 文件。

🙏 致谢

特别感谢

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

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

📞 支持

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

默认排序 时间排序

0 个评论

  • 0 关注
  • 0 收藏，10 浏览
  • system 提出于 2025-09-30 07:00

相似服务问题

热议话题 »