Skip to content
This repository has been archived by the owner. It is now read-only.
Go to file

Latest commit


Failed to load latest commit information.
Latest commit message
Commit time


Build Status Coverity Scan Build Status Slack Chat

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.


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



sudo ./


brew update && brew install cmake boost protobuf git

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


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 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 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 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 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


Semantic Analysis of Native Programs, introducing CodeReason


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

Contributions made by:

You can’t perform that action at this time.