headless-ghidra

ヘッドレス Ghidra — グローバルオーケストレーター

このスキルは、スキルファミリーのワークフローコーディネーターです。 P0～P4 の順序、ディスパッチルール、成果物の引き継ぎポイントを定義します。 ghidra-agent-cli は、コマンド構文と YAML 成果物の仕様を参照するためのツールです。

必須の共有ツール契約

• ghidra-agent-cli は、サポート対象のワークスペース、メタデータ、Ghidra、Frida、進捗、検証、ゲート操作に必須の共有インターフェースです。
• フェーズスキルでは、使用する ghidra-agent-cli のサブコマンドを正確に指定する必要があります。
• 下位レベルのシェルスクリプトや Java ヘルパーは、バックエンドの実装詳細です。CLI がすでに操作をサポートしている場合、主要なインターフェースとして CLI に取って代わってはなりません。
• すべてのワークフロー成果物は artifacts/<target-id>/ の下に配置する必要があります。
• YAML 成果物は、ghidra-agent-cli で作成、更新、検証する必要があります。
• CLI は git コミットを自動作成してはなりません。
• ゲートを移行するには、関連する成果物がディスク上に存在し、ユーザーによるレビューが可能な状態である必要があります。
• すべての Ghidra プロジェクト操作は ghidra-agent-cli を通して行う必要があります。CLI に必要な機能がない場合は、新しい Ghidra スクリプトを作成または実行する前に一時停止してユーザーに確認してください。

パイプライン

P0 Intake → P1 Baseline+Runtime → P2 Third-Party → [P3 Metadata Enrichment → P4 Function Substitution]*

フェーズ	スキル	目的	主な出力
P0	headless-ghidra-intake	対象ワークスペースを初期化し、前提条件を確認して、スコープを定義する	pipeline-state.yaml、scope.yaml、targets/<id>/ghidra-projects/
P1	headless-ghidra-baseline	Ghidra のインポート／解析を実行し、ベースライン YAML をエクスポートして、ランタイムの観測結果を準備する	baseline/*.yaml、runtime/run-manifest.yaml、runtime/run-records/*.yaml、runtime/hotpaths/call-chain.yaml
P2	headless-ghidra-evidence	サードパーティライブラリと未変更のソースを特定し、記録する	third-party/identified.yaml、third-party/pristine/<library>@<version>/、third-party/compat/<library>@<version>/
P3	headless-ghidra-discovery	名前、シグネチャ、型、定数、文字列、選択したホットパスのメタデータを充実させる	metadata/*.yaml、metadata/apply-records/
P4	headless-ghidra-batch-decompile	メタデータの適用と Ghidra のデコンパイルを通して、選択した関数を置き換える	substitution/next-batch.yaml、substitution/functions/<fn_id>/

共有成果物契約

すべてのフェーズは、次のアクティブなワークスペースレイアウト内で作業します。

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

artifacts/<target-id>/
├── pipeline-state.yaml
├── scope.yaml
├── intake/
├── baseline/
├── 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>/
└── gates/

オーケストレーターは pipeline-state.yaml を現在のターゲットレベルの状態記録として扱い、上記のフェーズが所有する YAML 成果物を引き継ぎに使用します。

オーケストレーターの責務

1. アクティブなターゲットを検出するか、再開します。
2. artifacts/<target-id>/pipeline-state.yaml を読み込みます。
3. 現在のステージに対応するフェーズスキルをディスパッチします。
4. 各移行時に ghidra-agent-cli gate check --phase ... を実行します。
5. ゲートを通過した後にのみ、フェーズの状態を進めます。
6. 再開／再起動、Frida による任意の補完、バッチ確認、差異レビュー、完了などのユーザーダイアログに対応します。

ゲートポリシー

• P0～P4 は、唯一の主要なパイプライン遷移です。
• ghidra-agent-cli gate check は、すべてのパイプラインフェーズ（P0～P4）における正式なゲート検証です。従来の gate-check.sh は削除されました。

必須の ghidra-agent-cli コマンド

• ghidra-agent-cli context use
• ghidra-agent-cli context show
• ghidra-agent-cli context clear
• ghidra-agent-cli workspace state show
• ghidra-agent-cli workspace state set-phase
• ghidra-agent-cli gate check
• ghidra-agent-cli validate
• ghidra-agent-cli progress compute-next-batch
• ghidra-agent-cli progress show

厳格な禁止事項

• 分析作業自体を実行してはいけません。
• 自身が所有する明示的な状態更新を除き、ベースライン、エビデンス、逆コンパイル、検証の成果物を直接編集してはいけません。
• サポート対象の状態、進捗、コンテキスト、検証、ゲートの操作で ghidra-agent-cli を迂回してはいけません。
• Ghidra の代わりに、別の逆コンパイルバックエンドを受け入れてはいけません。
• Git のコミットを自動的に作成してはいけません。
• CLI に機能がない場合、新しい Ghidra スクリプトを作成または実行してはいけません。いったん停止し、先にユーザーに確認してください。

次のスキルへのルーティング

• P0 完了 → headless-ghidra-baseline
• P1 完了 → headless-ghidra-evidence
• P2 完了 → headless-ghidra-discovery
• P3 完了 → headless-ghidra-batch-decompile
• 選択したすべての関数で P4 が完了 → P3 に戻るか、完了する

独立したスキル

以下のスキルは P0～P4 のパイプライン外で動作し、直接呼び出すことができます。

スキル	目的	呼び出し方法
headless-ghidra-analyze-function	型 → 定数 → vtable → 関数の識別 → 逆コンパイルという、厳格な 5 段階の復元順序に従って、単一関数を詳細に分析します。逆コンパイル結果を解釈する前に、特定の関数 1 つについて型、定数、vtable のコンテキストをすべて含む完全な分析が必要な場合に使用します。	ユーザーが「この関数を詳細に分析して」「完全なコンテキストを含めてアドレス 0x... の関数を逆コンパイルして」と依頼した場合、または関数ごとの完全な分析を求めた場合に呼び出されます。