one_gadget

[![Downloads](https://img.shields.io/gem/dt/one_gadget)](https://rubygems.org/gems/one_gadget)


[![Gem Version](https://badge.fury.io/rb/one_gadget.svg)](https://badge.fury.io/rb/one_gadget)
[![Build Status](https://github.com/david942j/one_gadget/workflows/build/badge.svg)](https://github.com/david942j/one_gadget/actions)
[![Maintainability](https://qlty.sh/gh/david942j/projects/one_gadget/maintainability.svg)](https://qlty.sh/gh/david942j/projects/one_gadget)
[![Code Coverage](https://qlty.sh/gh/david942j/projects/one_gadget/coverage.svg)](https://qlty.sh/gh/david942j/projects/one_gadget)
[![API Docs](https://img.shields.io/badge/API-RubyDoc-blue.svg)](https://www.rubydoc.info/gems/one_gadget/)
[![MIT License](https://img.shields.io/badge/license-MIT-blue.svg)](http://choosealicense.com/licenses/mit/)

## OneGadget

When solving CTF pwn challenges we usually want a one-gadget RCE: a single address in
libc that, jumped to, calls `execve("/bin/sh", NULL, NULL)`.

This gem finds them for you, so you don't have to dig through objdump or IDA Pro every
time :wink:

Point it at a libc -- `one_gadget /path/to/libc` -- and enjoy the magic :laughing:

## Installation

Available on RubyGems.org!
```bash
$ gem install one_gadget
```

## Supported Architectures

- [x] i386
- [x] amd64 (x86-64)
- [x] aarch64 (ARMv8)
- [x] arm (ARMv7, A32/Thumb-2)
- [x] riscv64 (RV64GC)
- [x] mips (MIPS32 o32, big- and little-endian)

## Implementation

OneGadget symbolically executes the code around each candidate address to work out what
has to hold for the gadget to work.

Gadgets are found by walking the control-flow graph backward from each `exec`/`posix_spawn`
call, following conditional branches both ways. When a gadget is only reachable if a branch is
(not) taken, that decision shows up as an extra constraint, e.g. `x2 == 0x1`.

The article introducing how I develop this tool can be found [on my blog](https://david942j.blogspot.com/2017/02/project-one-gadget-in-glibc.html).

### Checked by running them

Constraints are only worth as much as they are complete, so the gadgets this repository
ships are verified by being run. [Aletheia](aletheia/README.md) loads the libc in a live
process, arranges exactly what a gadget's constraints ask for, poisons every register and
page they *don't* mention, jumps to the offset, and requires a real `/bin/sh` to come back
and list the root directory. A gadget whose constraint list is missing something fails
there instead of passing by luck -- which is how several missing constraints were found.

```bash
bundle exec rake aletheia:verify                # every libc under spec/data, level 0
bundle exec rake "aletheia:verify[1, aarch64]"  # one output level, one architecture
```

Aletheia is development tooling: it lives outside `lib/` and `bin/`, so it is not part of
the published gem.

## Usage

### Command Line Interface

```bash
$ one_gadget
# Usage: one_gadget <FILE|-b BuildID> [options]
#     -b, --build-id BuildID           BuildID