Zap MCP Server

🚀 ZAP MCP Server

強力なモデルコンテキストプロトコル（MCP）サーバーです。このサーバーはOWASP ZAP（Zed Attack Proxy）を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. ステータスを確認する
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を直接使用でき、コンテナ内で実行する際に自動的に変換されます。

💻 ローカルインストール

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を使用してください。

サーバーは起動後、完全に動作可能になるまでおよそ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. 利用可能なツール

✨ 主な機能

• 🔍 複数のスキャンタイプ: アクティブ、パッシブ、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 Downloadsからダウンロードします。
• 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を直接使用でき、コンテナ内で実行する際に自動的に変換されます。

⚙️ 設定

サーバーは環境変数を使用して設定されます。主要な設定項目は以下の通りです。

カスタムポート設定

.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（変更なし）

これにより、localhostのURLを直接使用でき、コンテナ内で実行する際に自動的に変換されます。

📖 Docker/Podmanのローカルホストスキャンの例については、以下を参照してください。

• DOCKER.md - Dockerのローカルホストの例
• PODMAN.md - Podmanのローカルホストの例

基本的なセキュリティスキャン

💡 例のターゲット: OWASP Juice Shop - セキュリティテストとトレーニング用に意図的に脆弱性を持たせたウェブアプリケーション。

{
  "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コンテンツを持つモダンなウェブアプリケーション。

{
  "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"
  }
}

🔄 セキュリティの早期導入（Shift Left Security）の統合

開発ワークフロー

1. ローカル開発

• 開発中にローカルホストのアプリケーションをテストする
• セキュリティ問題に関する即時のフィードバックを得る
• コードをコミットする前に脆弱性を修正する

2. コミット前フック

• セキュリティスキャンをgitのコミット前フックに統合する
• 不安全なコードがリポジトリに入るのを防ぐ
• 自動化されたセキュリティ検証

3. CI/CDパイプラインの統合

• ビルドパイプラインにセキュリティテストを追加する
• ステージング環境を自動的にスキャンする
• 各デプロイに対するセキュリティレポートを生成する

4. AI支援型セキュリティ

• AIアシスタントを使用してスキャン結果を解釈する
• 脆弱性を修正するための推奨事項を得る
• AIのガイダンスを通じてセキュリティのベストプラクティスを学ぶ

開発チームにとってのメリット

• ⚡ より速いフィードバック - 数分で問題を検出し、数週間ではなく
• 💰 コスト削減 - 問題を早期に修正することで、解決コストを抑える
• 🎯 開発者教育 - 実践的なテストを通じてセキュリティを学ぶ
• 🛡️ 事前対策型セキュリティ - 最初から安全なアプリケーションを構築する
• 📊 継続的な改善 - 定期的なセキュリティ評価

🐳 コンテナデプロイメント

✅ 自動URL変換機能: サーバーはDocker/Podman環境を自動検出し、localhost/127.0.0.1のURLを適切なホストゲートウェイに変換します。localhostのURLを直接使用できます！

📖 完全なコンテナのセットアップと使用方法については、以下を参照してください。

• DOCKER.md - 自動URL変換機能付きの完全なDockerセットアップガイド
• PODMAN.md - 自動URL変換機能付きの完全なPodmanセットアップガイド

コンテナのクイックコマンド

# コンテナを起動する（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の設定が正しいことを確認する

コンテナの問題

📖 詳細なコンテナのトラブルシューティングについては、以下を参照してください。

• DOCKER.md - Dockerのトラブルシューティングガイド
• PODMAN.md - Podmanのトラブルシューティングガイド

📄 ライセンス

このプロジェクトはMITライセンスの下でライセンスされています。詳細についてはLICENSEファイルを参照してください。

🙏 謝辞

• OWASP ZAP - 素晴らしいセキュリティテストツール
• Model Context Protocol - AI統合を可能にするプロトコル
• Sovereign Engineering - 自由なテクノロジーと自己主権型アプリケーションを啓発するSEC-05コホート

特別な感謝

このプロジェクトはSovereign Engineering Communityに触発されて作成されました。彼らは自己主権的な未来のためのツールを構築することに取り組んでいます。SEC-05コホートの自由なテクノロジー、検閲耐性、および許可不要なアクセスへの献身は、セキュリティテストツールをよりアクセスしやすく分散化するという目標と完全に一致しています。

"自己主権的な未来のためのアプリケーションとサービスを構築する。" — Sovereign Engineering

📞 サポート

• 📖 ドキュメント
• 🐛 問題追跡
• 💬 ディスカッション

自己主権的なエンジニアのために愛を込めてコーディングされました - YOLO!