ghidra-agent-cli

ghidra-agent-cli

描述

ghidra-agent-cli 是 Headless Ghidra 技能系列随附的辅助工具。 它负责管理命令树、工作区布局、YAML 构件语义、输出封装格式，以及受支持的 Ghidra、Frida、进度和 gate 操作的运行时行为。

本文档介绍该辅助工具面向 Agent 的命令语义。它不 定义 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 — gate 检查失败
• 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	管理 P3 元数据 YAML，例如 metadata/renames.yaml 和 metadata/signatures.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	P3 恢复的名称、签名、类型、常量和字符串，供通过 CLI 应用到 Ghidra 之前使用
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 技能系列负责。