ZAP MCP Server

ZAP MCP服务器

  

一个强大的 模型上下文协议（MCP）服务器 整合 OWASP ZAP （Zed攻击代理）与AI助手和MCP客户端。通过自动漏洞扫描启用AI驱动的安全测试。

🎯 为什么选择ZAP MCP服务器？

左移安全 -使开发人员能够在开发生命周期的早期集成安全测试。开发人员现在可以：

• 🔧 开发过程中的测试 -在本地主机应用程序上运行安全扫描
• 🤖 人工智能辅助安全 -通过AI助手进行智能漏洞分析
• ⚡ 快速反馈 -在安全问题进入生产之前识别它们
• 🔄 CI/CD集成 -自动化开发工作流程中的安全测试
• 📊 开发者友好 -面向非安全专家的简单MCP接口

🚀 特性

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

📋 先决条件

• Python 3.8+
• OWASP ZAP 已安装并可通过PATH访问
• Java （ZAP要求）
• 码头工人 或 波德曼 （可选，用于容器化部署）
• Firefox ESR （包含在用于AJAX扫描的Docker/Podman容器中）

📖 有关容器特定的先决条件，请参阅：

• 医生.md -Docker的先决条件和设置
• PODMAN.md -Podman先决条件和设置

🛠️ 安装

封装结构

此项目使用正确的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 (from official repos)
     sudo apt-get update && sudo apt-get install -y zaproxy

     # If not available in your distro repos, download from ZAP website:
     # 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. Clone repository
git clone https://github.com/LisBerndt/zap-custom-mcp.git
cd zap-custom-mcp

# 2. Build and start containers (auto-detects Docker/Podman)
# Linux/Mac:
./build.sh
./start.sh

# Windows:
build.bat
start.bat

# 3. Check status
docker-compose ps  # or podman-compose ps

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

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

✅ 自动URL转换： 服务器自动检测Docker/Podman环境并转换 localhost/127.0.0.1 指向相应主机网关的URL：

• 码头工人: localhost:3000 → host.docker.internal:3000
• 波德曼: localhost:3000 → host.containers.internal:3000
• 本地：URL保持不变

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

⚙️ 配置

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

自定义端口配置

使用.env文件（推荐）：

# Copy the example file
cp env.example .env

# Edit .env file
ZAP_PORT=8081
ZAP_MCP_PORT=8083
ZAP_BASE=http://127.0.0.1:8081

使用环境变量：

# Set custom ports
export ZAP_PORT=8081
export ZAP_MCP_PORT=8083
export ZAP_BASE="http://127.0.0.1:8081"

# Then start containers
./start.sh

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

• 医生.md -Docker配置选项
• PODMAN.md -Podman配置选项

🚀 快速开始

🐳 Docker/Podman（推荐）

从容器开始最快：

# 1. Clone repository
git clone https://github.com/LisBerndt/zap-custom-mcp.git
cd zap-custom-mcp

# 2. Start (auto-detects Docker/Podman)
# Linux/Mac:
./build.sh && ./start.sh

# Windows:
build.bat
start.bat

# 3. Wait (approx. 90 seconds) and then connect:
# http://localhost:8082/mcp

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

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

✅ 自动URL转换： 服务器自动检测Docker/Podman环境并转换 localhost/127.0.0.1 指向相应主机网关的URL。您可以使用 localhost 直接URL-无需手动映射！

💻 本地安装

1.启动服务器

推荐方法（如包装）：

python -m zap_custom_mcp

替代方法：

# As specific module
python -m zap_custom_mcp.http_server

# Direct execution (legacy, may have import issues)
python zap_custom_mcp/http_server.py

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

服务器将自动：

• ✅ 检查ZAP是否正在运行
• ✅ 如果需要，启动ZAP（通过PATH）
• ✅ 创建/加载会话
• ✅ 启动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.可用工具

📖 使用示例

开发工作流集成

本地开发测试：

{
  "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 网址：

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

自动发生的事情：

• 码头工人: http://localhost:3000 → http://host.docker.internal:3000
• 波德曼: http://localhost:3000 → http://host.containers.internal:3000
• 本地: http://localhost:3000 → http://localhost:3000 （不变）

📖 有关Docker/Podman localhost扫描示例，请参阅：

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

基本安全扫描

💡 示例目标： OWASP果汁店 -为安全测试和培训而设计的故意易受攻击的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/AAJAX内容的现代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.地方发展

• 在开发过程中测试您的localhost应用程序
• 立即获得有关安全问题的反馈
• 在提交代码之前修复漏洞

2.预提交钩子

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

3.CI/CD管道集成

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

4.人工智能辅助安全

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

对开发团队的好处

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

🐳 容器部署

✅ 自动URL转换： 服务器自动检测Docker/Podman环境并转换 localhost/127.0.0.1 指向相应主机网关的URL。您可以使用 localhost 直接URL！

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

• 医生.md -完整的Docker设置指南，带有自动URL转换功能
• PODMAN.md -完整的Podman设置指南，带有自动URL转换功能

快速容器命令：

# Start containers (auto-detects Docker/Podman)
# Linux/Mac:
./start.sh

# Windows:
start.bat

# Follow logs
docker-compose logs -f    # Docker
podman-compose logs -f    # Podman

# Stop containers
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不会启动

# Check if ZAP is in PATH
where zap.bat  # Windows
which zap.sh   # Linux/Mac

# Check Java installation
java -version

# Enable debug logging
set ZAP_LOG_LEVEL=DEBUG
python -m zap_custom_mcp

连接问题

# Check if ZAP is running
curl http://localhost:8080/JSON/core/view/version/

# Check MCP server
curl http://localhost:8082/mcp

# Check firewall settings

MCP客户端连接问题

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

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

集装箱问题

📖 有关容器故障排除的详细信息，请参阅：

• 医生.md -Docker故障排除指南
• PODMAN.md -Podman故障排除指南

🤝 贡献

1. 分叉存储库
2. 创建要素分支： git checkout -b feature-name
3. 安装开发依赖项： pip install -e ".[dev]"
4. 运行测试： pytest
5. 提交更改： git commit -am 'Add feature'
6. 推送到分支： git push origin feature-name
7. 提交拉取请求

开发设置

# Clone and setup
git clone https://github.com/LisBerndt/zap-custom-mcp.git
cd zap-custom-mcp

# Install in development mode
pip install -e ".[dev]"

# Run tests
pytest

# Start development server
python -m zap_custom_mcp

📄 许可证

此项目根据MIT许可证获得许可-请参阅 许可证 文件以获取详细信息。

🙏 致谢

• OWASP ZAP -令人惊叹的安全测试工具
• 模型上下文协议 -使AI集成成为可能的协议
• 主权工程 -SEC-05队列激励自由技术和自主应用

特别感谢

这个项目的灵感来自 主权工程社区 以及他们致力于为自治的未来构建工具。SEC-05团队致力于自由技术、抗审查和无许可访问，这与使安全测试工具更易于访问和去中心化的目标完全一致。

_“为自治的未来构建应用程序和服务。”_ — 主权工程

📞 支持

• 📖 文档
• 🐛 问题追踪
• 💬 讨论

______________________________________________________________________

Vibe编码为❤️ 对于自主工程师来说，YOLO！