RetDec

RetDec is a retargetable machine-code decompiler based on LLVM.

The decompiler is not limited to any particular target architecture, operating system, or executable file format:

• Supported file formats: ELF, PE, Mach-O, COFF, AR (archive), Intel HEX, and raw machine code.
• Supported architectures (32b only): Intel x86, ARM, MIPS, PIC32, and PowerPC.

Features:

• Static analysis of executable files with detailed information.
• Compiler and packer detection.
• Loading and instruction decoding.
• Signature-based removal of statically linked library code.
• Extraction and utilization of debugging information (DWARF, PDB).
• Reconstruction of instruction idioms.
• Detection and reconstruction of C++ class hierarchies (RTTI, vtables).
• Demangling of symbols from C++ binaries (GCC, MSVC, Borland).
• Reconstruction of functions, types, and high-level constructs.
• Integrated disassembler.
• Output in two high-level languages: C and a Python-like language.
• Generation of call graphs, control-flow graphs, and various statistics.

Requirements

• A compiler supporting C++14
  • On Windows, only Microsoft Visual C++ is supported (version >= Visual Studio 2015 Update 2).
• CMake (version >= 3.6)
• Perl
  • On Windows, Active Perl needs to be the first Perl in PATH, or it has to be provided to CMake using CMAKE_PROGRAM_PATH variable, e.g. -DCMAKE_PROGRAM_PATH=/c/perl/bin.
• GNU Bison, Flex, GNU Tar, wget, sha256sum.
  • On Windows, you can follow RetDec's Windows environment setup guide to help you get everything you need.

Additionally, to run the decompiler once it is built and installed the following tools are needed:

• GNU Bash, UPX, bc, dot.
  • As before, you can follow RetDec's Windows environment setup guide to help you get everything you need on Windows.

Build and Installation

• Recursively clone the repository (it contains submodules):
  • git clone --recursive https://github.com/avast-tl/retdec
• Linux:
  • cd retdec
  • mkdir build && cd build
  • cmake .. -DCMAKE_INSTALL_PREFIX=<path>
  • make && make install
• Windows:
  • Open MSBuild command prompt, or any terminal that is configured to run the msbuild command.
  • Make sure you can run required commands listed in the Requirements section.
  • cd retdec
  • mkdir build && cd build
  • cmake .. -DCMAKE_INSTALL_PREFIX=<path> -G<generator>
  • msbuild /m /p:Configuration=Release retdec.sln
  • msbuild /m /p:Configuration=Release INSTALL.vcxproj
  • Alternatively, you can open retdec.sln generated by cmake in Visual Studio IDE.

You must pass the following parameters to cmake:

• -DCMAKE_INSTALL_PREFIX=<path> to set the installation path to <path>.
• (Windows only) -G<generator> is -G"Visual Studio 14 2015" for 32-bit build using Visual Studio 2015, or -G"Visual Studio 14 2015 Win64" for 64-bit build using Visual Studio 2015. Later versions of Visual Studio may be used.

You can pass the following additional parameters to cmake:

• -DRETDEC_DOC=ON to build with API documentation (requires Doxygen and Graphviz, disabled by default).
• -DRETDEC_TESTS=ON to build with tests, including all the tests in dependency submodules (disabled by default).
• -DCMAKE_BUILD_TYPE=Debug to build with debugging information, which is useful during development. By default, the project is built in the Release mode. This has no effect on Windows, but the same thing can be achieved by running msbuild with the /p:Configuration=Debug parameter.
• -DCMAKE_PROGRAM_PATH=<path> to use Perl at <path> (probably useful only on Windows).

Usage Example

To decompile a binary file named test.bin run:

./decompile.sh test.bin

Run ./decompile.sh --help to list all the available options.

Repository Overview

This repository contains the following libraries:

• bin2llvmir -- library of LLVM passes for translating binaries into LLVM IR modules.
• debugformat -- library for uniform representation of DWARF and PDB debugging information.
• dwarfparser -- library for high-level representation of DWARF debugging information.
• llvm-support -- set of LLVM related utility functions.
• llvmir2hll -- library for translating LLVM IR modules to high-level source codes (C, Python-like language).

This repository contains the following tools:

• bin2llvmirtool -- frontend for the bin2llvmir library.
• llvm2hlltool -- frontend for the llvmir2hll library.

This repository contains the following scripts:

• decompile.sh -- the main decompilation script binding it all together. This is the tool to use for full binary-to-C decompilations.
• Support scripts used by decompile.sh:
  • color-c.py -- decorates output C sources with IDA color tags -- syntax highlighting for IDA.
  • config.sh -- decompiler's configuration file.
  • decompile-archive.sh -- decompiles objects in the given AR archive.
  • fileinfo.sh -- a Fileinfo tool wrapper.
  • signature-from-library.sh -- extracts function signatures from the given library.
  • unpack.sh -- tries to unpack the given executable file by using any of the supported unpackers.
• Other utility scripts:
  • decompile-all.sh -- decompiles all executables in the given directory and subdirectories.
  • run-unit-test.sh -- run all tests in the unit test directory.
  • utils.sh -- a collection of bash utilities.

Related repositories

• RetDec IDA plugin -- embeds RetDec into IDA (Interactive Disassembler) and makes its use much easier.
• RetDec Regression Tests -- provides means to run and create regression tests for RetDec and related tools. This is a must if you plan to contribute to the RetDec project.

License

Copyright (c) 2017 Avast Software, licensed under the MIT license. See the LICENSE file for more details.

RetDec uses third-party libraries or other resources listed, along with their licenses, in the LICENSE-THIRD-PARTY file.

Contributing

See RetDec contribution guidelines.

Acknowledgements

This software was supported by the research funding TACR (Technology Agency of the Czech Republic), ALFA Programme No. TA01010667.