binary-analysis

二进制分析 — Agent 技能

通过确定性、非交互式的 CLI 规划对未知二进制文件的分析；该 CLI 面向 Ghidra，具体实现限制见下文。此技能会教你如何分析二进制文件：何时进行初步筛查，何时深入分析，如何解读规范证据，以及如何生成可审计的报告。所有可观察操作都通过 binary CLI 完成 — 你不会直接调用 Ghidra API。

实现状态

此版本不提供实时 Ghidra 分析。导入、分析、元数据、结构和函数查询、搜索、初步筛查以及报告生成都会因明确的后端错误而停止。安装依赖项无法使尚未完成的适配器正常运行。项目管理和依赖项诊断仍然可用。生产版 CLI 不会加载或选择 FakeAdapter；测试会显式注入它。没有 fixture/demo CLI 开关或环境覆盖。

以下工作流描述的是预期接口，并非此版本中可运行的分析流程。遇到后端错误时应停止，并说明这一限制。即使旧项目被标记为 READY，也不要引用由旧 fixture 生成的报告作为用户二进制文件的证据。未来的实时后端需要在多个不同的已知二进制文件上完成验证，才能将结果视为观察所得。

适用场景

符合以下任一条件时，加载此技能：

• 用户提供二进制文件（PE、ELF、Mach-O、固件映像），并询问其用途、导入的 API，或是否可疑。
• 用户要求对特定函数或地址进行反编译、反汇编、调用图探索或交叉引用分析。
• 用户需要针对未知二进制文件生成结构化初步筛查报告、可疑 API 分析或能力图谱。
• 用户要求比较两个二进制文件、验证导出表，或提取符合某种模式的字符串。
• 用户想要设置分析工具链（binary doctor、binary bootstrap）或管理分析项目。

不适用场景

以下情况不要加载此技能：

• 运行时或动态分析 — 调试、strace/dtrace、沙箱执行、进程监控。此技能仅用于静态分析（V1）。
• 二进制文件修补或修改 — 十六进制编辑、资源编辑、重新打包。此分析工具链的设计用途是只读。
• 已完全了解的二进制文件 — 如果用户询问的是已知代码的文档或说明，请使用通用技能。
• 源代码分析 — C、C++、Rust 或汇编源文件。请改用特定语言或通用代码分析技能。
• 网络取证或数据包捕获 — PCAP 分析、线路层协议逆向工程。请使用专注于网络的技能。
• 实时内存取证 — 进程内存转储、堆分析。对文件中内存映射区域进行静态分析属于适用范围；实时进程检查则不属于。

Agent 与 CLI 各自负责什么

这是本技能中最重要的概念。越过这条边界会导致证据不可靠、浪费上下文，或两者兼有。

层级	职责	不得
Agent（你）	对二进制文件的行为提出假设。选择要运行的分析及其顺序。将 CLI 证据综合为结论。用通俗语言向用户解释发现。撰写有证据支撑的报告。	编造 CLI 输出中没有的事实。对于 CLI 报告的部分结果或低置信度，不得声称确定。不得跳过诊断警告。
CLI	解析参数、管理项目生命周期、运行 Ghidra 分析、序列化规范实体、输出 JSON 信封、强制执行安全限制。	解读结果、得出结论或撰写叙述性文字。

经验法则： 单独的 JSON data 字段不足以构成证据。 请确认结果来自针对所提供二进制文件运行的已实现实时后端。如果你想推断证据未直接支持的内容，请将其标记为 Agent 推断，并注明置信度差距。

核心工作流

每次分析都遵循以下顺序。不要跳过任何阶段——每个阶段都会产生下一阶段所依赖的证据。

阶段 1：环境检查

binary doctor --json

如果任何组件报告 severity: "ERROR"，请运行引导计划：

binary bootstrap --plan --json

检查计划。如果用户授权安装，请运行：

binary bootstrap --apply --json

使用 binary version --json 验证。

阶段 2：项目设置

为每个要分析的二进制文件创建一个项目。项目会隔离分析状态并提供审计轨迹。

binary project create <project-name> --json
binary import <path-to-binary> --project <project-name> --json

为确保可复现性，请使用复制模式（默认）。仅当二进制文件较大、只读或由多个项目共享时，才使用 --reference，并向用户说明数据过时的风险。

阶段 3：初始分析

首先运行标准分析配置。它涵盖大多数初步排查工作流所需的结构查询。

binary analyze --project <project-name> --json

检查响应：

• success: true, partial: false — 继续阶段 4。
• success: true, partial: true — 检查 diagnostics 中的缺漏。基于有限结果继续，并注明局限性。
• success: false, partial: true — 超时。提取已完成的内容，并报告未完成的内容。
• success: false, partial: false — 硬性失败。检查 diagnostics 中的失败原因。项目现已标记为 FAILED；运行 binary project clean 以重置。

阶段 4：证据收集

根据用户的问题选择分析。按以下顺序运行，从广泛分析逐步深入到具体分析，构建证据。

用于初步排查（广泛调查）：

binary triage --project <project-name> --json
binary suspicious-apis --project <project-name> --json
binary capability-map --project <project-name> --json

用于理解结构：

binary metadata --project <project-name> --json
binary sections --project <project-name> --json
binary entrypoints --project <project-name> --json
binary imports --project <project-name> --json
binary exports --project <project-name> --json
binary strings --project <project-name> --contains "<pattern>" --json

用于函数级深入分析：

binary functions --project <project-name> --json
binary decompile --project <project-name> <function-selector> --json
binary disassemble --project <project-name> <target> --json
binary xrefs --project <project-name> <entity-selector> --json
binary callers --project <project-name> <function-selector> --json
binary callees --project <project-name> <function-selector> --json
binary callgraph --project <project-name> <function-selector> --depth 3 --json

用于路径分析：

binary trace --project <project-name> --from <source> --to <target> --json

阶段 5：报告与交接

在向用户解释结果之前，先生成一份可长期留存的报告：

binary export-report --project <project-name> --type triage --format markdown --json

阅读报告。综合发现并作出清晰解释。始终将 Agent 推断与 CLI 证据分开标注。示例：

## CLI Evidence (deterministic)
- The binary imports VirtualAlloc, WriteProcessMemory, and CreateRemoteThread
  (suspicious-apis, risk_score 8, rule_id: process-injection)
- Entry point at 0x401000, 3 sections (.text, .rdata, .data)

## Agent Assessment (inference)
- The API combination suggests process injection capability. This is a
  heuristic, not a confirmed behavior. The binary would need to be executed
  (out of scope for static analysis) to confirm.

安全边界

CLI 会自动强制执行这些边界。即使用户提出要求，也绝不能试图绕过它们。

边界	强制措施	原因
绝不执行目标	CLI 会拒绝；不存在执行路径	仅进行静态分析
绝不将目标作为库加载	尚未实现；不存在 dlopen/LoadLibrary 路径	防止意外执行代码
绝不开放网络监听器	不提供 HTTP、MCP 或套接字服务	CLI 是本地工具
绝不上传哈希或样本	不收集遥测数据，不发起出站调用	隐私与安全
路径限制	验证所有项目路径，防止路径遍历	防止逃逸工作区
输出大小限制	默认 64 MB，JSON 最大 256 MB	防止耗尽上下文
内存限制	可配置每项操作的上限	防止大型分析期间发生 OOM
超时强制	默认 300s，可按命令配置	限制操作时长
结果数量限制	采用分页，默认 100，最多 1000	防止输出无上限增长
图深度限制	调用图深度上限为 10	防止无限递归

证据标准

所有 CLI 证据都遵循置信度层级。在报告或说明中引用证据时，请遵守这些标准。

证据类别（分诊输出）

类别	定义	示例
观察结果	来自后端的直接、确定性事实。不含 confidence 字段。	“Section .text 可执行，大小为 4096 字节”
启发式判断	基于规则得出的解释，带有明确的 confidence。	“可疑 API：VirtualAlloc (risk_score: 8, confidence: HIGH)”
未知	在特定地址处明确提出的未解决问题。	“无法解析 0x402080 处间接调用的目标”

置信度等级

等级	含义	引用方式
HIGH	后端确定此结果	作为事实引用
MEDIUM	后端有较高把握	加上限定语引用（“很可能”）
LOW	后端给出了最佳猜测	仅在明确说明 caveat 时引用
UNKNOWN	后端无法确定	作为待解决问题呈现

Agent 推断

将多项 CLI 观察结果综合为结论时，请明确标注为 Agent 推断。绝不要把推断说成 CLI 事实。可使用以下表述：

• “根据 X 和 Y 的综合情况，Agent 评估认为……”
• “CLI 将 Z 报告为启发式判断（confidence: MEDIUM）。Agent 认为这与……相符。”
• “CLI 无法确定 W。Agent 指出这是一个待解决的问题。”

参考资料路由

参考资料按需加载——不要在启动时全部读取。使用此 表格，将当前任务路由到合适的参考文件。

参考资料	加载时机
references/installation.md	设置 Ghidra、Java 或 PyGhidra。运行 binary doctor 或 binary bootstrap。依赖项故障排查。
references/cli-reference.md	需要完整的命令参考，包括标志、退出代码和示例。对某个命令或标志不熟悉。
references/triage-workflow.md	对未知二进制文件进行初步分析。需要分步分析方法和解读指南。
references/function-analysis.md	反编译、反汇编或跟踪函数。理解反编译器输出或调用图分析。
references/binary-formats.md	识别或解读 PE、ELF 或 Mach-O 格式特征。理解节标志、入口点约定或特定格式的特殊情况。
references/security.md	解读可疑 API 结果、能力映射或安全规则匹配结果。理解风险评分和规则优先级。
references/evidence-and-confidence.md	编写报告，区分 CLI 证据与 Agent 推断。构建有证据支撑的论证。
references/packed-and-obfuscated.md	怀疑二进制文件经过加壳、压缩或混淆。高熵节、缺少导入项或导入表较小。
references/firmware.md	分析固件映像。需要了解固件专用的加载地址约定、文件系统提取模式或引导加载程序分析。
references/troubleshooting.md	CLI 返回意外错误、超时或部分结果。Ghidra 无法启动。项目状态卡住。
references/reporting.md	使用 binary export-report 生成报告。选择报告类型和格式。解读报告结构。

报告要求

在 Agent 认为任务已完成之前，每次分析至少必须生成以下一种输出：

1. 初步分析报告 — 适用于未知二进制文件。涵盖观察结果、启发式分析、 未知事项，以及与 CLI 证据明确分开的 Agent 评估部分。
2. 定向分析 — 适用于有关特定函数、导入项或行为的目标明确的问题。先 给出 CLI 证据，再给出 Agent 解读，以回答用户的问题。
3. 能力摘要 — 适用于“这个二进制文件有什么作用”这类问题。根据证据来源 和置信度，映射其功能领域。

报告必须：

• 区分 CLI 证据（确定性）与 Agent 评估（解读）。
• 为每项启发式判断标注置信度。
• 包含来源信息：项目 ID、二进制文件 SHA-256、适配器和后端版本。
• 注明部分结果、超时或诊断警告——不要隐瞒限制。

验证矩阵

向用户呈现结果之前，请验证：

检查项	方法
所有 CLI 命令均返回 success: true 或有文档记录的 partial: true	检查每个响应封装中的 success 和 partial
未静默忽略任何诊断警告	检查每个响应中的 diagnostics 数组
证据引用可追溯到 CLI 输出	每项事实陈述都与 data 块中的某个字段相符
明确标注了 Agent 推断	搜索输出中未加限定的陈述
项目状态干净	运行 binary project status --project <name> --json
已生成并审阅报告	报告文件存在于项目的 reports/ 目录中

退出标准

出现以下情况时，停止分析并报告结果：

• 已生成分类报告，且已根据有证据支持的发现回答用户的问题。
• 已通过有针对性的分析，结合来源信息，得出用户要求的具体信息（反编译函数、调用路径、导入列表）。
• 已针对同一问题尝试三轮无法收敛的诊断。报告已收集的证据和遇到的阻碍。
• 二进制格式不受支持（退出代码 5）。报告格式限制。
• 缺少硬性依赖，且用户拒绝安装。报告这一缺口。

除非一次结构查询已完全回答用户的问题，否则不要在查询后停止。静态分析是迭代过程——先进行广泛调查，再深入分析。