ghidra-agent-cli

ghidra-agent-cli

説明

ghidra-agent-cli は、Headless Ghidra スキルファミリーに同梱されているヘルパーです。 サポート対象の Ghidra、Frida、進捗、ゲートの各操作について、コマンドツリー、ワークスペースのレイアウト、YAML アーティファクトのセマンティクス、出力エンベロープ、実行時の動作を管理します。

このスキルでは、エージェント向けにヘルパーコマンドのセマンティクスを説明します。P0～P4 のワークフロー順序、ステージのルーティング、オーケストレーションポリシーは定義しません。これらは headless-ghidra/SKILL.md と各フェーズのスキルで定義されています。通常のユーザーはスキルファミリーをインストールして使用します。ワークフロー中にこの CLI を手動でインストール、ビルド、実行する必要はありません。

前提条件

• Node.js >= 18
• ghidra-agent-cli ghidra discover で検出可能なローカル Ghidra インストール
• frida * コマンドで使用する場合は、Frida のインストール（任意）

利用可能性

このヘルパーはスキルファミリーとともにインストールされ、headless-ghidra およびフェーズスキルと同じ階層に配置する必要があります。ghidra-agent-cli が利用できない場合は、対象のワークスペース内に別個の CLI パッケージをインストールするのではなく、スキルファミリー全体を再インストールまたは更新するようユーザーに依頼してください。

リリース管理対象のヘルパーパッケージバージョン：[email protected]。この識別子はパッケージングのメタデータです。分析ワークフロー中にユーザーへ手動でのインストールを依頼しないでください。

呼び出し

ghidra-agent-cli [GLOBAL FLAGS] <COMMAND> [COMMAND FLAGS]

入力

グローバルフラグ：

• --format yaml|json|toml — 出力形式（デフォルト：yaml）
• --target <id> — ターゲットセレクター
• --workspace <path> — ワークスペースのルートパス
• --config-dir <PATH> — 設定ディレクトリを上書き
• --data-dir <PATH> — データディレクトリを上書き
• --state-dir <PATH> — 状態ディレクトリを上書き
• --cache-dir <PATH> — キャッシュディレクトリを上書き
• --log-dir <PATH> — ログディレクトリを上書き
• --lock-timeout <SECS> — ロック取得のタイムアウト（秒）（デフォルト：30）
• --no-wait — ロック取得を待機しない
• --help — ヘルプテキストを表示

ほとんどのコマンドでは、--target <id> または context use で設定したアクティブなコンテキストが必要です。

出力

コマンドは、選択した形式で構造化されたエンベロープを出力します。

status: ok
message: "<summary>"
data: <structured payload>

エラー

エラーは構造化されており、形式が安定しています。

{
  "code": "E_ERROR",
  "message": "description of what went wrong",
  "source": "main",
  "format": "json"
}

既知のコード：

• E_ERROR — 一般的なエラー
• E_GATE_FAILED — ゲートチェックに失敗
• E_LOCK_TIMEOUT — ロック取得がタイムアウト

コマンドグループ

グループ	目的
workspace	対象ワークスペースを初期化し、フェーズの状態を管理します
scope	scope.yaml を管理します
functions / callgraph / types / vtables / constants / strings / imports	ベースラインの YAML メタデータを管理します
third-party	third-party/identified.yaml、サードパーティーなしとする明示的なレビュー、未変更のソースメタデータを管理します
runtime	runtime/run-manifest.yaml と runtime/run-records/*.yaml を管理します
hotpath	runtime/hotpaths/call-chain.yaml を管理します
metadata	metadata/renames.yaml や metadata/signatures.yaml などの P3 メタデータ YAML を管理します
substitute	substitution/functions/<fn_id>/ 以下の P4 置換レコードを管理します
git-check	ゲートから要求された場合に、成果物の YAML ファイルがレビュー可能な状態か検証します
execution-log	実行レコードを追加、確認します
progress	レガシーな逆コンパイル進捗 YAML 用の互換ヘルパー
gate	集約ゲートチェックを実行し、ゲートレポートを確認します
ghidra	Ghidra の検出、インポート／解析、ベースラインのエクスポート、変更の適用、カスタムヘッダー／シグネチャのインポート、逆コンパイル、再ビルド
frida	デバイス、キャプチャ、比較、トレース、実行、呼び出し用のヘルパー
inspect	読み取り専用のバイナリー検査用ヘルパー
context	アクティブコンテキスト用のヘルパー
paths	解決済みのワークスペース／ランタイムパスを表示します
validate / help	検証とヘルプの機能

ワークスペースモデル

ghidra-agent-cli では、次のアクティブなワークスペース構成を使用します。

targets/<target-id>/
└── ghidra-projects/

artifacts/<target-id>/
├── pipeline-state.yaml
├── scope.yaml
├── intake/
├── baseline/
│   ├── functions.yaml
│   ├── callgraph.yaml
│   ├── types.yaml
│   ├── vtables.yaml
│   ├── constants.yaml
│   ├── strings.yaml
│   └── imports.yaml
├── runtime/
│   ├── project/
│   ├── fixtures/
│   ├── run-manifest.yaml
│   ├── run-records/
│   └── hotpaths/call-chain.yaml
├── third-party/
│   ├── identified.yaml
│   ├── pristine/<library>@<version>/
│   └── compat/<library>@<version>/
├── metadata/
│   ├── renames.yaml
│   ├── signatures.yaml
│   ├── types.yaml
│   ├── constants.yaml
│   ├── strings.yaml
│   └── apply-records/
├── substitution/
│   ├── template/
│   ├── next-batch.yaml
│   └── functions/<fn_id>/
│       ├── capture.yaml
│       └── substitution.yaml
├── gates/
└── scripts/

workspace init は基本的なワークスペース構成を作成し、 pipeline-state.yaml と scope.yaml を初期化します。残りの アーティファクトは、後続のフェーズで追加されます。

アーティファクトの意味

アーティファクト	意味
pipeline-state.yaml	現在の対象、現在のフェーズ、記録されたバイナリパス
scope.yaml	明示的なスコープモードとエントリリスト
baseline/*.yaml	Ghidra からエクスポート、または CLI コマンドで整理されたベースラインメタデータ
runtime/run-manifest.yaml	P1 の再現可能なランタイムマニフェストと実行記録インデックス
runtime/run-records/*.yaml	P1 の具体的な実行可能ファイルまたはハーネスの実行観測結果
runtime/hotpaths/call-chain.yaml	P1 の Frida 由来ホットパス呼び出しチェーン優先順位のソース
third-party/identified.yaml	識別されたライブラリ、バージョン、証拠、ソースパス、未変更パス、関数分類。libraries: [] はサードパーティのレビューで該当なしと明示した記録です
third-party/pristine/<library>@<version>/	未変更のサードパーティソーススナップショット。未変更の状態を保つ必要があります
third-party/compat/<library>@<version>/	未変更のソースとは別に管理される互換性のための変更
metadata/*.yaml	CLI を介して Ghidra に適用する前の、P3 で復元された名前、シグネチャ、型、定数、文字列
metadata/apply-records/*.yaml	シリアライズされたメタデータ適用の試行を記録する P3 の記録
substitution/next-batch.yaml	P4 の置換作業リスト
substitution/functions/<fn_id>/*.yaml	P4 の関数フィクスチャ、キャプチャ、置換記録、ステータス、フォローアップデータ
gates/*-report.yaml	保存されたゲートチェックレポート

例

# Initialize a target
ghidra-agent-cli workspace init --target libfoo --binary ./libfoo.so

# Set scope and inspect state
ghidra-agent-cli --target libfoo scope set --mode full --entries 0x1000,0x2000
ghidra-agent-cli --target libfoo workspace state show

# Export and inspect baseline YAML
ghidra-agent-cli --target libfoo ghidra import
ghidra-agent-cli --target libfoo ghidra auto-analyze
ghidra-agent-cli --target libfoo ghidra export-baseline
ghidra-agent-cli --target libfoo functions list

# Import custom headers and signatures into the current Ghidra program
ghidra-agent-cli --target libfoo ghidra import-types-and-signatures --header ./include/custom_types.h --header ./include/custom_api.h

# Runtime, metadata, substitution, and gate checks
ghidra-agent-cli --target libfoo runtime record --key entrypoint --value 0x401000
ghidra-agent-cli --target libfoo hotpath add --addr 0x401000 --reason runtime
ghidra-agent-cli --target libfoo metadata enrich-function --addr 0x401000 --name main --prototype 'int(void)'
ghidra-agent-cli --target libfoo substitute add --fn-id fn_001 --addr 0x401000 --replacement 'return 0;'
ghidra-agent-cli --target libfoo gate check --phase P1

# Frida helpers
ghidra-agent-cli frida device-list
ghidra-agent-cli frida trace --target ./bin/app --functions open,read

境界

• 次の項目への回答には、このスキルを使用してください。コマンド名、フラグ、出力形式、アーティファクトのパス、 ファイルの意味、CLI の動作。
• P0〜P4 の順序、各ステージの担当範囲、ワークフローの判断について、このスキルを信頼できる情報源として 使用しないでください。これらは headless-ghidra スキル ファミリーで扱います。