Mcp Port Scan

🚀 MCP インテリジェントポートスキャナー

🌟 主な機能

インテリジェントな階層型スキャン

• 🧠 動的な判断：ポート数に応じてスキャンの深度を自動調整し、効率とカバレッジのバランスを取ります
• 🎯 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/>Top 1000 ports]
    COMMON --> CHECK{开放端口数量?}
    
    CHECK -->|< 3个端口| FULL[🔍 全端口深度扫描<br/>1-65535 ports<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

Docker ですぐに起動

# 启动stdio模式服务（本地Cursor集成）
docker-compose up -d mcp-port-scanner

# 启动SSE模式服务（支持远程访问）
docker-compose up -d mcp-port-scanner-sse

# 查看服务状态
docker-compose ps

🛠️ 使用方法

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

# 检查 RustScan 状态
python -m mcp_port_scanner.interfaces.cli_interface rustscan

# 扫描单个目标
python -m mcp_port_scanner.interfaces.cli_interface scan 192.168.1.1

# 扫描指定端口
python -m mcp_port_scanner.interfaces.cli_interface scan 192.168.1.1 -p 80,443,8080

# 批量扫描
python -m mcp_port_scanner.interfaces.cli_interface batch 192.168.1.1 192.168.1.2 192.168.1.3

# 查看帮助
python -m mcp_port_scanner.interfaces.cli_interface --help

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 Client の設定

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 環境：

⚠️ 前提条件：

1. プロジェクトの依存関係をインストールします：pip install -r requirements.txt
2. bin/ディレクトリに、使用するプラットフォームに対応した RustScan バイナリファイルがあることを確認します
3. または、システムに RustScan がインストールされていることを確認します（sudo apt install rustscan または brew install rustscan）

{
  "mcpServers": {
    "port-scanner-local": {
      "command": "python",
      "args": ["-m", "mcp_port_scanner.interfaces.mcp_local_server"],
      "cwd": "./mcp-port-scanner",
      "env": {
        "PYTHONPATH": "src"
      },
      "description": "本地MCP服务器 - 7个工具，智能扫描策略"
    }
  }
}

パス設定について：

• 相対パスの使用を推奨します："./mcp-port-scanner"（Cursor の作業ディレクトリからの相対パス）
• または絶対パスを使用します："/path/to/your/mcp-port-scanner"
• Windows の例："C:/Users/YourName/Projects/mcp-port-scanner"

SSE モード（リモートアクセスに対応）：

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

📋 ローカル MCP Server の簡易検証

設定が完了したら、次の方法で MCP サーバーが正常に動作していることを確認できます。

# 1. 切换到项目目录
cd ./mcp-port-scanner 

# 2. 设置环境变量
export PYTHONPATH=src  # Linux/macOS
# 或 Windows PowerShell：$env:PYTHONPATH="src"

# 3. 手动启动MCP服务器测试
python -m mcp_port_scanner.interfaces.mcp_local_server

# 4. 检查RustScan状态
python -c "from src.mcp_port_scanner.rustscan_manager import get_rustscan_manager; print(get_rustscan_manager().verify_rustscan())"

問題が発生した場合：

• 依存関係がインストールされていることを確認します：pip list | grep mcp
• RustScan を確認します：bin/rustscan-windows-x64.exe --version（Windows）
• ログを確認します：logs/ディレクトリ内のログファイルを確認します

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 サービスや管理画面の詳細なプローブ

🎯 パフォーマンス指標

スキャンタイプ	代表的な所要時間	説明
クイックスキャン	84.28-230.5秒	よく使うポートのみ
インテリジェントスキャン（ポート数が少ない場合）	30-60秒	全ポートスキャンを含みます
インテリジェントスキャン（ポート数が多い場合）	88-202.37秒	全ポートスキャンは行わず、すべてのスキャン層を実行します
完全スキャン	655-951秒	全ポートスキャンとすべてのスキャン層を実行します
C クラススキャン	5-15分	254 個の IP アドレス

📖 ドキュメント

• 📘 クイックスタートガイド - 5 分で始められるチュートリアル
• 📗 開発ドキュメント - アーキテクチャ設計と拡張開発
• 📙 API リファレンス - API の詳細なドキュメントと例
• 📕 アーキテクチャ設計 - 設計理念を詳しく解説
• 📓 MCP SSE 設定 - SSE トランスポートモードの設定ガイド
• 📔 Cursor 設定 - Cursor エディターとの連携ガイド

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

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

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

コミュニティからのコントリビューションを歓迎し、感謝します。プロジェクトの改善にご協力いただくには、コントリビューションガイドをご覧ください。

📄 ライセンス

本プロジェクトは MIT ライセンスを採用しています。詳細は LICENSE ファイルをご覧ください。

🙏 謝辞

• RustScan - 超高速ポートスキャナー
• MCP - Model Context Protocol
• FastAPI - モダンな Web フレームワーク

---