xteardx/diaphora-mcp自動バイナリ差分のためのMCPサーバー。
[ロシア語版](https://github.com/xteardx/diaphora-mcp/blob/master/README.ru.md)
# Diaphora MCP
AIアシスタントから、IDAで解析済みの2つのバイナリを比較します。Diaphora MCPは保存されたIDAデータベースをエクスポートし、[Diaphora](https://github.com/joxeankoret/diaphora)を実行して、AIが対応する関数とそのコールグラフを調査できるようにします。
デフォルトのインターフェースには、比較に焦点を当てた**10個のツール**があります。Diaphoraがマッチを提供し、AIが実際のコードを読み取って変更を説明します。
[クイックスタート](#quick-start) · [例](#examples) · [ツール](#tools) · [トラブルシューティング](#troubleshooting)
```text
old.i64 + new.i64 → headless export → SQLite exports + diff results
↓
summary → matched code → call graph
```
## 要件
- Python 3.10+、`idat.exe`/`idat64`を備えたIDA Pro、およびインストール済みのDiaphoraプラグイン。
- 両方のバイナリが解析され、`.i64`/`.idb`データベースとして保存されていること。
- Codex、Claude Code、CursorなどのローカルMCPクライアント。
- 疑似コードが必要な場合のみ、互換性のあるHex-Raysデコンパイラ。
IDAとDiaphoraは別々にインストールします。diffスキーマの検証は現在Diaphora **3.4.1**を対象としています。他のスキーマでは互換性の更新が必要になる場合があります。diffに使用するPythonインタプリタには、Diaphoraのスタンドアロン依存関係がインストールされている必要があります。
## クイックスタート
### 1. インストールと出力ディレクトリの作成
```powershell
git clone https://github.com/xTeardx/diaphora-mcp.git
cd diaphora-mcp
python -m venv .venv
.\.venv\Scripts\python.exe -m pip install -e .
New-Item -ItemType Directory -Force C:\diaphora-outputs | Out-Null
```
### 2. MCPサーバーの接続
クライアントのMCP設定にこのエントリを追加します。リポジトリ、IDA、Diaphoraのパスは、ご自身のインストールパスに置き換えてください。このプロジェクトをインストールした環境のPython実行ファイルを使用してください。
```json
{
"mcpServers": {
"diaphora": {
"command": "C:/src/diaphora-mcp/.venv/Scripts/python.exe",
"args": ["C:/src/diaphora-mcp/diaphora_mcp_server.py"],
"env": {
"IDAT_PATH": "C:/Program Files/IDA Professional 9.3/idat.exe",
"DIAPHORA_DIR": "C:/Program Files/IDA Professional 9.3/plugins/diaphora",
"DIAPHORA_OUTPUT_ROOT": "C:/diaphora-outputs"
}
}
}
}
```
クライアントはstdio経由でサーバーを起動します。別途起動するWebサービスはありません。コードや環境を変更した後は、MCPサーバーを再起動してください。接続に成功すると、以下に示す10個のツールが利用可能になります。
### 3. アシスタントにファイルの比較を依頼する
```text
Use Diaphora to compare C:/analysis/old.i64 (old) against
C:/analysis/new.i64 (new). Save output under C:/diaphora-outputs/run-001.
Export headlessly with assembly detail, keep the exports, show a summary,
then inspect partial matches and explain the code changes in the interesting
functions. Use the result mapping when comparing functions and call graphs.
```
毎回**新しい実行ディレクトリ**を選択してください。既存の生成済みターゲットが上書きされることはありません。
## 例
以下のJSONブロックは**MCPツールの引数**であり、シェルコマンドではありません。アシスタントは指定されたツールを直接呼び出すことができます。パスと`0x401000`は例です。ご自身の実行で返されたパスとアドレスを使用してください。
### 1. 2つのIDAデータベースのエクスポートと比較
ツール: **`batch_export_and_diff`**。oldが常に最初の入力、newが2番目です。
```json
{
"idb1_path": "C:/analysis/old.i64",
"idb2_path": "C:/analysis/new.i64",
"output_dir": "C:/diaphora-outputs/run-001",
"export_mode": "headless",
"use_decompiler": false,
"summaries_only": false,
"cleanup": false,
"limit": 100,
"unmatched_limit": 50
}
```
これにより、Hex-Raysを必要とせずにアセンブリの詳細が保持されます。必要なエクスポートプロファイルを選択してください:
| 詳細 | `use_decompiler` | `summaries_only` | 用途 |
| --- | --- | --- | --- |
| マッチングサマリー | `false` | `true` | 高速な初回パス。詳細なコードなし |
| アセンブリ | `false` | `false` | デコンパイラなしで逆アセンブリを比較 |
| アセンブリ + 疑似コード | `true` | `false` | 互換性のあるHex-Raysデコンパイラでのコードレビュー。低速 |
出力パスは常にレスポンスから取得してください:
```text
OLD_SQLITE = steps.export1.output
NEW_SQLITE = steps.export2.output
RESULTS = steps.diff.output
```
この例では、生成されるファイルは`run-001`配下の`old.diaphora.sqlite`、`new.diaphora.sqlite`、`old_vs_new.diaphora`です。入力のベース名が同じ場合、`old_`/`new_`という異なるエクスポート名が生成されます。後で関数を調査するために`cleanup=false`のままにしてください。
### 2. サマリーの取得と変更されたマッチの調査
ツール: **`get_diff_summary`**。
```json
{
"results_path": "C:/diaphora-outputs/run-001/old_vs_new.diaphora"
}
```
ツール: **`get_diff_results`**。このページは比率の低い部分マッチから始まります。
```json
{
"results_path": "C:/diaphora-outputs/run-001/old_vs_new.diaphora",
"match_type": "partial",
"min_ratio": 0.0,
"limit": 50,
"offset": 0,
"unmatched_limit": 50,
"unmatched_offset": 0,
"sort_by": "ratio",
"sort_order": "asc"
}
```
`partial`はDiaphoraのマッチカテゴリを選択するものであり、動作変更を保証するものではありません。サポートされているすべてのカテゴリには`match_type="all"`を使用してください。レスポンスには、カテゴリ別の件数、フィルタ後の合計、マッチ、未マッチ行、`next_offset`、`next_unmatched_offset`が含まれます。
続行するには、返された次のオフセットを次の呼び出しにコピーし、同じフィルタとソートを維持します。たとえば、それらが`50`と`50`の場合、`offset=50`と`unmatched_offset=50`を使用します。次のオフセットが`null`の場合は、そのリストが終了したことを意味するため、それ以上進めないでください。2つのリストは独立して進みます。ページサイズは正の値である必要があり、上限は5000です。最も強いマッチを先に調査するには`sort_order="desc"`を使用してください。
### 3. マッチした関数とそのグラフの比較
ツール: **`compare_functions`**。
```json
{
"db1_path": "C:/diaphora-outputs/run-001/old.diaphora.sqlite",
"db2_path": "C:/diaphora-outputs/run-001/new.diaphora.sqlite",
"address": "0x401000",
"match_results_path": "C:/diaphora-outputs/run-001/old_vs_new.diaphora"
}
```
レスポンスには、`function_old`、`function_new`、利用可能なアセンブリ/疑似コード、測定された差分、同一性の証拠が含まれます。`address`の代わりに`name`を使用できます。両方のセレクタが指定された場合、addressが優先されます。名前で選択する場合はaddressを省略してください。
ツール: **`get_changed_callgraph`**は上記と同じ引数を受け付けます。変更を報告する前に対応する呼び出し元/呼び出し先のアドレスを変換し、未解決の隣接ノードと確認済みのエッジ差分を分離します。
16進数入力を明確にするために、**`0x`プレフィックス付きのアドレス**を推奨します。利用可能な場合は`match_results_path`を指定してください。これはリベースと名前変更された関数を処理します。アドレスが同じだけでは同一性を確立できません。曖昧または欠落したマッチは、削除と見なされるのではなく未解決のままになります。ペアを手動で検証した場合は、`address2`または`name2`を明示的に指定できます。
### 4. 関数の検索とコードの読み取り
ツール: **`search_export_db`**。`name_pattern`はSQL LIKEを使用します。`%`は任意のシーケンスにマッチします。
```json
{
"db_path": "C:/diaphora-outputs/run-001/old.diaphora.sqlite",
"name_pattern": "%parse%",
"min_instructions": 20,
"limit": 20
}
```
ツール: **`get_function_pseudocode`**は、その名前にもかかわらず、利用可能な疑似コード**およびアセンブリ**を返します。
```json
{
"db_path": "C:/diaphora-outputs/run-001/old.diaphora.sqlite",
"address": "0x401000"
}
```
疑似コードが空の場合は、互換性のあるデコンパイラを使用して、`use_decompiler=true`と`summaries_only=false`で新しい実行ディレクトリにエクスポートを再実行してください。エクスポートのメタデータを調査するには、`db_path`を指定して`get_export_info`を使用してください。
### 5. 既存のエクスポートの比較
ツール: **`diff_diaphora_dbs`**。これはIDAエクスポートをスキップし、既存の公式SQLiteエクスポートを比較します。
```json
{
"db1_path": "C:/diaphora-outputs/run-001/old.diaphora.sqlite",
"db2_path": "C:/diaphora-outputs/run-001/new.diaphora.sqlite",
"output_path": "C:/diaphora-outputs/another-diff.diaphora"
}
```
1つの新しいエクスポートには、`idb_path`、新しい`output_path`、`export_mode="headless"`を指定して`export_idb_to_diaphora`を使用してください。
## ツール
| ツール | 目的 |
| --- | --- |
| `export_idb_to_diaphora` | 保存された1つのIDAデータベースをエクスポート |
| `batch_export_and_diff` | 両方のデータベースをエクスポートして比較 |
| `diff_diaphora_dbs` | 既存のエクスポートを比較 |
| `get_diff_summary` | マッチ統計と範囲を限定した例 |
| `get_diff_results` | フィルタ、ソート、ページングされた結果 |
| `get_export_info` | エクスポートのメタデータと件数 |
| `search_export_db` | 関数の検索 |
| `get_function_pseudocode` | アセンブリ/疑似コードの読み取り |
| `compare_functions` | 解決されたold/newペアの比較 |
| `get_changed_callgraph` | マッピングされた呼び出し元/呼び出し先の比較 |
正確なシグネチャはMCPの`tools/list`で確認できます。[ツールリファレンス](https://github.com/xteardx/diaphora-mcp/blob/master/docs/TOOLS.md)を参照してください。
## エクスポートモードと設定
| モード | 動作 |
| --- | --- |
| `headless` | IDAをヘッドレスで起動し、diffスキーマを検証。比較に推奨 |
| `auto` | アクティブなGUIブリッジを試し、次にヘッドレスにフォールバック |
| `gui` | 正しい開いているGUIセッションを要求。ヘッドレスへのフォールバックなし |
`batch_export_and_diff`には`headless`が必要です。
| 環境変数 | 意味 |
| --- | --- |
| `IDAT_PATH` | IDAヘッドレス実行ファイルへの絶対パス |
| `DIAPHORA_DIR` | Diaphoraスクリプトを含むディレクトリ |
| `DIAPHORA_OUTPUT_ROOT` | 新しいエクスポートとdiff結果のための既存の許可されたルート |
| `DIAPHORA_PYTHON` | オプションのdiffインタプリタ。デフォルトはMCPサーバーのインタプリタ |
| `DIAPHORA_ENABLE_LEGACY_TOOLS` | 正確に`1`で以前の21ツールインターフェースを有効化 |
レガシーマッチング、特徴スコア、セキュリティトリアージ、レポート、メタデータ、診断はオプトインのままです。有効にするには、設定の`env`オブジェクトに以下のエントリを追加して再起動してください:
```json
{
"DIAPHORA_ENABLE_LEGACY_TOOLS": "1"
}
```
これらのツールはヒューリスティックを使用します。そのスコアは、意味的な等価性、セキュリティ修正、因果関係を証明するものではありません。[設定](https://github.com/xteardx/diaphora-mcp/blob/master/docs/CONFIGURATION.md) · [GUIセットアップ](https://github.com/xteardx/diaphora-mcp/blob/master/GUI_INSTRUCTIONS.md)。
## トラブルシューティング
| 症状 | 対処 |
| --- | --- |
| ターゲットが既に存在する | 新しい実行ディレクトリまたは出力ファイル名を使用 |
| 出力が許可されたルート外 | `DIAPHORA_OUTPUT_ROOT`配下の宛先を選択。ルートを先に作成 |
| 結果ツールにIDAデータベースを渡した | 返された`.diaphora.sqlite`エクスポートまたは`.diaphora`結果を適切に使用 |
| 対応するものが欠落/曖昧 | old/newの順序とマッピングを確認。候補を手動で調査 |
| アセンブリ/疑似コードが空 | エクスポートプロファイルを確認。新しい詳細エクスポートを取得 |
| エクスポート/diffに長時間かかる | MCPクライアントのタイムアウトを増やす。ローカルの`logs/`を確認。サマリーのみの初回パスを検討 |
| IDBがIDAセッションにロックされている | セッションを閉じるか、単一エクスポートには対応するGUIエクスポートモードを使用 |
| サポートされていないスキーマ | サポートされているDiaphoraバージョンで再エクスポート。報告された欠落テーブル/カラムを確認 |
マッチングはヒューリスティックのままです。高い比率は証拠であり、証明ではありません。未マッチの関数は、追加/削除が確認されたものではありません。バイナリ、IDB、エクスポート、ログはGitに含めないでください。[ワークフロー](https://github.com/xteardx/diaphora-mcp/blob/master/docs/WORKFLOWS.md)、[制限事項](https://github.com/xteardx/diaphora-mcp/blob/master/docs/LIMITATIONS.md)、[セキュリティ](https://github.com/xteardx/diaphora-mcp/blob/master/SECURITY.md)を参照してください。
## 開発
```powershell
.\.venv\Scripts\python.exe -m pip install -e ".[dev]"
.\.venv\Scripts\python.exe -m pytest -q
.\.venv\Scripts\python.exe -m compileall -q .
git diff --check
```
回帰テストスイートは合成データベースとモック化されたIDAプロセスを使用します。実際のIDAエクスポートにはローカル統合検証が必要です。[コントリビューション](https://github.com/xteardx/diaphora-mcp/blob/master/CONTRIBUTING.md) · [エージェント指示](https://github.com/xteardx/diaphora-mcp/blob/master/AGENTS.md)。