RetDec : RetDec Is A Retargetable Machine-Code Decompiler Based On LLVM

RetDec is a retargetable machine-code de compiler based on LLVM. The de-compiler 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:
  • 32-bit: Intel x86, ARM, MIPS, PIC32, and PowerPC
  • 64-bit: x86-64, ARM64 (AArch64)

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.

Installation & Use

Currently, we support Windows (7 or later), Linux, macOS, and (experimentally) FreeBSD. An installed version of RetDec requires approximately 4 GB of free disk space.

Windows

• Either download and unpack a pre-built package, or build and install the decompiler by yourself (the process is described below).
• Install Microsoft Visual C++ Redistributable for Visual Studio 2017.
• Install the following programs:
  • Python (version >= 3.4)
  • UPX (Optional: if you want to use UPX unpacker in the preprocessing stage)
  • Graphviz (Optional: if you want to generate call or control flow graphs)
• Now, you are all set to run the decompiler. To decompile a binary file named test.exe, run the following command (ensure that python runs Python 3; as an alternative, you can try py -3) python $RETDEC_INSTALL_DIR/bin/retdec-decompiler.py test.exe For more information, run retdec-decompiler.py with --help.

Linux

• Either download and unpack a pre-built package, or build and install the decompiler by yourself (the process is described below).
• After you have built the decompiler, you will need to install the following packages via your distribution’s package manager:
  • Python (version >= 3.4)
  • UPX (Optional: if you want to use UPX unpacker in the preprocessing stage)
  • Graphviz (Optional: if you want to generate call or control flow graphs)
• Now, you are all set to run the decompiler. To decompile a binary file named test.exe, run $RETDEC_INSTALL_DIR/bin/retdec-decompiler.py test.exe For more information, run retdec-decompiler.py with --help.

macOS

• Either download and unpack a pre-built package, or build and install the decompiler by yourself (the process is described below).
• After you have built the decompiler, you will need to install the following packages:
  • Python (version >= 3.4)
  • UPX (Optional: if you want to use UPX unpacker in the preprocessing stage)
  • Graphviz (Optional: if you want to generate call or control flow graphs)
• Now, you are all set to run the decompiler. To decompile a binary file named test.exe, run $RETDEC_INSTALL_DIR/bin/retdec-decompiler.py test.exe For more information, run retdec-decompiler.py with --help.

FreeBSD (Experimental)

• There are currently no pre-built “ports” packages for FreeBSD. You will have to build and install the decompiler by yourself. The process is described below.
• After you have built the decompiler, you may need to install the following packages and execute the following command: sudo pkg install python37 sudo ln -s /usr/local/bin/python3.7 /usr/local/bin/python3
• Now, you are all set to run the decompiler. To decompile a binary file named test.exe, run $RETDEC_INSTALL_DIR/bin/retdec-decompiler.py test.exe For more information, run retdec-decompiler.py with --help.

Build in Docker

Docker support is maintained by community. If something does not work for you or if you have suggestions for improvements, open an issue or PR.

Build Image

Building in Docker does not require installation of the required libraries locally. This is a good option for trying out RetDec without setting up the whole build tool chain.

To build the RetDec Docker image, run

docker build -t retdec – < Dockerfile

This builds the image from the master branch of this repository.

To build the image using the local copy of the repository, use the development Dockerfile, Dockerfile.dev:

docker build -t retdec:dev . -f Dockerfile.dev

Run Container

If your uid is not 1000, make sure that the directory containing your input binary files is accessible for RetDec:

chmod 0777 /path/to/local/directory

Now, you can run the decompiler inside a container:

docker run –rm -v /path/to/local/directory:/destination retdec retdec-decompiler.py /destination/binary

Note: Do not modify the /destination part is. You only need to change /path/to/local/directory. Output files will then be generated to /path/to/local/directory.

Automated TeamCity Builds

Our TeamCity servers are continuously generating up-to-date RetDec packages from the latest commit in the master branch. These are mostly meant to be used by RetDec developers, contributors, and other people experimenting with the product (e.g. testing if an issue present in the official release still exists in the current master).

You can use these as you wish, but keep in mind that there are no guarantees they will work on your system (especially the Linux version), and that regressions are a possibility. To get a stable RetDec version, either download the latest official pre-built package or build the latest RetDec version tag.

• Windows Server 2016, version 10.0
• Ubuntu Bionic Linux, version 18.04
• Mac OS X, version 10.14.6

Repository Overview

This repository contains the following libraries:

• ar-extractor – library for extracting object files from archives (based on LLVM).
• bin2llvmir – library of LLVM passes for translating binaries into LLVM IR modules.
• capstone2llvmir – binary instructions to LLVM IR translation library.
• config – library for representing and managing RetDec configuration databases.
• cpdetect – library for compiler and packer detection in binaries.
• crypto – collection of cryptographic functions.
• ctypes – C++ library for representing C function data types.
• debugformat – library for uniform representation of DWARF and PDB debugging information.
• demangler – demangling library capable to handle names generated by the GCC/Clang, Microsoft Visual C++, and Borland C++ compilers.
• dwarfparser – library for high-level representation of DWARF debugging information.
• fileformat – library for parsing and uniform representation of various object file formats. Currently supporting the following formats: COFF, ELF, Intel HEX, Mach-O, PE, raw data.
• llvm-support – set of LLVM related utility functions.
• llvmir-emul – LLVM IR emulation library used for unit testing.
• llvmir2hll – library for translating LLVM IR modules to high-level source codes (C, Python-like language).
• loader – library for uniform representation of binaries loaded to memory. Supports the same formats as fileformat.
• macho-extractor – library for extracting regular Mach-O binaries from fat Mach-O binaries (based on LLVM).
• patterngen – binary pattern extractor library.
• pdbparser – Microsoft PDB files parser library.
• stacofin – static code finder library.
• unpacker – collection of unpacking functions.
• utils – general C++ utility library.

This repository contains the following tools:

• ar-extractortool – frontend for the ar-extractor library (installed as retdec-ar-extractor).
• bin2llvmirtool – frontend for the bin2llvmir library (installed as retdec-bin2llvmir).
• bin2pat – tool for generating patterns from binaries (installed as retdec-bin2pat).
• capstone2llvmirtool – frontend for the capstone2llvmir library (installed as retdec-capstone2llvmir).
• configtool – frontend for the config library (installed as retdec-config).
• ctypesparser – C++ library for parsing C function data types from JSON files into ctypes representation (installed as retdec-ctypesparser).
• demangler_grammar_gen — tool for generating new grammars for the demangler library (installed as retdec-demangler-grammar-gen).
• demanglertool — frontend for the demangler library (installed as retdec-demangler).
• fileinfo – binary analysis tool. Supports the same formats as fileformat (installed as retdec-fileinfo).
• idr2pat – tool for extracting patterns from IDR knowledge bases (installed as retdec-idr2pat).
• llvmir2hlltool – frontend for the llvmir2hll library (installed as retdec-llvmir2hll).
• macho-extractortool – frontend for the macho-extractor library (installed as retdec-macho-extractor).
• pat2yara – tool for processing patterns to YARA signatures (installed as retdec-pat2yara).
• stacofintool – frontend for the stacofin library (installed as retdec-stacofin).
• unpackertool – plugin-based unpacker (installed as retdec-unpacker).

This repository contains the following scripts:

• retdec-decompiler.py – the main decompilation script binding it all together. This is the tool to use for full binary-to-C decompilations.
• Support scripts used by retdec-decompiler.py:
  • retdec-color-c.py – decorates output C sources with IDA color tags – syntax highlighting for IDA.
  • retdec-config.py – decompiler’s configuration file.
  • retdec-archive-decompiler.py – decompiles objects in the given AR archive.
  • retdec-fileinfo.py – a Fileinfo tool wrapper.
  • retdec-signature-from-library-creator.py – extracts function signatures from the given library.
  • retdec-unpacker.py – tries to unpack the given executable file by using any of the supported unpackers.
  • retdec-utils.py – a collection of Python utilities.
• retdec-tests-runner.py – run all tests in the unit test directory.
• type_extractor – generation of type information (for internal use only)