Expand description
rop-finder — ROPgadget-compatible CLI library.
Phase 1: ELF, PE, Mach-O, Universal/fat Mach-O, and raw blobs; all
supported architectures. Format dispatch mirrors ROPgadget’s
binary.py: --rawArch forces the raw loader regardless of magic
bytes; otherwise magic-byte dispatch via rf_core::Binary::load.
Universal (fat Mach-O) binaries follow ROPgadget’s universal.py:
every slice’s executable regions are concatenated and scanned with the
FIRST slice’s arch/mode/endianness (universal.py:92-108 returns
“whatever is in the first binary”).
Phase 2 (PLAN.md §6.3/§6.4):
--section <glob>— restrict the scan to named executable sections (repeatable, comma-separated,*globbing).--base <hex>— rebase the image at load time (rf-corerebase).--info— dump image metadata as JSON without scanning.
Phase 3 (PLAN.md §6.1): the scan orchestration (ScanRequest →
scan_bytes / info_bytes) is library API so the rf-mcp MCP
server reuses it without shelling out to the CLI. Since v1.0 that
orchestration lives in the rf-api LIBRARY crate and is re-exported
here unchanged (ENG-08/ECO-10): rf-mcp depends on rf-api, never on
this binary crate. What is left in this file is the CLI itself — the
clap surface, the output formats, the scan cache’s key and directory,
and main_entry.
Exit codes: 0 success, 1 usage error, 2 malformed/unsupported binary.
Modules§
- pe_
exports - The shared request layer, re-exported so that
rf_cli::ScanRequestandrf_api::ScanRequeststay one type and every existinguse rf_cli::…keeps compiling. The definitions live inrf-api.CHWIN-08#3 — the PE export directory. - query
- The shared request layer, re-exported so that
rf_cli::ScanRequestandrf_api::ScanRequeststay one type and every existinguse rf_cli::…keeps compiling. The definitions live inrf-api. ECO-01 / ECO-12: the constraint query layer.
Structs§
- Chain
Outcome - The shared request layer, re-exported so that
rf_cli::ScanRequestandrf_api::ScanRequeststay one type and every existinguse rf_cli::…keeps compiling. The definitions live inrf-api. A generated chain plus the scan it was built from. - Chain
Plan Outcome - The shared request layer, re-exported so that
rf_cli::ScanRequestandrf_api::ScanRequeststay one type and every existinguse rf_cli::…keeps compiling. The definitions live inrf-api. A plan plus the scan it was measured on, so a front end can turn the satisfying gadgets into the stable idsget_gadgetsresolves. - Chain
Spec - The shared request layer, re-exported so that
rf_cli::ScanRequestandrf_api::ScanRequeststay one type and every existinguse rf_cli::…keeps compiling. The definitions live inrf-api. Chain target + Windows parameters (the CLI’s--chain,--api-addr,--api-name,--shellcode-addr,--shellcode-size,--chain-base,--prot; MCP passes the same). - Cli
- Prepared
View - The shared request layer, re-exported so that
rf_cli::ScanRequestandrf_api::ScanRequeststay one type and every existinguse rf_cli::…keeps compiling. The definitions live inrf-api. Result ofprepare_view: the scan view, the selected-section table (when--sectionwas used), and the stripped-ELF fallback-name flag. - Region
View - The shared request layer, re-exported so that
rf_cli::ScanRequestandrf_api::ScanRequeststay one type and every existinguse rf_cli::…keeps compiling. The definitions live inrf-api. Format-agnostic scan view over a loaded image. - Scan
Budget - The shared request layer, re-exported so that
rf_cli::ScanRequestandrf_api::ScanRequeststay one type and every existinguse rf_cli::…keeps compiling. The definitions live inrf-api. Cancellation and resource limits layered on top of aScanRequest. - Scan
Outcome - The shared request layer, re-exported so that
rf_cli::ScanRequestandrf_api::ScanRequeststay one type and every existinguse rf_cli::…keeps compiling. The definitions live inrf-api. Everything a scan produces, plus the resolved options (needed for the offset-aware JSONsectionlookup) and the stripped-ELF warning flag. - Scan
Product - The shared request layer, re-exported so that
rf_cli::ScanRequestandrf_api::ScanRequeststay one type and every existinguse rf_cli::…keeps compiling. The definitions live inrf-api. Everything a cancellable scan produced. - Scan
Request - The shared request layer, re-exported so that
rf_cli::ScanRequestandrf_api::ScanRequeststay one type and every existinguse rf_cli::…keeps compiling. The definitions live inrf-api. Scan inputs at the same string level as the CLI flags, so both front ends share parsing and validation. - Scan
Result - The shared request layer, re-exported so that
rf_cli::ScanRequestandrf_api::ScanRequeststay one type and every existinguse rf_cli::…keeps compiling. The definitions live inrf-api. Everything scannable: one image’s gadgets plus its display parameters.
Enums§
- Scan
Error - The shared request layer, re-exported so that
rf_cli::ScanRequestandrf_api::ScanRequeststay one type and every existinguse rf_cli::…keeps compiling. The definitions live inrf-api. Structured failure for library callers. The CLI mapsUsageto exit 1 andBinaryto exit 2. - Scan
Failure - The shared request layer, re-exported so that
rf_cli::ScanRequestandrf_api::ScanRequeststay one type and every existinguse rf_cli::…keeps compiling. The definitions live inrf-api. Howscan_bytes_cancellablefailed. - Target
- The shared request layer, re-exported so that
rf_cli::ScanRequestandrf_api::ScanRequeststay one type and every existinguse rf_cli::…keeps compiling. The definitions live inrf-api. A loaded binary before it is flattened into a scan view.
Constants§
- DEFAULT_
MAX_ FILE_ SIZE - The shared request layer, re-exported so that
rf_cli::ScanRequestandrf_api::ScanRequeststay one type and every existinguse rf_cli::…keeps compiling. The definitions live inrf-api. ROB-06 default input cap: 512 MiB.
Functions§
- arch_
name - The shared request layer, re-exported so that
rf_cli::ScanRequestandrf_api::ScanRequeststay one type and every existinguse rf_cli::…keeps compiling. The definitions live inrf-api. rop-finder’s own architecture spelling, as it appears in--infoand in JSON gadget records:"x86","x64","arm-thumb","mips32". - build_
view - The shared request layer, re-exported so that
rf_cli::ScanRequestandrf_api::ScanRequeststay one type and every existinguse rf_cli::…keeps compiling. The definitions live inrf-api. Flatten a loadedTargetinto theRegionViewthe scanner walks. - build_
view_ selected - The shared request layer, re-exported so that
rf_cli::ScanRequestandrf_api::ScanRequeststay one type and every existinguse rf_cli::…keeps compiling. The definitions live inrf-api.build_viewwith a fat-Mach-O slice already chosen.archcomes fromresolve_arch;Nonekeeps the legacy whole-container view, which is only reachable for a single-slice container. - chain_
bytes - The shared request layer, re-exported so that
rf_cli::ScanRequestandrf_api::ScanRequeststay one type and every existinguse rf_cli::…keeps compiling. The definitions live inrf-api.--ropchainpipeline: options → load → dispatch on--chaintarget → rebase → scan → chain build. - chain_
json - The shared request layer, re-exported so that
rf_cli::ScanRequestandrf_api::ScanRequeststay one type and every existinguse rf_cli::…keeps compiling. The definitions live inrf-api. The Chain IR as pretty JSON, with the Windowsassumptionsobject beside it (nullfor a target that makes none). - chain_
targets - The shared request layer, re-exported so that
rf_cli::ScanRequestandrf_api::ScanRequeststay one type and every existinguse rf_cli::…keeps compiling. The definitions live inrf-api. Every--chainvalue, in help order.linux-*need an ELF x86/x64,windows-virtualprotecta PE x86/x64. - check_
input_ metadata - The shared request layer, re-exported so that
rf_cli::ScanRequestandrf_api::ScanRequeststay one type and every existinguse rf_cli::…keeps compiling. The definitions live inrf-api. ROB-06: decide whetherpathmay be read at all, from its metadata alone — BEFORE a byte is allocated. - endian_
name - The shared request layer, re-exported so that
rf_cli::ScanRequestandrf_api::ScanRequeststay one type and every existinguse rf_cli::…keeps compiling. The definitions live inrf-api."little"or"big", as--infospells it. - fmt_
addr - The shared request layer, re-exported so that
rf_cli::ScanRequestandrf_api::ScanRequeststay one type and every existinguse rf_cli::…keeps compiling. The definitions live inrf-api. A gadget address, zero-padded to the image’s address width. - hexs
- The shared request layer, re-exported so that
rf_cli::ScanRequestandrf_api::ScanRequeststay one type and every existinguse rf_cli::…keeps compiling. The definitions live inrf-api.0x-prefixed lowercase hex, unpadded - the spelling every JSON address field uses. - info_
bytes - The shared request layer, re-exported so that
rf_cli::ScanRequestandrf_api::ScanRequeststay one type and every existinguse rf_cli::…keeps compiling. The definitions live inrf-api.--infopipeline over in-memory bytes.new_baseis the already-parsed--basevalue (parse errors are usage errors on the caller side). - info_
json - The shared request layer, re-exported so that
rf_cli::ScanRequestandrf_api::ScanRequeststay one type and every existinguse rf_cli::…keeps compiling. The definitions live inrf-api. PLAN.md §6.4:--infopayload. Addresses are hex strings (consistent with gadget vaddrs), sizes are numbers.--baseis honoured so the printed addresses match what a scan would emit. - linux_
opts - The shared request layer, re-exported so that
rf_cli::ScanRequestandrf_api::ScanRequeststay one type and every existinguse rf_cli::…keeps compiling. The definitions live inrf-api. Parse the Linux chain parameters (ECO-04/CHLX-07). - load_
target - The shared request layer, re-exported so that
rf_cli::ScanRequestandrf_api::ScanRequeststay one type and every existinguse rf_cli::…keeps compiling. The definitions live inrf-api. Loadbytesinto aTarget;rawforces the raw loader (binary.py:32-49 — –rawArch wins over magic-byte detection). - main_
entry - parse_
badbytes - The shared request layer, re-exported so that
rf_cli::ScanRequestandrf_api::ScanRequeststay one type and every existinguse rf_cli::…keeps compiling. The definitions live inrf-api. ROPgadget –badbytes syntax: “bb|bb|lo-hi” (hex bytes, ranges inclusive). - parse_
hex - The shared request layer, re-exported so that
rf_cli::ScanRequestandrf_api::ScanRequeststay one type and every existinguse rf_cli::…keeps compiling. The definitions live inrf-api. Parse a hexadecimal integer, with an optional0x/0Xprefix. - parse_
hex_ bytes - The shared request layer, re-exported so that
rf_cli::ScanRequestandrf_api::ScanRequeststay one type and every existinguse rf_cli::…keeps compiling. The definitions live inrf-api.--stage 9090cc-> the bytes to write. - parse_
range - The shared request layer, re-exported so that
rf_cli::ScanRequestandrf_api::ScanRequeststay one type and every existinguse rf_cli::…keeps compiling. The definitions live inrf-api. ROPgadget –range syntax: “0xSTART-0xEND”. “0x0-0x0” means no range. - parse_
size - The shared request layer, re-exported so that
rf_cli::ScanRequestandrf_api::ScanRequeststay one type and every existinguse rf_cli::…keeps compiling. The definitions live inrf-api. Parse a byte count with an optional binaryK/M/Gsuffix (--max-file-size,--max-memory). Plain decimal, never hex: these are sizes a human types, and--max-file-size 10Mmust not silently become 0x10. - parse_
syscall_ args - The shared request layer, re-exported so that
rf_cli::ScanRequestandrf_api::ScanRequeststay one type and every existinguse rf_cli::…keeps compiling. The definitions live inrf-api. The Chain IR as JSON, plus theassumptionsobject a Windows chain carries (CHWIN-04). The IR itself isrf_chain’s serialisation, untouched; the assumptions sit beside it as their own key so a reader gets the layout AND what the layout took for granted from one document. ECO-04: parse--syscall-args rdi=0x1000,rsi=8into(reg, value)pairs. Register names are validated by the builder against the ABI, so the error here is only about the SHAPE. - parse_
syscall_ nr - The shared request layer, re-exported so that
rf_cli::ScanRequestandrf_api::ScanRequeststay one type and every existinguse rf_cli::…keeps compiling. The definitions live inrf-api.--syscall <n>: DECIMAL by default (a syscall number is written in decimal everywhere from the kernel table to strace), hexadecimal only with an explicit0x— the same ruleparse_alignapplies for the same reason (ANCH-02). - plan_
chain_ bytes - The shared request layer, re-exported so that
rf_cli::ScanRequestandrf_api::ScanRequeststay one type and every existinguse rf_cli::…keeps compiling. The definitions live inrf-api.ECO-04: the feasibility report, with COMPUTED relaxations. - plan_
json - The shared request layer, re-exported so that
rf_cli::ScanRequestandrf_api::ScanRequeststay one type and every existinguse rf_cli::…keeps compiling. The definitions live inrf-api.--plan-chain’s document. - prepare_
view - The shared request layer, re-exported so that
rf_cli::ScanRequestandrf_api::ScanRequeststay one type and every existinguse rf_cli::…keeps compiling. The definitions live inrf-api. Build the scan view fortarget, applying--archslice selection,--baserebase and--sectionselection. - read_
input_ file - The shared request layer, re-exported so that
rf_cli::ScanRequestandrf_api::ScanRequeststay one type and every existinguse rf_cli::…keeps compiling. The definitions live inrf-api. ROB-06: stat, then read. Neverstd::fs::reada path the caller has not bounded. - request_
options - The shared request layer, re-exported so that
rf_cli::ScanRequestandrf_api::ScanRequeststay one type and every existinguse rf_cli::…keeps compiling. The definitions live inrf-api. Turn aScanRequestinto engineScanOptions, with no budget and no cancellation. - request_
options_ with - The shared request layer, re-exported so that
rf_cli::ScanRequestandrf_api::ScanRequeststay one type and every existinguse rf_cli::…keeps compiling. The definitions live inrf-api.request_optionswith aScanBudgetwired in. - resolve_
arch - The shared request layer, re-exported so that
rf_cli::ScanRequestandrf_api::ScanRequeststay one type and every existinguse rf_cli::…keeps compiling. The definitions live inrf-api. CORE-03/CORE-05 — resolve--archagainst a loaded target. - run_
scan_ engine - The shared request layer, re-exported so that
rf_cli::ScanRequestandrf_api::ScanRequeststay one type and every existinguse rf_cli::…keeps compiling. The definitions live inrf-api. PERF-05: run the engine, choosing the bounded (streaming-sink) entry point when--max-gadgets/--max-memoryasked for one. - scan_
bytes - The shared request layer, re-exported so that
rf_cli::ScanRequestandrf_api::ScanRequeststay one type and every existinguse rf_cli::…keeps compiling. The definitions live inrf-api. Full scan pipeline over in-memory bytes: options → load → view → scan. - scan_
bytes_ cancellable - The shared request layer, re-exported so that
rf_cli::ScanRequestandrf_api::ScanRequeststay one type and every existinguse rf_cli::…keeps compiling. The definitions live inrf-api.scan_byteswith aScanBudgetthreaded into the engine, so the scan can be stopped from another thread and capped in gadgets and memory. - scan_
error_ message - The shared request layer, re-exported so that
rf_cli::ScanRequestandrf_api::ScanRequeststay one type and every existinguse rf_cli::…keeps compiling. The definitions live inrf-api. The user-facing wording for a scan-time failure. - scan_
warnings - The shared request layer, re-exported so that
rf_cli::ScanRequestandrf_api::ScanRequeststay one type and every existinguse rf_cli::…keeps compiling. The definitions live inrf-api. Everything the user has to be told BEFORE reading a gadget listing. - section_
of - The shared request layer, re-exported so that
rf_cli::ScanRequestandrf_api::ScanRequeststay one type and every existinguse rf_cli::…keeps compiling. The definitions live inrf-api. Name of the selected section containingvaddr(a scan-view address, i.e. after –base but before –offset), if any. - select_
sections - The shared request layer, re-exported so that
rf_cli::ScanRequestandrf_api::ScanRequeststay one type and every existinguse rf_cli::…keeps compiling. The definitions live inrf-api.--sectionselection: keep the named exec sections whose name matches any glob pattern. Returns the matched sections plus a flag telling whether the binary only has synthetic fallback names (PT_LOAD#n, i.e. a stripped ELF without a section table). - target_
base - The shared request layer, re-exported so that
rf_cli::ScanRequestandrf_api::ScanRequeststay one type and every existinguse rf_cli::…keeps compiling. The definitions live inrf-api. Image base of a target (first slice for Universal) — the pre-rebase view base, used to compute the--baseslide for the search sections. - target_
format - The shared request layer, re-exported so that
rf_cli::ScanRequestandrf_api::ScanRequeststay one type and every existinguse rf_cli::…keeps compiling. The definitions live inrf-api. Format name for chain dispatch / errors. - win_
opts - The shared request layer, re-exported so that
rf_cli::ScanRequestandrf_api::ScanRequeststay one type and every existinguse rf_cli::…keeps compiling. The definitions live inrf-api. Parse the Windows chain parameters (hex strings → WinChainOpts).
Type Aliases§
- RawSpec
- The shared request layer, re-exported so that
rf_cli::ScanRequestandrf_api::ScanRequeststay one type and every existinguse rf_cli::…keeps compiling. The definitions live inrf-api. Raw-loader spec: (arch, endianness, thumb) as resolved by the CLI’s--rawArch/--rawMode/--rawEndian/--thumbvalidation. - Section
Entry - The shared request layer, re-exported so that
rf_cli::ScanRequestandrf_api::ScanRequeststay one type and every existinguse rf_cli::…keeps compiling. The definitions live inrf-api. Build the scan view fortarget, applying--baserebase and Selected-section table entry: (name, vaddr, size) — used for the JSONsectionfield lookup.