ghidra-cli

ghidra-cli エージェントリファレンス

Ghidra のリバースエンジニアリング用 Rust CLI です。バイナリ名：ghidra。

アーキテクチャ

CLI (Rust/clap) ──TCP──► GhidraCliBridge.java (GhidraScript in Ghidra JVM)

• ダイレクトブリッジ：デーモンプロセスはありません。Java ブリッジ自体が常駐サーバーです。
• プロジェクトごとにブリッジを 1 つ起動し、~/.local/share/ghidra-cli/bridge-{md5}.port をキーとして識別します
• Import／Analyze／query コマンドは、ブリッジが起動していない場合に自動起動します
• コマンドは順次処理されます（Ghidra API はスレッドセーフではありません）

グローバルフラグ

フラグ	効果
--json	コンパクトな JSON 出力（1 行）
--pretty	整形された JSON
--project P / --program PROG	対象のプロジェクト／プログラム。グローバルなので、サブコマンドより前に指定できます
--projects-dir DIR	Ghidra プロジェクトの保存先（ghidra_project_dir を上書き）
--java-home PATH	Ghidra 用の JDK の完全なパス（自動検出を上書き）
-v / -vv / -vvv	ログの詳細度：warn／info／debug
-q / --quiet	必須ではない stderr 出力を抑制します

すべてのフラグはグローバルなので、ghidra --project P --program bin function list は、サブコマンドの後に指定した場合と同じように動作します。

出力形式の自動検出：TTY → コンパクトで読みやすい形式、パイプ → json-compact です。--json、--pretty、または -o FORMAT で上書きできます。

Ghidra 12.1 以降では、ドットで始まるコンポーネント（例：~/.cache）を含むプロジェクトディレクトリは拒否されます。Linux では、デフォルトで ~/ghidra-cli-projects にフォールバックします。--projects-dir で上書きできます。

クイックスタート

# Fastest path: import runs auto-analysis automatically; bridge starts on demand
ghidra import ./binary --project myproject

# All subsequent queries reuse the running bridge
ghidra function list --project myproject
ghidra decompile main --project myproject

コマンドリファレンス

ブリッジのライフサイクル

ghidra start [--project P] [--program PROG]
ghidra stop [--project P]
ghidra restart [--project P] [--program PROG]
ghidra status [--project P]
ghidra ping [--project P]
ghidra jobs [JOB_ID] [--project P]      # bridge queue + recent jobs, or one job by ID
ghidra cancel [JOB_ID] [--project P]    # cooperatively cancel active (or given) job

ping、status、jobs、cancel は、制御プレーンで即座に応答します。プログラムジョブは次のレーンで実行されます：read（低コストの読み取り。並行実行）、read-heavy（逆コンパイル／検索／グラフ／統計／script run --read-only。並行実行しますが、プールサイズ − 1 に制限）、exclusive（書き込み、開く／閉じる、解析、インポート、通常の script run）。ghidra jobs は各ジョブの lane、queue_position、blocked_by と、abandoned ジョブ（クライアントが切断されたため、スキップまたはキャンセルされたジョブ）を表示します。読み取りプールのサイズは GHIDRA_CLI_READ_THREADS で指定します（デフォルトは min(8, cores/2)、0 はすべてを排他的に実行）。CLI はブリッジを自動再起動しません。ブリッジが CLI より古い場合は、ほかのクライアントが使用していないときに ghidra restart を実行してください。

プロジェクト管理

ghidra project create NAME
ghidra project list
ghidra project info [NAME]
ghidra project delete NAME

インポートと解析

ghidra import BINARY [--project P] [--program PROG] [--no-analyze] [--detach]
ghidra analyze [--project P] [--program PROG] [--detach]

どちらのコマンドもブリッジを自動起動します。ghidra import はデフォルトで自動解析を実行し（プログラムを永続化します）、解析せずに生の状態でインポートするには --no-analyze を指定します。 --detach は即座に制御を返します。

プログラム管理

ghidra program list [--project P]          # alias: prog, programs
ghidra program open --program PROG [--project P]   # --program required by runtime
ghidra program close [--project P]
ghidra program delete --program PROG [--project P]
ghidra program info [--project P]
ghidra program export FORMAT [--project P] [-o OUTPUT]   # FORMAT: json, xml, c/cpp, binary/bin, gzf, ascii/asm, hex, html

関数操作

ghidra function list [QUERY_OPTS]           # aliases: fn, func, functions
ghidra function get TARGET [QUERY_OPTS]     # TARGET = name or 0xADDRESS
ghidra function decompile TARGET [--with-vars] [--with-params] [QUERY_OPTS]
ghidra function disasm TARGET [QUERY_OPTS]   # whole body; --limit N (default 1000, 0 = all); truncation warned on stderr
ghidra function calls TARGET [QUERY_OPTS]   # outgoing calls
ghidra function xrefs TARGET [QUERY_OPTS]   # incoming references
ghidra function rename OLD NEW [--project P] [--program PROG]
ghidra function create ADDRESS [NAME] [--project P] [--program PROG]
ghidra function delete TARGET [QUERY_OPTS]
ghidra function set-signature TARGET --signature "int foo(int x, char *y)" [--project P] [--program PROG]
ghidra function set-return-type TARGET --type TYPE [--project P] [--program PROG]
ghidra function set-calling-convention TARGET --convention CC [--project P] [--program PROG]
ghidra function set-var-type TARGET --var VARNAME --type TYPE [--project P] [--program PROG]

トップレベルのショートカット

ghidra decompile TARGET [--with-vars] [--with-params] [QUERY_OPTS]   # aliases: decomp, dec
ghidra disasm TARGET [-n COUNT] [QUERY_OPTS]   # TARGET = name or 0xADDRESS; aliases: disassemble, dis

--with-vars を指定すると、ローカル変数の詳細（名前、型、ストレージ）が応答に含まれます。 --with-params を指定すると、パラメーターの詳細（名前、型、ストレージ）が応答に含まれます。 どちらのフラグも、逆コンパイルされた C コードに構造化データを追加します。出力全体を確認するには --json を使用してください。

文字列操作

ghidra strings list [QUERY_OPTS]            # aliases: string, str
ghidra strings refs STRING [QUERY_OPTS]     # xrefs to string

シンボル操作

ghidra symbol list [QUERY_OPTS]             # aliases: sym, symbols
ghidra symbol get NAME [QUERY_OPTS]
ghidra symbol create ADDRESS NAME [--project P] [--program PROG]
ghidra symbol delete NAME [QUERY_OPTS]
ghidra symbol rename OLD NEW [--project P] [--program PROG]

メモリ操作

ghidra memory map [QUERY_OPTS]              # alias: mem
ghidra memory read ADDRESS SIZE [QUERY_OPTS]
ghidra memory write ADDRESS BYTES [--project P] [--program PROG]
ghidra memory search PATTERN [QUERY_OPTS]

クロスリファレンス

ghidra x-ref to ADDRESS [QUERY_OPTS]        # aliases: xref, xrefs, crossref
ghidra x-ref from ADDRESS [QUERY_OPTS]
ghidra x-ref list TARGET [QUERY_OPTS]   # refs both to and from the target

x-ref list は対象（名前、0xADDR、または FUN_<hex>）を受け取り、双方向の参照を返します。対象が関数の場合、「from」側はエントリだけでなく、関数本体全体をスキャンします。

型操作

ghidra type list [QUERY_OPTS]               # alias: types  (includes "kind" field: struct/union/enum/typedef/pointer/array/other)
ghidra type get NAME [QUERY_OPTS]           # shows struct fields, enum members, typedef base type, kind
ghidra type create DEFINITION [--project P] [--program PROG]        # create empty struct
ghidra type apply ADDRESS TYPE_NAME [--project P] [--program PROG]
ghidra type delete NAME [--project P] [--program PROG]              # alias: rm
ghidra type rename OLD NEW [--project P] [--program PROG]           # alias: mv
ghidra type create-enum NAME --values "A=0,B=1,C=2" [--size 4] [--project P] [--program PROG]
ghidra type typedef NAME BASE_TYPE [--project P] [--program PROG]   # create type alias
ghidra type add-field STRUCT_NAME --name FIELD --type TYPE [--offset N] [--size N] [--project P] [--program PROG]
ghidra type del-field STRUCT_NAME --name FIELD [--project P] [--program PROG]

タグ操作

関数タグは、大規模なコードベースを整理するための機能です。名前とプログラムスコープを持ち、任意のコメントを付けられるラベルで、任意の数の関数に付与できます。

ghidra tag list [--function TARGET] [QUERY_OPTS]   # alias: tags — all tags (name, comment, use_count), or one function's tags
ghidra tag get NAME [QUERY_OPTS]                   # alias: show — member functions of a tag (rows: name, address)
ghidra tag create NAME [--comment TEXT] [--project P] [--program PROG]
ghidra tag delete NAME [--project P] [--program PROG]                  # alias: rm — detaches from ALL functions; reports use_count + functions_affected
ghidra tag rename OLD NEW [--project P] [--program PROG]               # alias: mv — global; errors if NEW exists (no implicit merge)
ghidra tag set-comment NAME COMMENT [--project P] [--program PROG]     # "" clears
ghidra tag add TARGET TAG... [--no-create] [--project P] [--program PROG]    # auto-creates missing tags; reports added/created/already_present
ghidra tag remove TARGET TAG... [--project P] [--program PROG]         # reports removed/not_present; idempotent
ghidra tag remove TARGET --all [--project P] [--program PROG]          # detach every tag
ghidra function list --tag NAME [--tag NAME2] [QUERY_OPTS]             # server-side filter; multiple --tag = AND
ghidra function list --untagged [QUERY_OPTS]                           # functions with no tags (triage complement)

エージェントが把握しておくべきセマンティクス：

• タグ名は大文字と小文字を区別します（Crypto ≠ crypto）。不明なタグのエラーには Did you mean ...? のヒントが含まれ、終了コードは非ゼロです。推測を繰り返すループでは、まず ghidra tag list を確認するか（または --filter を使用してください）。一致するものがない --filter は、空の出力で終了コード 0 を返します。不明な --tag は終了コードが非ゼロになります。
• tag add／remove は冪等です。タグがすでに付与されている場合や存在しない場合も、エラーにはならず、レスポンスでその旨が報告されます。安全に再試行できます。
• 関数の行（function list／get）には、ソート済みの tags 配列が含まれます（空の場合も常に存在します）。そのため、--fields name,address,tags と --filter "tags ~ 'crypto'" を使用できます。DSL の ~／^／$／=~／in はタグに対して大文字と小文字を区別しませんが、=／!= は完全一致です。CSV 出力では、タグ配列は ; で連結されます。
• 名前を空にしたり、, や ; を含めたりすることはできません（作成時に拒否されます。ただし、Ghidra GUI で作成された特殊な名前は、引き続き付与、削除、消去できます）。
• 空白を含む名前は使用できますが、ghidra batch ファイルでは使用できません（空白でトークン化され、引用符で囲む機能はありません）。
• 外部関数は、タグのメンバーシップ操作の対象外です。Ghidra GUI で外部関数にタグを付与すると、tag list の use_count が tag get のメンバー数より大きくなる場合があります。

エージェントの一般的なワークフロー：

# Define a taxonomy (comments document meaning for future sessions)
ghidra tag create crypto --comment "Key schedule, cipher rounds, RNG"
ghidra tag create reviewed --comment "Decompiled and understood"

# Triage and tag
ghidra tag add FUN_00401a20 crypto
ghidra tag add aes_key_expand crypto reviewed

# Bulk via batch (one process, one bridge connection; bare tag names only)
printf 'tag add FUN_00402000 network\ntag add parse_packet network reviewed\n' > triage.batch
ghidra batch triage.batch

# Drive the next pass off the taxonomy
ghidra tag list                              # names, comments, use counts
ghidra tag get network                       # member functions (rows)
ghidra function list --tag network --filter "size > 200" --fields name,address,tags
ghidra function list --untagged --limit 20   # what's left to triage
ghidra tag remove parse_packet wip

コメント操作

ghidra comment list [QUERY_OPTS]            # alias: comments
ghidra comment get ADDRESS [QUERY_OPTS]
ghidra comment set ADDRESS TEXT [--comment-type TYPE] [--project P] [--program PROG]
ghidra comment delete ADDRESS [QUERY_OPTS]

--comment-type には、EOL（デフォルト）、PRE、POST、PLATE を指定します。

検索／検索結果の取得

ghidra find string PATTERN [QUERY_OPTS]     # alias: search
ghidra find bytes HEX [QUERY_OPTS]
ghidra find function PATTERN [QUERY_OPTS]   # glob patterns
ghidra find calls FUNCTION [QUERY_OPTS]
ghidra find crypto [QUERY_OPTS]             # detect AES/SHA/RSA constants
ghidra find interesting [QUERY_OPTS]        # suspicious patterns

グラフ／コールグラフ

ghidra graph calls [QUERY_OPTS]             # aliases: callgraph, cg
ghidra graph callers FUNCTION [--depth N] [QUERY_OPTS]
ghidra graph callees FUNCTION [--depth N] [QUERY_OPTS]
ghidra graph export FORMAT [QUERY_OPTS]     # FORMAT: dot, json

差分

ghidra diff programs PROG1 PROG2 [--project P] [--format F]
ghidra diff functions FUNC1 FUNC2 [--project P] [--format F]

ダンプ／エクスポート

ghidra dump imports [QUERY_OPTS]            # alias: export
ghidra dump exports [QUERY_OPTS]
ghidra dump functions [QUERY_OPTS]
ghidra dump strings [QUERY_OPTS]

パッチ

ghidra patch bytes ADDRESS HEX [--project P] [--program PROG]
ghidra patch nop ADDRESS [--count N] [--project P] [--program PROG]
ghidra patch export -o OUTPUT [--project P] [--program PROG]

--count N は、ADDRESS から連続する N 個の命令を NOP 化します（デフォルトは 1）。命令ごとに順に処理します。対象範囲内のいずれかのアドレスに命令がない場合、パッチ全体がロールバックされます。

スクリプト実行

ghidra script run PATH [--read-only] [--expect PATH[:MIN_ROWS]]... [--allow-empty] [--project P] [--program PROG] [-- ARGS...]
ghidra script python CODE   # NOT supported in bridge mode; use script run
ghidra script java CODE     # NOT supported in bridge mode; use script run
ghidra script list

script run は PATH を絶対パスに解決し、-- の後の引数を実際の位置引数としてスクリプトに渡し、標準出力をレスポンス（{script, path, stdout, args}）に取り込みます。--expect PATH[:MIN_ROWS]（繰り返し指定可能）を指定すると、成果物が存在しない、空である、または MIN_ROWS 未満の場合にジョブが失敗します。--allow-empty を指定すると、期待する成果物が空でも存在を許可します。スクリプトは排他的に実行され、キャンセルできます（ghidra cancel）。--read-only を指定すると、ほかの読み取り処理と並行してスクリプトを実行します。プログラムの変更番号が変わった場合、スクリプトは read_only_violation で失敗します。コンパイルエラーが発生した場合は、javac の診断を伴って失敗します（script_compile_error）。

バッチ

ghidra batch SCRIPT_FILE [--project P] [--program PROG]

バッチファイルでは、1 行に 1 つのサブコマンドを記述します（ghidra プレフィックスは付けません）。# はコメントです。

ユニバーサルクエリ

ghidra query DATA_TYPE [QUERY_OPTS]

DATA_TYPE：functions、strings、imports、exports、memory。

統計と情報

ghidra summary [QUERY_OPTS]       # alias: info
ghidra stats [QUERY_OPTS]

設定

ghidra init                       # create config
ghidra doctor                     # check installation
ghidra version
ghidra config list
ghidra config get KEY
ghidra config set KEY VALUE       # keys: ghidra_install_dir, ghidra_project_dir, default_program, default_project, default_output_format, default_limit, launch_timeout_secs
ghidra config reset
ghidra set-default KIND VALUE     # KIND: program, project
ghidra setup [--version V] [--dir D] [--force]

ブリッジの待機時間は環境変数で制御します。通常のコマンドには GHIDRA_CLI_READ_TIMEOUT、analyze／import には GHIDRA_CLI_OP_TIMEOUT、接続の確立には GHIDRA_CLI_CONNECT_DEADLINE を使用します。古いファイルを読み込む際、従来の設定キー timeout は無視され、config set では拒否されます。

共通のクエリオプション（QUERY_OPTS）

すべてのクエリコマンドで、次のオプションを使用できます：

オプション	説明
--project P	プロジェクト名またはパス
--program PROG	プロジェクト内のプログラム
--filter EXPR	フィルター式
--fields LIST	返すフィールド（カンマ区切り）
-o FORMAT	出力形式
--limit N	最大結果数
--offset N	先頭からスキップする件数
--sort FIELDS	ソート：カンマ区切り。降順にするには先頭に - を付けます
--count	件数のみを返す
--json	--format=json の省略形

出力形式

値	用途
compact	TTY のデフォルト。項目ごとに 1 行で表示します。
full	ラベル付きの複数行ブロック
json	整形済み JSON
json-compact	パイプのデフォルト。1 行の JSON。
json-stream / ndjson	1 行ごとに JSON オブジェクトを表示します。
csv / tsv	ヘッダー付きの区切り形式
table	ASCII 罫線の表
count	数値のみ
ids / minimal	アドレス／名前のみを 1 行ごとに表示します。
tree	インデント付きの階層
hex	16 進数ダンプ
asm	アセンブリ
c	C 風の擬似コード

フィルター式

# Numeric
--filter "size > 100"
--filter "size >= 50"

# String
--filter "name ~ 'crypt'"

# Combined
--filter "size > 100 AND name ~ 'main'"
--filter "name != 'main'"

演算子：=, !=, >, >=, <, <=, ~（含む）, ^（〜で始まる）, $（〜で終わる）, =~（正規表現）, AND, OR, NOT, IN, EXISTS。

エージェントのベストプラクティス

1. 件数を先に確認するパターン

取得前に、必ず結果の件数を確認してください。

ghidra function list --count --project P
# If manageable:
ghidra function list --limit 50 --fields name,address,size --project P

2. 積極的なフィルタリング

クライアント側ではなく、サーバー側で事前にフィルタリングしてください。

# GOOD
ghidra function list --filter "size > 1000" --project P
# BAD
ghidra function list --project P  # then filter in agent code

3. フィールドの選択

必要なフィールドのみを要求してください。

ghidra function list --fields name,address --json --project P

4. デフォルトの設定

--project と --program の繰り返しを避けてください。

ghidra set-default project myproject
ghidra set-default program mybinary
# Now: ghidra function list  (no flags needed)

.NET に関する警告

出力が .NET のマネージドコード（例：halt_baddata() または .NET CLR Managed Code マーカー）のように見える場合、ghidra decompile は警告を出力します。

「これは .NET マネージドコードのようです。Ghidra は .NET IL バイトコードを逆コンパイルできません。より良い結果を得るには、.NET 逆コンパイラー（例：ilspy-cli）の使用を検討してください。」

Ghidra では IL の有用な出力は得られません。代わりに、専用の .NET 逆コンパイラーを使用してください。ilspy-cli は別のツールであり、ghidra-cli の一部ではありません。

分析ワークフロー

# 1. Import and analyze
ghidra import ./target.exe --project analysis
ghidra analyze --project analysis

# 2. Recon
ghidra summary --project analysis
ghidra function list --count --project analysis
ghidra function list --filter "NOT name ^ 'FUN_'" --fields name,address,size --limit 30 --project analysis

# 3. Investigate
ghidra decompile main --project analysis
ghidra decompile main --with-vars --with-params --json --project analysis  # structured output
ghidra find crypto --project analysis
ghidra find string "password" --project analysis

# 4. Deep dive
ghidra graph callers suspicious_func --depth 3 --project analysis
ghidra x-ref to 0x401000 --project analysis
ghidra function disasm 0x401000 --project analysis

# 5. Type annotation (improves decompile output)
ghidra type create MyStruct --project analysis
ghidra type add-field MyStruct --name fd --type int --project analysis
ghidra type add-field MyStruct --name flags --type uint --project analysis
ghidra type create-enum ErrorCode --values "OK=0,ENOENT=2,EPERM=1" --project analysis
ghidra type typedef HANDLE void --project analysis
ghidra function set-return-type main --type int --project analysis
ghidra function set-signature parse_data --signature "int parse_data(char *buf, int len)" --project analysis
ghidra function set-var-type main --var local_10 --type "MyStruct *" --project analysis
ghidra decompile main --project analysis  # re-decompile with new types applied

# 6. Patch
ghidra patch nop 0x401234 --count 3 --project analysis
ghidra patch export -o patched.exe --project analysis

環境変数

変数	用途
GHIDRA_INSTALL_DIR	Ghidra のインストールパス
GHIDRA_PROJECT_DIR	プロジェクトのベースディレクトリ
GHIDRA_CLI_JAVA_HOME	Ghidra 用の完全な JDK（自動検出を上書き）
GHIDRA_DEFAULT_PROJECT	ghidra query のデフォルト --project
GHIDRA_DEFAULT_PROGRAM	ghidra query のデフォルト --program とプログラムの自動選択
GHIDRA_CLI_CONFIG	設定パスを上書き
GHIDRA_CLI_LAUNCH_TIMEOUT	ブリッジの起動準備完了までの上限（デフォルトは 180s）
GHIDRA_CLI_OP_TIMEOUT	時間のかかる analyze／import 処理の上限（デフォルトは無制限）
GHIDRA_CLI_DECOMPILE_TIMEOUT	Ghidra 側の逆コンパイル制限、秒単位。0 = 無制限（デフォルトは無制限）
GHIDRA_CLI_READ_TIMEOUT	リクエストごとのソケット読み取りタイムアウト。0 = 無期限（デフォルトは 300s）
GHIDRA_CLI_CONNECT_DEADLINE	起動中または再起動中のブリッジへの接続再試行時間（デフォルトは 60s）
GHIDRA_CLI_SHUTDOWN_TIMEOUT	強制終了前にジョブを完了させる猶予時間。0 = 無期限（デフォルトは 300s）
GHIDRA_CLI_READ_THREADS	ブリッジの読み取りプールサイズ。ブリッジ起動時に読み取られます。0 = すべてのジョブを排他的に実行（デフォルトは min(8, cores/2)、最小 2）

ファイルの場所

ファイル	用途
~/.local/share/ghidra-cli/bridge-{md5}.port	実行中のブリッジの TCP ポート
~/.local/share/ghidra-cli/bridge-{md5}.pid	ブリッジプロセスの PID
~/.config/ghidra-cli/config.yaml	設定
~/.config/ghidra-cli/scripts/GhidraCliBridge.java	実体化された Java ブリッジスクリプト
~/.local/share/ghidra-cli/ghidra-cli.log	デバッグログ

エラーからの復旧

問題	対処方法
"No project specified"	--project NAME を追加するか、ghidra set-default project NAME を実行してください。
"Bridge not responding"	ghidra stop --project P を実行してから再試行してください（自動的に起動します）。
"Ghidra installation not configured"	ghidra setup を実行するか、GHIDRA_INSTALL_DIR を設定してください。
関数が見つからない	ghidra find function "*pattern*" を使用してください。
最初のコマンドが遅い	正常です。ブリッジの起動と分析には数秒かかります。