Awesome

dewolf

dewolf is a research decompiler we developed during a research cooperation from 2019 to 2021 between Germany (Fraunhofer FKIE) and Singapore (DSO National Laboratories).

The restructuring of dewolf is based on the former DREAM/DREAM++ approach [Yakdan et al. NDSS 2015, IEEE (SP) 2016].

The decompiler dewolf is implemented as a plugin for Binary Ninja and uses their Medium-Level intermediate language as the starting point. Although we consider dewolf to be pretty stable, it is still a research prototype and not extensively optimized for production use. Consequently, you will likely observe a few bugs or even decompilation failures when applying dewolf on real-world binaries.

If you encounter any bugs, please report them to us so that we can further improve dewolf. :)

Installation

Dependencies

Before we start, please make sure you have the following dependencies installed and available on your computer:

At least Python 3.10
Latest stable release of Binary Ninja (>=3.4)
astyle for proper indentation of the decompiled code
libgraph-easy-perl only required for printing ASCII graphs

Under Linux (Ubuntu / Debian), you can use the following command to install both astyle and libgraph-easy-perl:

sudo apt install astyle libgraph-easy-perl

Under Windows, please make sure the astyle-binary has been added to the environment Path.

Binary Ninja Plugin

Follow the steps below to setup dewolf as a GUI plugin for Binary Ninja. Afterwards, you will be able to inspect decompiled code from a Binary Ninja dock.

Step 1:

Clone the dewolf repository into the Binary Ninja plugin folder which is located in one of the following paths corresponding to your operating system:

Linux: ~/.binaryninja/plugins MacOS: ~/Library/Application Support/Binary Ninja Windows: %APPDATA%\Binary Ninja

Attention: If you want to use a python virtual environment, make sure it is enabled for the next steps and also when starting Binary Ninja.

Step 2:

Install dewolf's python dependencies with:

pip install -r requirements.txt

Step 3:

Install Binary Ninja python API with:

python <binaryninja_path>/scripts/install_api.py [--install-on-pyenv if using virtualenv]

Warning: Changes made to the dewolf plugin only comes into effect after restarting the Binary Ninja GUI.

Usage

The dewolf decompiler can be used from both the command line and within Binary Ninja.

GUI

After enabling the dewolf decompilation widget via Tools > dewolf decompiler, the decompiled code for the currently active symbol will be displayed. In the dewolf widget, it is possible to navigate through functions by double-clicking them.

The automatic decompilation of selected functions can be toggled with the follow button. Decompiled code is cached and can be generated again with the decompile button, e.g. after patching instructions in the binary view.

Widget

CLI

For batch decompilation, it may be more convenient to utilize dewolf as a command line program. If you would like to use dewolf from the command line, you can invoke decompilation of an entire binary with the following command:

python decompile.py <path/to/binary>

If you wish to decompile a specific function, the function name can be provided as the second parameter:

python decompile.py <path/to/binary> <function_name>

By default, the generated code is displayed on the console. If you want to write the output to a file instead, you can specify it with the --output/-o flag. Please use the --help flag for more information.

Configuration

dewolf has multiple configuration options of which some are configurable via the GUI.

via GUI

You can configure dewolf from the Binary Ninja GUI by navigating to Edit > Preferences > Settings or by pressing <kbd>Ctrl</kbd> + <kbd>,</kbd>. Search for dewolf in the search bar and all dewolf related settings will be displayed.

Warning: Configurations made through Binary Ninja will not be taken into account when dewolf is started via command line interface. To configure dewolf when started via CLI, do as described in the following section.

via CLI

To apply settings for command line mode or using advanced settings not shown in the GUI, you can provide a config.json file in the decompiler root folder. The format of such a config file has to be as follows:

{
  "section.key": value,
  "expression-propagation.maximum_instruction_complexity": 5
}

All available settings can be found in decompiler/util/default.json.

Support

If you have any suggestions, or bug reports, please create an issue in the Issue Tracker.

In case you have any questions or other problems, feel free to send an email to:

dewolf@fkie.fraunhofer.de.