CodeReason

CodeReason is a semantic binary code analysis framework and toolset. The tool RopTool discovers ROP gadgets in ARM, X86 and X86-64 binaries by providing pre- and post-conditions for the CPU and memory context using Lua scripts. Examples of other tools that can be created with CodeReason are available in the tools/ directory.

Building

CodeReason builds on Linux and OS X. Windows are builds currently broken. Help us fix them!

Requirements

• LibVEX with custom patches to support static analysis
• gtest for unit tests
• lua for the user interface
• protobuf
• boost
• capstone for pretty printing disassembly

Ubuntu

sudo ./install_deps.sh
./make.sh

OS X

brew update && brew install cmake boost protobuf git
./install_vex.sh
./make.sh

Several helper scripts are available: install_deps.sh installs Ubuntu dependencies, make.sh creates a full build, recompile.sh recompiles CodeReason, and package.sh creates a debian package. See our Travis-CI configuration for more details about building.

Usage

Lua scripting

The Lua script bindings are defined in libs/VEE/VEElua.cpp. These bindings provide a way of describing CPU register values and memory contents to the VEX Execution Engine (VEE) which analyzes binary code.

The most common functions are:

• putreg - Writes value to a register vee.putreg(v, R1, 32, 80808080)
• putmem - Writes a value at an address vee.putmem(v, 0x40000000, 32, 0x20202020)
• getreg - Read value from a register vee.getreg(v, R15, 32)
• getmem - Read a value from memory vee.getmem(v, 0x40000000, 32)

For additional examples, check the scripts/ directory.

RopTool

RopTool takes in a binary and a Lua script as input and will output results to stdout.

Example usage:

./build/bin/RopTool -a x64 -c ./scripts/x64/call_reg.lua -f ./tests/ELF/ls_x64

BlockExtract

BlockExtract reads in a binary and outputs a database file containing block information. This can be useful when analyzing large binaries that take a long time to extract code blocks. Currently only 64-bit block extraction is supported.

Example usage:

./build/bin/BlockExtract -f ./tests/ELF/ls_x64 -a x64  --blocks-out ./blockdbfile

BlockReader

BlockReader consumes the block database created by BlockExtract. It may be useful when debugging information stored inside of blocks. VEX output is printed to stdout.

Example usage:

./build/bin/BlockReader -d ./blockdbfile

ImgTool

ImgTool is a test program that prints information about executable code sections found in a binary.

Example usage:

./build/bin/ImgTool -a x64 -f ./tests/MachO/ls_FAT_x86_x64

Example output:

In file ./tests/MachO/ls_FAT_x86_x64
found 6 +X sections
------------------
Section of arch AMD64
beginning at 0x1778 of size 0x3635
------------------
Section of arch AMD64
beginning at 0x4dae of size 0x1bc
------------------
Section of arch AMD64
beginning at 0x4f6c of size 0x2f4
------------------
Section of arch AMD64
beginning at 0x5260 of size 0x568
------------------
Section of arch AMD64
beginning at 0x57c8 of size 0x a0
------------------
Section of arch AMD64
beginning at 0x5868 of size 0x798
------------------

References

Semantic Analysis of Native Programs, introducing CodeReason

Authors

Originally developed by Andrew Ruef under contract for DARPA Cyber Fast Track.

Contributions made by:

• Markus Gaasedelen
• Jay Little
• Peter Goodman
• Nick Anderson
• Santiago Torres
• Luke Mladek