IRENE-3

IRENE-3 is a decompilation tool that ties together Anvill, Remill, Rellic, and Ghidra to create an interface for defining binary patches directly in Ghidra. Patch definitions localize user desired semantics to an exact region within the target binary. The user edits decompilation of patch region to define a patch in C. A patch definition generated by the Ghidra plugin contains the new user provided semantics for the region along with the region's location and variable information.

The user can also define smaller patch regions in order to create smaller sub-block patches.

Goals

• Decompile "patch regions" accurately, recording all assumptions the decompiler makes about the state of the program at entry and exit to the region.
• Provide high-level C-like output for patch regions while remaining localizable
• Communicate user semantics and patch context to patch compilers in a convenient format
• Provide as many features as possible directly in Ghidra

Anti-Goals

• Full Binary Recompilation
• Provide UI components outside of Ghidra
• Global analysis capabilities of decompilation or lifting (analysis should be local to a patch region after committing to that region's assumptions)

Repository Layout

• irene-ghidra a Ghidra plugin for exporting first layer specifications from Ghidra to bootstrap decompilation.
• bin contains C++ code for different binary utilities
• lib contains C++ code for the library
• include contains public headers for the library
• scripts contains miscellaneous scripts for installing prerequisites and running tests
• cmake contains CMake helpers

Installing IRENE from a Release

Please see the installation instructions

IRENE Build Instructions (Docker)

Building and Installing the Ghidra Plugin

Set your Ghidra path either by updating GHIDRA_INSTALL_DIR in gradle.properties or set the environment variable then run:

just install-irene3-ghidra

Build Docker Image

just build-docker

Decompile a test specification to C

docker run irene3:latest \
    /opt/trailofbits/bin/irene3-server --help

IRENE Usage Instructions

Usage directions are located here.

IRENE Build Instructions (Native)

Install prerequisites

./scripts/install-prereqs.sh
just install-prereqs

Build + Install IRENE3

just install-irene3

Verify Installation

To verify installation worked, first we run the unit tests:

# test the IRENE3 Ghidra Plugin
just test-irene3-ghidra

# test the C++ Decompilation Portion
just test-irene3-cpp

Decompile a Binary to C

just decompile-binary ./tests/bins/test-hello-elf-x64 o.c
just decompile-binary-ll ./tests/bins/test-hello-elf-x64 o.ll
just decompile-spec ./tests/specs/test-hello-elf-x64.spec.json o.c
just decompile-spec-ll ./tests/specs/test-hello-elf-x64.spec.json o.ll

IRENE Ghidra Development Instructions

Install just with brew install just and get a copy of Ghidra (Currently 10.1.5) from Ghidra Releases

Then add gradle.properties to the assume unchanged list with git update-index --assume-unchanged gradle.properties

Afterwards you can modify gradle.properties with the path to your Ghidra install without having those changes pushed to main.

You can also set the GHIDRA_INSTALL_DIR environment variable, but your IDE may not recognize the environment variable.

just test-irene3-ghidra will run the unit tests for the plugin.

Provided your gradle.properties file is up to date any Scala IDE should work without any setup. Given the mixing of Java and Scala an IDE that supports both is ideal. VScode with Metals + the Java extension pack works well.

MacOS Instructions

brew tap homebrew/cask-versions
brew install --cask temurin17

IRENE C++ Development Instructions

• Run ./scripts/install-prereqs.sh to install just
• Install the rest of the dependencies with just install-prereqs
• Install BinaryNinja and install it to the python3 path
• (Optional) Set path to CMAKE_INSTALL_PREFIX in .env, this determines where the compiled artifacts will be installed to
• (M1 Only) Set path to VCPKG_ROOT to compiled cxx-common
• Build and install IRENE3 just install-irene3

just build-irene3-cpp will compile the C++ project just install-irene3-cpp will compile and install the C++ project to ./install/bin the specified install prefix just test-irene3-cpp will do a simple test for output on some sample specifications and a simple roundtrip test

Acknowledgements:

This research was developed with funding from the Defense Advanced Research Projects Agency (DARPA). The views, opinions, and/or findings contained in this material are those of the authors and should not be interpreted as representing the official views or policies of the Department of Defense or the U.S. Government.

Distribution Statement A – Approved for Public Release, Distribution Unlimited