CiRCLE

中文说明

CiRCLE: Recovering Complex Data Structures in Binaries beyond Fragmentation

The paper text is available as sp2026.pdf.

CiRCLE is a structure-recovery system for stripped binaries. It combines expression-level evidence, inter-procedural propagation, top-down consolidation, and optional LLM-assisted refinement to recover nested and non-rigid data layouts from binary code.

Start Here

This repository has three main entry paths:

• If you want to use CiRCLE itself, start with circle/.
• If you want the example with sample outputs, go to example/.
• If you want baseline wrappers / reproduction support, go to baseline/.

Use CiRCLE

The main implementation, CLI, tests, Docker packaging, and IDA plugin live under circle/.

Typical local setup to install the dependencies and create the local config is:

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

Minimal direct run on the tracked public sample:

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

That produces the standard CiRCLE artifacts under example/circle/no_llm_full/, including:

• circle.c Import-ready C declarations for the recovered structures, rendered from the finalized CiRCLE result and annotated with concise source func@var comments.
• circle_result.json The public JSON form of the finalized structures: field offsets, inferred types, sizes, pointer/nesting relations, source functions, and bound IDA variables.
• typesystem_manager_snapshot.json A fuller internal type-system snapshot, useful for debugging intermediate or non-materialized structures that may not appear in the public result.
• statistics.json Run metadata and counters, including binary metadata, configuration, timing breakdowns, LLM call/token counts, result counts, and IDA apply/save stats.

If you also want CiRCLE to apply the recovered structs inside IDA and save the resulting database, enable these settings in circle/config.yaml first:

ida:
  final_apply: true
  save_applied_db: true

Then run the same command again. In addition to the JSON and circle.c artifacts above, the output directory will also contain a saved IDA database such as case.strip.i64. You can open that .i64 directly in IDA to inspect the database after structure recovery and apply. If the pseudocode view does not refresh immediately after opening it, one manual F5 refresh may still be necessary.

If you want more implementation-facing detail, command variants, tests, or the headless API packaging, continue in circle/README.md.

Install The IDA Plugin

CiRCLE also ships an interactive IDA Pro plugin under circle/ida_plugin/.

Copy the following into your IDA plugins/ directory:

plugins/
  ida_circle.py
  circle/

• ida_circle.py comes from circle/ida_plugin/ida_circle.py
• circle/ comes from circle/circle/

If IDA should use a specific Python interpreter for the headless subprocess, set:

export CIRCLE_IDA_PYTHON=/path/to/python

For the full plugin workflow, cache layout, and UI behavior, see circle/ida_plugin/README.md.

Public Example

The tracked public example is documented separately in example/README.md.

Use that directory if you want:

• the canonical sample binary pair
• tracked example outputs
• sample evaluation reports
• the example-specific workflow and helper targets

Reproduction And Baselines

Baseline wrappers, provenance notes, compatibility patches, and local environment guidance live under baseline/README.md.

Start there if you want:

• to run the comparison tools
• to understand which external assets are still required
• to reproduce the baseline evaluation

If you specifically need the reusable evaluation pipeline, see evaluation/README.md.

Repository Layout

• circle/: main implementation and user-facing CiRCLE entrypoint
• baseline/: baseline wrappers and environment notes
• evaluation/: reusable evaluation pipeline
• example/: tracked public example
• evaluation/paper-cases/: supplementary evaluation and paper-aligned cases
• paper-chart/: figures and plotting assets used in the paper

License

MIT License. See LICENSE.

Citation

@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},
}