zap-mcp服务器

Name: zap-mcp服务器
Author: LisBerndt

作者：LisBerndt2 星标更新：2025-10-27

安装使用来源：spider==github.com

项目介绍

ZAP MCP Server

一个强大的模型上下文协议（MCP）服务器，集成了OWASP ZAP（Zed Attack Proxy）与AI助手及MCP客户端。通过自动漏洞扫描实现AI驱动的安全测试。

🎯 为什么选择ZAP MCP Server？

左移安全 - 赋予开发者在开发周期早期集成安全测试的能力。无需等到开发结束再进行安全审查，开发者现在可以：

🔧 开发期间测试 - 在本地应用上运行安全扫描
🤖 AI辅助安全 - 通过AI助手获得智能漏洞分析
⚡ 快速反馈 - 在生产前识别安全问题
🔄 CI/CD集成 - 自动化开发流程中的安全测试
📊 开发者友好 - 非安全专家也能轻松使用的MCP接口

🚀 功能

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

📋 先决条件

Python 3.8+
OWASP ZAP 安装并可通过PATH访问
Java（由ZAP所需）
Docker 或 Podman（可选，用于容器化部署）
Firefox ESR（包含在Docker/Podman容器中，用于AJAX扫描）

📖 对于特定容器的先决条件，请参见：

DOCKER.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：本地安装

克隆仓库

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

安装OWASP ZAP
- 从OWASP ZAP下载页面下载
- 确保zap.bat可以通过PATH访问
- 测试：where zap.bat（Windows）或which zap.sh（Linux/Mac）
安装Python依赖项
```
pip install -r requirements.txt
```

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.1URL转换为适当的主机网关：

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

这意味着您可以直接使用localhostURL——当在容器中运行时，它们会被自动转换！

⚙️ 配置

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

变量	默认值	描述
`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配置选项

🚀 快速开始

🐳 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.1URL转换为适当的主机网关。您可以直接使用localhostURL——无需手动映射！

💻 本地安装

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是否正在运行
✅ 如需启动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. 可用工具

工具	描述
`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会话

📖 使用示例

开发工作流集成

本地开发测试：

{
  "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.1URL转换为适当的主机网关：

{
  "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.1URL转换为适当的主机网关。您可以直接使用localhostURL！

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

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注入", "风险": "高", "数量": 1 },
    { "name": "XSS", "风险": "中", "数量": 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/

#