ropnroll 0.1.0__tar.gz

ropnroll-0.1.0/PKG-INFO

@@ -0,0 +1,12 @@
+Metadata-Version: 2.4
+Name: ropnroll
+Version: 0.1.0
+Summary: Semantic ROP/JOP gadget finder and automatic exploit-chain synthesizer
+Requires-Python: >=3.10
+Requires-Dist: capstone>=5.0
+Requires-Dist: lief>=0.14
+Requires-Dist: unicorn>=2.0
+Requires-Dist: rich>=13.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: keystone-engine>=0.9; extra == "dev"

ropnroll-0.1.0/README.md

@@ -0,0 +1,274 @@
+# ropnroll
+
+A ROP/JOP gadget finder and **automatic exploit-chain synthesizer**. You give it
+a binary (and optionally a library it links against); it gives you a verified,
+ready-to-fire chain for "call this function with these arguments," "make this
+syscall," "pop a shell via a single sigreturn frame," "pivot the stack," or a
+raw semantic gadget search — grounded in real CPU emulation at every step, not
+a modeled instruction set.
+
+Built for the case in the brief: you already have an arbitrary read/write
+primitive (or a straightforward stack overflow) and want the rest of exploit
+construction — register setup, calling convention, ASLR-aware addressing,
+chain correctness — handled for you. It's been fired for real against a live
+process (see [Live-fire demo](#live-fire-demo)), not just checked against a
+static binary.
+
+## Support matrix
+
+Honest, not aspirational — "tested" means an automated test in `tests/`
+actually exercises it against a real binary, every run.
+
+| | ELF (Linux) | PE (Windows) |
+|---|---|---|
+| **x86-64** | ✅ tested — scanner, solver, call/syscall/SROP chains, live-fire exploit, verifier | ✅ tested — loading, mitigations (incl. Control Flow Guard), scanning, MS x64 ABI (RCX/RDX/R8/R9 + shadow space) |
+| **x86 (32-bit)** | 🟡 wired up, scanner-level tested; solver/chain builders share the same code path as x86-64 but aren't exercised by an automated test against a real 32-bit target | ✅ tested — loading, mitigations, scanning (cdecl/stdcall stack-arg calling convention) |
+| **ARM32 / ARM64** | 🟡 scanner + semantic engine wired up (shares the Unicorn-measured-effects design with x86), not exercised by an automated test against a real ARM binary this session | — |
+| **MIPS32 / MIPS64** | 🟡 scanner + semantic engine wired up, including branch-delay-slot handling; not exercised by an automated test this session | — |
+| **RISC-V / PowerPC / Thumb** | ❌ not supported | — |
+
+SROP is Linux x86-64 only (it's a Linux kernel ABI detail, not portable). The
+one-gadget finder and libc.rip lookup are scoped to x86/x86-64. Everything in
+the ✅ row has a corresponding test in `tests/` that runs against a real
+binary — not a mock — every time the suite runs.
+
+## Why another one of these
+
+Market research before writing any code, plus a live head-to-head:
+
+| Tool | Approach | Notable limitation ropnroll targets |
+|---|---|---|
+| **Ropper** / **ROPgadget** | Syntactic/regex gadget search | No semantics at all — you read disassembly and build chains by hand |
+| **angrop** (angr) | Symbolic execution via claripy | Powerful but slow (minutes on libc-sized targets per public benchmarks), no standalone CLI |
+| **ROPium** | Custom IR + semantic queries (`rax=rbx+8`) | Gadget-level chaining only; no concrete verification, no JOP synthesis |
+| **Ropinator** | Z3-backed solver + "affine executor" fast path, TUI + MCP server | Closest competitor — see below |
+| **wedp** | WinDbg plugin for interactive Windows exploit dev | Different category: live-debugger-assisted workflow, not offline gadget/chain synthesis |
+| **one_gadget** | Curated, per-glibc-version static analysis of source | Needs a maintained version database; ropnroll's `onegadget` instead concretely emulates forward from shell-string references, no database, works on whatever you hand it |
+| **libc-database** / pwntools `libcdb` | Local database you build and query | ropnroll's `libcid` hits libc.rip directly — no local DB to maintain |
+
+**Ropinator specifically** (`pip install ropinator`) is the tool ropnroll has the
+most in common with, so I installed it and ran it head-to-head rather than
+guessing. On `libc.so.6` at matched depth: Ropinator found 63,964 gadgets in
+20s wall-clock (using ~2m39s of CPU across threads); ropnroll found 34,235 in
+15.9s single-threaded, pure Python. The gap isn't random — **13,971 (~22%) of
+Ropinator's results contain a mid-body conditional jump** (`je`, `jne`, ...),
+which ropnroll's scanner deliberately excludes: a gadget whose body can branch
+away before reaching its own terminator isn't a gadget you can rely on to do
+what its disassembly suggests. That's a real trade — fewer total matches for a
+hard reliability guarantee on every one that's returned.
+
+Where ropnroll tries to actually add something new, not just re-implement:
+
+1. **Semantics measured by real emulation, not modeled.** Every gadget's
+   effect (which register gets what value, which memory gets written) is
+   determined by actually running it in Unicorn across several input vectors
+   and fitting the relation — correct for whatever the silicon does,
+   automatically, with no per-opcode IR to write or get wrong.
+2. **Concrete chain verification.** Once a chain is built, ropnroll re-emulates
+   the *whole thing* against the real target's mapped memory and reports
+   pass/fail per goal register, plus exactly which gadget faulted. This isn't
+   a nicety — building this tool, the verifier (and a live-fire test against
+   a real process) caught five real bugs in the solver, none of which would
+   have been caught by inspection. See "How this was validated."
+3. **A register/call/syscall solver that goes past one hop.** Backward-
+   chaining search with memoization and a work budget, not just "pop-style
+   gadget or bail" — finds multi-gadget indirection paths (`pop reg1` →
+   `mov reg2, reg1` → `mov target, reg2`) when no direct popper exists, and
+   explicitly rejects any candidate that turns out to be a disguised stack
+   pivot or that touches memory through an uncontrolled register.
+4. **SROP as a first-class goal**, not an afterthought: one sigreturn frame
+   can set *every* register in a single step, including chaining straight
+   into execve with zero conventional gadgets beyond a single `pop rax`.
+5. **JOP is actually synthesized, not just tagged.** `ropnroll jop` finds
+   *dispatcher* gadgets in the Bletsch et al. sense — an indirect jump/call
+   through a register that the same gadget also advances by a constant — by
+   asking the semantic engine directly, and can build the function-pointer
+   table that turns one into an arbitrary-length JOP chain.
+6. **CET/CFG-aware by construction.** Under Intel CET-IBT or Windows Control
+   Flow Guard, an indirect branch may only land on an approved entry point.
+   The JOP dispatcher builder checks a PE's real Guard CF function table
+   (read via LIEF) instead of silently producing a chain that dies on the
+   first hop on a hardened target.
+7. **Empirical one-gadget discovery.** No curated glibc-version database:
+   finds every place the binary's own code loads a shell-string pointer, and
+   concretely emulates forward (with syscalls it can't service — `clone`,
+   `mmap` — faked plausibly so real code paths like modern glibc's
+   `posix_spawn`-based `system()` can be walked) to confirm a real execve
+   fires. A hit is observed, not guessed.
+8. **libc identification** against libc.rip from as few as 2–3 leaked symbol
+   offsets, with the exact build's full symbol table and a download link, in
+   one call.
+9. **Live-target orchestration.** Attach to a running process via
+   `/proc/<pid>/maps` (no ptrace, no special privileges), rebase gadget pools
+   to the *actual* runtime addresses, and hand back an `Image` the rest of
+   the tool uses exactly like a static file. `examples/live_fire_demo.py`
+   uses this to build a chain and pop a real shell in a real subprocess.
+
+What I'm *not* claiming to beat Ropinator on: it already ships a TUI and an
+MCP server for agent-native use, and covers RISC-V/PowerPC/Thumb, which this
+project doesn't attempt (see the support matrix above — a deliberate scope
+decision, not an oversight). It's also a shipped, presumably battle-tested
+tool; this was built and tested in one sitting against real binaries and a
+real live process, not years of field use.
+
+## Install
+
+```bash
+# pip
+pip install -e .
+
+# uv (fast, and what this repo's CI/dev workflow assumes)
+uv pip install -e .
+# or, without an explicit venv step:
+uv sync   # if you're working from a clone and want a project-local .venv
+
+# uvx: run the CLI directly without a persistent install
+uvx --from git+https://github.com/jordanallred/ropnroll ropnroll security ./target
+
+# once a release is published to PyPI (tag a v* release to trigger it):
+uvx ropnroll security ./target
+```
+
+Needs `capstone`, `lief`, `unicorn`, `rich` — all pulled in automatically.
+`libcid` uses the standard library's `urllib` (no extra dependency).
+
+## Usage
+
+```bash
+# security/mitigation report (NX, PIE, RELRO, canary, CFG for PE...)
+ropnroll security ./target
+
+# raw gadget listing (like Ropper/ROPgadget, but conditional-jump-free by default)
+ropnroll scan ./target --regex "pop r.i"
+
+# semantic search, ROPium-style DSL
+ropnroll search ./target ./libc.so.6 --query "rdi=rax+8"
+
+# stack pivots / JOP dispatcher gadgets
+ropnroll pivot ./target
+ropnroll jop ./libc.so.6
+
+# build + verify a ret2libc call, emit a pwntools-ready payload
+ropnroll call ./target ./libc.so.6 --target system --args 0x1cc42f \
+    --verify --emit pwntools
+
+# build + verify a direct execve("/bin/sh", NULL, NULL) syscall chain
+ropnroll syscall ./libc.so.6 --nr 59 --args 0x1cc42f,0,0 --verify --emit pwntools
+
+# a sigreturn frame that pops a shell with a single gadget, period
+ropnroll srop ./libc.so.6 --args 0x1cc42f,0,0 --verify --emit pwntools
+
+# empirically confirmed one-gadgets (no curated database)
+ropnroll onegadget ./libc.so.6
+
+# identify a libc build from a couple of leaked symbol offsets
+ropnroll libcid --symbol system=0x58750 --symbol read=0x11bd20 --download /tmp/libc.so.6
+```
+
+`call`, `syscall`, and `srop` accept multiple binaries (target + libc) and
+pool their gadgets together, same as a real exploit would pull from both.
+
+## Live-fire demo
+
+`examples/live_fire_demo.py` doesn't just build a chain — it spawns the real
+vulnerable test binary, attaches to it, reads its *actual* runtime memory map
+(standing in for whatever leak primitive gets you the same information
+against a real target), rebases ropnroll's gadget pool to those live
+addresses, builds a ret2libc chain with the solver, delivers it through the
+real stack overflow, and confirms a real shell by running a command in it and
+reading the output back:
+
+```
+[*] live binary base : 0x555555554000
+[*] live libc   base : 0x7ffff7c00000
+[*] building the call chain with ropnroll's own solver (not hand-picked)...
+    pop-style: pop rdi ; ret @ 0x7ffff7d0c08d sets ['rdi']
+[*] payload is 104 bytes (72 junk + 32 chain)
+[+] SHELL CONFIRMED -- got real code execution via a chain ropnroll built itself
+```
+
+(This sandbox has ASLR disabled system-wide — no root available to change it
+— so the "defeated" addresses happen to match the static file. The code path
+reads live addresses from the live process either way, so the mechanism is
+real; there just isn't a randomized target to prove it against here.)
+
+## How this was validated
+
+Nothing here is asserted without having actually run it — against real
+binaries, a real libc, and in one case a real running process:
+
+- Scanner + semantic engine run against `/lib/x86_64-linux-gnu/libc.so.6` (a
+  real, unmodified system libc), freshly-`gcc`-compiled x86-64 test binaries,
+  and real 32-bit/64-bit Windows PE executables — loading, mitigation
+  detection (including Control Flow Guard), and gadget scanning all
+  confirmed.
+- The register solver, call/syscall/SROP chain builders were used to build
+  an actual `system("/bin/sh")` ret2libc chain, a direct `execve` syscall
+  chain, and a single-gadget SROP execve chain — sourced *entirely* from
+  libc's own gadgets, no hand-picked addresses — then concretely
+  re-emulated against libc's real mapped memory via `--verify`. All pass.
+- The one-gadget finder found and concretely confirmed a real one-gadget in
+  system libc by emulating through actual modern glibc `posix_spawn`
+  internals (not a toy code path).
+- The libc.rip lookup was checked against a real leak of this exact libc's
+  `system`/`read`/`printf` offsets and correctly identified the exact build,
+  including the `/bin/sh` string offset matching what the scanner found
+  independently.
+- `examples/live_fire_demo.py` spawns the real vulnerable binary, attaches
+  via `/proc/<pid>/maps`, and pops a real shell with a chain the solver
+  built itself — the strongest verification available short of a randomized
+  remote target.
+- Along the way, **five real bugs were found and fixed by this same testing
+  loop, not by inspection**: a terminator-classification bug that let
+  byte-overlap coincidences masquerade as valid gadgets; a `leave`-based
+  pivot gadget getting silently used as a plain register setter; a
+  chain-assembly gap that left an unfilled word between gadgets; a solver
+  combinatorial-blowup bug once stricter safety checks narrowed the search
+  (fixed with memoization + a work budget); and a ret2libc stack-alignment
+  gotcha (entering a function via `ret` instead of `call` needs the same
+  rsp%16==8 residue, or its own callees crash on the first SSE instruction)
+  that the live-fire demo caught by actually crashing until it was fixed.
+
+## Design notes
+
+- **Scanner** (`core/scanner.py`): classic backward-window technique for x86
+  (misaligned/"unintended" gadgets included, like Ropper/ROPgadget), fixed-
+  instruction-width backward stepping for ARM/ARM64/MIPS (including MIPS
+  branch-delay-slot handling). Deliberately excludes conditional branches,
+  privileged instructions, and segment-register writes from gadget bodies —
+  each found because a gadget slipping through actually broke something
+  downstream, not preemptively.
+- **Semantic engine** (`semantics/engine.py`): per-gadget effects are inferred
+  by running the gadget in Unicorn with several trial register values (basis
+  includes 0, all-ones, and a few patterns to catch AND/OR/XOR/scale
+  relations, not just copy/add) and fitting a closed-form relation to each
+  output register and memory write. Results are exact, not guessed — a
+  relation is only accepted if it holds across every trial.
+- **Solver** (`solve/chain.py`): greedy multi-cover search over "pop"-style
+  (load-from-stack) gadgets first; falls back to depth-bounded, memoized
+  backward-chaining search for register-to-register indirection when no
+  direct popper exists. Rejects any candidate that's a disguised stack pivot
+  or touches memory through a register nothing set.
+- **Windows ABI awareness**: x86-64 PE targets automatically get the
+  Microsoft calling convention (RCX/RDX/R8/R9 + 32 bytes of shadow space),
+  not SysV's RDI/RSI/RDX/RCX/R8/R9 — picked from the binary's own format.
+- **Stack-alignment correction**: `build_call` can take `bytes_before_chain`
+  (how much padding precedes the chain in the final payload) and will insert
+  a single bare `ret` gadget automatically if needed to keep a directly-
+  entered function's incoming stack correctly aligned.
+
+## Known limitations / roadmap (being upfront, not shipping silently)
+
+- ARM/ARM64/MIPS share the same scanner/semantic-engine design as x86-64 and
+  should work the same way, but aren't exercised by an automated test
+  against a real binary this session — see the support matrix.
+- RISC-V, PowerPC, and Thumb are explicitly out of scope (a deliberate call
+  to focus on the architectures people actually hit, not a gap to fill
+  later without reconsidering).
+- Register-value solving is depth-bounded backward-chaining, not full
+  BFS/constraint propagation like angrop — handles multi-hop indirection but
+  isn't exhaustive.
+- `onegadget`'s syscall-faking (for `clone`/`mmap`/etc.) is a pragmatic
+  stand-in for real kernel behavior, not a full OS emulation layer — it gets
+  far enough to find real gadgets through modern glibc, but an exotic code
+  path could still need a syscall this doesn't stub correctly.

ropnroll-0.1.0/pyproject.toml

@@ -0,0 +1,30 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "ropnroll"
+version = "0.1.0"
+description = "Semantic ROP/JOP gadget finder and automatic exploit-chain synthesizer"
+requires-python = ">=3.10"
+dependencies = [
+    "capstone>=5.0",
+    "lief>=0.14",
+    "unicorn>=2.0",
+    "rich>=13.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+    "keystone-engine>=0.9",
+]
+
+[project.scripts]
+ropnroll = "ropnroll.cli.main:main"
+
+[tool.setuptools.packages.find]
+include = ["ropnroll*"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

ropnroll-0.1.0/ropnroll/cli/main.py

@@ -0,0 +1,356 @@
+from __future__ import annotations
+
+import argparse
+import sys
+
+from rich.console import Console
+from rich.markup import escape
+from rich.table import Table
+
+from .. import libcdb
+from ..core import loader, output, scanner, security
+from ..core.gadget import Terminator
+from ..solve import callchain, chain as chainmod, jop, onegadget, pivot, srop, syscallchain
+from ..solve.pool import GadgetPool
+from ..semantics import query as querymod
+from ..verify.emulate import verify_chain
+
+console = Console()
+
+
+def _load_pool(paths: list[str], scan_opts: scanner.ScanOptions) -> tuple[GadgetPool, list]:
+    pool = GadgetPool()
+    images = []
+    for p in paths:
+        img = loader.load(p)
+        gs = scanner.scan_image(img, scan_opts)
+        pool.add(img, gs)
+        images.append(img)
+    return pool, images
+
+
+def _scan_opts(args) -> scanner.ScanOptions:
+    bad = bytes.fromhex(args.bad_bytes) if getattr(args, "bad_bytes", None) else b""
+    return scanner.ScanOptions(
+        max_insns=args.max_insns, rop=not args.no_rop, jop=not args.no_jop,
+        sys=not args.no_sys, bad_bytes=bad,
+    )
+
+
+def cmd_scan(args):
+    pool, images = _load_pool([args.binary], _scan_opts(args))
+    gadgets = pool.all()
+    if args.regex:
+        import re
+        rx = re.compile(args.regex)
+        gadgets = [g for g in gadgets if rx.search(g.text)]
+    gadgets.sort(key=lambda g: g.address)
+    if args.out:
+        with open(args.out, "w") as f:
+            for g in gadgets:
+                f.write(f"0x{g.address:016x} : {g.text}\n")
+        console.print(f"[green]wrote {len(gadgets)} gadgets to {args.out}[/green]")
+        return
+    for g in gadgets[: args.limit]:
+        console.print(f"0x{g.address:016x} : {escape(g.text)}")
+    console.print(f"[bold]{len(gadgets)}[/bold] gadgets total"
+                   + (f" (showing first {args.limit})" if len(gadgets) > args.limit else ""))
+
+
+def cmd_security(args):
+    img = loader.load(args.binary)
+    opts = _scan_opts(args)
+    gs = scanner.scan_image(img, opts)
+    report = security.build_report(img, gs)
+    t = Table(title=f"security report: {args.binary}")
+    t.add_column("property")
+    t.add_column("value")
+    for k, v in report.lines:
+        t.add_row(k, v)
+    console.print(t)
+
+
+def cmd_search(args):
+    pool, images = _load_pool(args.binary, _scan_opts(args))
+    try:
+        results = querymod.search(pool, args.query, limit=args.limit)
+    except ValueError as e:
+        console.print(f"[red]{e}[/red]")
+        sys.exit(1)
+    if not results:
+        console.print("[yellow]no gadgets matched[/yellow]")
+        return
+    for g, eff, field in results:
+        console.print(f"0x{g.address:016x} : {escape(g.text)}  [dim]sp_delta={eff.sp_delta}[/dim]")
+
+
+def cmd_pivot(args):
+    pool, images = _load_pool(args.binary, _scan_opts(args))
+    pivots = pivot.find_pivots(pool)
+    t = Table(title="stack pivots")
+    t.add_column("address")
+    t.add_column("gadget")
+    t.add_column("kind")
+    for p in pivots[: args.limit]:
+        t.add_row(f"0x{p.gadget.address:x}", escape(p.gadget.text), p.kind)
+    console.print(t)
+
+
+def cmd_jop(args):
+    pool, images = _load_pool(args.binary, _scan_opts(args))
+    disp = jop.find_dispatchers(pool, img=images[0])
+    t = Table(title="JOP dispatcher gadgets (self-advancing jmp/call-through-register)")
+    t.add_column("address")
+    t.add_column("gadget")
+    t.add_column("reg")
+    t.add_column("advance")
+    for d in disp[: args.limit]:
+        t.add_row(f"0x{d.gadget.address:x}", escape(d.gadget.text), d.reg, f"0x{d.advance:x}")
+    console.print(t)
+    console.print(f"[bold]{len(disp)}[/bold] dispatcher(s) found")
+
+
+def cmd_onegadget(args):
+    img = loader.load(args.binary)
+    if img.arch not in ("x86_64", "x86"):
+        console.print(f"[red]one-gadget search is scoped to x86/x86-64 (target is {img.arch})[/red]")
+        sys.exit(1)
+    console.print("[dim]searching for shell-string references and emulating forward "
+                  "from each one -- this concretely runs the real code, so it can take "
+                  "a few seconds...[/dim]")
+    rep = onegadget.find_one_gadgets(img, max_insns=args.max_insns)
+    t = Table(title="one-gadgets (empirically confirmed via emulation, not a curated database)")
+    t.add_column("address")
+    t.add_column("string")
+    t.add_column("starting state that worked")
+    t.add_column("instructions run")
+    for c in rep.candidates:
+        t.add_row(f"0x{c.address:x}", c.string.decode(), c.constraint, str(c.instructions_run))
+    console.print(t)
+    console.print(f"searched {rep.searched_sites} shell-string reference site(s), "
+                   f"[bold]{len(rep.candidates)}[/bold] confirmed")
+
+
+def cmd_libcid(args):
+    offsets = {}
+    for item in args.symbol:
+        name, _, off = item.partition("=")
+        if not off:
+            console.print(f"[red]expected name=0xoffset, got {item!r}[/red]")
+            sys.exit(1)
+        offsets[name] = int(off, 0)
+    try:
+        matches = libcdb.identify(offsets)
+    except ConnectionError as e:
+        console.print(f"[red]{e}[/red]")
+        sys.exit(1)
+    if not matches:
+        console.print("[yellow]no matching libc build found[/yellow]")
+        return
+    for m in matches:
+        console.print(f"[bold]{m.id}[/bold]  buildid={m.buildid}")
+        console.print(f"  download: {m.download_url}")
+        for k, v in sorted(m.symbols.items()):
+            console.print(f"    {k} = 0x{v:x}")
+    if args.download:
+        if len(matches) > 1:
+            console.print(f"[yellow]{len(matches)} matches -- downloading the first ({matches[0].id})[/yellow]")
+        path = libcdb.download(matches[0], args.download)
+        console.print(f"[green]saved to {path}[/green]")
+
+
+def cmd_srop(args):
+    pool, images = _load_pool(args.binary, _scan_opts(args))
+    if pool.ai.arch != "x86_64":
+        console.print("[red]SROP support here is scoped to Linux x86-64[/red]")
+        sys.exit(1)
+    args_list = [int(a, 0) for a in args.args.split(",")] if args.args else [0, 0, 0]
+    while len(args_list) < 3:
+        args_list.append(0)
+    res = srop.build_srop_execve(pool, path_ptr=args_list[0], argv_ptr=args_list[1], envp_ptr=args_list[2])
+    for l in res.solve.log:
+        console.print(f"[dim]{l}[/dim]")
+    if not res.ok:
+        console.print(f"[red]could not build SROP chain: {res.solve.unresolved}[/red]")
+        sys.exit(1)
+    console.print(output.stack_layout(res.chain), markup=False)
+    expect = {"rax": 59, "rdi": args_list[0], "rsi": args_list[1], "rdx": args_list[2]}
+    consistent = srop.verify_srop_frame(res.chain, res.frame_offset_words, expect)
+    console.print(f"\nframe self-consistency check: {'[green]OK[/green]' if consistent else '[red]FAIL[/red]'}")
+    if args.verify:
+        ok, result = srop.emulate_srop_chain(images[0], res.chain, expect)
+        console.print(f"emulated (simulated sigreturn semantics -- see srop.py docstring): "
+                       f"{'[green]OK[/green]' if ok else '[red]FAIL[/red]'}")
+    if args.emit:
+        _emit(res.chain, args.emit, args.out)
+
+
+def _emit(chain, fmt: str, out: str | None):
+    if fmt == "pwntools":
+        text = output.to_pwntools(chain)
+    elif fmt == "c":
+        text = output.to_c_array(chain)
+    elif fmt == "json":
+        text = output.to_json(chain)
+    elif fmt == "raw":
+        data = output.to_raw(chain)
+        if out:
+            with open(out, "wb") as f:
+                f.write(data)
+            console.print(f"[green]wrote {len(data)} raw bytes to {out}[/green]")
+        else:
+            sys.stdout.buffer.write(data)
+        return
+    else:
+        raise ValueError(fmt)
+    if out:
+        with open(out, "w") as f:
+            f.write(text)
+        console.print(f"[green]wrote to {out}[/green]")
+    else:
+        console.print(text, markup=False)
+
+
+def _do_verify(images, chain, final_target, goal_regs):
+    rep = verify_chain(images[0], chain, final_target=final_target, goal_regs=goal_regs)
+    console.print(f"\n[bold]-- concrete verification (Unicorn) --[/bold]")
+    console.print(f"reached target: {rep.reached_target}   fault: {rep.fault}   "
+                   f"insns executed: {rep.instructions_executed}")
+    for reg, (ok, want, got) in rep.goal_results.items():
+        mark = "[green]OK[/green]" if ok else "[red]MISMATCH[/red]"
+        console.print(f"  {reg}: expected 0x{want:x}, got "
+                       f"{'0x%x' % got if got is not None else '?'}  {mark}")
+    if rep.fault:
+        console.print(f"[red]fault at 0x{rep.fault_address:x} near: {rep.last_gadget_context}[/red]")
+    console.print(f"[bold]{'PASS' if rep.ok else 'FAIL'}[/bold]")
+
+
+def cmd_call(args):
+    pool, images = _load_pool(args.binary, _scan_opts(args))
+    target = int(args.target, 0) if args.target.startswith("0x") or args.target.isdigit() else None
+    if target is None:
+        for img in images:
+            if args.target in img.symbols:
+                target = img.symbols[args.target]
+                break
+        if target is None:
+            console.print(f"[red]symbol {args.target!r} not found[/red]")
+            sys.exit(1)
+    args_list = [int(a, 0) for a in args.args.split(",")] if args.args else []
+    res = callchain.build_call(pool, target, args_list)
+    for l in res.solve.log:
+        console.print(f"[dim]{l}[/dim]")
+    if not res.ok:
+        console.print(f"[red]could not build call chain; unresolved: {res.solve.unresolved}[/red]")
+        sys.exit(1)
+    console.print(output.stack_layout(res.chain), markup=False)
+    if args.emit:
+        _emit(res.chain, args.emit, args.out)
+    if args.verify:
+        goal = {r: v for r, v in zip(pool.ai.call_arg_regs, args_list)}
+        _do_verify(images, res.chain, target, goal)
+
+
+def cmd_syscall(args):
+    pool, images = _load_pool(args.binary, _scan_opts(args))
+    args_list = [int(a, 0) for a in args.args.split(",")] if args.args else []
+    res = syscallchain.build_syscall(pool, args.nr, args_list)
+    for l in res.solve.log:
+        console.print(f"[dim]{l}[/dim]")
+    if not res.ok:
+        console.print(f"[red]could not build syscall chain; unresolved: {res.solve.unresolved}[/red]")
+        sys.exit(1)
+    console.print(output.stack_layout(res.chain), markup=False)
+    if args.emit:
+        _emit(res.chain, args.emit, args.out)
+    if args.verify:
+        _do_verify(images, res.chain, res.gadget_addr, {})
+
+
+def build_parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(prog="ropnroll", description="ROP/JOP gadget finder and chain synthesizer")
+    common = argparse.ArgumentParser(add_help=False)
+    common.add_argument("--max-insns", type=int, default=6)
+    common.add_argument("--no-rop", action="store_true")
+    common.add_argument("--no-jop", action="store_true")
+    common.add_argument("--no-sys", action="store_true")
+    common.add_argument("--bad-bytes", help="hex string, e.g. 000a0d")
+
+    sub = p.add_subparsers(dest="cmd", required=True)
+
+    s = sub.add_parser("scan", parents=[common])
+    s.add_argument("binary")
+    s.add_argument("--regex")
+    s.add_argument("--limit", type=int, default=50)
+    s.add_argument("--out")
+    s.set_defaults(func=cmd_scan)
+
+    s = sub.add_parser("security", parents=[common])
+    s.add_argument("binary")
+    s.set_defaults(func=cmd_security)
+
+    s = sub.add_parser("search", parents=[common])
+    s.add_argument("binary", nargs="+")
+    s.add_argument("--query", required=True, help='e.g. "rdi=rax+8", "[rbx]=rax", "rax=0"')
+    s.add_argument("--limit", type=int, default=20)
+    s.set_defaults(func=cmd_search)
+
+    s = sub.add_parser("pivot", parents=[common])
+    s.add_argument("binary", nargs="+")
+    s.add_argument("--limit", type=int, default=30)
+    s.set_defaults(func=cmd_pivot)
+
+    s = sub.add_parser("jop", parents=[common])
+    s.add_argument("binary", nargs="+")
+    s.add_argument("--limit", type=int, default=30)
+    s.set_defaults(func=cmd_jop)
+
+    s = sub.add_parser("onegadget")
+    s.add_argument("binary")
+    s.add_argument("--max-insns", type=int, default=2000,
+                    help="instruction budget per candidate site during emulation")
+    s.set_defaults(func=cmd_onegadget)
+
+    s = sub.add_parser("srop", parents=[common], help="build a sigreturn-oriented execve chain")
+    s.add_argument("binary", nargs="+")
+    s.add_argument("--args", default="", help="path_ptr,argv_ptr,envp_ptr (comma-separated)")
+    s.add_argument("--emit", choices=["pwntools", "raw", "c", "json"])
+    s.add_argument("--out")
+    s.add_argument("--verify", action="store_true")
+    s.set_defaults(func=cmd_srop)
+
+    s = sub.add_parser("libcid", help="identify a libc build from leaked symbol offsets via libc.rip")
+    s.add_argument("--symbol", action="append", required=True,
+                    help="name=0xoffset (offset from the leaked libc's own base), repeatable")
+    s.add_argument("--download", metavar="PATH", help="save the (first) matched libc here")
+    s.set_defaults(func=cmd_libcid)
+
+    s = sub.add_parser("call", parents=[common])
+    s.add_argument("binary", nargs="+")
+    s.add_argument("--target", required=True, help="address (0x...) or symbol name")
+    s.add_argument("--args", default="", help="comma-separated integers, e.g. 0x1000,0,0")
+    s.add_argument("--emit", choices=["pwntools", "raw", "c", "json"])
+    s.add_argument("--out")
+    s.add_argument("--verify", action="store_true")
+    s.set_defaults(func=cmd_call)
+
+    s = sub.add_parser("syscall", parents=[common])
+    s.add_argument("binary", nargs="+")
+    s.add_argument("--nr", type=int, required=True)
+    s.add_argument("--args", default="")
+    s.add_argument("--emit", choices=["pwntools", "raw", "c", "json"])
+    s.add_argument("--out")
+    s.add_argument("--verify", action="store_true")
+    s.set_defaults(func=cmd_syscall)
+
+    return p
+
+
+def main(argv=None):
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    args.func(args)
+
+
+if __name__ == "__main__":
+    main()