Metadata-Version: 2.3
Name: ropinator
Version: 0.1.0
Summary: A better way to build a ROP chain.
Author: Jeremy Dunn
Author-email: Jeremy Dunn <jeremy.dunn315@gmail.com>
Requires-Dist: capstone>=5.0.6
Requires-Dist: cmd2>=3.2.0
Requires-Dist: keystone-engine>=0.9.2
Requires-Dist: z3-solver>=4.15.4.0
Requires-Python: >=3.13
Description-Content-Type: text/markdown

# ropinator

ROP gadget finder with constraint-based semantic search.

Finds gadgets in ELF, PE, Mach-O, and raw binaries across x86, ARM, MIPS,
PowerPC, and RISC-V. Includes a Z3-backed symbolic execution engine for
searching gadgets by behavior rather than text patterns.

## Install

```
pip install ropinator
```

Requires Python 3.13+.

## Usage

Find gadgets:

```
ropinator -f binary.elf
```

Set search depth (max instructions per gadget, default 3):

```
ropinator -f binary.elf -d 5
```

Custom base address:

```
ropinator -f binary.elf -b 0x400000
```

Export to file:

```
ropinator -f binary.elf -o gadgets.txt
```

Load previously exported gadgets:

```
ropinator -f binary.elf -g gadgets.txt --start-solver
```

Load gadgets without the original binary (requires `--arch`):

```
ropinator --arch x86_64 -g gadgets.txt --start-solver
```

Override architecture detection:

```
ropinator -f binary.raw --arch arm -b 0x10000
```

Expand all gadget addresses:

```
ropinator -f binary.elf -a
```

## Constraint Solver

Launch the interactive solver to search gadgets by semantic behavior:

```
ropinator -f binary.elf --start-solver
```

### Commands

| Command | Description |
|---------|-------------|
| `move [dst] [src]` | Find register-to-register moves |
| `const <dst> <value>` | Find gadgets that load a constant |
| `load <dst> <src> [offset]` | Find memory read gadgets |
| `show <index>` | Inspect symbolic register state |
| `export <file>` | Export results to file |
| `registers` | List available registers |

### Examples

```
rop> move rax rbx
Found 3 move gadget(s):

  [0] 0x0000000000401000: rax <- rbx | mov rax, rbx ; ret
  [1] 0x0000000000401020: rax <- rbx | push rbx ; pop rax ; ret
  [2] 0x0000000000401040: rax <- rbx | xchg rax, rbx ; xchg rax, rbx ; mov rax, rbx ; ret
```

```
rop> const rax 0xdeadbeef
Found 1 constant-loading gadget(s):

  [0] 0x0000000000401234: rax = 0xdeadbeef | pop rax ; ret
```

```
rop> load rax rbx 0x10
Found 2 load gadget(s):

  [0] 0x0000000000402000: rax <- [rbx + 0x10] | mov rax, qword ptr [rbx + 0x10] ; ret
  [1] 0x0000000000402030: rax <- [rbx + 0x10] | lea rcx, [rbx + 0x10] ; mov rax, qword ptr [rcx] ; ret
```

```
rop> show 0
Result [0]
  Address:      0x0000000000401000
  Instructions: mov rax, rbx ; ret
  Move:         rax <- rbx

  Register state after execution:
    rax    = rbx
    rbx    = rbx  (unchanged)
    rcx    = rcx  (unchanged)
    ...
```

## Supported Formats

| Format | Description |
|--------|-------------|
| **ELF** | Linux, BSD, embedded |
| **PE** | Windows executables and DLLs |
| **Mach-O** | macOS, iOS |
| **Raw** | Flat binaries (use with `-b` to set base address) |

## Supported Architectures

**Gadget finding:** x86 (16/32/64-bit), ARM (32/64/Thumb), MIPS (32/64),
PowerPC (32/64), RISC-V (32/64).

**Constraint solver:** x86-64. Other architectures planned.

## Options

```
-f, --file FILE           Binary to analyze (required unless --arch and -g are used)
-b, --base ADDR           Override base address
-d, --depth N             Max gadget depth (default: 3)
-a, --all                 Expand all gadget addresses
-o, --output FILE         Export gadgets to file
-g, --gadgets-file FILE   Load gadgets from exported file instead of searching
--arch ARCH               Override architecture detection (see below)
--start-solver            Launch constraint solver shell
```

Architecture names for `--arch`:

| Name | Aliases |
|------|---------|
| x86_64 | x86-64, x64 |
| x86 | i386 |
| ARM64 | aarch64 |
| ARM32 | arm |
| ThumbBE | thumb-be |
| MIPS32 | mips |
| MIPS64 | |
| PowerPC32 | ppc, ppc32 |
| PowerPC64 | ppc64 |
| RISCV64 | riscv |

## Dependencies

Installed automatically via pip:

- [Capstone](https://www.capstone-engine.org/) - disassembly engine
- [Keystone](https://www.keystone-engine.org/) - assembler engine (for gadget file loading)
- [z3-solver](https://github.com/Z3Prover/z3) - symbolic execution backend
- [cmd2](https://cmd2.readthedocs.io/) - interactive shell framework

## License

[GPL-3.0](LICENSE)
