Skip to content

README.zh-CN.md

Latest commit

 

History

History
151 lines (107 loc) · 5.2 KB

README.zh-CN.md

File metadata and controls

151 lines (107 loc) · 5.2 KB
Raw

CiRCLE

English

CiRCLE: Recovering Complex Data Structures in Binaries beyond Fragmentation

论文正文见 sp2026.pdf。

CiRCLE 是一个面向 stripped binary 的结构恢复系统。它结合表达式级证据、跨过程传播、 自顶向下整合，以及可选的 LLM 辅助精化，从二进制代码中恢复嵌套和非刚性数据布局。

CiRCLE pipeline overview

从哪里开始

这个仓库主要有三条入口：

  • 如果你只是想 使用 CiRCLE 本身，从 circle/ 开始。
  • 如果你想看 标准样例，去 example/。
  • 如果你想做 baseline / 复现，去 baseline/。

使用 CiRCLE

主实现、CLI、测试、Docker 打包以及 IDA 插件都在 circle/ 下面。

典型本地准备流程：

uv sync --all-packages
cd circle
cp -n config.yaml.example config.yaml

直接在仓库自带的样例上运行一个最小命令：

CIRCLE_CONFIG_PATH=./config.yaml \
uv run circle ../example/case.strip -o ../example/circle/no_llm_full

这会在 example/circle/no_llm_full/ 下生成标准 CiRCLE 输出，包括：

  • circle.c 可直接导入的恢复结构体 C 声明，由 finalized CiRCLE 结果渲染而来，并带有简洁的来源 func@var 注释。
  • circle_result.json finalized 结构体的 JSON 形式，包含字段偏移、推断类型、大小、指针/嵌套关系、 来源函数以及绑定到的 IDA 变量。
  • typesystem_manager_snapshot.json 更完整的类型系统快照，适合调试中间结构体或未 materialize 到最终结果里的结构体。
  • statistics.json 运行元信息和统计计数，包括二进制元数据、配置、阶段耗时、LLM 调用/token 统计、 结果计数以及 IDA apply/save 统计。

如果你还希望 CiRCLE 在 IDA 里把恢复出来的结构体直接 apply 进去，并把结果数据库一起保存， 先在 circle/config.yaml 里打开这两个配置：

ida:
  final_apply: true
  save_applied_db: true

然后再运行同一条命令。除了上面的 JSON 和 circle.c 产物之外，输出目录里还会多出一个 保存后的 IDA 数据库，例如 case.strip.i64。你可以直接用 IDA 打开这个 .i64， 查看结构恢复并 apply 之后的数据库状态。如果打开后伪代码没有立即刷新，手动按一次 F5 仍然可能是有必要的。

如果你想继续看更完整的实现说明、命令变体、测试或 headless API 打包方式， 请继续阅读 circle/README.zh-CN.md。

安装 IDA 插件

仓库里也带了一个交互式 IDA Pro 插件，说明在 circle/ida_plugin/。

把下面这些内容复制到 IDA 的 plugins/ 目录：

plugins/
  ida_circle.py
  circle/

如果希望 IDA 固定使用某个 Python 解释器来启动无头子进程，可以设置：

export CIRCLE_IDA_PYTHON=/path/to/python

插件的完整工作流、缓存布局和交互行为说明见 circle/ida_plugin/README.zh-CN.md。

标准样例

仓库跟踪的标准样例单独写在 example/README.zh-CN.md。

如果你想看这些内容，请直接去 example/：

  • 标准样例二进制
  • 已跟踪的示例输出
  • 示例评估报告
  • 样例专用的工作流和辅助命令

复现与 Baseline

baseline 包装脚本、来源说明、兼容性 patch 和本地环境要求统一写在 baseline/README.zh-CN.md。

如果你想：

  • 运行对比工具
  • 看当前还依赖哪些外部资产
  • 做 baseline 侧复现

就从 baseline/ 开始。

如果你单独需要可复用的评估管线，再去看 evaluation/README.zh-CN.md。

仓库结构

许可证

MIT License。见 LICENSE。

引用

@inproceedings{circle,
  title      = {CiRCLE: Recovering Complex Data Structures in Binaries beyond Fragmentation},
  author     = {Zeyu Gao and Junlin Zhou and Songtao Yang and Chao Zhang},
  booktitle  = {2026 IEEE Symposium on Security and Privacy (SP)},
  year       = {2026},
  publisher  = {IEEE Computer Society},
  pages      = {2576-2595},
  doi        = {10.1109/SP63933.2026.00146},
}