Awesome REA
中文Star on GitHubStar1.1k stars
Star on GitHubStar1.1k stars

Tool

ollvm-unflattener

Python command-line deobfuscator for the control-flow flattening applied by Obfuscator-LLVM (OLLVM). Given a flattened function's address, it uses Miasm's symbolic execution to track the dispatcher's state variable, records which blocks each state value selects and which state follows it, and writes a copy of the binary in which the function is reassembled with Keystone in its recovered order; an optional mode also follows the function's calls. The README covers 32- and 64-bit x86 Windows and Linux binaries and contrasts this approach with MODeflattener's static one.

Targets
Binary
Category
Native analysis tools
Relationship
Foundation tool
Sources reviewed

Requirements & limits

  • Latest release at review: v2.0, published 2025-04-16 without attached binaries; its notes call it most likely the final release, and the reviewed master commit is that tag and the repository's last push. The tool runs from a clone as python unflattener -i <input> -o <output> -t <hex address>, with -a to follow calls; there are no tests or CI.
  • The README requires Python 3.10+ and Git; requirements.txt lists miasm, graphviz and keystone-engine without version pins. The code handles PE and ELF files for x86_32 and x86_64 and raises an error for other formats or architectures.
  • The analyst supplies the obfuscated binary and the target function's address. Functions scoring below 0.9 on a dominator-based flattening heuristic are left unchanged, the dispatcher and state variable are located by structural assumptions about OLLVM's layout, and -a only follows calls into the .text section. Output is a patched copy in which the original function bytes are overwritten with int3 padding and the reassembled function is written at its start.
  • The samples folder bundles small obfuscated test programs for 32- and 64-bit Linux and Windows (CFF.bin, CFF_full.bin, CFF_full_linux64.bin, CFF_win.exe, CFF_win_full.exe, CFF_win64.exe and CFF_win64_full.exe), their deob_* outputs and C/C++ sources for most of them; a comment in CFF_full.c says Claude generated that test program. The README's only reported result is a before/after control-flow graph of target_function in CFF_full.bin, with no check that deobfuscated binaries behave like the originals.
  • Apache-2.0; the dependencies keep their own licenses, including GPL-2.0-only for Miasm and GPL-2.0 with a FOSS exception for Keystone.

About this entry

The description was reviewed against primary sources.

Report an outdated entry Suggest a translation fix

Primary sources

  1. README.md GitHub · cdong1012/ollvm-unflattener · Revision d006201
  2. requirements.txt GitHub · cdong1012/ollvm-unflattener · Revision d006201
  3. unflattener/__main__.py GitHub · cdong1012/ollvm-unflattener · Revision d006201
  4. unflattener/unflattener.py GitHub · cdong1012/ollvm-unflattener · Revision d006201
  5. unflattener/binrewrite.py GitHub · cdong1012/ollvm-unflattener · Revision d006201
  6. samples GitHub · cdong1012/ollvm-unflattener · Revision d006201
  7. samples/linux/CFF_full.c GitHub · cdong1012/ollvm-unflattener · Revision d006201
  8. LICENSE GitHub · cdong1012/ollvm-unflattener · Revision d006201
  9. https://github.com/cdong1012/ollvm-unflattener/releases/tag/v2.0
  10. LICENSE GitHub · cea-sec/miasm · Revision 3671fc2
  11. EXCEPTIONS-CLIENT GitHub · keystone-engine/keystone · Revision dc7932e

More in Native binaries

All 269 entries in Native binaries

↑↓ move↵ open⌘↵ new tab