roachspray/remill

Machine code to LLVM binary translator

Remill

Remill is a static binary translator that translates machine code into LLVM bitcode. It translates x86 and amd64 machine code (including AVX and AVX512) into LLVM bitcode.

Build Status

	master
Linux
macOS

Additional Documentation

• How to contribute
• How to implement the semantics of an instruction
• How instructions are lifted
• How binaries are represented
• The design and architecture of Remill

Getting Help

If you are experiencing undocumented problems with Remill then ask for help in the #tool-remill channel of the Empire Hacking Slack.

Supported Platforms

Remill is supported on Linux platforms and has been tested on Ubuntu 14.04 and 16.04.

We are actively working on porting Remill to macOS.

Dependencies

Name	Version
Git	Latest
CMake	3.2+
Google Log	0.3.3
Google Test	1.6.0
Google Protobuf	2.4.1
LLVM	3.9
Clang	3.9
Intel XED	2016-02-02
Python	2.7
Python Package Index	Latest
python-magic	Latest
Unzip	Latest
python-protobuf	2.4.1
Binary Ninja	Latest
IDA Pro	6.7+

Getting and Building the Code

Step 1: Install dependencies

On Linux

Install Dependencies

sudo apt-get update
sudo apt-get upgrade

sudo apt-get install \
     git \
     cmake \
     libgoogle-glog-dev \
     libgtest-dev \
     libprotoc-dev libprotobuf-dev libprotobuf-dev protobuf-compiler \
     python2.7 python-pip \
     g++-multilib \
     unzip \
     software-properties-common \
     realpath

sudo pip install --upgrade pip

sudo pip install python-magic 'protobuf==2.4.1'

Upgrade CMake (Ubuntu 14.04)

Users wishing to run Remill on Ubuntu 14.04 should upgrade their version of CMake.

sudo add-apt-repository -y ppa:george-edison55/cmake-3.x
sudo apt-get update
sudo apt-get upgrade
sudo apt-get install cmake

On OS X

Install Dependencies

brew install glog
brew install protobuf

Step 2: Clone and Enter the Repository

Clone the repository

git clone git@github.com:trailofbits/remill.git

Enter the repository

cd remill

Run the Build Script

./build.sh

Step 3: Install the disassembler

cd ..
sudo python tools/setup.py install

Building and Running the Test Suite

Build Google Test

On Linux

This script will build and install the Google Test framework. It will request administrator permissions.

./scripts/unix/install_gtest.sh

Generate and Run the Test Cases

./scripts/x86/generate_tests.sh
./scripts/x86/run_tests.sh

Try it Out

TODO(pag): Make remill-lift.