OpenREIL

OpenREIL is open source library that implements translator and tools for REIL (Reverse Engineering Intermediate Language).

About
Installation
- Linux and OS X
- Windows
IR format
C API
Python API
Debugging OpenREIL
Using with third party tools
Links and examples
TODO

About <a id="_1"></a>

REIL was initially developed by Zynamics as part of their BinNavi framework, proprietary code analysis software written in Java. To learn more about REIL read the following documents:

«REIL − The Reverse Engineering Intermediate Language» (link)
«The REIL language» (part 1, part 2, part 3, part 4)
«Applications of the Reverse Engineering Language REIL» (PDF)
«REIL: A platform-independent intermediate representation of disassembled code for static code analysis» (PDF)

However, after Zynamics was acquired by Google they abandoned BinNavi, so, I decided to develop my own implementation of REIL. I made it relatively small and portable in comparison with original, the translator itself is just a single library written in C++, it can be statically linked with any program for static or dynamic code analysis. The higher level API of OpenREIL is written in Python, so, it can be easily utilized in plugins and scripts for your favourite reverse engineering tool (almost all modern debuggers and disassemblers has Python bindings).

OpenREIL is not a 100% compatible with Zynamics REIL, it has the same ideology and basics, but there's some changes in IR instruction set and representation of the traget hardware platform features.

OpenREIL is based on my custom fork of libasmir − IR translation library from old versions of BAP framework. I removed some 3-rd party dependencies of libasmir (libbfd, libopcodes) and features that irrelevant to translation itself (binary files parsing, traces processing, etc.), than I did some minor refactoring/bugfixes, switched to Capstone for instruction length disassembling and implemented BAP IR → REIL translation logic on the top of libasmir.

Because libasmir uses VEX (production-quality library, part of Valgrind), full code translation sequence inside of OpenREIL is looks as binary → VEX IR → BAP IR → REIL. It's kinda ugly from engineering point of view, but it allows us to have a pretty robust and reliable support of all general instructions of x86. Current version of OpenREIL still has no support of other architectures, but I'm working on x86_64 and ARMv7.

UPDATE: Current version of OpenREIL already has much or less usable ARMv7 support with dynamic switching of translation context between ARM and Thumb execution modes. There is no proper documentation on ARM yet, but you can check some unit tests for this functionality as usage examples: 1, 2, 3

Please note, that currently OpenREIL is a far away from stable release, so, I don't recommend you to use it for any serious purposes.

Installation <a id="_2"></a>

OpenREIL supports Linux, Mac OS X and Windows. Structure of the project source code directory:

VEX − VEX source code with BAP patches applied.
capstone − Capstone engine source code will be downloaded here.
docs − documentation directory.
libasmir − libasmir source code.
libopenreil − OpenREIL translator source code.
pyopenreil − OpenREIL Python API.
tests − unit tests launcher and stand-alone test programs.

Linux and OS X <a id="_2_1"></a>

To build OpenREIL under *nix operating systems you need to install git, gcc, make, Python 2.x with header files, NumPy and Cython. After that you can run configure and make just as usual.

Example for Debian:

$ sudo apt-get install git gcc make python python-dev python-numpy cython
$ git clone https://github.com/Cr4sh/openreil.git
$ cd openreil
$ ./autogen.sh
$ ./configure
$ make
$ make test
$ sudo make install

If you planning to use MongoDB as IR code storage you need to install some additional dependencies:

$ sudo apt-get install mongodb python-pymongo python-setuptools
$ sudo easy_install cachetools

OpenREIL can be used not only for debugger/disassembler plugins, but also for standalone code analysis tools. For loading of executable files it uses pybfd (ELF, Mach-O) and pefile (Portable Execute) Python libraries:

$ sudo apt-get install libbfd-dev
$ sudo easy_install pefile pybfd

Windows <a id="_2_2"></a>

Building OpenREIL on Windows requires MinGW build environment and all of the dependencies that was mentioned above.

You also can download compiled Win32 binaries of OpenREIL:

IR format <a id="_3"></a>

Available instructions <a id="_3_1"></a>

REIL language traditionally uses three address form of IR instruction where arguments a and b are source, and c is destination.

Example of IR code for mov eax, ecx x86 instruction:

;
; asm: mov eax, ecx
; data (2): 89 c8
;
00000000.00     STR         R_ECX:32,                 ,          V_00:32
00000000.01     STR          V_00:32,                 ,         R_EAX:32

OpenREIL offers 23 different instructions:

| Mnemonic | Pseudocode | Instruction description | |-----------|----------------------|-----------------------------| | STR | c = a | Store to register | | STM | *c = a | Store to memory | | LDM | c = *a | Load from memory | | ADD | c = a + b | Addition | | SUB | c = a − b | Subtraction | | NEG | c = −a | Negation | | MUL | c = a * b | Multiplication | | DIV | c = a / b | Division | | MOD | c = a % b | Modulus | | SHL | c = a << b | Shift left | | SHR | c = a >> b | Shift right | | AND | c = a & b | Binary AND | | OR | c = a | b | Binary OR | | XOR | c = a ^ b | Binary XOR | | NOT | c = ~a | Binary NOT | | EQ | c = a == b | Equation | | LT | c = a < b | Less than | | SMUL | c = a * b | Signed multiplication | | SDIV | c = a / b | Signed division | | SMOD | c = a % b | Signed modulus | | JCC | | Jump to c if a is not zero | | NONE | | No operation | | UNK | | Untranslated instruction |

Each instruction argument can have 1, 8, 16, 32 or 64 bits of length. Most of arithmetic instructions operates with unsigned arguments. SMUL, SDIV and SMOD instructions operates with signed arguments in two’s complement signed number representation form.

Most of instructions supposes the same size of their source and destination arguments, but there’s a several exceptions:

Result (argument c) of EQ and LT instructions always has 1 bit size.
Argument a of STM and argument c of LDM must have 8 bits or gather size (obviously, there is no memory read/write operations with single bit values).
Result of OR instruction can have any size. It may be less, gather or equal than size of it’s input arguments.

OpenREIL uses OR operation for converting to value of different size. For example, converting value of 8 bit argument V_01 to 1 bit argument V_02 (1-7 bits of V_01 will be ignored):

00000000.00      OR           V_01:8,              0:8,           V_02:1

Converting 1 bit argument V_02 to 32 bit argument V_03 (1-31 bits of V_03 will be zero extended):

00000000.00      OR           V_02:1,

Openreil

Install / Use

README