From 1bdb0c403064fd8a16f8d7ab428f57a87f5b9a33 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ricardo=20J=2E=20Rodr=C3=ADguez?= Date: Tue, 23 Jun 2026 22:49:54 +0200 Subject: [PATCH] docs: add a Features summary to the README Add a high-level Features section that summarizes rop3's capabilities, including the recent additions: --arch slice selection, --badchar-bytes, --symbols, json/csv output, interactive mode, parallel scan (--jobs), the on-disk cache (--cache) and the Rop3 library API. Co-Authored-By: Claude Opus 4.8 --- README.md | 13 +++++++++++++ 1 file changed, 13 insertions(+) diff --git a/README.md b/README.md index 3cd6820..152aa4d 100644 --- a/README.md +++ b/README.md @@ -6,6 +6,19 @@ rop3 is a tool developed in [Python](https://www.python.org/downloads/) and it r [![License: GPL v3](https://img.shields.io/badge/License-GPLv3-blue.svg)](https://www.gnu.org/licenses/gpl-3.0) +## Features + +- **Multi-format, multi-arch**: analyzes ELF, PE and Mach-O binaries (x86 and x86-64). For fat/universal Mach-O binaries, `--arch` selects the slice to analyze. +- **Gadget search**: ROP, JOP and RETF gadgets, with controls for search depth (`--depth`), undeterministic gadgets (`--allow-undeterministic-gadgets`) and complex memory operands (`--allow-complex-memory-ops`). +- **Operations and ROP chains**: search for high-level operations (`--op`/`--dst`/`--src`) and build ROP chains from a ROPLang file (`--ropchain`, `--exhaustive`), including multi-step composite operations. +- **Relocation**: rebase any binary (ELF/PE/Mach-O) with `--base`, one address per binary. +- **Bad-char filtering**: avoid bytes in the gadget address (`--badchar`) and/or in the gadget opcode bytes (`--badchar-bytes`). By default, duplicate gadgets prefer canary-free addresses (`0x00`, `0x0a`, `0x0d`, `0xff`); disable with `--keep-canary-address`. +- **Symbol annotation**: with `--symbols`, each gadget is tagged with the nearest symbol (`name+offset`) when the binary is not stripped. +- **Output formats**: human-readable text (default), or machine-readable `--output json`/`--output csv` for scripting. Colors are emitted only on a TTY. +- **Interactive mode**: `--interactive` scans the binary once and drops into a REPL to explore gadgets, operations and chains without re-scanning. +- **Performance**: parallel scanning across processes (`--jobs N`) and an optional on-disk gadget cache (`--cache`) for repeated runs over the same file. +- **Library API**: use rop3 programmatically through the `Rop3` class (see [Use as a library](#use-as-a-library)). + ## Installation We recommend to install rop3's dependencies with [pip](https://pypi.org/project/pip/) in a virtual environment to not to mess up with your current configuration: