headless-ghidra-analyze-function

Headless Ghidra — 单函数深度分析

此技能为单个函数提供专门且严格按顺序执行的分析工作流。 它针对现有目标产物树运行，并可更新基线、元数据和替代产物， 同时记录针对单函数调查的来源信息。

解析目标函数

在第 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 后，才能开始第 1 步。

严格恢复顺序

每次函数分析必须遵循以下五步顺序：

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

不得跳过或调整任何步骤的顺序。 只有在完成第 1–4 步后，第 5 步的反编译分析才有效，因为类型、常量、虚表和正确的函数身份是准确解读反编译结果的前提。

---

第 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 文件。

---

第 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）
• 特定于协议的常量
• 用作键或标识符的字符串常量

---

第 3 步 — 恢复虚表

判断该函数是否为虚方法，或是否与虚分发表交互。恢复该函数读取或写入的所有虚表。

必需的 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 — 虚表分析结果（如果已生成）

关注点

• 函数是虚方法（跳板函数，转发到虚表分发）
• 函数读取或初始化虚表指针
• 涉及虚表的对象构造/析构序列
• 通过虚表进行的多个分发路径

---

步骤 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-agent-cli functions show --addr <addr>，查看 Ghidra 当前分配的名称

---

步骤 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 下写入由 Agent 撰写的可选笔记：

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 自动生成。如果用户需要按步骤记录分析笔记，Agent 必须明确编写并维护这些 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	虚函数表恢复	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>

约束

• 必须按五步顺序执行。 不要跳过步骤 1–4，直接执行步骤 5。
• 先解析 addr，再选择 fn_id。 对于地址输入，使用 functions show --addr <addr>；对于符号名称查询，使用 functions list --named-only。复用用户提供的 fn_id，或根据规范化地址推导出一个。
• 不要先反编译再倒推。 缺少类型、常量和虚函数表上下文时，反编译会导致分析不准确。
• 仅使用 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 的函数”
• “这个函数的作用是什么，包括它使用的所有类型和常量”
• “对 [函数名称] 进行完整分析”