headless-ghidra-analyze-function

ヘッドレス Ghidra — 単一関数の詳細分析

このスキルは、単一関数を対象とした専用の厳密な順序の分析ワークフローを提供します。 既存のターゲットアーティファクトツリーを対象に動作し、対象を絞った単一関数の調査に関する出所情報を記録しながら、ベースライン、メタデータ、置換アーティファクトを更新する場合があります。

対象関数の解決

Step 1 の前に、要求された関数を一意の addr に解決し、この分析用に安定したローカル fn_id を導出します。

入力がアドレスの場合

アドレスをそのまま使い、解決された関数の識別情報を確認します。

ghidra-agent-cli --target <id> functions show --addr <addr>

アドレスが有効であることを確認し、ワークフローの残りでは正規の関数ロケーターとして使用します。

入力がシンボルまたは関数名の場合

まず、名前付きのベースライン関数を検索します。

ghidra-agent-cli --target <id> functions list --named-only

要求された名前と照合し、一致するエントリーから一意の addr を記録します。

解決ルール

• 複数の一致がある場合は停止し、どの関数を指しているのかユーザーに確認します。
• 一致がない場合は、artifacts/<target-id>/baseline/functions.yaml を調べ、名前が存在しないのか、曖昧なのか、綴りが異なるのかを確認します。
• 部分的な名前やおおよその名前からアドレスを推測してはいけません。
• ユーザーがすでに fn_id を指定している場合は、それを再利用します。
• それ以外の場合は、正規化したアドレスから安全なローカル fn_id を導出します。例：fn_<addr_without_0x>、たとえば fn_00102140。
• addr が確認され、使用する fn_id が選ばれた後にのみ、Step 1 を開始できます。

厳密な復元順序

すべての関数分析は、必ず次の5ステップの順序に従う必要があります。

Step 1 → Type Definitions
Step 2 → Constant Definitions
Step 3 → Vtable Recovery
Step 4 → Function Name & Signature
Step 5 → Decompilation Analysis

ステップを省略したり、順序を入れ替えたりしてはいけません。 Step 5 の逆コンパイル分析は、Step 1〜4 の完了後にのみ有効です。型、定数、vtable、および関数の正確な識別が、逆コンパイル結果を正確に解釈するための前提となるためです。

---

Step 1 — 型定義の復元

何よりも先に、関数が使用するすべてのデータ型（構造体、共用体、列挙型、typedef、ポインター、配列）を列挙して復元します。

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

# List all types from baseline
ghidra-agent-cli --target <id> types list

# Export fresh baseline types if needed
ghidra-agent-cli --target <id> ghidra export-baseline

# Show resolved function details (check signature/return type)
ghidra-agent-cli --target <id> functions show --addr <addr>

出力

• artifacts/<target-id>/baseline/types.yaml — 型システム全体
• 関数が参照する型のサブセットを作業分析に記載

確認する項目

• 関数のパラメーターまたはローカル変数が参照する構造体定義
• switch 文または比較で使用される列挙値
• 可読性を高める typedef エイリアス
• 他の関数へのポインター型（コールバックのシグネチャ用）

CLI の調整

ghidra-agent-cli types list で結果が返されない場合は、まず ghidra export-baseline を実行してベースライン YAML ファイルを生成します。

---

Step 2 — 定数定義の復元

型の復元後、関数が参照するすべての定数（マジックナンバー、ビットマスク、フラグ値、列挙定数、文字列定数）を復元します。

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

# List all constants from baseline
ghidra-agent-cli --target <id> constants list

# List all strings (format strings, keys, identifiers)
ghidra-agent-cli --target <id> strings list

出力

• artifacts/<target-id>/baseline/constants.yaml — 定数プール全体
• artifacts/<target-id>/baseline/strings.yaml — 文字列定数
• 関数が参照する定数のサブセットを作業分析に記載

確認する項目

• #define マクロの値である可能性がある数値リテラル
• ビットマスク演算と、その構成フラグ
• 意味が既知のマジックナンバー（例：ELF ヘッダーの 0x202）
• プロトコル固有の定数
• キーまたは識別子として使用される文字列定数

---

Step 3 — Vtable の復元

関数が仮想メソッドか、仮想ディスパッチテーブルとやり取りするかを特定します。関数が読み取る、または書き込むすべての vtable を復元します。

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

# List all vtables from baseline
ghidra-agent-cli --target <id> vtables list

# Analyze vtables in the binary and refresh baseline/vtables.yaml
ghidra-agent-cli --target <id> ghidra analyze-vtables --write-baseline

出力

• artifacts/<target-id>/baseline/vtables.yaml — すべての仮想テーブル
• artifacts/<target-id>/baseline/vtable-analysis-report.yaml — vtable 分析の結果（生成された場合）

確認する項目

• 関数が仮想メソッドである（vtable ディスパッチへのサンク）
• 関数が vtable ポインターを読み取る、または初期化する
• vtable が関わるオブジェクトの構築／破棄シーケンス
• vtable を経由する複数のディスパッチ経路

---

ステップ 4 — 関数名とシグネチャの特定

型、定数、仮想関数テーブルを把握した後、関数の正式名称と完全な型シグネチャを特定します。

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

# Show current resolved function info
ghidra-agent-cli --target <id> functions show --addr <addr>

# Name lookup is handled earlier during target resolution when needed
# ghidra-agent-cli --target <id> functions list --named-only

# Write enriched name and signature together.
# This command updates both metadata/renames.yaml and metadata/signatures.yaml.
ghidra-agent-cli --target <id> metadata enrich-function --addr <addr> --name '<recovered_name>' --prototype '<signature>'

# Apply the metadata YAML back into Ghidra without per-function flags
ghidra-agent-cli --target <id> ghidra apply-renames
ghidra-agent-cli --target <id> ghidra apply-signatures

入力

• ステップ 1 の出力：パラメーター型と戻り値型の特定に役立つ型
• ステップ 3 の出力：仮想メソッドのシグネチャを示す可能性のある仮想関数テーブルのコンテキスト
• artifacts/<target-id>/metadata/renames.yaml — 既存の P3 名称変更エンリッチメント（利用可能な場合）
• artifacts/<target-id>/metadata/signatures.yaml — 既存の P3 シグネチャエンリッチメント（利用可能な場合）

メタデータの確認

以下のファイルが存在する場合は、直接読み取ります。

1. artifacts/<target-id>/metadata/renames.yaml
2. artifacts/<target-id>/metadata/signatures.yaml

functions list --named-only は、ターゲット解決時のベースライン名の検索にのみ使用し、メタデータ確認コマンドとしては使用しません。

出力

• artifacts/<target-id>/metadata/renames.yaml — 関数名のレコード
• artifacts/<target-id>/metadata/signatures.yaml — 関数プロトタイプ

確認する項目

• インポート／エクスポートからデマングルしたシンボル名
• 呼び出し箇所の分析から得られる呼び出し規約の手掛かり
• 呼び出し先の参照から得られるパラメーターの数と型
• 戻り値の使用状況の分析から得られる戻り値型

CLI の代替手順

metadata enrich-function を使用しない場合は、これらの YAML ファイルを直接編集し、関数ごとのフラグを付けずに適用コマンドを実行します。

1. artifacts/<target-id>/metadata/renames.yaml
2. artifacts/<target-id>/metadata/signatures.yaml
3. ghidra-agent-cli --target <id> ghidra apply-renames
4. ghidra-agent-cli --target <id> ghidra apply-signatures

ghidra-agent-cli metadata list --addr が必要な場合は、代わりに次の手順を実行します。

1. artifacts/<target-id>/metadata/renames.yaml を直接読み取る
2. artifacts/<target-id>/metadata/signatures.yaml を直接読み取る
3. 現在 Ghidra が割り当てている名前を ghidra-agent-cli functions show --addr <addr> で確認する

---

ステップ 5 — デコンパイル分析

ステップ 1〜4 が完了した後にのみ、最終的なデコンパイル分析を行い、型と定数のコンテキストをすべて含めて結果を提示します。

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

# Decompile the function with full context using the chosen local fn_id
ghidra-agent-cli --target <id> ghidra decompile --fn-id <fn_id> --addr <addr>

# Review the generated decompilation, then save a curated function-level
# replacement C file before recording it.
decompiled_c="artifacts/<target-id>/decompilation/functions/<fn_id>/<fn_id>.c"
replacement_c="$(mktemp)"
cp "$decompiled_c" "$replacement_c"
ghidra-agent-cli --target <id> substitute add --fn-id <fn_id> --addr <addr> --replacement "$(cat "$replacement_c")"

出力

• artifacts/<target-id>/baseline/vtables.yaml — 仮想関数テーブル分析によってベースライン状態が更新される場合は、先に更新済み
• artifacts/<target-id>/substitution/functions/<fn_id>/capture.yaml — デコンパイル前のスナップショット
• artifacts/<target-id>/substitution/functions/<fn_id>/substitution.yaml — 来歴情報を含む最終分析
• artifacts/<target-id>/substitution/next-batch.yaml — substitute add によって更新される置換キューの状態

分析の成果物

1. 解決済みの型をすべて含むデコンパイル済みソース（生の ID はありません）
2. 定数の置換 — すべてのマジックナンバーを意味のある名前に置き換えます
3. 仮想関数テーブルの注釈 — 仮想関数呼び出しのターゲットを特定します
4. 関数プロトタイプ — パラメーター名を含む最終的なシグネチャ
5. 来歴の連鎖 — 各解決の根拠となったステップ 1〜4 の成果物

---

関数ごとの成果物の出力

このスキルは、既存のパイプライン成果物に来歴情報を記録し、以下を更新する場合があります。

artifacts/<target-id>/
├── baseline/
│   └── vtables.yaml
├── metadata/
│   ├── renames.yaml
│   └── signatures.yaml
└── substitution/
    ├── next-batch.yaml
    └── functions/
        └── <fn_id>/
            ├── capture.yaml
            └── substitution.yaml

任意のエージェント作成メモも、選択したローカルの fn_id の下に書き込めます。

artifacts/<target-id>/analysis/functions/<fn_id>/
├── step1-types.yaml
├── step2-constants.yaml
├── step3-vtables.yaml
├── step4-identity.yaml
├── step5-decompilation.yaml
└── provenance.yaml

これらの analysis/functions/<fn_id>/step*.yaml ファイルは、ghidra-agent-cli によって自動生成されません。ユーザーがステップごとの分析メモを希望する場合、エージェントはそれらの YAML ファイルを明示的に作成し、維持する必要があります。

---

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

手順	目的	主なコマンド
1	型定義	ghidra-agent-cli types list、ghidra export-baseline
2	定数定義	ghidra-agent-cli constants list、ghidra-agent-cli strings list
3	Vテーブルの復元	ghidra-agent-cli vtables list、ghidra analyze-vtables --write-baseline
4	関数名とシグネチャ	ghidra-agent-cli functions show、metadata enrich-function、ghidra apply-renames/signatures
5	逆コンパイル	ghidra-agent-cli ghidra decompile、substitute add --replacement ...

---

呼び出し方法

アドレスを指定して特定の関数を分析するには：

Use the headless-ghidra-analyze-function skill with:
- Function address: <hex address>
- Target ID: <target-id>

エクスポートされている場合は、シンボル名で分析するには：

Use the headless-ghidra-analyze-function skill with:
- Symbol name: <mangled or demangled name>
- Target ID: <target-id>

制約事項

• 必ず5つの手順を順番に実行してください。 手順1～4を飛ばして手順5に進まないでください。
• まず addr を解決してから、fn_id を選択してください。 アドレスを入力する場合は functions show --addr <addr> を、シンボル名を検索する場合は functions list --named-only を使用してください。ユーザーが指定した fn_id を再利用するか、正規化したアドレスから導出してください。
• 先に逆コンパイルして、後から逆算しないでください。 型、定数、Vテーブルのコンテキストなしで逆コンパイルすると、分析が不正確になります。
• ghidra-agent-cli のみを使用してください。 Ghidra に関するすべての操作は CLI 経由で行う必要があります。
• 分析の根拠を記録してください。 最終的な分析では、各手順で何が明らかになり、それが次の手順にどう役立ったかを説明してください。手順ごとのファイルが必要な場合に限り、任意で analysis/functions/<fn_id>/step*.yaml のメモを作成してください。
• 既存の成果物は更新できます。 このスキルでは、baseline/vtables.yaml、metadata/renames.yaml、metadata/signatures.yaml、substitution/functions/<fn_id>/*、substitution/next-batch.yaml を変更できます。
• CLI コマンドでメタデータを一覧表示できない場合は、メタデータファイルを直接読み込んでください。 メタデータの一覧表示に対応する CLI コマンドがない場合は、Read ツールを使って YAML ファイルを直接読み込んでください。

起動条件

ユーザーが次のように依頼した場合、このスキルが呼び出されます。

• 「この関数を徹底的に分析してください」
• 「完全なコンテキストで、0x401000 の関数を逆コンパイルしてください」
• 「この関数が使用するすべての型と定数を含めて、この関数が何をするのか教えてください」
• 「[関数名] の完全な分析をお願いします」