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 隊列對自由技術、抗審查性和無許可訪問的執著追求，與使安全測試工具更易於訪問和去中心化的目標完美契合。

"為自我主權的未來構建應用程序和服務。" — 主權工程

📞 支持

• 📖 文檔
• 🐛 問題跟蹤器
• 💬 討論區

---

為自我主權的工程師用心編碼 - 勇往直前！