# 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.

- Type: Tool
- Targets: Binary
- Category: Native analysis tools
- Relationship: Foundation tool
- Sources reviewed: 2026-10-20
- Added to the catalog: 2026-11-02
- Original resource: <https://github.com/cdong1012/ollvm-unflattener>
- Primary source: <https://github.com/cdong1012/ollvm-unflattener/blob/d0062012b66ab2c845207c733216900d5e99f0a9/README.md>
- Catalog page: <https://awesomerea.org/resources/ollvm-unflattener/>
- Record JSON: <https://awesomerea.org/resources/ollvm-unflattener/record.json>
- Chinese version: [简体中文](https://awesomerea.org/zh/resources/ollvm-unflattener/index.md)

## 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.

## Primary sources

1. <https://github.com/cdong1012/ollvm-unflattener/blob/d0062012b66ab2c845207c733216900d5e99f0a9/README.md>
2. <https://github.com/cdong1012/ollvm-unflattener/blob/d0062012b66ab2c845207c733216900d5e99f0a9/requirements.txt>
3. <https://github.com/cdong1012/ollvm-unflattener/blob/d0062012b66ab2c845207c733216900d5e99f0a9/unflattener/__main__.py>
4. <https://github.com/cdong1012/ollvm-unflattener/blob/d0062012b66ab2c845207c733216900d5e99f0a9/unflattener/unflattener.py>
5. <https://github.com/cdong1012/ollvm-unflattener/blob/d0062012b66ab2c845207c733216900d5e99f0a9/unflattener/binrewrite.py>
6. <https://github.com/cdong1012/ollvm-unflattener/tree/d0062012b66ab2c845207c733216900d5e99f0a9/samples>
7. <https://github.com/cdong1012/ollvm-unflattener/blob/d0062012b66ab2c845207c733216900d5e99f0a9/samples/linux/CFF_full.c>
8. <https://github.com/cdong1012/ollvm-unflattener/blob/d0062012b66ab2c845207c733216900d5e99f0a9/LICENSE>
9. <https://github.com/cdong1012/ollvm-unflattener/releases/tag/v2.0>
10. <https://github.com/cea-sec/miasm/blob/3671fc24d6e625c2d75f3311724eb6b0c97664f8/LICENSE>
11. <https://github.com/keystone-engine/keystone/blob/dc7932ef2b2c4a793836caec6ecab485005139d6/EXCEPTIONS-CLIENT>

## More in Native binaries

- [GolangAnalyzerExtension](https://awesomerea.org/resources/ghidra-golanganalyzerextension/index.md) · Tool
- [IDA iOS Helper](https://awesomerea.org/resources/ida-ios-helper/index.md) · Tool
- [MAMBO](https://awesomerea.org/resources/mambo/index.md) · Tool
- [Class Informer](https://awesomerea.org/resources/class-informer/index.md) · Tool
- [Kam1n0](https://awesomerea.org/resources/kam1n0/index.md) · Tool
- [iblessing](https://awesomerea.org/resources/iblessing/index.md) · Tool

## About this entry

The description was reviewed against primary sources.
Original editorial content: MIT. Linked projects, papers and assets retain their own rights and licenses.