MCP Port Scanner

🚀 MCP智能ポートスキャナー

MCPプロトコルに基づく、AIアシスタントと開発ツール向けの、スマートな階層型ポートスキャンサービスです。

✨ 主な機能

スマートな階層型スキャン

• 🧠 動的決定：ポート数に応じてスキャンの深さを自動調整し、効率と網羅率のバランスを取ります。
• 🎯 3層アーキテクチャ：ポートスキャン → HTTP検出 → Web深度探査と、段階的に詳細な情報を取得します。
• ⚡ 高速性能：RustScanをベースにしており、従来のスキャナーよりも10倍高速です。

複数のインターフェースサポート

• 🔌 MCPプロトコル：stdioとHTTP/SSEの2種類の転送モードをサポートしています。
• 📊 リアルタイムフィードバック：SSEで進捗を送信し、スキャンプロセスを可視化します。
• 🤖 AI統合：CursorなどのAIツールとシームレスに統合できます。

適用シーン

• セキュリティ監査：ネットワーク資産と潜在的なリスクを迅速に発見します。
• 運用監視：インフラストラクチャを定期的にスキャンし、サービスの正常性を確保します。
• 開発テスト：ポート設定とサービスのデプロイを検証します。
• AI支援分析：MCPプロトコルを通じて、高度なセキュリティ分析を実現します。

🏗️ アーキテクチャ設計

システムアーキテクチャ

graph TB
    subgraph "インターフェース層 (Interfaces)"
        CLI["🖥️ CLI<br/>コマンドラインインターフェース"]
        MCP["🔌 MCP<br/>プロトコルインターフェース"]
        HTTP["🌐 HTTP<br/>Webインターフェース"]
        SSE["📡 Cursor SSE<br/>リアルタイムプッシュ"]
    end
    
    subgraph "アダプター層 (Adapters)"
        CLI_ADAPTER["CLIアダプター"]
        MCP_LOCAL["MCPローカルアダプター"]
        MCP_REMOTE["MCPリモートアダプター"]
        SSE_ADAPTER["SSEアダプター"]
    end
    
    subgraph "サービス層 (Service Layer)"
        SCANNER["🔍 Scanner<br/>ポートスキャナー"]
        DETECTOR["🔎 Detector<br/>HTTP検出器"]
        PROBER["🕵️ Prober<br/>Web探査器"]
        MODELS["📊 Models<br/>データモデル"]
    end
    
    CLI --> CLI_ADAPTER
    MCP --> MCP_LOCAL
    MCP --> MCP_REMOTE
    HTTP --> MCP_REMOTE
    SSE --> SSE_ADAPTER
    
    CLI_ADAPTER --> SCANNER
    MCP_LOCAL --> SCANNER
    MCP_REMOTE --> SCANNER
    SSE_ADAPTER --> SCANNER
    
    SCANNER --> DETECTOR
    DETECTOR --> PROBER
    
    SCANNER -.-> MODELS
    DETECTOR -.-> MODELS
    PROBER -.-> MODELS
    
    style CLI fill:#e1f5fe
    style MCP fill:#f3e5f5
    style HTTP fill:#e8f5e8
    style SSE fill:#fff3e0
    
    style SCANNER fill:#ffebee
    style DETECTOR fill:#f1f8e9
    style PROBER fill:#e3f2fd
    style MODELS fill:#fafafa

階層型スキャンロジック

flowchart TD
    START([スキャン開始]) --> COMMON[🔍 一般的なポートスキャン<br/>上位1000ポート]
    COMMON --> CHECK{開放ポートの数?}
    
    CHECK -->|< 3つのポート| FULL[🔍 全ポート深度スキャン<br/>1 - 65535ポート<br/>隠れたサービスが存在する可能性あり]
    CHECK -->|≥ 3つのポート| SKIP[⏭️ 全ポートスキャンをスキップ<br/>十分な情報が得られた]
    
    FULL --> HTTP[🔎 HTTPサービス検出<br/>Webサービスを識別]
    SKIP --> HTTP
    
    HTTP --> WEB{Webサービスが見つかった?}
    WEB -->|はい| PROBE[🕵️ Web深度探査<br/>• ディレクトリスキャン<br/>• 管理バックエンドの発見<br/>• テクノロジースタックの識別]
    WEB -->|いいえ| RESULT
    
    PROBE --> RESULT[📊 スキャン結果を出力]
    
    style START fill:#e3f2fd
    style COMMON fill:#f3e5f5
    style CHECK fill:#fff3e0
    style FULL fill:#ffebee
    style SKIP fill:#e8f5e8
    style HTTP fill:#f1f8e9
    style WEB fill:#fff3e0
    style PROBE fill:#e1f5fe
    style RESULT fill:#fafafa

🚀 クイックスタート

環境準備

# プロジェクトをクローン
git clone https://github.com/relaxcloud-cn/port-scanner.git
cd mcp-port-scanner

# Python依存関係をインストール
pip install -r requirements.txt
pip install mcp

# RustScanをインストール（必須）
# macOS
brew install rustscan

# Linux
wget https://github.com/RustScan/RustScan/releases/download/2.0.1/rustscan_2.0.1_amd64.deb
sudo dpkg -i rustscan_2.0.1_amd64.deb

Dockerでの迅速な起動

# stdioモードのサービスを起動（ローカルCursor統合）
docker-compose up -d mcp-port-scanner

# SSEモードのサービスを起動（リモートアクセスをサポート）
docker-compose up -d mcp-port-scanner-sse

# サービスの状態を確認
docker-compose ps

💻 使用例

1. コマンドラインモード

# 単一のターゲットをスキャン
python -m mcp_port_scanner scan 192.168.1.1

# 指定したポートをスキャン
python -m mcp_port_scanner scan 192.168.1.1 -p 80,443,8080

# バッチスキャン
python -m mcp_port_scanner batch 192.168.1.1 192.168.1.2 192.168.1.3

2. MCP Serverモード

MCPツールセット

1. scan_target - スマートな単一ターゲットスキャン

   • パラメータ：ip(必須), ports(オプション), scan_layers(オプション), config(オプション)

2. batch_scan - バッチスキャン

   • パラメータ：targets(必須), scan_layers(オプション), max_concurrent(オプション)

3. get_scan_status - スキャン状態を照会

   • パラメータ：scan_id(必須)

4. list_active_scans - アクティブなスキャンをリスト表示

   • パラメータ：なし

5. get_scan_result - スキャン結果を取得

   • パラメータ：scan_id(必須)

MCPクライアントを設定する

stdioモード（ローカル使用を推奨）：

Docker環境：

{
  "mcpServers": {
    "port-scanner-stdio": {
      "command": "docker",
      "args": ["exec", "-i", "mcp-port-scanner", "python", "-m", "mcp_port_scanner.interfaces.mcp_local_server"],
      "description": "新バージョンのMCPサーバー - 7つのツール、スマートなスキャン戦略"
    }
  }
}

ローカルPython環境：

{
  "mcpServers": {
    "port-scanner-local": {
      "command": "python",
      "args": ["-m", "mcp_port_scanner.interfaces.mcp_local_server"],
      "cwd": "/path/to/mcp-port-scanner",
      "env": {
        "PYTHONPATH": "src"
      },
      "description": "ローカルの新バージョンのMCPサーバー"
    }
  }
}

SSEモード（リモートアクセスをサポート）：

{
  "mcpServers": {
    "port-scanner-remote": {
      "url": "http://YOUR_SERVER_IP:3000/mcp"
    }
  }
}

AIアシスタントのシステムプロンプトとして prompt.md を使用することをおすすめします。これにより、専門的なネットワークセキュリティ分析機能を得ることができます。

3. Python SDK

from mcp_port_scanner import PortScannerSDK

# インスタンスを作成
sdk = PortScannerSDK()

# ターゲットをスキャン
result = sdk.scan("192.168.1.1")
print(f"{len(result.open_ports)} 個の開放ポートが見つかりました")
print(f"{len(result.http_services)} 個のWebサービスが見つかりました")
print(f"{len(result.admin_directories)} 個の管理インターフェースが見つかりました")

具体的な使用例

単一ターゲットのスキャン：

8.8.8.8をスキャンし、包括的なセキュリティ分析を行ってください

バッチスキャン：

以下のターゲットをバッチスキャンしてください：
- 8.8.8.8
- www.producthunt.com
- 192.168.2.229

緊急対応：

192.168.2.229を緊急スキャンしてください。異常なサービスが疑われます。

Cursor + Dockerの統合例

以下は、CursorをMCPクライアントとして使用し、Dockerで実行されるスキャナーサービスとの実際のやり取りの流れです。

1. 一般的なポートの迅速なスキャン

2. 開放ポートを発見した後のスマートな分析

3. Webサービスと管理バックエンドの詳細な探査

🎯 性能指標

📚 ドキュメント

• 📘 クイックスタートガイド - 5分で始めるチュートリアル
• 📗 開発ドキュメント - アーキテクチャ設計と拡張開発
• 📙 APIリファレンス - 詳細なAPIドキュメントとサンプル
• 📕 アーキテクチャ設計 - 設計理念を深く理解する
• 📓 MCP SSE設定 - SSE転送モードの設定ガイド
• 📔 Cursor設定 - Cursorエディタの統合ガイド

🛡️ セキュリティに関する注意事項

• 承認されたネットワーク環境でのみ使用してください。
• 現地の法令を遵守してください。
• スキャン頻度を適切に管理してください。
• 機密情報を記録しないでください。

🤝 コントリビューションガイド

コミュニティからの貢献を歓迎し、感謝しています。プロジェクトを改善するために、コントリビューションガイドを参照してください。

📄 ライセンス

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

🙏 謝辞

• RustScan - 超高速のポートスキャナー
• MCP - Model Context Protocol
• FastAPI - 最新のWebフレームワーク