Ghidra ヘッドレスアナライザー：CLIで一括解析

Ghidra ヘッドレスアナライザーとは何か、いつ使うか

Ghidra ヘッドレスアナライザーは、デスクトップ画面を開かずに解析を実行するコマンドラインの入口です。プロジェクトを新しく作成または補完し、インポート済みまたは既存のプログラムを解析し、サンプルフォルダー、ファームウェアのトリアージ、定期レポート、管理されたビルドパイプライン向けにGUIを使わないスクリプトを実行できます。

ヘッドレス実行はリモートサーバーではなく、すべての判断を自動化する機能でもありません。Ghidraのインストール、プロジェクトの場所、ローダー、アナライザー、スクリプト、通常のプロジェクト規則に依存します。リリース、入力セット、オプション、出力プロジェクト、ログを記録し、解析は許可を得た素材だけに限定してください。

インストール、プロジェクト、入力ファイルを準備する

公式Ghidra ZIPと、対応する64ビットJDKから始めます。このサイトで確認したリリースは2026年8月18日公開のGhidra 12.1.3で、アーカイブのsupport/にランチャーが含まれています。デスクトップ版が起動しない場合はGhidraインストールガイドを確認してください。JDKの不備や展開漏れは、ヘッドレス実行も失敗させます。

アプリケーション、プロジェクト、入力・レポート用フォルダーは分けて管理します。調査中にライブプロジェクトをバッチジョブから編集したり、確認前に既知の正常なコピーを上書きしたりしないでください。スクリプトやアナライザー設定を試すときは、新しいプロジェクト名を使います。

1. 1

   ランチャーを確認する

   Ghidraのインストール先で、使用するOSのランチャーが存在し、ヘルプを表示できることを確認します。Windowsはバッチファイル、macOSとLinuxはシェルランチャーを使います。

   support/analyzeHeadless.bat または support/analyzeHeadless
2. 2

   書き込み可能なプロジェクト領域を選ぶ

   インポートしたプログラム、データベース、キャッシュ、レポートを置ける容量を確保します。ファイルロックや同時書き込みを調べる間は、同期フォルダーを避けます。

   D:\analysis\projects /srv/ghidra/projects
3. 3

   入力セットを記録する

   ファイル名、ハッシュ、想定アーキテクチャー、収集日を記録します。中身を記録しないディレクトリパスは、再現可能な入力とは言えません。

   samples/firmware-a.bin samples/firmware-b.bin
4. 4

   処理前にバックアップする

   シンボルやデータ型の変更、プログラムの削除、保存を行うスクリプトを実行する前に、プロジェクトをコピーします。

   ProjectName.gpr + ProjectName.rep/

-import と -process の使い分け

Ghidra ヘッドレスアナライザーで最初に決めるのは、入力ファイルからプロジェクトを作成または補完するのか、すでにプロジェクトにあるプログラムを開いて処理するのかです。ファイルやディレクトリをプロジェクトのプログラムにしたい場合は-importを使います。プログラムがすでにプロジェクトにある場合は-processを使います。

インターネット上の例に両方が書かれているからといって、両方のモードを追加しないでください。まずは説明できる小さなジョブを作り、必要な場合だけローダーやプロセッサーを指定し、成功したコマンドをバージョン管理したスクリプトに保存します。

再現性を失わずにスクリプトを使う

ヘッドレスジョブは、解析状態を小さく確認しやすい結果へ変換するスクリプトと組み合わせると便利です。pre-scriptでプロジェクト操作を準備し、post-scriptで解析済みプログラムを調べてレポートを書けます。関数、文字列、インポート、メタデータの一項目を出力するような狭いスクリプトは、大きなプロジェクトを黙って改名するスクリプトよりテストしやすくなります。

スクリプトはバージョン管理したディレクトリに置き、-scriptPathで渡します。役割を明確にするため-preScriptと-postScriptを使い、対応するログも保存します。Ghidraの外でCPythonを使う場合はPyGhidraガイドを参照してください。二つの自動化境界は関連しますが、同じランタイムではありません。

• 読み取り専用またはレポート作成の作業と、許可を得た小さなサンプルから始める。
• スクリプトのリビジョンをコマンドとGhidraのリリースの横に固定する。
• スクリプトがプロジェクトデータを保存する必要がなければ、レポートはプロジェクト外に書く。
• 空の結果、存在しない項目、未対応のプログラム種別、2回目の実行をテストする。
• シンボルやデータ型の変更を受け入れる前に、バックアップしたプロジェクトと比較する。

ディレクトリ処理、ログ、CIジョブ

ディレクトリを扱う場合、ファイルを一つのプロジェクトにまとめるか、分離したプロジェクトを使うか決めます。一つのプロジェクトならファイル間の確認が便利ですが、分離すれば意図しない混在を減らせます。-recursiveは、入れ子のフォルダーまで範囲に含める場合だけ使います。広すぎるパスは想定外のデータをインポートする可能性があります。

コマンド、Ghidraのリリース、Javaのバージョン、入力マニフェスト、スクリプトのリビジョン、終了ステータス、ログ、プロジェクトパス、想定外の出力ファイルを記録します。CIではログとレポートを保存し、ランチャーやpost-scriptがエラーを報告したら失敗にします。プロセスが正常終了しても、期待した関数や文字列がすべて見つかった証拠にはなりません。

結果を読み、Ghidraで検証する

ヘッドレス実行後、プロジェクトを開く前に終了ステータスとログを確認します。ローダーのメッセージ、選択された言語やコンパイラー、解析の完了、スクリプト例外、スキップされたファイル、書き込み失敗を見ます。その後、GUIでコピーを開き、Listing、参照、Decompiler、シンボルなどで少数の結果を確認します。Ghidra検索ガイドとDecompilerガイドも役立ちます。

レポートは出力物であって、それだけで証拠になるわけではありません。スクリプトが文字列を見つけなかった場合は、言語、範囲、APIオブジェクトを確認します。入力マニフェストと正確な実行記録を保存したプロジェクトデータと一緒に残してください。

ヘッドレスアナライザー、Script Manager、PyGhidraの違い

ヘッドレスアナライザーはCLIジョブの境界です。Script Managerは、表示中のGhidraアプリケーション内でスクリプトを実行します。PyGhidraは外部のCPythonプロセスをGhidra APIへ接続します。同じ調査で組み合わせることはできますが、実行環境は異なります。

1つのプログラムを画面で確認するならGUI、繰り返し可能なインポートやプロジェクト処理ならヘッドレスアナライザー、外部Pythonプロセスが中心ならPyGhidraを選びます。