ghidra-rpc

Ghidra RPC

Unix ドメインソケットを介して Ghidra のリバースエンジニアリング機能を公開する CLI デーモンです。 bash ツールから ghidra-rpc コマンドを実行して操作します。すべてのコマンドは JSON を標準出力に出力します。

コマンドの実行

すべての ghidra-rpc コマンドは、ghidra-rpc スキルディレクトリ （この SKILL.md ファイルを含むディレクトリ）から uv run を付けて実行してください：

cd <skill-dir> && uv run ghidra-rpc <command> ...

前提条件の確認

コマンドを使用する前に、セットアップを確認してください。

1. デーモンは起動していますか？ uv run ghidra-rpc status --project <path> を実行します。起動していない場合は、 ユーザーが別のターミナルで起動する必要があります：uv run ghidra-rpc start --project /path/to/project.gpr （ブロッキング、ユーザーによる操作が必要です）。--headless フラグを指定すると GUI をスキップします。ノンブロッキングまたは自動起動するには、 start --detach --headless または restart --headless を使用してください。どちらのコマンドも --timeout SECS を受け付けます（デフォルト：ヘッドレスでは 60 秒、GUI では 180 秒）。また、デーモンの出力は /tmp/ghidra-rpc-<hash>.log（Windows では %LOCALAPPDATA%\ghidra-rpc\ghidra-rpc-<hash>.log） に記録されます。
2. GUI モード：正しいプロジェクトがアクティブか確認します。 デーモンは --project のパスを GhidraRun に直接渡すため、Ghidra は指定されたプロジェクトをすぐに開きます。start --detach（GUI モード）の後、 分析コマンドを実行する前に、正しいプロジェクトが読み込まれていることを確認してください：

   uv run ghidra-rpc list-project-programs --project /path/to/project.gpr
   

   返されたバイナリ名が想定と一致するか照合してください。名前が一致しない場合 （または応答に warning フィールドが含まれる場合）は、作業を中断し、続行する前に Ghidra のプロジェクトウィンドウで 正しいプロジェクトを開くようユーザーに依頼してください。
3. GUI モード：CodeBrowser でバイナリを開きます。 GUI モードでは、デーモンは実行中の CodeBrowser ツールを介してプログラムを検出します。バイナリがプロジェクト内にあっても、現在 CodeBrowser で開かれていない場合、list-binaries は空の結果を返し、すべてのコマンドが 「Binary not found」で失敗します。list-project-programs を使用してプロジェクトに保存されている内容を確認し、Ghidra のプロジェクトウィンドウでプログラムをダブルクリックして開いてください。
4. GHIDRA_INSTALL_DIR は設定されていますか？ この設定がない場合、デーモンは明確なエラーを出して失敗します。

デーモンが起動すれば、以下のすべてのコマンドが自動的に使用できます。デーモンが停止した場合、 コマンドは保存済みのセッションからの自動再起動を試みます。

コマンドリファレンス

すべてのコマンドは --project <path> を受け付けます（または GHIDRA_RPC_PROJECT 環境変数を読み取ります）。 すべての出力は JSON です。終了コード 0 は成功、1 はエラーを表します。

プロジェクト管理

コマンド	説明	例
ghidra-rpc start --project <gpr> [--headless] [--detach] [--ghidra-install-dir DIR]	デーモンを起動します（デフォルトではフォアグラウンドで実行されます。--detach を指定するとバックグラウンドで実行されます）	ghidra-rpc start -p /tmp/re.gpr --headless --detach
ghidra-rpc stop --project <gpr>	デーモンを停止します	ghidra-rpc stop -p /tmp/re.gpr
ghidra-rpc status --project <gpr>	デーモンが実行中かどうかを確認します	ghidra-rpc status -p /tmp/re.gpr

status の出力：{running, socket, mode, mode_source, project, binaries}。binaries は、デーモンの実行中は読み込み済みバイナリのリスト、停止中は null です（list-binaries を別途呼び出すことなく、1 回のヘルスチェックで確認できます）。mode_source は、デーモンが実行中の場合は "running"、保存済みセッションからのみモードを取得する場合（デーモン停止中）は "session"、セッションが存在しない場合は null です。 | ghidra-rpc restart --project <gpr> [--headless] [--timeout SECS] [--ghidra-install-dir DIR] | デーモンをバックグラウンドで再起動します（--headless を指定するとモードを上書きします） | ghidra-rpc restart -p /tmp/re.gpr --headless | | ghidra-rpc list-binaries --project <gpr> | デーモンに読み込み済みのバイナリを一覧表示します | ghidra-rpc list-binaries -p /tmp/re.gpr | | ghidra-rpc list-project-programs --project <gpr> | プロジェクトリポジトリに保存されているすべてのプログラムを一覧表示します（CodeBrowser のライブ状態ではなくプロジェクトフォルダーを読み取ります。有効な Ghidra プロジェクトが一致しない場合は warning を返します） | ghidra-rpc list-project-programs -p /tmp/re.gpr | | ghidra-rpc save [binary] --project <gpr> | プログラムをディスクに保存します（書き込みのたびに自動保存も実行されます） | ghidra-rpc save -p /tmp/re.gpr |

読み込みと解析

コマンド	説明	例
ghidra-rpc load <path> -p <gpr> [--no-analyze] [--analysis-timeout SECS]	バイナリをインポートして解析します	ghidra-rpc load /usr/bin/target -p /tmp/re.gpr
ghidra-rpc metadata <binary> -p <gpr>	バイナリのメタデータ（アーキテクチャ、ビット数、形式）	ghidra-rpc metadata target -p /tmp/re.gpr

load のフラグ：

• --no-analyze - 自動解析を完全にスキップします（高速です。リスティングだけが必要な場合や、後で Ghidra GUI から解析を実行する場合に便利です）。
• --analysis-timeout SECS - 指定した実時間の上限が経過した後、自動解析を中止します（可能な範囲で実行します）。時間内に完了した解析結果を反映してバイナリを保存します。

リスティング

コマンド	説明	出力形式
ghidra-rpc functions <binary> [--offset N] [--limit N] [--address-min ADDR] [--address-max ADDR] [--with-body]	関数を一覧表示します（ページネーション対応）。サーバー側で範囲を絞り込むには --address-min/max を指定します。--with-body を指定すると、本体の範囲を示すフィールドが追加されます	{functions: [{name, address, signature[, body_min, body_max, body_size]}], count, total, offset}
ghidra-rpc imports <binary>	インポートを一覧表示します	{imports: [{name, address, library}], count}
ghidra-rpc exports <binary>	エクスポートを一覧表示します	{exports: [{name, address}], count}
ghidra-rpc relocations <binary> [--address ADDR] [--limit N]	再配置テーブルのエントリを一覧表示します	{relocations: [{address, type, symbol, bytes, status}], count, total}
ghidra-rpc list-calling-conventions <binary>	アーキテクチャで有効な呼び出し規約名を一覧表示します	{conventions: [str], default, count}

逆コンパイル

コマンド	説明	出力形式
ghidra-rpc decompile <binary> <func> [--timeout SECS]	疑似 C に逆コンパイルします（デフォルト 120 s）	{name, address, signature, c_code}
ghidra-rpc basic-blocks <binary> <func> [--limit N]	関数の基本ブロック（CFG）を取得します	{name, address, blocks:[{start,end,size,instructions,successors,predecessors}], num_blocks, edges}
ghidra-rpc pcode <binary> <func> [--high] [--timeout SECS] [--limit N]	P-code（Ghidra IR）を取得します。raw または high SSA 形式（--high）を指定できます	{name, address, mode, ops:[{address,seq,opcode,output,inputs}], count, truncated}
ghidra-rpc search-decompiled <binary> <regex> [--class NAME] [--case-sensitive] [--limit N] [--max-scan N] [--timeout SECS] [--socket-timeout SECS]	1 回の呼び出しで多数の関数の逆コンパイル済み C を正規表現検索します（関数ごとに decompile と grep を呼び出すループを省略できます）	{matches:[{function,address,matching_lines:[{line,text}]}], count, functions_searched, functions_total, truncated}

<func> には関数名または 16 進数のアドレス（例：main または 0x401000）を指定できます。名前が曖昧な場合、エラーメッセージに候補が表示されるため、代わりにアドレスを指定できます。

search-decompiled は、特に multidex Android プロジェクトで役立ちます。この場合、メソッドに対する xrefs-to では、同じ DEX プログラム内の呼び出し元しか確認できません（Android APK/DEX のセクションを参照）。たとえば、symbols、decompile、grep のループの代わりに search-decompiled app.apk targetF1 --class com::example::Foo を使用します。--class を指定しない場合、--max-scan（デフォルト 5000）によって逆コンパイルする関数の数が制限されるため、関数が 50k 以上あるバイナリの検索が際限なく実行されることはありません。検索範囲を広げる場合は、あわせて --socket-timeout（デフォルト 1800s）も大きくしてください。

検索

コマンド	説明	出力形式
ghidra-rpc find-bytes <binary> <pattern> [--limit N] [--address ADDR]	ワイルドカードを含むバイトパターンを検索します（例："55 8b ?? 83 ec"）	{pattern, matches: [{address, context_hex}], count, truncated}
ghidra-rpc strings <binary> <query> [--limit N]	文字列を検索します（部分一致）	{strings: [{address, value, type}], count}
ghidra-rpc symbols <binary> <query> [--limit N] [--offset N]	シンボルを検索します	{symbols: [{name, address, type}], count, total}

symbols は照合の前に、通常のスペースとアンダースコアを同等のものとして扱います。そのため、strings の出力からそのまま貼り付けたクエリ（通常のスペースを含む）でも、対応するラベルを検索できます。Ghidra は文字列の各スペースを _ に変換してラベルを自動生成しますが、それ以外の文字（非 ASCII/CJK テキストを含む）はすべてそのまま保持します。

クロスリファレンス

コマンド	説明	出力形式
ghidra-rpc xrefs-to <binary> <target> [--limit N] [--all-binaries]	これを参照している箇所を検索します	{xrefs: [{from_address, from_function, type}], count}
ghidra-rpc xrefs-from <binary> <target> [--limit N] [--no-stack]	これが参照している箇所を検索します（--no-stack は Stack[-0x...] エントリを非表示にします）	{xrefs: [{to_address, to_function, type}], count}

Ghidra の参照マネージャーはバイナリごとに動作します。呼び出し元と対象が 異なる 読み込み済みバイナリにある呼び出しは、単一バイナリの xrefs-to 検索では検出されません（これは multidex Android プロジェクトでよく発生します。ある classesN.dex のメソッドが別の DEX から呼び出される場合などです。ただし DEX 固有ではなく、デーモンに複数のバイナリが読み込まれているあらゆるプロジェクトで発生します）。--all-binaries を指定すると、現在読み込まれている他のすべてのバイナリからも完全修飾名が同じシンボルを検索し、そこで見つかった実際の呼び出し元を統合します。統合された各エントリには binary フィールドが含まれるため、どのバイナリに由来するかを確認できます。

ナビゲーション（GUI モードのみ）

コマンド	説明	出力形式
ghidra-rpc goto <binary> <target> [function|address]	GUI で移動します	{address, success}

メモリと逆アセンブル

コマンド	説明	出力形式
ghidra-rpc memory-map <binary>	すべてのメモリセグメント（名前、アドレス範囲、サイズ、rwx フラグ、タイプ）を一覧表示します	{segments: [{name, start, end, size, read, write, execute, initialized, type, source_name}], count}
ghidra-rpc write-bytes <binary> <address> <hex>	アドレスに生のバイトを書き込みます。自動的に再逆アセンブルは行いません	{address, length, hex, verified}
ghidra-rpc read-bytes <binary> <address> <length>	生のバイトを読み取ります。LENGTH には10進数または 0x 形式の16進数を指定できます	{address, length, hex, hexdump}
ghidra-rpc read-pointers <binary> <address> <count> [--pointer-size N]	COUNT 個のポインターを読み取り、それぞれのシンボルを解決します（vtables、インポート／ジャンプテーブル、RTTI 配列）	{address, count, pointer_size, endian, pointers:[{index, offset, slot_address, value, target_address, target_name, target_kind}]}
ghidra-rpc list-vtable <binary> <address> [--count N] [--pointer-size N]	C++ vtable のスロットを解決済みメソッドとしてダンプします。ADDRESS にはシンボル名を指定できます。--count を指定しない場合、次の vftable シンボルまたは最初の関数以外のポインターで停止します（stopped_reason を参照）	{vtable_address, symbol, count, pointer_size, stopped_reason, slots:[{index, offset, slot_address, target_address, target_name, target_kind}]}
ghidra-rpc disassemble <binary> <address> [--count N] [--with-instructions]	N 個の命令を逆アセンブルします（デフォルトは20）。アドレス／バイト／ニーモニック／オペランド／コメントを含む listing テキストを返します。機械処理可能な配列が必要な場合に限り --with-instructions を指定してください（出力は約4倍になります）。開始アドレスに命令がない場合は warning フィールドが含まれます	{address, count, listing[, instructions][, warning]}
ghidra-rpc assemble <binary> <address> <instr> [<instr> ...]	アドレスに命令テキストをアセンブルします（Ghidra SLEIGH アセンブラー）	{address, bytes_written, hex, instructions:[{address,bytes,mnemonic,operands,length}]}

変更

コマンド	説明	出力形式
ghidra-rpc create-function <binary> <address> [--name NAME]	アドレスに関数を作成します（フローから本体を自動検出します）	{name, address, size, body}
ghidra-rpc delete-function <binary> <target>	関数定義を削除します（バイト列は変更されず、アドレスは未定義に戻ります）	{address, name, deleted}
ghidra-rpc rename-function <binary> <target> <new_name> [--namespace NS]	関数の名前を変更します。--namespace を指定すると、関数を名前空間に移動します	{address, old_name, new_name, verified[, old_namespace, new_namespace]}
ghidra-rpc rename-symbol <binary> <address> <new_name> [--create]	シンボルの名前を変更します。既存のシンボルがない場合、--create で新しいラベルを作成します	{address, old_name, new_name, created, verified}
ghidra-rpc create-label <binary> <address> <name>	任意のアドレスにラベルを作成または名前変更します（アップサート）	{address, name, old_name, action, created, verified}
ghidra-rpc set-comment <binary> <address> --comment <text> [--type TYPE]	コメントを設定します（コメント本文には set-bookmark と同様に --comment を使用します）	{address, comment_type, comment, verified}
ghidra-rpc batch-rename <binary> --json |--json-file FILE [--mode function|label]	1 回のトランザクションで 40 個以上の関数やラベルの名前を変更します。項目ごとにエラーを報告します	{results:[{ok, index, address, old_name, new_name}], count, ok_count, error_count}
ghidra-rpc batch-set-comment <binary> --json |--json-file FILE	1 回のトランザクションで複数のアドレスにコメントを設定します	{results:[{ok, index, address, comment_type, comment}], count, ok_count, error_count}
ghidra-rpc set-signature <binary> <target> <signature>	関数のシグネチャを設定します	{address, old_signature, new_signature, verified}
ghidra-rpc set-data-type <binary> <address> <type>	リスト表示にデータ型を定義します	{address, data_type, length, value}
ghidra-rpc retype-variable <binary> <func> <variable> <type> [--timeout SECS]	デコンパイラー変数の型を変更します	{function, variable, old_type, new_type, verified}
ghidra-rpc rename-variable <binary> <func> <variable> <new_name> [--timeout SECS]	デコンパイラー変数の名前を変更します	{function, variable, new_name, verified}
ghidra-rpc batch-edit-variable <binary> <func> --json |--json-file FILE [--timeout SECS]	1 つのデコンパイラースナップショットで複数のローカル変数の名前変更や型変更を行います。連続した個別編集で発生する自動名の再採番を回避できます。各操作：{variable|storage, new_name?, data_type?}（名前またはストレージ文字列で指定します。new_name/data_type の少なくとも一方が必要です）	{function, results:[{ok, index, variable, storage, old_name, new_name, old_type, new_type, verified}], count, ok_count, error_count, verified_count}
ghidra-rpc set-calling-convention <binary> <target> <convention>	関数の呼び出し規約を変更します	{address, name, old_convention, new_convention, verified}
ghidra-rpc set-thunk <binary> <thunk> <target>	関数をサンク（転送ラッパー）としてマークします	{thunk_address, thunk_name, target_address, target_name, verified}
ghidra-rpc set-flow-override <binary> <address> <override>	命令のフロー型（NONE/BRANCH/CALL/CALL_RETURN/RETURN）を上書きします	{address, override, old_override, verified}
ghidra-rpc get-processor-context <binary> <address> [--register REG]	ISA コンテキストのレジスター値を確認します（例：ARM の TMode）	{address, registers:{name:value}}
ghidra-rpc set-processor-context <binary> <address> <register> <value> [--end ADDR]	範囲内の ISA コンテキストレジスターを設定します。ARM Thumb の誤分類を修正できます	{address, end, register, value, verified}
ghidra-rpc create-namespace <binary> <name> [--parent NS]	名前空間を作成または検索します	{name, path, id, created}
ghidra-rpc list-namespaces <binary> [--limit N]	シンボル数とともにすべての名前空間を一覧表示します	{namespaces:[{name,path,id,type,symbol_count}], count}

コメント型：plate、pre、post、eol（デフォルト）、repeatable。 シグネチャ入力は自動的にサニタイズされます。末尾のセミコロンが削除され、空白がトリミングされ、インラインの呼び出し規約（__thiscall、__fastcall、 __stdcall、__cdecl、__vectorcall、__pascal）が文字列から抽出され、適切な Ghidra API を通じて適用されます。そのため、C のプロトタイプをそのまま貼り付けられます （例：void __thiscall Foo::Bar(int x); は手動で整形しなくても動作します）。

set-data-type、retype-variable、構造体フィールドの型で使用できる型式：

• 組み込み型：byte、char、int、uint、short、long、float、double、void、string、unicode
• ポインター：char *、void *、int **
• 配列：char[11]、int[4]
• プログラムのデータ型マネージャーに名前またはパスで登録されている任意の型：MyStruct、/POSIX/size_t

操作の順序 — ローカル変数に名前を付ける前に、シグネチャと型を設定してください。 set-signature、set-data-type、retype-variable、rename-variable はそれぞれデコンパイラーを再実行し、残りの自動命名されたローカル変数（uVar1、dVar2、…）の番号を振り直します。そのため、変数を1つずつ編集して連続して適用する方法は不安定です。dVar1 の名前を変更すると、以前の dVar2 が dVar1 になっている場合があります。先にシグネチャと this の型をすべて設定してからローカル変数に名前を付けるか、さらに良い方法として、batch-edit-variable を使って1回の呼び出しで、単一のデコンパイラーのスナップショットに対してすべての名前変更と型変更を適用してください（この方法では、変動する自動名ではなく、安定した storage 文字列で変数を指定することもできます）。

ブックマーク

コマンド	説明	出力形式
ghidra-rpc set-bookmark <binary> <address> [--type TYPE] [--category CAT] [--comment TEXT]	アドレスにブックマークを作成／更新します	{address, type, category, comment, action}
ghidra-rpc list-bookmarks <binary> [--type TYPE] [--category CAT] [--address ADDR] [--limit N]	ブックマークを一覧表示します（すべて、種類別、カテゴリ別、またはアドレス指定）	{bookmarks: [{address, type, category, comment}], count, total}
ghidra-rpc remove-bookmark <binary> <address> [--type TYPE] [--category CAT]	アドレスのブックマークを削除します	{address, type, removed}

ブックマークの種類：Note（デフォルト）、Warning、Error、Info、Analysis。

--category は大文字と小文字を区別しない部分一致フィルターです。自動解析が大量に行われたバイナリ（大規模なネイティブプログラム、特に DEX/Dalvik では、関数数が 50k 以上になるのは一般的です）では、Ghidra が Analysis タイプのブックマーク（多くの場合、カテゴリは Address Table）を大量に生成し、自分で作成した少数のブックマークが埋もれてしまうことがあります。フィルターなしの一覧をページ送りする代わりに、--category で絞り込むか、--type で自分のブックマークの種類（例：Note）だけに絞り込んでください。

ブックマークは Ghidra GUI の Bookmarks ウィンドウに表示されます。興味深い場所に永続的に印を付けたり、解析の進捗を追跡したり、人による確認が必要な調査結果にフラグを立てたりするために使用します。

関数タグ

コマンド	説明	出力形式
ghidra-rpc tag-function <binary> <target> --tag TAG	分類用のタグを関数に追加します	{address, name, tag, all_tags}
ghidra-rpc untag-function <binary> <target> --tag TAG	関数からタグを削除します	{address, name, tag, removed, all_tags}
ghidra-rpc list-tags <binary>	使用数とともに定義済みのタグをすべて一覧表示します	{tags:[{name,count}], count}
ghidra-rpc functions-by-tag <binary> --tag TAG [--limit N]	特定のタグが付いた関数を一覧表示します	{tag, functions:[{name,address,signature}], count, total}

タグは文字列ラベル（例：crypto、vuln-sink、analyzed、needs-review）で、Ghidra の Function Tags ウィンドウに表示されます。関数を分類し、解析の進捗を追跡するために使用します。

データ型の作成

コマンド	説明	出力形式
ghidra-rpc create-struct <binary> <name> TYPE FIELD [TYPE FIELD ...] [--if-not-exists|--or-replace]	名前付き構造体を作成します。--if-not-exists は冪等で、--or-replace は再構築します	{name, path, size, fields:[...], already_existed}
ghidra-rpc create-struct <binary> <name> --field OFFSET TYPE NAME [--field ...]	フィールドを明示的なバイトオフセットに配置した構造体を作成します（OFFSET は 10 進数または 0x 形式の 16 進数です）。フィールド間の隙間には未定義バイトが自動的にパディングされます（手動でパディングフィールドを指定する必要はありません）。重複は拒否されます。	{name, path, size, fields:[...], already_existed}
ghidra-rpc create-union <binary> <name> TYPE FIELD [TYPE FIELD ...] [--if-not-exists|--or-replace]	名前付き共用体を作成します。すべてのフィールドはオフセット 0 を共有します	{name, path, size, fields:[...], already_existed}
ghidra-rpc modify-struct <binary> <struct_name> --field-offset N|--field-name NAME [--new-type TYPE] [--new-name NAME]	構造体フィールドの型を変更、名前を変更、またはコメントを変更します	{name, path, size, fields:[...], modified_field:{...}}
ghidra-rpc clear-data-range <binary> <start> <end>	包含範囲のバイトを未定義にリセットします	{start, end, cleared}
ghidra-rpc apply-data-type-range <binary> <start> <end> <type> [--clear]	包含範囲に型を繰り返し適用します。--clear を指定すると、適用前に範囲をアトミックにクリアします	{start, end, data_type, type_size, applied_count, cleared}
ghidra-rpc list-labels <binary> <address> [--end ADDR] [--limit N]	アドレスまたは範囲内のシンボルを、それぞれの位置のデータ型とともに一覧表示します	{labels:[{address,name,type,source,is_primary,data_type,data_length}], count, total}
ghidra-rpc create-enum <binary> <name> NAME VAL [NAME VAL ...] [--size 1|2|4|8] [--if-not-exists|--or-replace]	DTM に名前付き列挙型を作成します	{name, path, size, values:[{name,value}], already_existed}
ghidra-rpc modify-enum <binary> <name> [--add NAME:VAL ...] [--remove NAME ...]	既存の列挙型に個別のエントリーを追加または削除します	{name, path, size, values:[{name,value}]}
ghidra-rpc set-equate <binary> <addr> <equate_name> <value> [--operand-index N] [--enum-path PATH]	名前付きスカラー定数を命令オペランドに関連付けます。該当する列挙型が見つかった場合は自動的にリンクします	{address, operand_index, equate_name, value, enum_linked, verified}
ghidra-rpc list-equates <binary> [address] [--limit N]	プログラム内のすべての等値定義、または指定したアドレスに適用された等値定義のみを一覧表示します	{equates:[{name,value[,operand_index,address]}], count, total}
ghidra-rpc list-data-types <binary> [--category CAT] [--query SUBSTR] [--limit N]	DTM 内の型を一覧表示します。カテゴリ：struct、enum、union、typedef、pointer、array、all	{data_types:[{name,path,category,size}], count, total}

バージョンの追跡と差分

コマンド	説明	出力形式
ghidra-rpc version-track <old> <new> [--changed-only] [--limit N] [--min-similarity F]	2つのバージョン間で関数を照合し、変更点を特定します。結果はソース関数ごとに重複を除去します。	{matched:[{source_name,destination_name,similarity,confidence,correlator}], unmatched_source, unmatched_destination, summary:{source_functions_total, changed_functions, identical_functions, ...}}
ghidra-rpc function-diff <bin1> <func1> <bin2> <func2> [--mode decompile|disassembly]	2つのバージョン間の関数の統合差分です。自動生成された名前（FUN_*、DAT_*、local_*、param_*）を正規化して、再配置によるノイズを抑制します。	{is_identical, diff, raw_code1, raw_code2, func1_address, func2_address}
ghidra-rpc match-function <bin1> <func> <bin2> [--threshold F]	BSim とコリレーターを使用して、別のバイナリ内で関数の最適な一致候補を検索します。	{source:{name,address}, candidates:[{name,address,similarity,confidence,correlator}], count}
ghidra-rpc decompile-all <binary> [--limit N] [--offset N] [--timeout SECS] [--socket-timeout SECS]	すべての関数を一括で逆コンパイルします。エクスポートや外部差分ツールで使用します。	{functions:[{name,address,signature,c_code}], count, total, offset, errors}

decompile-all のデフォルトの --socket-timeout（1800s）は、一括処理に個々の関数の --timeout より はるかに長い時間がかかる場合があることを想定しています。数万件の関数を含むバイナリ（大規模な DEX/APK プログラムなど）では、さらに長い値を設定してください。

パッチ差分のワークフロー全体については、docs/flows/patch-analysis.md を参照してください。

エラー処理

エラーレスポンスの形式は次のとおりです。

{"id": "...", "ok": false, "error": "FunctionNotFound", "message": "Function 'foo' not found."}

よくあるエラー：

• DaemonNotRunning：デーモンが起動していません。ユーザーに ghidra-rpc start を実行するよう伝えてください。
• ValueError：引数が不正です（名前が曖昧、アドレスが無効など）。メッセージには通常、より具体的な名前やアドレスを使用するなど、対処方法が示されています。
• RuntimeError：Ghidra レベルのエラーです。ヘッドレスモードで GUI 専用コマンドを実行した場合は、その旨がエラーに明示されます。

使用法エラーも含め、すべての CLI 出力は JSON です。 不正な呼び出し（不明なオプション、無効な --type の選択肢、不明なサブコマンド、必須引数の不足）も、標準出力に {"ok": false, "error": "...", "message": "..."} として報告され、終了コードはゼロ以外になります。プレーンテキストの Click 使用法メッセージが出力されることはありません。スクリプトから呼び出す場合は、引数エラーを個別に処理する必要はなく、常に標準出力に対して json.loads() を実行できます。

書き込み操作と永続化

書き込み操作（rename、create-label、create-function、delete-function、set-comment、batch-rename、batch-set-comment、set-signature、set-data-type、retype-variable、rename-variable、batch-edit-variable、set-calling-convention、set-thunk、set-flow-override、set-processor-context、create-struct、create-union、modify-struct、create-enum、modify-enum、set-equate、set-bookmark、clear-data-range、apply-data-type-range、write-bytes、assemble、tag-function、untag-function、create-namespace） では、内部的に Ghidra のトランザクションを使用します。**すべての書き込みは、トランザクションのコミット後にプロジェクトデータベースへ自動的に保存されます。**そのため、変更はデーモンの再起動後も保持され、Ghidra GUI でプロジェクトを再度開いたときにも反映されます。

すべての書き込みレスポンスには、コミット後に変更を正常に読み戻せたかを示す verified ブール値が含まれます。

必要に応じて、いつでも明示的に保存することもできます。

ghidra-rpc save              # saves all loaded programs
ghidra-rpc save <binary>     # saves one program

正常に終了した場合（stop または Ctrl+C）、すべてのプログラムが自動的に保存されます。

パッチ／差分分析のクイックスタート

# 1. Load both versions
ghidra-rpc load /path/to/binary_v1 -p project.gpr
ghidra-rpc load /path/to/binary_v2 -p project.gpr

# 2. Find changed functions (summary counts all changes; matched list is filtered)
ghidra-rpc version-track binary_v1 binary_v2 --changed-only

# 3. Diff a specific changed function
ghidra-rpc function-diff binary_v1 <func> binary_v2 <func>

ワークフロー全体（コリレーターの詳細、一致しなかった項目の分析、一括逆コンパイル）については、 docs/flows/patch-analysis.md を参照してください。

Android APK / DEX の解析

Ghidra は APK と DEX を標準でサポートしています（Dalvik プロセッサーと FileFormats ローダー）。拡張機能のインストールは不要です。.dex または .apk を直接 load すれば、通常のコマンド（decompile、functions、strings、xrefs-*、…）を Dalvik プログラムに対して実行でき、Java のような疑似コードに逆コンパイルされます。複数 DEX に関する注意点として、load app.apk でインポートされるのはプライマリの classes.dex のみです。

ワークフロー全体（複数 DEX の抽出、クラス修飾付きの :: シンボルと曖昧なメソッド、DEX の文字列と xrefs-to に関する注意点、難読化されたアプリ、マニフェスト／.so の抽出）については、docs/flows/android-apk.md を参照してください。

一般的なワークフロー

1. ユーザーがデーモンを起動します：cd <skill-dir> && uv run ghidra-rpc start --project /path/to/project.gpr --headless 自動化やブロックしない起動の場合：uv run ghidra-rpc start --project /path/to/project.gpr --headless --detach
2. バイナリをロードします：uv run ghidra-rpc load /path/to/binary -p /path/to/project.gpr レスポンスには short_name が含まれます（以降のすべてのコマンドでエイリアスとして使用できます）。 （分析をスキップするには --no-analyze を追加し、分析時間を制限するには --analysis-timeout SECS を追加します）
3. 概要を取得します：metadata、functions、imports、exports
4. 調査します：興味のある関数には decompile を、呼び出し元をたどるには xrefs-to を使います
5. 注釈を付けます：調査結果を記録するには rename-function、set-comment を使います
6. 検索します：ハードコードされた値には strings、特定のパターンには symbols を使います

FAQ／よくある注意点

create-label は DEFAULT（自動分析）シンボルを適切に置き換えます： create-label は USER_DEFINED ラベルを作成し、そのアドレスのプライマリシンボルに設定します。DEFAULT シンボル（例：DAT_00418138）がすでに存在する場合は、セカンダリに降格されます。その後、デコンパイラーは新しい名前を使用します。rename-symbol は既存のシンボルが必要で、その場で名前を変更します。既存のシンボルの有無にかかわらずアドレスに注釈を付ける場合は、create-label を推奨します。

既存のシンボルがないアドレスに注釈を付ける場合（rename-symbol が「No symbol found」で失敗する場合）： rename-symbol では、アドレスにシンボルがすでに存在している必要があります。自動分析で DAT_ シンボルが設定されるのは、データが検出された場所のみです。配列内や密な構造体領域では、多くのアドレスにシンボルがありません。代わりに create-label を使ってください。シンボルがなければ新しい USER_DEFINED ラベルを作成し、あれば既存のものの名前を変更します：

ghidra-rpc create-label <binary> 0x0040e4ac topPtrErrorMsg

同じ upsert の動作をさせるには、rename-symbol に --create を追加することもできます。

メモリー領域全体で構造体を定義して適用する場合： 繰り返しデータテーブル全体に構造体を適用するワークフロー：

# 1. Create the struct type in the DTM (--if-not-exists makes the call idempotent)
ghidra-rpc create-struct binary ErrorEntry int errorNumber "char *" ptrErrorMsg --if-not-exists

# 2. Stamp the struct across the range with --clear to atomically clear + apply
#    (23 × 8-byte ErrorEntry structs, both endpoints inclusive)
ghidra-rpc apply-data-type-range binary 0x0040e4a8 0x0040e55f ErrorEntry --clear

これにより、各アドレス 0x0040e4a8、0x0040e4b0、… の型が ErrorEntry になります。--clear を指定しない場合、apply-data-type-range は既存データと競合する位置をスキップし、それらを errors リストに報告します。クリアする領域をより細かく制御する必要がある場合は、先に clear-data-range を使ってください。

アドレスまたは範囲に存在するラベルを確認する場合：

# Single address
ghidra-rpc list-labels binary 0x0040e4a8

# Range
ghidra-rpc list-labels binary 0x0040e4a8 --end 0x0040e55f --limit 50

load 後にバイナリ名を使う場合： load は、ハッシュ接尾辞付きの完全なキー（binary）と、元のファイル名である short_name の両方を返します。以降のすべてのコマンドで short_name を使用してください。コマンドはバイナリ名の部分文字列に一致するため、これを使用できます：

# Load response: {"binary": "/WinHelloCPP.exe-85cbcc", "short_name": "WinHelloCPP.exe", ...}
ghidra-rpc decompile WinHelloCPP.exe main        # short_name works
ghidra-rpc decompile WinHelloCPP main            # even without extension, if unambiguous

同じステム名を持つバイナリが2つある場合は、完全なキーを使って区別してください。

シグネチャ末尾のセミコロン：Ghidra のパーサーは、末尾に ; が付いた C プロトタイプを拒否します。ghidra-rpc は末尾のセミコロンを自動的に削除するため、コードをそのまま貼り付けられます。

バイナリをロードしたのに list-binaries が空の場合：GUI モードでは、バイナリを CodeBrowser で開く必要があります。プロジェクトリポジトリに保存されているものを確認するには list-project-programs を使い、その後 CodeBrowser の Project ウィンドウで開いてください。 デーモンのログファイル：バックグラウンドで起動した場合（start --detach または restart）、ログは /tmp/ghidra-rpc-<hash>.log に書き込まれます。デーモンのエンドポイントと同じディレクトリ、同じファイル名のため、Windows では %LOCALAPPDATA%\ghidra-rpc\ghidra-rpc-<hash>.log になります。デーモンの起動に失敗したり、応答可能にならなかったりした場合は、まずこのファイルを確認してください。

tail -50 /tmp/ghidra-rpc-*.log

タイムアウトエラーメッセージには、すべてのプラットフォームで常に正確なログのパスが表示されます。

バックグラウンド化後に GHIDRA_INSTALL_DIR が見つからない：デーモン化（nohup、cron、systemd ユニットなど）の際に、環境変数が失われる場合があります。推奨順に、次の方法をお試しください。

1. start または restart に --ghidra-install-dir /path/to/ghidra を渡します。この値はセッションファイルに保存され、その後の再起動にも自動的に引き継がれます。
2. ログインセッションをまたいで設定が保持されるよう、シェルプロファイル（~/.bashrc、~/.zshrc）で GHIDRA_INSTALL_DIR をエクスポートします。
3. 環境変数が設定されている同じターミナルから start --detach --headless を使用します。

セッションファイルの場所：デフォルトでは、セッションファイル（.ghidra-rpc-<hash>.json）は .gpr プロジェクトファイルと同じ場所に書き込まれ、すべての状態が1か所にまとまります。カスタムディレクトリ（共有場所やRAMディスクなど）を使用するには、GHIDRA_RPC_STATE_DIR を設定します。

export GHIDRA_RPC_STATE_DIR=/tmp/ghidra-sessions

Ghidra GUI に変更が表示されない：File → Open からバイナリを直接開くのではなく、プロジェクトのコピー（Project ウィンドウの basic_code-501243 など）を開いていることを確認してください。また、同じプロジェクトに対して別々の Ghidra インスタンスを2つ実行していないことも確認してください（ロックの競合が発生します）。ghidra-rpc による変更は自動的にディスクに保存され、次回 GUI でプログラムを開いたときに表示されます。

以前のセッションがない状態での restart：以前の start がなくても restart で新しいヘッドレスセッションを作成できるように、--headless を渡してください。

特定の関数でのデコンパイラーのタイムアウト：一部の関数では、アセンブリが単純でも、デコンパイラーの処理負荷が高い分析経路が実行され、タイムアウトすることがあります。処理が難しい関数には decompile --timeout 300（またはそれ以上）を使用してください。デフォルトのタイムアウトは 120 s です（大きなファームウェア関数に対応するため、60 s から延長されています）。retype-variable コマンドと rename-variable コマンドも、内部でデコンパイル処理を実行するため、--timeout を受け付けます。

decompile で不正な命令の警告が返る場合は、代わりに pcode --high を使用します： decompile の出力に "Bad instruction data" のようなメッセージが含まれる場合や、関数本体のデコードに失敗する場合（自動解析でデータと誤分類された領域の ARM Thumb コードでよく発生します）は、代わりに pcode --high を試してください。

ghidra-rpc pcode binary 0x03288102 --high

P-code エンジンは、リスティングレベルの逆アセンブラーではなく、関数オブジェクトのコンテキストからバイトを再デコードするため、decompile が失敗する場合でも成功することがよくあります。High P-code では、すべての CALL／CALLIND／BRANCHIND のターゲットとデータフローも確認できるため、デコンパイルが正常に行えない場合でも、引数を追跡するのに役立ちます。set-processor-context（下記参照）を使って根本原因を修正してください。

disassemble が誤ったアドレスから開始する（B2 の警告）： disassemble が命令のないアドレス（命令の途中のアドレスや未定義のアドレスなど）で呼び出された場合、レスポンスに、次に利用可能な命令から逆アセンブルが開始されたことを示す warning フィールドが含まれるようになりました。リスティングが正しくないように見える場合は、JSON レスポンスの warning を確認してください。

ARM Thumb の誤分類には set-processor-context を使用します（F1/F5）： ARM の自動解析で Thumb コードがデータに分類されると、リスティングの逆アセンブラーは32ビット ARM（TMode=0）としてデコードし、無意味な結果を生成します。完全な復旧手順は次のとおりです。

# 1. Diagnose: check TMode at the affected address
ghidra-rpc get-processor-context binary 0x03288100 --register TMode
# Expected: {"TMode": 0}  ← this is the problem

# 2. Clear the bad data/code classification
ghidra-rpc clear-data-range binary 0x03288100 0x032883ff

# 3. Set Thumb mode for the range
ghidra-rpc set-processor-context binary 0x03288100 TMode 1 --end 0x032883ff

# 4. Verify disassembly now shows Thumb-2 instructions
ghidra-rpc disassemble binary 0x03288100 --count 20

# 5. Re-create the function
ghidra-rpc create-function binary 0x03288100

アドレスに不正なスタブが残っているため create-function に失敗する場合は、まず delete-function を使って削除してください。

不正なスタブが関数の再作成を妨げる場合は delete-function を使用します（F2）： create-function 0x03288103（誤った偶奇アドレス）によってスタブが残り、その後 create-function 0x03288102（正しいアドレス）が "already exists at overlapping address" というエラーで失敗する場合は、先に不正なスタブを削除してください。

ghidra-rpc delete-function binary 0x03288103
ghidra-rpc create-function  binary 0x03288102

40 以上の関数をラウンドトリップのオーバーヘッドなしで一括リネーム／コメント（F7）： batch-rename と batch-set-comment を使用すると、1 回のサーバーラウンドトリップと Ghidra トランザクションで多数の注釈を適用できます。

# Rename functions from a JSON file
ghidra-rpc batch-rename binary --json-file renames.json

# Or inline
ghidra-rpc batch-rename binary --json \
  '[{"target":"sub_401234","new_name":"init_uart"},{"target":"0x400200","new_name":"isr_handler"}]'

# Label-mode (symbol/label rename by address)
ghidra-rpc batch-rename binary --mode label --json \
  '[{"address":"0x0333afcc","new_name":"g_debugStr"}]'

# Batch comments
ghidra-rpc batch-set-comment binary --json \
  '[{"address":"0x03288102","comment":"Thumb ISR entry","comment_type":"plate"}]'

成功したすべての項目は 1 つのトランザクションでコミットされます。失敗した項目は results[].ok=false として個別に報告され、成功した項目はロールバックされません。

書き込み操作は同時実行されず、順番に処理されます：Ghidra のトランザクション競合を防ぐため、デーモンはすべてのコマンドハンドラーの呼び出しを内部で順番に処理します。書き込みコマンドを外部で順番に実行する必要はありません。並列の書き込みは自動的にキューに入れられます。これは同時実行より少し遅くなりますが、サイレントな部分的失敗を防げます。

バグや不足している機能の報告

ghidra-rpc の使用中に、バグ、エラー、または機能の不足に遭遇することがあります。ぜひ報告してください。実際の使用状況が継続的な改善につながります。

問題が発生した分析セッションの最後に、簡単なレポートを保存してください。

cat > /tmp/ghidra-rpc-issues-$(date +%Y%m%d-%H%M%S).md << 'EOF'
## ghidra-rpc Issue Report

**Date:** $(date)
**Binary:** <name of binary analysed>

### Bugs encountered


### Missing features


### Suggestions

EOF

その後、ユーザーに次のように伝えてください。

「ghidra-rpc の問題レポートを /tmp/ghidra-rpc-issues-<timestamp>.md に保存しました。 提出する場合は、cat /tmp/ghidra-rpc-issues-*.md を実行してください。」

レポートは /tmp に書き込まれるため、マシン上にのみ保存され、再起動時に失われます。自動的にどこかへ送信されることはありません。Windows では代わりに %TEMP% に書き込んでください。上記のスニペットは bash 用のため、実際に使用しているシェルに合わせて調整してください。

詳細ドキュメント

特定のワークフローの詳しいガイダンスについては、以下を参照してください。

• インストールとセットアップ：docs/install.md を参照してください
• クイックスタートチュートリアル：docs/quickstart.md を参照してください
• トラブルシューティング：docs/troubleshooting.md を参照してください
• バイナリー監査ワークフロー：docs/flows/binary-audit.md を参照してください
• 脆弱性調査：docs/flows/vulnerability-research.md を参照してください
• パッチ／差分分析：docs/flows/patch-analysis.md を参照してください
• Android APK／DEX 分析：docs/flows/android-apk.md を参照してください