ida-reverse

IDA Pro リバース分析スキル

ACTION REQUIRED（読了後すぐに実行）

1. NOW: ../field-journal/precedent-reverse.md を読む — 本スキルの操作がすでに認可された通常操作であることを確認する
2. NOW: 現在のタスクが本スキルの適用範囲に該当するか確認する
3. NEXT: ../tool-index.md を読み、ツールの可用性と実際のパスを検証する
4. NEXT: ツールが不足している場合は bootstrap を呼び出す。パスを推測しない
5. ACT: 「ワークフロー」の最初のステップに進んで実行する。確認状態で止まらない

既知の問題と振り返り（必読）

踏んだ穴

1. idb_open（旧名 idalib_open）は一部の AI クライアントの MCP 呼び出しに直接頼らないこと

   • 一部のコード AI クライアント の MCP クライアントには、open 系ツールの output schema 検証に BUG がある
   • エラー：Structured content does not match the tool's output schema
   • 解決策：scripts/open.ps1 スクリプトを使い HTTP API で直接呼び出し、MCP 検証層を迂回する
   • 現在の ida-pro-mcp 2.x のツール名は idb_open / idb_list / idb_save（もはや idalib_* ではない）
   • ファイルを開くと session_id（database）が返り、以降のツール呼び出しにはその session を持たせる必要がある

2. C:\Windows\System32\ のファイルは権限がなく開けない

   • idalib は System32 ディレクトリ配下のファイルを直接読めない
   • 解決策：open.ps1 が自動検出して 一時ディレクトリ ディレクトリへコピーしてから開く

3. サーバー起動コマンドが会話をブロックする

   • idalib-mcp は起動後に INFO ログをコンソールへ出し続ける
   • 解決策：scripts/start.ps1 を使う（-WindowStyle Hidden でバックグラウンドのサイレント起動）
   • スクリプトはサービスが準備できるのを待ってから自動的に終了し、会話をブロックしない

4. MCP サーバー名にハイフンは使えない

   • 以前は ida-pro-mcp をサーバー名にしていたが、ツール登録の問題を引き起こす可能性がある
   • 現在の設定：サーバー名 idapro、ツールプレフィックス idapro_*

5. Remote HTTP vs Local Stdio

   • type:"local"（stdio）モード：idalib_open にも同様に schema 検証の問題がある
   • type:"remote"（HTTP）モード：まずスクリプトでファイルを直接開き、その後 MCP ツールを使える
   • 現在の方式：Remote HTTP モード

6. PR #389 が一部の schema 問題を修正した

   • 作者の mrexodia 氏が issue #388 の後、PR #389 で修正をマージした
   • HTTP モードでの structuredContent schema を修正したが、一部のコード AI クライアント 側の検証には依然として問題がある
   • 最新の main ブランチ版をインストール済み

7. idalib のタイムアウトが孤児 worker プロセスのロックファイルを残す

   • 最初の open.ps1 がタイムアウトした後、idalib の python worker 子プロセスが孤児になり、.id0/.id1/.nam を掴んだまま離さないことがある
   • 以降、どのツールでも、あるいは手動で IDA GUI にドラッグしても「権限不足」と報告される
   • 禁止：taskkill /F /T でプロセスツリーを殺すこと——/T は GUI の ida.exe 子プロセスも一緒に殺してしまう
   • 解決策：start.ps1 は、ポートで誰も待ち受けていない場合、または tools/list が素早く返るが py_eval が欠けている場合（旧 supervisor）にのみ managed supervisor を置き換える。RPC タイムアウトかつ 13337 がまだ待ち受けている場合はビジーとみなし、殺さない。ライブラリを開くとき open.ps1 が opening.lock を書き、watchdog は -Force を使ってはならない
   • デッドロックの例外：tools/list が 3 分を超えて連続失敗（プロセス作成時刻ではなく last-healthy タイムスタンプによる）し、in-flight の opening.lock がなく、GUI がポートを占有していない場合にのみ -Force で supervisor を置き換える。それでも ida.exe は殺さない
   • フォールバック：open.ps1 が旧ライブラリのロックを検出すると自動的に Temp へコピーし GUID プレフィックスを付ける

8. 自動分析付きで開くとフリーズしたように見える

   • idalib_open(run_auto_analysis=true) は長時間応答を返さないことがあるが、バックエンドでは実際には開く処理と分析が続いている
   • 以前、ユーザー側からは「PowerShell がずっと無出力」に見え、スクリプトのフリーズと誤判定しやすかった
   • 現在の解決策：open.ps1 に -TimeoutSeconds を追加し、バックグラウンドリクエスト + フォアグラウンドポーリング + 定期的な進捗出力に変更
   • ポーリングでセッションが準備完了になると早期に OK:ファイル名:session_id を返し、タイムアウト時は ERR:open_timeout_xxs を返す

9. HTTP MCP はログイン後にサイレント終了する

   • Cursor/Claude の type: http はプロセスを代行起動しない。旧タスクスケジューラはログイン時に一度だけ実行される
   • pythonw はコンソールがなく、クラッシュしても Application ログは空のまま
   • 解決策：start.ps1 はデフォルトで健全なら再利用する。watchdog.ps1 が毎分巡回する。ログは %LOCALAPPDATA%\reverse-skill\ida-mcp\ にある
   • インストール：scripts/install-autostart.ps1。HTTP クライアントは起動時にポートがまだ立ち上がっていない場合、MCP パネルで手動リフレッシュが一度必要

10. Streamable HTTP GET /mcp がシングルスレッド supervisor を詰まらせる

• 一部の HTTP MCP クライアントは /mcp に対して長接続 GET（SSE）を送る。stock な idalib_supervisor は background=False の HTTPServer を使い、一度に一つのリクエストしか処理しない
• 結果：tools/list がタイムアウトし、クライアントが idapro を error とマークする
• 解決策：run-supervisor.py が HTTP を ThreadingHTTPServer に置き換え、GET /mcp を受け付ける。パッチが失敗した場合はスキップし、それでも supervisor を起動する。詰まったときは scripts/recover.ps1 を使う（即座に -Force）

ワークフローの原則

ステップ	何をするか	何を使うか
1	HTTP サーバーが稼働していることを確認する	scripts/start.ps1（引数なし）
2	対象のバイナリファイルを開く	scripts/open.ps1 -Path "xxx.exe"
3	MCP 分析ツールを使う	idapro_* / HTTP tools を直接呼び出す（約 65 個、バージョンによる）
4	分析完了	ツールは自動的に利用可能

スクリプトリソース

start.ps1 — MCP HTTP サーバーを起動する

パス：scripts/start.ps1

• IDADIR を自動解決する（環境変数 / ポータブル版デスクトップパス / 一般的なインストールパス）
• 優先的に IDA 付属の Python314\python.exe -m ida_pro_mcp.idalib_supervisor を使う
• デフォルトではまず http://127.0.0.1:13337/mcp をプローブし、健全なら OK:<n>:reuse を出力して終了する
• 13337 が待ち受けているが tools/list がタイムアウトする → WARN:busy / OK:busy:reuse、殺さない（ライブラリを開いているか GUI が占有していると応答を返せない）
• tools/list が 3 分を超えて連続失敗（last-healthy タイムスタンプ）かつ opening.lock がない → デッドロックとみなし、INFO:deadlock を出力して -Force で supervisor を置き換える。進行中の idb_open と GUI はこのパスを通らない
• ポートで誰も待ち受けていない場合、py_eval が欠けている場合、または上記のデッドロックの場合にのみ managed supervisor を置き換える。決して ida.exe を殺さず、taskkill /T を使わない
• GUI が 13337 を占有している場合は WARN:gui_busy を出力して終了し、別の supervisor を起動しない
• 成功時は OK:<ツール数>（現在約 66）を出力し、失敗時は ERR:timeout を出力する
• supervisor ログ：%LOCALAPPDATA%\reverse-skill\ida-mcp\supervisor.log
• サーバーはバックグラウンドで動作し、会話をブロックしない

呼び出し方：

powershell -File "<skill-root>\ida-reverse\scripts\start.ps1"

watchdog.ps1 / recover.ps1 / install-autostart.ps1 — 保活

• watchdog.ps1：探测 13337；健康 reuse（并刷新 last-healthy）；GUI / open.ps1 开库锁 / last-healthy 未满 3 分钟的 busy → reuse；只有 tools/list 连续失败超过 3 分钟才 start.ps1 -Force
• recover.ps1：立刻 start.ps1 -Force（不杀 ida.exe）。HTTP 客户端把 idapro 标成 error 时用这个
• install-autostart.ps1：注册计划任务 reverse-skill-ida-mcp（登录 + 每分钟）
• 日志：%LOCALAPPDATA%\reverse-skill\ida-mcp\watchdog.log

open.ps1 — 打开二进制文件

路径：scripts/open.ps1

• 通过 HTTP API 直调 idb_open，绕过 MCP schema 校验
• 自动检测 System32 路径并复制到临时目录
• 自动清理同名旧数据库文件（.id0/.id1/.nam/.til/.i64）
• 旧库被锁时自动降级：复制到 Temp 加 GUID 前缀后打开，不报错
• 将打开请求放到后台执行，避免长时间同步等待导致脚本无响应
• 支持 -TimeoutSeconds，超时后返回 ERR:open_timeout_xxs，不会无限卡住
• 每隔 10 秒输出一次 INFO:opening:已用时/超时秒数，便于判断仍在分析中
• 成功输出 OK:文件名:session_id，降级时加 (temp copy) 标记
• 失败时自动重试走 Temp 副本

调用方式：

powershell -File "<skill-root>\ida-reverse\scripts\open.ps1" -Path "C:\path\to\file.exe"

可选参数：

# 指定 SessionId
powershell -File "scripts\open.ps1" -Path "file.exe" -SessionId "my_session"

# 跳过自动分析（大文件推荐）
powershell -File "scripts\open.ps1" -Path "large.exe" -NoAutoAnalysis

# 设置超时，避免带自动分析时长时间无返回
powershell -File "scripts\open.ps1" -Path "file.exe" -TimeoutSeconds 600

输出约定：

# 分析进行中（每 10 秒输出一次）
INFO:opening:11/600s

# 成功打开
OK:sample.exe:abcd1234

# 成功打开，但因锁文件降级到 Temp 副本
OK:1234abcd-sample.exe:abcd1234 (temp copy)

# 达到超时上限
ERR:open_timeout_600s

实测说明：

• Snipaste.exe 带自动分析实测约 324s 才返回成功，属于“分析很久”而不是“脚本死锁”
• 因此遇到 GUI 程序或较复杂样本时，建议优先显式设置 -TimeoutSeconds 600

核心工具列表

概况分析（第一步）

• idapro_survey_binary(detail_level="minimal") — 快速概况：函数数、字符串、段、入口点、导入分类（加密/网络/文件IO）
• idapro_list_funcs(queries) — 列出函数（分页、按名称过滤）
• idapro_list_globals(queries) — 列出全局变量
• idapro_entity_query(kind, filter) — 统一查询：functions/globals/imports/strings/names

反编译与反汇编

• idapro_decompile(addr) — 反编译为伪代码
• idapro_disasm(addr, max_instructions=N) — 反汇编
• idapro_analyze_function(addr, include_asm=false) — 综合分析（伪代码+字符串+常量+调用者+被调用者+块）
• idapro_func_profile(queries) — 函数概要指标

交叉引用与数据流

• idapro_xrefs_to(addrs) — 查谁引用目标地址
• idapro_xref_query(addr, direction) — 高级 xref 查询（方向/类型过滤）
• idapro_callees(addrs) — 子函数列表
• idapro_callgraph(roots, max_depth) — 调用图
• idapro_trace_data_flow(addr, direction, max_depth) — 数据流追踪（forward/backward）

搜索

• idapro_find_regex(pattern, limit) — 正则搜字符串
• idapro_search_text(pattern) — 在反汇编列表中搜文本
• idapro_find_bytes(patterns, limit) — 字节模式搜索（支持 ?? 通配符）
• idapro_find(type, targets) — 高级搜索（立即数/字符串/引用）

内存与数据

• idapro_get_bytes(addrs) — 读原始字节
• idapro_get_string(addrs) — 读字符串
• idapro_get_int(queries) — 读整数值
• idapro_get_global_value(queries) — 读全局变量值
• idapro_read_struct(queries) — 读结构体字段值
• idapro_search_structs(filter) — 搜索结构体

修改操作

• idapro_set_comments(items) — 添加注释（反汇编+反编译双向同步）
• idapro_append_comments(items) — 追加注释
• idapro_rename(batch) — 批量重命名（函数/全局/局部/栈变量）
• idapro_patch_asm(items) — Patch 汇编指令
• idapro_patch(patches) — Patch 字节
• idapro_define_func(items) — 定义函数
• idapro_undefine(items) — 取消定义
• idapro_define_code(items) — 将字节转为代码

类型系统

• idapro_declare_type(decls) — 声明 C 结构体/枚举/联合体
• idapro_set_type(edits) — 应用类型到函数/全局/局部
• idapro_infer_types(addrs) — 推断类型
• idapro_type_query(queries) — 查询已声明类型
• idapro_type_inspect(queries) — 查看类型详情

栈帧

• idapro_stack_frame(addrs) — 查看栈帧变量
• idapro_declare_stack(items) — 声明栈变量
• idapro_delete_stack(items) — 删除栈变量

签名

• idapro_make_signature(addrs) — 为地址生成唯一字节签名
• idapro_make_signature_for_function(addrs) — 为函数生成签名
• idapro_find_xref_signatures(addrs) — 为引用地址的代码生成签名

调试器（需要 ?ext=dbg）

• idapro_open_file(file_path) — 在 GUI IDA 实例中打开文件
• 调试器工具默认隐藏，可通过 URL 参数 ?ext=dbg 启用

会话管理（ida-pro-mcp 2.x）

• idapro_idb_open / HTTP idb_open — ⚠️ 建议用 open.ps1 打开
• idapro_idb_list / HTTP idb_list — 列出所有 session
• idapro_idb_save / HTTP idb_save — 保存数据库
• 多数分析工具需要 database=<session_id> 参数（open.ps1 输出的 session）

其他

• idapro_int_convert(inputs) — 进制转换（必须用这个，不要自己算进制！）
• idapro_export_funcs(addrs, format) — 导出函数（json/c_header/prototypes）
• idapro_py_eval(code) — 在 IDA 上下文执行 Python
• idapro_server_health() — 服务器健康检查
• idapro_server_warmup() — 预热子系统（字符串缓存、Hex-Rays 等）

逆向分析完整工作流

ステップ 1: サーバーを起動する

パス A — Headless idalib（有効な license が必要）

powershell -File "scripts/start.ps1"

OK:<ツール数>（現在は約 65）が出力されれば準備完了です。

パス B — GUI + プラグイン（idalib license が失敗した場合、または対話的な分析が必要な場合）

powershell -File "scripts/start-gui.ps1" -Path "C:\目标.exe"

またはポータブル版 Launch-IDA-Pro.cmd をダブルクリックし、IDA でサンプルを開きます。

Output ウィンドウに [MCP] ... port=13337 が表示されたことを確認すると、MCP ツールが使用可能になります。

共通の接続手順については LOCAL-SETUP.md を参照してください。

ステップ 2: ファイルを開く

Headless：

powershell -File "scripts/open.ps1" -Path "C:\目标.exe" -TimeoutSeconds 600

OK:ファイル名:session_id が出力されれば成功です（後ろに (temp copy) が付く場合は一時コピーへの自動降格を意味します）。

ERR:idalib_license:... が発生した場合は、パス B（GUI モード）に切り替えてください。open.ps1 を何度もリトライしないでください。

GUI モード：IDA で直接サンプルを Open するだけでよく、open.ps1 は不要です。

ステップ 3: 全体概要（インポートテーブルのハードゲートを含む）

idapro_survey_binary(detail_level="minimal")

注目する点：

• アーキテクチャ（x86/x64/ARM）
• エントリポイント（main/WinMain/DllMain）
• 興味深い文字列（URL、パス、エラーメッセージ）
• インポート分類（MUST）：暗号化関数 / ネットワーク API / ファイル操作 / プロセスインジェクション / レジストリ — 必ず Evidence として記録すること（推奨 id：E-imports）。idapro_entity_query(kind="imports") または survey 出力の imports セクションを利用できます
• DLL/SYS：エクスポートテーブルとインポートテーブルを併記する（Evidence E-exports）
• .NET：従来の IAT が存在しない場合は、モジュール/メタデータ/マネージド参照の要約を等価なアンカーとして E-imports のセマンティックスロットに書き込む
• クリーンなインポートテーブル：動的ロードの疑いを明記し、動的 API ブレークポイントによる検証を促す
• ホットな関数（xref カウントが高い関数は通常、重要なロジックである）

ハードゲート：imports ビュー/分類の要約（または正当な等価アンカー）を Evidence に書き込む前に、ステップ 4 の深掘り結論に進んではならない（MUST NOT）。survey 完了を主張してはならない（MUST NOT）。インポートテーブルが空、またはクエリが失敗した場合でも、失敗の現象を必ず記録すること（MUST）。パックされた IAT の修復に失敗した場合は、E-iat-repair-fail を記録し（MUST）、動的デバッグによる API キャプチャに切り替えること。静的なまま突き進んではならない。ユーザーがインポートテーブル/IAT の検査をやり直すよう要求した場合は、指名されたステップを必ずやり直すこと（MUST）（ブロック時のフィージビリティゲート：説明+確認。強制の場合は quality=unreadable とマークする）。無関係なステップへの差し替えは禁止です。

ステップ 4: 重要な関数を深掘りする

idapro_analyze_function(addr="关键函数名")

または：

idapro_decompile(addr="函数名")
idapro_disasm(addr="函数名", max_instructions=50)

ステップ 5: データフローとクロスリファレンス

idapro_xrefs_to(addrs="关键地址/字符串")
idapro_callgraph(roots=["关键函数"], max_depth=3)
idapro_trace_data_flow(addr="关键地址", direction="backward", max_depth=5)

ステップ 6: 記録と最適化

idapro_set_comments(items=[{"addr": "0x140001000", "comment": "你的理解"}])
idapro_rename(batch={"func": [{"addr": "函数地址", "name": "有意义的名字"}]})

ステップ 7: レポートを出力する

分析が完了したら、発見事項と手順を記録した report.md を生成します。

Prompt エンジニアリングの指針

1. 手動で進数変換しない — 数値の変換が必要なときは常に idapro_int_convert を使う
2. まず survey、次に深掘り — まず概要を見てから的を絞った分析を行う
3. コメントとリネームを継続する — 分析の過程で関数名や変数名を随時更新し、後続の分析精度を高める
4. クロスリファレンスを追跡する — 興味深いデータ/文字列を見つけたら、xrefs_to で誰が参照しているかを確認する
5. 難読化コードに遭遇したら — まず文字列復号、インポートハッシュ除去、制御フロー平坦化除去などの前処理を行う
6. C++ STL コード — FLIRT/Lumina でライブラリ関数を識別してから、ビジネスロジックを分析する
7. ブルートフォースしない — 分析は逆アセンブリから解決策を導き出すべきであり、簡単な Python で計算を補助する
8. "No database bound" に遭遇したら — まだどのバイナリファイルも開かれていないので、まず open.ps1 を実行する
9. "Failed to open database" に遭遇したら — 古いデータベースファイルがロックされている可能性があり、open.ps1 は自動的に Temp コピーに降格します（出力に (temp copy) マークが含まれる）
10. 自動分析付きで GUI/複雑なサンプルを開くとき — デフォルトで -TimeoutSeconds 600 を付ける。長時間の INFO:opening:... をスクリプトのハングと誤判定しないこと

---

ルーティングコンテキスト

上流エントリ: skills/SKILL.md（総合制御）、routing.md 上流代替: radare2/（IDA を開きたくない場合、まず r2 で素早く偵察できます） 下流出口:

• Frida による動的検証が必要 → reverse-engineering/tools-dynamic.md
• シンボリック実行/angr が必要 → reverse-engineering/tools-dynamic.md
• 汎用のリバースエンジニアリング方法論が必要 → reverse-engineering/SKILL.md

同階層の関連モジュール: radare2/（IDA が利用できない場合の代替手段）

---

オンデマンド自举（On-Demand Bootstrap）

本 skill のエントリスクリプトは統合自举システムに接続されています。

自動化能力の境界

ツール	自動インストール可	インストール方式	説明
idalib-mcp	✓	pip install (from GitHub)	start.ps1 が欠落時に自動インストール
IDA Pro 本体	✗	商用ソフトウェア、手動インストールが必要	IDADIR 環境変数をインストールディレクトリに設定する

インストール手順（検証済み）

# 1. 设置 IDA 路径（替换为你的实际 IDA 安装目录）
setx IDADIR "<你的IDA安装目录>"

# 2. 从 GitHub 安装 ida-pro-mcp（PyPI 上的 ida-mcp 是另一个项目，不要装错！）
pip install git+https://github.com/mrexodia/ida-pro-mcp.git

# 3. 安装 IDA 插件（选择 Streamable HTTP + Global + 全选客户端）
ida-pro-mcp --install

# 4. 重启 IDA Pro，打开目标文件
# 插件自动监听 127.0.0.1:13337

# 5. 验证
ida-pro-mcp --config

⚠️ 注意：PyPI 上の ida-mcp パッケージ（作者 jtsylve）は別のプロジェクトであり、私たちが必要としているものではありません。 必ず GitHub から mrexodia/ida-pro-mcp をインストールしてください。

自举のトリガーポイント

• scripts/start.ps1：idalib-mcp が欠落時に bootstrap-reverse.ps1 を自動的に呼び出す
• MCP 登録：bootstrap は idapro を Claude MCP 設定に自動的に書き込みます

前提条件

• IDA Pro がインストール済みで、IDADIR 環境変数が設定されている（またはスクリプト内のデフォルトパスが正しい）
• IDA 付属の Python314 内の ida-pro-mcp の使用を推奨（ポータブル版には内蔵済み）
• よくあるローカル構成：
  • User env IDADIR → IDA インストールディレクトリ（ida.exe を含む）
  • オプション ~\Tools\bin\idalib-mcp.cmd / ida-pro-mcp.cmd ラッパー
  • クライアントの MCP サーバー名は idapro のみ → http://127.0.0.1:13337/mcp

タスク完了のセルフチェック（完了を主張する前に MUST 通過）

• 私はワークフローの各ステップを（読むだけでなく）実行しましたか？
• survey/imports は Evidence（E-imports または等価）に書き込まれましたか？DLL/SYS は E-exports を含みますか？IAT の失敗は E-iat-repair-fail に記録しましたか？
• ユーザーがインポートテーブル/IAT のやり直しを要求した場合、同じステップをやり直しましたか？
• 私は tool-index に基づいて実際のツールパスを使用しましたか？
• 私は再現可能な証拠（コマンド/スクリプト/スクリーンショット/レポート）を産出しましたか？
• 私は RULES が要求する Checklist 項目を完了し、書き戻しましたか？