Expose rop3 as a Python library and add an interactive mode (#24)

[ricardojrdez]

Closes #24.

Library API (rop3.api.Rop3)

A small, stable entry point so rop3 can be used from other Python tools. Gadgets are scanned once and cached on the instance, so repeated queries (and the interactive mode) don't re-scan.

from rop3 import Rop3

r = Rop3("libc.so.6", base="0x7f0000000000", symbols=True)
r.gadgets()                       # list[Gadget] (cached)
r.find_op("mov", dst="rdi", src="rax")
r.ropchain("chain.txt")           # iterator over ROP chains

Rop3.from_args(args) reuses the CLI's already-parsed flags, and main() now drives everything through Rop3 (no behaviour change for the CLI).

Interactive mode (--interactive)

Scans the binary once and drops into a cmd-based REPL, so exploring gadgets no longer pays the start-up/scan cost per query:

$ python rop3.py --binary /bin/ls --interactive
Loaded 71 gadgets from /bin/ls
rop3> count
71
rop3> search pop rbp
[ls @ 0x100000777]: pop rbp ; ret (x29)
rop3> op mov rdi rax
rop3> chain chain.txt
rop3> quit

Commands: gadgets/search [substring], count, op <name> [dst] [src], chain <file>, help, quit.

Testing

• 85 tests pass on Python 3.11 and 3.13 (+7).
• New test_api.py covers the Rop3 API (caching, single-vs-list binaries, find_op) and the interactive shell commands, driven over an in-memory generated ELF.
• CLI verified unchanged end-to-end; interactive mode exercised over stdin.
• README documents both the interactive mode and library usage.

🤖 Generated with Claude Code