Cerberus RE

cerberus-re 是一个面向苹果生态的本地化逆向工程工作台，用于围绕 Ghidra、LLDB 和 Frida 构建可重复的三头静态/动态/插装循环。

它专为需要持久工件而非仅终端笔记的分析师和编码代理而设计：

• Ghidra 导入、无头导出、反编译、交叉引用及元数据恢复。
• LLDB 运行时跟踪，并利用静态富化信息回填到导出函数上下文。
• Frida 诊断、受控运行时重新检查、Objective-C 探针以及堆或归档检查辅助工具。
• 基于导出的 Objective-C/字符串/符号数据的 XPC 接口及图报告。
• RE 证据报告、笔记、案例文件以及发布门控验证检查。
• 跨平台 Python CLI 支持 macOS、Linux、Windows、OpenAI Codex 和 Claude Code。

运行时附加和目标调用始终是显式的。该工具集倾向于自有进程、无附加验证、生成的工件以及边界探针，其假设与证据一并记录。

公共范围

公共工作台是通用的苹果二进制分析基础设施：Ghidra 导入与导出、LLDB/Frida 关联、Mach-O/ObjC/Swift/XPC 证据以及便携式报告。它既不是特定项目的研究日志，也不是通用的长期运行代理记忆系统。特定领域的研究工作流应存在于私有覆盖层或持久运行工件中，而通用长期运行状态属于 long-run-agent。

强烈推荐的配套依赖

对于重大的逆向工程工作，请将 Cerberus RE 与 long-run-agent 配合使用。Cerberus RE 提供静态、动态和插装工作台；long-run-agent 保留任务状态、声明、工件、故障、摩擦和下一步行动，使较长的调查保持可审计和可恢复。Cerberus RE 可以单独运行以完成有界任务，但基准测试和发布工作流应首选 cerberus-re + long-run-agent 组合配置。

安装

对于全新检出，以试运行模式启动依赖安装程序：

python3 scripts/install_dependencies.py
python3 scripts/install_dependencies.py --execute
source .venv/bin/activate
cerberus-re bootstrap

安装程序创建一个本地虚拟环境，安装 Cerberus RE 并添加 Frida Python 工具。在安装了 Homebrew 的 macOS 上，它可以安装 Ghidra/Java 和 Node。在 Linux 和 Windows 上，它会打印特定于包管理器的命令供审查，而不是自动运行系统安装。

如果您的系统依赖已经存在：

pip install -e .
cerberus-re bootstrap

可选技能安装：

cerberus-re install --host codex
cerberus-re install --host claude
cerberus-re install --host both

要求

• Python 3.11+
• Ghidra 12.x
• Java 21
• macOS、Linux 或 Windows（用于 Python CLI 和报告工具）
• macOS（用于针对本地苹果框架的 Apple 运行时附加工作流）
• LLDB 和 Frida（仅用于使用它们的工作流）

默认路径可以通过环境变量覆盖，详见 templates/config.env.example。

核心循环

cerberus-re doctor
cerberus-re bootstrap
cerberus-re import analyze /path/to/Binary my_project
cerberus-re export apple-bundle my_project BinaryName
cerberus-re bridge arm my_project BinaryName
cerberus-re bridge call /functions/search '{"query":"interestingName"}'
cerberus-re validate lldb-trace my_project BinaryName --launch-cmd /path/to/host --symbols '-[Owner selector:]'
cerberus-re validate lldb-trace my_project BinaryName --launch-cmd /path/to/host --symbols FirstExport --symbols SecondExport
cerberus-re frida validate-scripts
cerberus-re frida recheck-attach --target /path/to/owned-host --symbol '-[Owner selector:]' --allow-runtime
cerberus-re export runtime-enrich my_project BinaryName /path/to/runtime_hits.json

常用命令

cerberus-re export xpc-surface my_project BinaryName
cerberus-re export xpc-graph my_project:BinaryName other_project:OtherBinary
cerberus-re export function-dossier my_project BinaryName --function '-[Owner selector:]'
cerberus-re export triage-bundle my_project BinaryName --top-candidates 25
cerberus-re polish release --mode quick --strict-command-surface

如果 export xpc-surface 报告为零计数，在将其用作缺失证据前请检查 warnings 和 missing_input_count。在分析存储于默认导出目录之外的 Apple 捆绑包时，请传递 --bundle-dir 或显式的导出 JSON 路径。

使用 python3 -m cerberus_re_skill 或 cerberus-re 进行自动化。通用长期运行状态、引导文件、持久项目记忆以及代理收尾编排属于 long-run-agent，而非此工作台。

基准测试

公共基准测试脚手架定义了一个可重现的代理/任务矩阵，但不附带基准测试结果：

python3 scripts/agent_benchmark.py list
python3 scripts/agent_benchmark.py scaffold --runner codex --configuration cerberus-re-long-run-agent --output benchmarks/results/example/codex/cerberus-re-long-run-agent
python3 scripts/agent_benchmark.py validate --bundle benchmarks/results/example/codex/cerberus-re-long-run-agent

以 benchmarks/agent_benchmark.v1.json 作为机器可读的真实数据源。只有经过真实运行器记录下持久命令、声明、工件、故障和指标后，脚手架的捆绑包才成为结果。

安全模型

• 除非命令接收到显式的运行时标志，否则不会发生运行时附加。
• 变异的桥接调用需要显式的写入选择加入。
• 破坏性桥接调用需要单独的破坏性选择加入。
• 生成的测试套件将调用保持注释或受边界限制，直到调用者提供目标特定对象。
• 报告应区分成功的运行时命中、无命中状态、附加阻塞因素以及未经验证的假设。

仓库布局

• SKILL.md：代理面向的操作规程。
• cerberus_re_skill/：Python CLI 和报告构建器。
• scripts/：安装程序、辅助脚本、源 shell 库和 Ghidra Java 脚本。
• bridge-extension/：Ghidra 桥接源码。
• references/：公共命令和工件参考。
• benchmarks/：基准测试定义、结果捆绑包脚手架以及未来公共结果样版。
• tests/：冒烟和回归测试。

验证

在发布里程碑之前：

python3 -m unittest discover -s tests
python3 -m compileall cerberus_re_skill scripts tests
python3 -m cerberus_re_skill polish release --mode quick --strict-command-surface
python3 -m cerberus_re_skill bridge audit
git diff --check

许可证

Apache-2.0。详见 LICENSE。