AwesomeREA.org

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. This entry covers analysis of code the analyst is entitled to study, and rewritten functions are analysis aids rather than verified equivalents. No binaries were deobfuscated or run, and the reviewed sources establish no REA connection.

About this entry

The description was reviewed against primary sources. This does not establish runtime testing, security auditing or verified compatibility.

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 122 entries in Native binaries