xgadget

crates.io GitHub Actions

Fast, parallel, cross-variant ROP/JOP gadget search for 8086 (16-bit), x86 (32-bit), and x64 (64-bit) binaries. Uses official Rust bindings for the zydis disassembler library.

Current state: decent test coverage, but still in beta :)

About

To the best of my knowledge, xgadget is the first gadget search tool to have these features:

Other features include:

API Usage

Find gadgets:

```rust use xgadget;

let maxgadgetlen = 5; let search_config = xgadget::SearchConfig::DEFAULT;

// Search single binary let bin1 = xgadget::Binary::frompathstr("/path/to/binv1").unwrap(); let bins = vec![bin1]; let gadgets = xgadget::findgadgets(&bins, maxgadgetlen, search_config).unwrap();

// Search for cross-variant gadgets let bin1 = xgadget::Binary::frompathstr("/path/to/binv1").unwrap(); let bin2 = xgadget::Binary::frompathstr("/path/to/binv2").unwrap(); let bins = vec![bin1, bin2]; let crossgadgets = xgadget::findgadgets(&bins, maxgadgetlen, search_config).unwrap(); ```

CLI Usage

Run xgadget --help:

``` xgadget v0.1.0

About: Fast, parallel, cross-variant ROP/JOP gadget search for 8086/x86/x64 binaries. CPUs: 8 logical, 8 physical

USAGE: xgadget [FLAGS] [OPTIONS]

FLAGS: -8, --8086 For raw (no header) files: assume 8086 (16-bit) [default: assumes x64 (64-bit)] -t, --att Display gadgets using AT&T syntax [default: Intel syntax] -h, --help Prints help information -i, --imm16 Include '{ret, ret far} imm16' (e.g. add to stack ptr) [default: don't include] -j, --jop Search for JOP gadgets only [default: ROP, JOP, and SYSCALL] -m, --partial-match Include cross-variant partial matches [default: full matches only] -r, --rop Search for ROP gadgets only [default: ROP, JOP, and SYSCALL] -p, --stack-pivot Filter to gadgets that write the stack ptr [default: all gadgets] -s, --sys Search for SYSCALL gadgets only [default: ROP, JOP, and SYSCALL] -V, --version Prints version information -x, --x86 For raw (no header) files: assume x86 (32-bit) [default: assumes x64 (64-bit)]

OPTIONS: -f, --str-filter Filter to gadgets containing a substring -l, --max-len Gadgets up to LEN instrs long. If 0: all gadgets, any length [default: 5]

ARGS:

CLI Build and Install

Build from source and install locally:

bash sudo apt-get install cmake # Ubuntu-specific, adjust for your package manager cargo install xgadget # Build on host (pre-req: https://www.rust-lang.org/tools/install)

CLI Binary Releases for Linux

Commits to this repo's master branch automatically run integration tests and build a dynamically-linked binary for 64-bit Linux. You can download it here and use the CLI immediately, instead of building from source. Static binaries for Linux and Windows may be supported in the future.

~~Yeah, but can it do 10 OS kernels in 30 seconds?!~~ Repeatable Benchmark Harness

bash bash ./benches/bench_setup_ubuntu.sh # Ubuntu-specific, download/build 10 kernel versions cargo bench # Grab a coffee, this'll take a while...

On an i7-9700K (8C/8T, 3.6GHz base, 4.9 GHz max, e.g. an older-gen consumer CPU) machine with gcc version 8.4.0: the average runtime, to process all ten 54MB kernels simultaneously with a max gadget length of 5 instructions and full-match search for all gadget types (ROP, JOP, and syscall gadgets), is only 26 seconds!

Note this is a statistical benchmark that samples from many iterations, and requires a lot of RAM (> 32GB). If you just want to run xgadget on the 10 kernels once, use ./benches/run_on_bench_kernels.sh.

Searching all 10 kernels for both partial and full matches is still in beta, no benchmarks yet (implemented but not yet optimized). Because of the performance hit and the lower utility of partial gadget matches, this search option is disabled by default. It can be enabled with the --partial-match flag for the CLI, or via setting a configuration bit, e.g. search_config |= xgadget::SearchConfig::PART, for the library API. Conversely, removing default options improves performance: searching all 10 kernels for only ROP gadgets (ignoring JOP and syscall gadgets) takes just 17 seconds. xgadget is designed to scale for large binaries while being easily configurable.

Acknowledgements

This project started as an optimized solution to Chapter 8, exercise 3 of "Practical Binary Analysis" by Dennis Andreisse [6], and builds on the design outlined therein.

References