Skip to main content

Crate rf_cli

Crate rf_cli 

Source
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-core rebase).
  • --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::ScanRequest and rf_api::ScanRequest stay one type and every existing use rf_cli::… keeps compiling. The definitions live in rf-api. CHWIN-08 #3 — the PE export directory.
query
The shared request layer, re-exported so that rf_cli::ScanRequest and rf_api::ScanRequest stay one type and every existing use rf_cli::… keeps compiling. The definitions live in rf-api. ECO-01 / ECO-12: the constraint query layer.

Structs§

ChainOutcome
The shared request layer, re-exported so that rf_cli::ScanRequest and rf_api::ScanRequest stay one type and every existing use rf_cli::… keeps compiling. The definitions live in rf-api. A generated chain plus the scan it was built from.
ChainPlanOutcome
The shared request layer, re-exported so that rf_cli::ScanRequest and rf_api::ScanRequest stay one type and every existing use rf_cli::… keeps compiling. The definitions live in rf-api. A plan plus the scan it was measured on, so a front end can turn the satisfying gadgets into the stable ids get_gadgets resolves.
ChainSpec
The shared request layer, re-exported so that rf_cli::ScanRequest and rf_api::ScanRequest stay one type and every existing use rf_cli::… keeps compiling. The definitions live in rf-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
PreparedView
The shared request layer, re-exported so that rf_cli::ScanRequest and rf_api::ScanRequest stay one type and every existing use rf_cli::… keeps compiling. The definitions live in rf-api. Result of prepare_view: the scan view, the selected-section table (when --section was used), and the stripped-ELF fallback-name flag.
RegionView
The shared request layer, re-exported so that rf_cli::ScanRequest and rf_api::ScanRequest stay one type and every existing use rf_cli::… keeps compiling. The definitions live in rf-api. Format-agnostic scan view over a loaded image.
ScanBudget
The shared request layer, re-exported so that rf_cli::ScanRequest and rf_api::ScanRequest stay one type and every existing use rf_cli::… keeps compiling. The definitions live in rf-api. Cancellation and resource limits layered on top of a ScanRequest.
ScanOutcome
The shared request layer, re-exported so that rf_cli::ScanRequest and rf_api::ScanRequest stay one type and every existing use rf_cli::… keeps compiling. The definitions live in rf-api. Everything a scan produces, plus the resolved options (needed for the offset-aware JSON section lookup) and the stripped-ELF warning flag.
ScanProduct
The shared request layer, re-exported so that rf_cli::ScanRequest and rf_api::ScanRequest stay one type and every existing use rf_cli::… keeps compiling. The definitions live in rf-api. Everything a cancellable scan produced.
ScanRequest
The shared request layer, re-exported so that rf_cli::ScanRequest and rf_api::ScanRequest stay one type and every existing use rf_cli::… keeps compiling. The definitions live in rf-api. Scan inputs at the same string level as the CLI flags, so both front ends share parsing and validation.
ScanResult
The shared request layer, re-exported so that rf_cli::ScanRequest and rf_api::ScanRequest stay one type and every existing use rf_cli::… keeps compiling. The definitions live in rf-api. Everything scannable: one image’s gadgets plus its display parameters.

Enums§

ScanError
The shared request layer, re-exported so that rf_cli::ScanRequest and rf_api::ScanRequest stay one type and every existing use rf_cli::… keeps compiling. The definitions live in rf-api. Structured failure for library callers. The CLI maps Usage to exit 1 and Binary to exit 2.
ScanFailure
The shared request layer, re-exported so that rf_cli::ScanRequest and rf_api::ScanRequest stay one type and every existing use rf_cli::… keeps compiling. The definitions live in rf-api. How scan_bytes_cancellable failed.
Target
The shared request layer, re-exported so that rf_cli::ScanRequest and rf_api::ScanRequest stay one type and every existing use rf_cli::… keeps compiling. The definitions live in rf-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::ScanRequest and rf_api::ScanRequest stay one type and every existing use rf_cli::… keeps compiling. The definitions live in rf-api. ROB-06 default input cap: 512 MiB.

Functions§

arch_name
The shared request layer, re-exported so that rf_cli::ScanRequest and rf_api::ScanRequest stay one type and every existing use rf_cli::… keeps compiling. The definitions live in rf-api. rop-finder’s own architecture spelling, as it appears in --info and in JSON gadget records: "x86", "x64", "arm-thumb", "mips32".
build_view
The shared request layer, re-exported so that rf_cli::ScanRequest and rf_api::ScanRequest stay one type and every existing use rf_cli::… keeps compiling. The definitions live in rf-api. Flatten a loaded Target into the RegionView the scanner walks.
build_view_selected
The shared request layer, re-exported so that rf_cli::ScanRequest and rf_api::ScanRequest stay one type and every existing use rf_cli::… keeps compiling. The definitions live in rf-api. build_view with a fat-Mach-O slice already chosen. arch comes from resolve_arch; None keeps 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::ScanRequest and rf_api::ScanRequest stay one type and every existing use rf_cli::… keeps compiling. The definitions live in rf-api. --ropchain pipeline: options → load → dispatch on --chain target → rebase → scan → chain build.
chain_json
The shared request layer, re-exported so that rf_cli::ScanRequest and rf_api::ScanRequest stay one type and every existing use rf_cli::… keeps compiling. The definitions live in rf-api. The Chain IR as pretty JSON, with the Windows assumptions object beside it (null for a target that makes none).
chain_targets
The shared request layer, re-exported so that rf_cli::ScanRequest and rf_api::ScanRequest stay one type and every existing use rf_cli::… keeps compiling. The definitions live in rf-api. Every --chain value, in help order. linux-* need an ELF x86/x64, windows-virtualprotect a PE x86/x64.
check_input_metadata
The shared request layer, re-exported so that rf_cli::ScanRequest and rf_api::ScanRequest stay one type and every existing use rf_cli::… keeps compiling. The definitions live in rf-api. ROB-06: decide whether path may 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::ScanRequest and rf_api::ScanRequest stay one type and every existing use rf_cli::… keeps compiling. The definitions live in rf-api. "little" or "big", as --info spells it.
fmt_addr
The shared request layer, re-exported so that rf_cli::ScanRequest and rf_api::ScanRequest stay one type and every existing use rf_cli::… keeps compiling. The definitions live in rf-api. A gadget address, zero-padded to the image’s address width.
hexs
The shared request layer, re-exported so that rf_cli::ScanRequest and rf_api::ScanRequest stay one type and every existing use rf_cli::… keeps compiling. The definitions live in rf-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::ScanRequest and rf_api::ScanRequest stay one type and every existing use rf_cli::… keeps compiling. The definitions live in rf-api. --info pipeline over in-memory bytes. new_base is the already-parsed --base value (parse errors are usage errors on the caller side).
info_json
The shared request layer, re-exported so that rf_cli::ScanRequest and rf_api::ScanRequest stay one type and every existing use rf_cli::… keeps compiling. The definitions live in rf-api. PLAN.md §6.4: --info payload. Addresses are hex strings (consistent with gadget vaddrs), sizes are numbers. --base is honoured so the printed addresses match what a scan would emit.
linux_opts
The shared request layer, re-exported so that rf_cli::ScanRequest and rf_api::ScanRequest stay one type and every existing use rf_cli::… keeps compiling. The definitions live in rf-api. Parse the Linux chain parameters (ECO-04 / CHLX-07).
load_target
The shared request layer, re-exported so that rf_cli::ScanRequest and rf_api::ScanRequest stay one type and every existing use rf_cli::… keeps compiling. The definitions live in rf-api. Load bytes into a Target; raw forces 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::ScanRequest and rf_api::ScanRequest stay one type and every existing use rf_cli::… keeps compiling. The definitions live in rf-api. ROPgadget –badbytes syntax: “bb|bb|lo-hi” (hex bytes, ranges inclusive).
parse_hex
The shared request layer, re-exported so that rf_cli::ScanRequest and rf_api::ScanRequest stay one type and every existing use rf_cli::… keeps compiling. The definitions live in rf-api. Parse a hexadecimal integer, with an optional 0x/0X prefix.
parse_hex_bytes
The shared request layer, re-exported so that rf_cli::ScanRequest and rf_api::ScanRequest stay one type and every existing use rf_cli::… keeps compiling. The definitions live in rf-api. --stage 9090cc -> the bytes to write.
parse_range
The shared request layer, re-exported so that rf_cli::ScanRequest and rf_api::ScanRequest stay one type and every existing use rf_cli::… keeps compiling. The definitions live in rf-api. ROPgadget –range syntax: “0xSTART-0xEND”. “0x0-0x0” means no range.
parse_size
The shared request layer, re-exported so that rf_cli::ScanRequest and rf_api::ScanRequest stay one type and every existing use rf_cli::… keeps compiling. The definitions live in rf-api. Parse a byte count with an optional binary K/M/G suffix (--max-file-size, --max-memory). Plain decimal, never hex: these are sizes a human types, and --max-file-size 10M must not silently become 0x10.
parse_syscall_args
The shared request layer, re-exported so that rf_cli::ScanRequest and rf_api::ScanRequest stay one type and every existing use rf_cli::… keeps compiling. The definitions live in rf-api. The Chain IR as JSON, plus the assumptions object a Windows chain carries (CHWIN-04). The IR itself is rf_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=8 into (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::ScanRequest and rf_api::ScanRequest stay one type and every existing use rf_cli::… keeps compiling. The definitions live in rf-api. --syscall <n>: DECIMAL by default (a syscall number is written in decimal everywhere from the kernel table to strace), hexadecimal only with an explicit 0x — the same rule parse_align applies for the same reason (ANCH-02).
plan_chain_bytes
The shared request layer, re-exported so that rf_cli::ScanRequest and rf_api::ScanRequest stay one type and every existing use rf_cli::… keeps compiling. The definitions live in rf-api. ECO-04: the feasibility report, with COMPUTED relaxations.
plan_json
The shared request layer, re-exported so that rf_cli::ScanRequest and rf_api::ScanRequest stay one type and every existing use rf_cli::… keeps compiling. The definitions live in rf-api. --plan-chain’s document.
prepare_view
The shared request layer, re-exported so that rf_cli::ScanRequest and rf_api::ScanRequest stay one type and every existing use rf_cli::… keeps compiling. The definitions live in rf-api. Build the scan view for target, applying --arch slice selection, --base rebase and --section selection.
read_input_file
The shared request layer, re-exported so that rf_cli::ScanRequest and rf_api::ScanRequest stay one type and every existing use rf_cli::… keeps compiling. The definitions live in rf-api. ROB-06: stat, then read. Never std::fs::read a path the caller has not bounded.
request_options
The shared request layer, re-exported so that rf_cli::ScanRequest and rf_api::ScanRequest stay one type and every existing use rf_cli::… keeps compiling. The definitions live in rf-api. Turn a ScanRequest into engine ScanOptions, with no budget and no cancellation.
request_options_with
The shared request layer, re-exported so that rf_cli::ScanRequest and rf_api::ScanRequest stay one type and every existing use rf_cli::… keeps compiling. The definitions live in rf-api. request_options with a ScanBudget wired in.
resolve_arch
The shared request layer, re-exported so that rf_cli::ScanRequest and rf_api::ScanRequest stay one type and every existing use rf_cli::… keeps compiling. The definitions live in rf-api. CORE-03/CORE-05 — resolve --arch against a loaded target.
run_scan_engine
The shared request layer, re-exported so that rf_cli::ScanRequest and rf_api::ScanRequest stay one type and every existing use rf_cli::… keeps compiling. The definitions live in rf-api. PERF-05: run the engine, choosing the bounded (streaming-sink) entry point when --max-gadgets / --max-memory asked for one.
scan_bytes
The shared request layer, re-exported so that rf_cli::ScanRequest and rf_api::ScanRequest stay one type and every existing use rf_cli::… keeps compiling. The definitions live in rf-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::ScanRequest and rf_api::ScanRequest stay one type and every existing use rf_cli::… keeps compiling. The definitions live in rf-api. scan_bytes with a ScanBudget threaded 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::ScanRequest and rf_api::ScanRequest stay one type and every existing use rf_cli::… keeps compiling. The definitions live in rf-api. The user-facing wording for a scan-time failure.
scan_warnings
The shared request layer, re-exported so that rf_cli::ScanRequest and rf_api::ScanRequest stay one type and every existing use rf_cli::… keeps compiling. The definitions live in rf-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::ScanRequest and rf_api::ScanRequest stay one type and every existing use rf_cli::… keeps compiling. The definitions live in rf-api. Name of the selected section containing vaddr (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::ScanRequest and rf_api::ScanRequest stay one type and every existing use rf_cli::… keeps compiling. The definitions live in rf-api. --section selection: 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::ScanRequest and rf_api::ScanRequest stay one type and every existing use rf_cli::… keeps compiling. The definitions live in rf-api. Image base of a target (first slice for Universal) — the pre-rebase view base, used to compute the --base slide for the search sections.
target_format
The shared request layer, re-exported so that rf_cli::ScanRequest and rf_api::ScanRequest stay one type and every existing use rf_cli::… keeps compiling. The definitions live in rf-api. Format name for chain dispatch / errors.
win_opts
The shared request layer, re-exported so that rf_cli::ScanRequest and rf_api::ScanRequest stay one type and every existing use rf_cli::… keeps compiling. The definitions live in rf-api. Parse the Windows chain parameters (hex strings → WinChainOpts).

Type Aliases§

RawSpec
The shared request layer, re-exported so that rf_cli::ScanRequest and rf_api::ScanRequest stay one type and every existing use rf_cli::… keeps compiling. The definitions live in rf-api. Raw-loader spec: (arch, endianness, thumb) as resolved by the CLI’s --rawArch/--rawMode/--rawEndian/--thumb validation.
SectionEntry
The shared request layer, re-exported so that rf_cli::ScanRequest and rf_api::ScanRequest stay one type and every existing use rf_cli::… keeps compiling. The definitions live in rf-api. Build the scan view for target, applying --base rebase and Selected-section table entry: (name, vaddr, size) — used for the JSON section field lookup.