Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/lifting-bits/anvill
anvill forges beautiful LLVM bitcode out of raw machine code
https://github.com/lifting-bits/anvill
decompiler llvm remill
Last synced: 6 days ago
JSON representation
anvill forges beautiful LLVM bitcode out of raw machine code
- Host: GitHub
- URL: https://github.com/lifting-bits/anvill
- Owner: lifting-bits
- License: agpl-3.0
- Created: 2019-10-19T03:46:47.000Z (over 5 years ago)
- Default Branch: master
- Last Pushed: 2024-09-03T21:03:44.000Z (5 months ago)
- Last Synced: 2025-01-27T05:45:19.501Z (13 days ago)
- Topics: decompiler, llvm, remill
- Language: LLVM
- Homepage:
- Size: 71.2 MB
- Stars: 345
- Watchers: 26
- Forks: 39
- Open Issues: 56
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# 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](https://github.com/lifting-bits/rellic.git).
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](https://github.com/lifting-bits/anvill/tree/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](https://slack.empirehacking.nyc/).
## 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](https://github.com/lifting-bits/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](https://git-scm.com/) | Latest |
| [CMake](https://cmake.org/) | 3.14+ |
| [Clang](http://clang.llvm.org/) | 12.0+ |
| [Remill](https://github.com/lifting-bits/remill) | Latest |
| [Python](https://www.python.org/) | 3.9 |
| [Ghidra](https://github.com/NationalSecurityAgency/ghidra) | Latest |
## Getting and Building the Code
### On Linux
First, update aptitude and get install the baseline dependencies.
```shell
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](https://github.com/lifting-bits/remill) properly installed the following steps provide a fresh build of Anvill.
```shell
# 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="/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:
```shell
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](https://github.com/lifting-bits/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.