Skip to main content

Crate rf_api

Crate rf_api 

Source
Expand description

rf-api — the front-end-agnostic request layer of rop-finder.

Everything both front ends need in order to turn strings a user typed into a scan, an image report or a ROP chain: ScanRequest and its option building (request_options), the loader dispatch (load_target, prepare_view), the three pipelines (scan_bytes, info_bytes, chain_bytes) with their cancellable twin (scan_bytes_cancellable), and the v0.4 constraint query layer (query).

§Why this crate exists

It used to live in rf-cli, which is a binary crate, and rf-mcp depended on it there. That is not publishable (a binary crate has no usable library API for a third party), and it had already cost the project two real defects: the MCP server had to re-implement the option mapping and the cache key because the CLI’s were private, and the --align post-filter (ANCH-02) and the cache char-boundary panic (ROB-04) each existed in two slightly different copies. rf-cache was split out for the second pair; this crate is the first pair, and it is the reason cargo tree -p rop-finder-mcp no longer mentions rf-cli.

rf-cli re-exports everything here, so rf_cli::ScanRequest and rf_api::ScanRequest are the same type.

§Layers

  rf-core   loaders, sections, mitigations
  rf-scan   the gadget engine (ScanOptions -> Vec<Gadget>)
  rf-classify  semantics over one gadget
  rf-chain  chain builders over a gadget set
       |
  rf-api   <-- strings in, results out; no I/O policy, no output format
     |  \
  rf-cli   rf-mcp

This crate deliberately holds no output formatting (human text, CSV, the MCP wire shapes) and no I/O policy (the cache directory, path confinement, the interactive console). Those differ per front end and are exactly the things that should not be shared.

§Semver policy

See docs/API-STABILITY.md. In short: the item signatures below are covered by semver; the text of an error message, the exact JSON produced by info_json / plan_json, and anything marked #[doc(hidden)] are not. Pin rf-api = "1" and treat error strings as diagnostics, not as an API.

§Example

Scan a raw x86-64 blob and print what came back. pop rdi ; ret is 5f c3; a real caller passes std::fs::read("/bin/ls")? instead of a byte literal.

use rf_api::{scan_bytes, ScanRequest};
use rf_core::{Arch, Endianness};

let bytes = [0x5fu8, 0xc3];
let req = ScanRequest {
    depth: 4,
    ..ScanRequest::default()
};
let out = scan_bytes(&bytes, Some((Arch::X64, Endianness::Little, false)), &req)?;
let texts: Vec<String> = out.result.gadgets.iter().map(|g| g.text()).collect();
assert!(texts.iter().any(|t| t == "pop rdi ; ret"));

Modules§

pe_exports
CHWIN-08 #3 — the PE export directory.
query
ECO-01 / ECO-12: the constraint query layer.

Structs§

ChainOutcome
A generated chain plus the scan it was built from.
ChainPlanOutcome
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
Chain target + Windows parameters (the CLI’s --chain, --api-addr, --api-name, --shellcode-addr, --shellcode-size, --chain-base, --prot; MCP passes the same).
PreparedView
Result of prepare_view: the scan view, the selected-section table (when --section was used), and the stripped-ELF fallback-name flag.
RegionView
Format-agnostic scan view over a loaded image.
ScanBudget
Cancellation and resource limits layered on top of a ScanRequest.
ScanOutcome
Everything a scan produces, plus the resolved options (needed for the offset-aware JSON section lookup) and the stripped-ELF warning flag.
ScanProduct
Everything a cancellable scan produced.
ScanRequest
Scan inputs at the same string level as the CLI flags, so both front ends share parsing and validation.
ScanResult
Everything scannable: one image’s gadgets plus its display parameters.

Enums§

ScanError
Structured failure for library callers. The CLI maps Usage to exit 1 and Binary to exit 2.
ScanFailure
How scan_bytes_cancellable failed.
Target
A loaded binary before it is flattened into a scan view.

Constants§

DEFAULT_MAX_FILE_SIZE
ROB-06 default input cap: 512 MiB.

Functions§

arch_name
rop-finder’s own architecture spelling, as it appears in --info and in JSON gadget records: "x86", "x64", "arm-thumb", "mips32".
build_view
Flatten a loaded Target into the RegionView the scanner walks.
build_view_selected
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
--ropchain pipeline: options → load → dispatch on --chain target → rebase → scan → chain build.
chain_json
The Chain IR as pretty JSON, with the Windows assumptions object beside it (null for a target that makes none).
chain_targets
Every --chain value, in help order. linux-* need an ELF x86/x64, windows-virtualprotect a PE x86/x64.
check_input_metadata
ROB-06: decide whether path may be read at all, from its metadata alone — BEFORE a byte is allocated.
endian_name
"little" or "big", as --info spells it.
fmt_addr
A gadget address, zero-padded to the image’s address width.
hexs
0x-prefixed lowercase hex, unpadded - the spelling every JSON address field uses.
info_bytes
--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
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
Parse the Linux chain parameters (ECO-04 / CHLX-07).
load_target
Load bytes into a Target; raw forces the raw loader (binary.py:32-49 — –rawArch wins over magic-byte detection).
parse_badbytes
ROPgadget –badbytes syntax: “bb|bb|lo-hi” (hex bytes, ranges inclusive).
parse_hex
Parse a hexadecimal integer, with an optional 0x/0X prefix.
parse_hex_bytes
--stage 9090cc -> the bytes to write.
parse_range
ROPgadget –range syntax: “0xSTART-0xEND”. “0x0-0x0” means no range.
parse_size
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 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
--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
ECO-04: the feasibility report, with COMPUTED relaxations.
plan_json
--plan-chain’s document.
prepare_view
Build the scan view for target, applying --arch slice selection, --base rebase and --section selection.
read_input_file
ROB-06: stat, then read. Never std::fs::read a path the caller has not bounded.
request_options
Turn a ScanRequest into engine ScanOptions, with no budget and no cancellation.
request_options_with
request_options with a ScanBudget wired in.
resolve_arch
CORE-03/CORE-05 — resolve --arch against a loaded target.
run_scan_engine
PERF-05: run the engine, choosing the bounded (streaming-sink) entry point when --max-gadgets / --max-memory asked for one.
scan_bytes
Full scan pipeline over in-memory bytes: options → load → view → scan.
scan_bytes_cancellable
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 user-facing wording for a scan-time failure.
scan_warnings
Everything the user has to be told BEFORE reading a gadget listing.
section_of
Name of the selected section containing vaddr (a scan-view address, i.e. after –base but before –offset), if any.
select_sections
--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
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
Format name for chain dispatch / errors.
win_opts
Parse the Windows chain parameters (hex strings → WinChainOpts).

Type Aliases§

RawSpec
Raw-loader spec: (arch, endianness, thumb) as resolved by the CLI’s --rawArch/--rawMode/--rawEndian/--thumb validation.
SectionEntry
Build the scan view for target, applying --base rebase and Selected-section table entry: (name, vaddr, size) — used for the JSON section field lookup.