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:本地安装
- 克隆存储库```bash
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依赖项**```bash
pip install -r requirements.txt
- Linux特定注意事项
- 安装Java(建议使用OpenJDK 11+):```bash
Debian/Ubuntu
sudo apt-get update && sudo apt-get install -y default-jre
Fedora
sudo dnf install -y java-11-openjdk
- 安装OWASP ZAP:```bash
# 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):```bash
which zap.sh || echo "zap.sh not found in PATH"
### 选项2:Docker/Podman部署(推荐)
**🐳 Docker/Podman是最简单、最可靠的方法!**```bash
# 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-在容器中运行时,它们将自动转换!
⚙️ 配置
服务器使用环境变量进行配置。关键设置:
| 变量 | 默认值 | 描述 |
|---|---|---|
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文件(推荐):```bash
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
**使用环境变量:**```bash
# 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(推荐)
从容器开始最快:```bash
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.启动服务器
**推荐方法(如包装):**```bash
python -m zap_custom_mcp
替代方法:```bash
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`:```json
{
"mcpServers": {
"zap-mcp": {
"url": "http://localhost:8082/mcp"
}
}
}
对于其他MCP客户端,使用相同的URL端点。
3.可用工具
| 工具 | 说明 |
|---|---|
start_active_scan |
运行主动安全扫描(Spider+active) |
start_complete_scan |
运行完整扫描(AJAX+Spider+主动+被动) |
start_passive_scan |
运行被动安全分析 |
start_ajax_scan |
为现代网络应用程序运行AJAX蜘蛛 |
get_scan_status |
获取实时扫描状态 |
cancel_scan |
取消正在运行的扫描 |
list_scans |
列出所有活动扫描 |
create_new_session |
创建新的ZAP会话 |
📖 使用示例
开发工作流集成
本地开发测试:```json
{
"tool": "start_passive_scan",
"arguments": {
"url": "http://localhost:3000",
"timeout_seconds": 60
}
}
**预提交安全检查:**```json
{
"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 网址:```json
{
"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应用程序。```json
{
"tool": "start_complete_scan",
"arguments": {
"url": "https://juice-shop.herokuapp.com/#/",
"include_findings": true,
"include_evidence": false
}
}
快速被动扫描
💡 非常适合: 无需主动测试即可快速进行安全评估。```json
{
"tool": "start_passive_scan",
"arguments": {
"url": "https://juice-shop.herokuapp.com/#/",
"timeout_seconds": 300
}
}
### AJAX蜘蛛扫描
**💡 非常适合:** 具有JavaScript/AAJAX内容的现代web应用程序。```json
{
"tool": "start_ajax_scan",
"arguments": {
"url": "https://juice-shop.herokuapp.com/#/",
"maxDuration": 5,
"maxCrawlDepth": 5,
"numberOfBrowsers": 1,
"browserId": "firefox-headless"
}
}
注: AJAX扫描需要在容器中安装Firefox(默认包含)。Firefox在无头模式下运行,不需要任何显示服务器。
自定义主动扫描
💡 高级配置: 自定义超时和扫描策略以进行彻底测试。```json
{
"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转换功能
**快速容器命令:**```bash
# 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
📊 扫描结果
扫描返回结构化结果,包括:```json
{
"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不会启动```bash
# 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
连接问题```bash
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秒
1. 验证URL是否正确: `http://localhost:8082/mcp`
1. 检查防火墙是否阻止了端口8082
1. 对于Cursor IDE,请确保 `mcp.json` 配置正确
### 集装箱问题
**📖 有关容器故障排除的详细信息,请参阅:**
- **医生.md** -Docker故障排除指南
- **PODMAN.md** -Podman故障排除指南
## 🤝 贡献
1. 分叉存储库
1. 创建要素分支: `git checkout -b feature-name`
1. 安装开发依赖项: `pip install -e ".[dev]"`
1. 运行测试: `pytest`
1. 提交更改: `git commit -am 'Add feature'`
1. 推送到分支: `git push origin feature-name`
1. 提交拉取请求
### 开发设置```bash
# 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!
