BinAssist-MCP

BinAssistMCP

重要

アーカイブ予定： Binary Ninja にネイティブ MCP サーバーがバンドルされる予定のため、BinAssistMCP はアーカイブされる予定です。ネイティブサポートにより、個別の MCP 統合を保守する必要がなくなり、Binary Ninja 自体との整合性も保たれます。インストール済みのバージョンで利用可能になったら、Binary Ninja のネイティブ MCP サーバーをご利用ください。このリポジトリは参考資料として引き続き公開されます。

AI を活用したリバースエンジニアリング機能を備えた、Binary Ninja 用の包括的な Model Context Protocol（MCP）サーバー

概要

BinAssistMCP は、Binary Ninja と Claude などの大規模言語モデル（LLM）をつなぐ強力なブリッジであり、Model Context Protocol（MCP）を通じて包括的なリバースエンジニアリングツールを提供します。Server-Sent Events（SSE）および Streamable HTTP トランスポートを介して Binary Ninja の高度な機能を公開し、AI によるバイナリ解析を可能にします。

主な機能

• MCP 2025-11-25 準拠：ツールのアノテーション、リソース、プロンプトを完全にサポート
• デュアルトランスポート対応：SSE（Server-Sent Events）および Streamable HTTP トランスポート
• 45 個の統合ツール：統一されたツール設計による、効率化された Binary Ninja API ラッパー
• 8 個の MCP リソース：閲覧可能でキャッシュ可能なバイナリメタデータ
• 7 個のガイド付きプロンプト：一般的なリバースエンジニアリングタスク向けの、すぐに使えるワークフロー
• 複数バイナリのセッション：インテリジェントなコンテキスト管理による、複数バイナリの同時解析
• コンテキスト豊富なコード出力：関数シグネチャと Binary Ninja のコメントをコードの結果に埋め込みます
• 解析に安全なクエリ：コードの取得では、すでに読み込まれている IL を使用し、グローバルな再解析を強制しません
• セッションに依存しない検出：直接ツールを呼び出すことで、事前に一覧表示を呼び出すことなく、開いている Binary Ninja のビューを検出できます
• ブロッキングしないバイナリのオープン：大きなバイナリや .bndb データベースを非同期で開き、ポーリング可能な操作ステータスを提供します
• スレッドセーフ：同時アクセスを同期する RLock ベースの仕組み
• 自動統合：起動時の自動実行機能を備えた、シームレスな Binary Ninja プラグイン

ユースケース

• AI 支援によるリバースエンジニアリング：LLM を活用した、インテリジェントなコード解析とドキュメント作成
• プロトコル解析：ネットワークデータの流れを追跡し、プロトコル構造を再構築
• 脆弱性調査：ガイド付きワークフローを用いた、体系的なセキュリティ監査
• バイナリ解析の自動化：自然言語で複雑な解析ワークフローをスクリプト化
• コードの理解：包括的なドキュメントと解説を生成

---

アーキテクチャ

src/binassist_mcp/
├── server.py        # FastMCP server - SSE/Streamable HTTP transport, tool registration
├── tools.py         # Binary Ninja API wrapper - 45 MCP tools
├── plugin.py        # Binary Ninja plugin integration
├── context.py       # Thread-safe multi-binary session management
├── config.py        # Pydantic configuration with Binary Ninja settings
├── prompts.py       # 7 guided workflow prompts
├── resources.py     # 8 MCP resource definitions
├── cache.py         # Cache primitives (not currently connected to MCP tools)
├── tasks.py         # Task lifecycle support (tool dispatch is not yet implemented)
├── logging.py       # Binary Ninja logging integration
└── utils.py         # Utility functions

__init__.py          # Plugin entry point (root level)

---

ツール（合計 45 個）

BinAssistMCP は、機能別のカテゴリに整理された 45 個のツールを提供します。クライアントが十分な情報に基づいて判断できるよう、ツールには MCP アノテーション（readOnlyHint、idempotentHint）が含まれています。

バイナリ管理

ツール	説明
list_binaries	Binary Ninja と同期し、読み込まれているすべてのバイナリファイルを一覧表示します
get_binary_info	解析ステータスとメタデータを確認します
get_binary_status	操作 ID、パス、または名前を指定して、キューに入ったオープン処理をポーリングし、解析の進行状況を報告します
open_binary	ブロッキングしないバイナリまたは .bndb のオープン処理をキューに追加します。raw バイナリには保存先の bndb_path が必要です
update_analysis_and_wait	解析の更新を強制し、完了まで待機します
export_program	パッチ適用済みのバイナリまたは Binary Ninja データベースをディスクにエクスポートします

デフォルトでは、open_binary はパスを検証し、Binary Ninja のオープン処理をスケジュールして、status="opening" の operation_id をすぐに返します。ready または failed が報告されるまで get_binary_status(operation_id) をポーリングしてください。準備ができると、name フィールドに解析ツールへ渡す最終的なコンテキスト名が格納されます。同じパスへの同時リクエストでは、実行中の操作が再利用されます。レガシーのブロッキング動作が明示的に必要な場合に限り、wait_for_analysis=true を設定してください。

コード分析（統合）

ツール	説明
get_code	署名とコメントを含む、解析に安全なコードを読み取ります。decompile、hlil、mlil、llil、disasm、pseudo_c に対応しています
get_function_low_level_il	関数の Low-Level IL を取得します
get_function_signature	関数のネイティブなマスク済みバイト署名を生成します
analyze_function	制御フローと複雑度の指標を含む、包括的な関数分析を行います
get_basic_blocks	制御フロー分析用の基本ブロック情報を取得します
get_function_stack_layout	変数のオフセットを含むスタックフレームのレイアウトを取得します

get_code の動作

get_code は読み取り専用のクエリです。analysis_skipped をクリアしたり、IL の生成を要求したり、グローバル分析を実行したりすることはありません。format="decompile" の場合、利用可能であれば読み込み済みの HLIL を返し、次に MLIL、LLIL の順にフォールバックし、最後に命令に対応した逆アセンブルを返します。新しい分析が必要な場合は、update_analysis_and_wait を明示的に使用してください。

code 文字列は現在の関数シグネチャで始まり、関数レベルおよび命令レベルの Binary Ninja コメントを含みます。レスポンスには以下が含まれます。

• function と address：解決された関数の識別情報
• format：要求された形式
• actual_format：実際に返された表現。明示的に要求した IL が利用できない場合は null
• fallback_used：decompile が低レベルの表現にフォールバックしたかどうか
• code：描画されたコード、シグネチャ、コメント
• note：フォールバックが発生した理由と返された内容を説明する場合に表示されます

クロスリファレンス（統合）

ツール	説明
xrefs	direction を to、from、both に設定できる統合クロスリファレンス。必要に応じて呼び出し関係も含められます

コメント（統合）

ツール	説明
comments	統合コメント管理 - アクション：get、set、list、remove、set_function

変数（統合）

ツール	説明
variables	統合変数管理 - アクション：list、create、rename、set_type。rename は scope によるローカルまたはグローバルの指定に対応しています

型（統合）

ツール	説明
types	統合型管理 - アクション：create、create_enum、create_typedef、create_class、add_member、info、list
get_classes	すべてのクラスと構造体を一覧表示します

関数の検索

ツール	説明
get_functions	メタデータとともにすべての関数を一覧表示します
search_functions_by_name	名前のパターンで関数を検索します
get_functions_advanced	サイズ、複雑度、パラメーターによる高度なフィルタリングを行います
search_functions_advanced	名前、コメント、呼び出し、変数を対象に複数条件で検索します
get_function_statistics	すべての関数について包括的な統計情報を取得します

シンボル管理

ツール	説明
rename_symbol	関数とデータ変数の名前を変更します
batch_rename	複数のシンボルの名前を一度の操作で変更します
get_namespaces	名前空間とシンボルの構成を一覧表示します

バイナリ情報

ツール	説明
get_imports	モジュールごとにグループ化されたインポートテーブルを取得します
get_exports	シンボル情報を含むエクスポートテーブルを取得します
get_strings	ページネーションに対応した文字列の抽出を行います
search_strings	パターンで文字列を検索します
get_segments	メモリセグメントのレイアウトを取得します
get_sections	バイナリセクションの情報を取得します
get_entry_points	すべてのバイナリのエントリーポイントを一覧表示します

データ分析

ツール	説明
create_data_var	アドレスにデータ変数を定義します
get_data_vars	定義済みのすべてのデータ変数を一覧表示します
get_data_at	生データを読み取り、分析します
search_bytes	バイナリ内でバイトパターンを検索します

パッチ適用

ツール	説明
patch_bytes	指定したアドレスのバイナリ内の生バイト列にパッチを適用します
assemble_code	指定したアドレスで命令テキストをアセンブルし、必要に応じてパッチを適用します

ナビゲーションとブックマーク

ツール	説明
get_current_address	コンテキストとともに現在のカーソル位置を取得します
get_current_function	現在のアドレスにある関数を特定します
bookmarks	ブックマークを一元管理 - アクション：list、set、remove

タスク管理（実験的）

ツール	説明
start_task	プレースホルダーとなるバックグラウンドタスクの記録を作成します。tool_name のディスパッチはまだ実装されていません
get_task_status	非同期操作のステータスを確認します
list_tasks	保留中または実行中のすべてのタスクを一覧表示します
cancel_task	実行中のタスクをキャンセルします

これらの API は現在、タスクのライフサイクル管理のみを実行します。指定された MCP ツールをバックグラウンドで実行することはありません。

---

MCP リソース（合計 8 個）

リソースは、クライアントがツールを呼び出さずに参照できる、キャッシュ可能なデータを提供します。

URI パターン	説明
binassist://{filename}/triage_summary	バイナリの完全な概要
binassist://{filename}/functions	メタデータ付きのすべての関数
binassist://{filename}/imports	インポートテーブル
binassist://{filename}/exports	エクスポートテーブル
binassist://{filename}/strings	文字列テーブル
binja://{filename}/info	バイナリのメタデータ（アーキテクチャ、プラットフォーム、エントリーポイント）
binja://{filename}/segments	アクセス許可付きのメモリーセグメント
binja://{filename}/sections	バイナリのセクション

---

MCP プロンプト（合計 7 個）

組み込みのプロンプトは、LLM を構造化された分析ワークフローに沿ってガイドします。

プロンプト	引数	説明
analyze_function	function_name、filename	関数を包括的に分析するワークフロー
identify_vulnerability	function_name、filename	セキュリティ監査チェックリスト（メモリー安全性、入力検証、暗号）
document_function	function_name、filename	Doxygen 形式のドキュメントを生成します
trace_data_flow	address、filename	データ依存関係と汚染の伝播を追跡します
compare_functions	func1、func2、filename	類似性分析のために 2 つの関数を比較します
reverse_engineer_struct	address、filename	使用パターンから構造体定義を復元します
trace_network_data	filename	プロトコル分析のために POSIX／Winsock の send／recv を追跡します

例：ネットワークプロトコル分析

trace_network_data プロンプトは、ネットワーク通信の分析をガイドします。

1. ネットワーク関数の特定：POSIX（send／recv／sendto／recvfrom）および Winsock（WSASend／WSARecv）の呼び出しを検索します
2. コールスタックの追跡：アプリケーションのハンドラーからネットワーク I/O までをマッピングします
3. バッファーの分析：プロトコル構造（ヘッダー、長さフィールド、TLV エンコーディング）を特定します
4. プロトコルの再構築：メッセージ形式の C 構造体定義を生成します
5. セキュリティ評価：バッファーオーバーフロー、整数関連の問題、情報漏えいを確認します

---

インストール

前提条件

• Binary Ninja：バージョン 5000 以降
• Python：3.10 以降（通常は Binary Ninja に同梱されており、固定バージョンの MCP SDK が必要とします）
• プラットフォーム：Windows、macOS、Linux

注：Windows ユーザーは、こちらから始めてください：Windows での BinAssistMCP

方法 1：Binary Ninja プラグインマネージャー（推奨）

1. Binary Ninja を開きます
2. Tools → Manage Plugins に移動します
3. 「BinAssistMCP」を検索します
4. Install をクリックします
5. Binary Ninja を再起動します

方法 2：手動インストール

# Clone the repository
git clone https://github.com/symgraph/BinAssistMCP.git
cd BinAssistMCP

# Install dependencies
pip install -r requirements.txt

Binary Ninja のプラグインディレクトリにコピーします。

プラットフォーム	パス
Windows	%APPDATA%\Binary Ninja\plugins\
macOS	~/Library/Application Support/Binary Ninja/plugins/
Linux	~/.binaryninja/plugins/

---

設定

Binary Ninja Settings

Edit → Preferences → binassistmcp を開きます。

設定	デフォルト	説明
server.host	localhost	サーバーのバインドアドレス
server.port	8000	サーバーのポート
server.transport	streamablehttp	トランスポート：streamablehttp または sse
binary.max_binaries	10	同時に扱えるバイナリの最大数
plugin.auto_startup	true	ファイル読み込み時にサーバーを自動起動

環境変数

export BINASSISTMCP_SERVER__HOST=localhost
export BINASSISTMCP_SERVER__PORT=8000
export BINASSISTMCP_SERVER__TRANSPORT=streamablehttp
export BINASSISTMCP_BINARY__MAX_BINARIES=10

---

使用方法

サーバーの起動

Binary Ninja メニューから：

1. Tools → BinAssistMCP → Start Server
2. ログパネルで次のメッセージを確認します：BinAssistMCP server started on http://localhost:8000

自動起動： Binary Ninja がファイルを読み込むと、サーバーが自動的に起動します（設定可能）。

MCP クライアントの接続

ストリーミング可能な HTTP（デフォルト）：

http://localhost:8000/mcp

サーバー送信イベント：

http://localhost:8000/sse

Claude Desktop の設定

Claude Desktop の MCP 設定（claude_desktop_config.json）に追加します。

{
  "mcpServers": {
    "binassist": {
      "url": "http://localhost:8000/mcp"
    }
  }
}

---

統合例

バイナリ固有のツールの多くでは、filename にコンテキスト名が必要です。list_binaries からこれらの名前を取得できますが、初期化時に必須というわけではありません。ファイル名を直接指定した呼び出しでは、必要に応じて Binary Ninja からコンテキストが自動的に更新されます。

基本的な関数解析

User: "Analyze the main function and explain what it does"

Claude uses:
1. list_binaries() - obtain the context filename
2. get_functions(filename='sample.bndb') - find main
3. get_code(filename='sample.bndb', function_name_or_address='main', format='decompile')
4. xrefs(filename='sample.bndb', address_or_name='main', direction='from')
5. analyze_function(filename='sample.bndb', function_name_or_address='main')

脆弱性調査

User: "Find buffer overflow vulnerabilities in input handling functions"

Claude uses:
1. search_functions_advanced(filename='sample.bndb', search_term='strcpy', search_in='calls')
2. get_code(filename='sample.bndb', function_name_or_address='handler', format='decompile')
3. variables(filename='sample.bndb', action='list', function_name_or_address='handler')
4. comments(filename='sample.bndb', action='set', address='0x401000', text='Unchecked copy')

プロトコルのリバースエンジニアリング

User: "Analyze the network protocol used by this binary"

Claude uses the trace_network_data prompt:
1. Identifies send/recv call sites
2. Traces data flow from handlers to network I/O
3. Reconstructs message structures
4. Checks for network vulnerabilities

---

トラブルシューティング

サーバーの問題

問題	解決策
サーバーが起動しない	ポート 8000 が使用可能か確認し、依存関係を検証します
接続が拒否される	サーバーが実行中であることを確認し、ファイアウォールの設定を確認します
要求した IL を利用できない	update_analysis_and_wait を実行してから、get_code を再試行します
バイナリ名が拒否される	list_binaries を呼び出し、返されたコンテキスト名を使用します

パフォーマンス

• メモリ使用量：max_binaries の設定値を下げます
• コードの取得：get_code は読み込み済みの解析結果をすぐに返し、解析を開始する代わりにフォールバックします

ログ

詳細なエラーメッセージは、Binary Ninja のログパネルで確認してください。

---

コントリビュート

1. リポジトリをフォークします
2. 機能ブランチを作成します
3. 既存のコードパターン（Pydantic モデル、型ヒント、ドキュメント文字列）に従います
4. 複数のバイナリタイプでテストします
5. プルリクエストを送信します

---

ライセンス

このプロジェクトは MIT License のもとでライセンスされています。詳細は LICENSE ファイルをご覧ください。