Anvill

Anvill implements simple machine code lifting primitives using Remill. The goal of these components is to produce high quality bitcode, which can then be further decompiled to C (via Clang ASTs) using Rellic.

We define "high quality bitcode" as being similar in form to what the Clang compiler would produce if it were executed on a semantically equivalent C function.

Note on Specification Generation

The main branch of anvill consumes protobuf specifications generated by an in development Ghidra plugin that is currently closed source. You can checkout the tag: binja-final-version which has an open source specification generation script that uses Binary Ninja. We are hoping to release the Ghidra specification generation plugin soon!

Getting Help

If you are experiencing undocumented problems with Anvill then ask for help in the #binary-lifting channel of the Empire Hacking Slack.

Supported Platforms

Anvill is supported on Linux platforms and has been tested on Ubuntu 20.04.

Dependencies

Most of Anvill's dependencies can be provided by the cxx-common repository. Trail of Bits hosts downloadable, pre-built versions of the libraries for select operating systems, which makes it substantially easier to get up and running with Anvill. Nonetheless, the following table represents most of Anvill's dependencies.

Name	Version
Git	Latest
CMake	3.14+
Clang	12.0+
Remill	Latest
Python	3.9
Ghidra	Latest

Getting and Building the Code

On Linux

First, update aptitude and get install the baseline dependencies.

dpkg --add-architecture i386

sudo apt-get update
sudo apt-get upgrade

sudo apt-get install \
     git \
     python3.8 \
     python3-pip \
     wget \
     curl \
     build-essential \
     libtinfo-dev \
     lsb-release \
     zlib1g-dev \
     ccache \
     cmake \
     libc6-dev:i386 \
     'libstdc++-*-dev:i386' \
     g++-multilib

# Ubuntu 14.04, 16.04
sudo apt-get install realpath

Assuming we have Remill properly installed the following steps provide a fresh build of Anvill.

# clone anvill repository
git clone https://github.com/lifting-bits/anvill.git

# update the git submodules
git submodule update --init --recursive

# create a build dir
mkdir anvill-build && cd anvill-build

# configure
CC=clang cmake ../anvill

# build
make -j 5

# install
sudo make install

Or you can tell CMake where to find the remill installation prefix by passing -Dremill_DIR="<remill_prefix>/lib/cmake/remill" during configuration.

Running tests

1. Configure with the following parameter: -DANVILL_ENABLE_TESTS=true
2. Run the test target: cmake --build build_folder --target test

Docker image

To build via Docker run, specify the architecture, base Ubuntu image and LLVM version. For example, to build Anvill linking against LLVM 14 on Ubuntu 20.04 on AMD64 do:

ARCH=amd64; UBUNTU_VERSION=20.04; LLVM=14; \
   docker build . \
   -t anvill-llvm${LLVM}-ubuntu${UBUNTU_VERSION}-${ARCH} \
   -f Dockerfile \
   --build-arg UBUNTU_VERSION=${UBUNTU_VERSION} \
   --build-arg ARCH=${ARCH} \
   --build-arg LLVM_VERSION=${LLVM}

anvill-specify-bitcode (Currently unsupported)

anvill-specify-bitcode is a tool that produces specifications for all functions contained in an LLVM bitcode module. The purpose of this tool is to enable the creation of a database of specifications for commonly used, often externally- defined functions in binaries (e.g. libc, libc++, libstdc++) in binaries lifted by McSema.

This tool also exists for enabling function declarations for binary code to be written in C or C++, and then translated down into the specification form within a decompiler toolchain.

Finally, this tool exists to enable round-trip testing of LLVM's ISEL lowering and code generation for arbitrary functions.