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-mcpThis 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§
- Chain
Outcome - A generated chain plus the scan it was built from.
- Chain
Plan Outcome - A plan plus the scan it was measured on, so a front end can turn the
satisfying gadgets into the stable ids
get_gadgetsresolves. - Chain
Spec - Chain target + Windows parameters (the CLI’s
--chain,--api-addr,--api-name,--shellcode-addr,--shellcode-size,--chain-base,--prot; MCP passes the same). - Prepared
View - Result of
prepare_view: the scan view, the selected-section table (when--sectionwas used), and the stripped-ELF fallback-name flag. - Region
View - Format-agnostic scan view over a loaded image.
- Scan
Budget - Cancellation and resource limits layered on top of a
ScanRequest. - Scan
Outcome - Everything a scan produces, plus the resolved options (needed for the
offset-aware JSON
sectionlookup) and the stripped-ELF warning flag. - Scan
Product - Everything a cancellable scan produced.
- Scan
Request - Scan inputs at the same string level as the CLI flags, so both front ends share parsing and validation.
- Scan
Result - Everything scannable: one image’s gadgets plus its display parameters.
Enums§
- Scan
Error - Structured failure for library callers. The CLI maps
Usageto exit 1 andBinaryto exit 2. - Scan
Failure - How
scan_bytes_cancellablefailed. - 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
--infoand in JSON gadget records:"x86","x64","arm-thumb","mips32". - build_
view - Flatten a loaded
Targetinto theRegionViewthe scanner walks. - build_
view_ selected 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 --ropchainpipeline: options → load → dispatch on--chaintarget → rebase → scan → chain build.- chain_
json - The Chain IR as pretty JSON, with the Windows
assumptionsobject beside it (nullfor a target that makes none). - chain_
targets - Every
--chainvalue, in help order.linux-*need an ELF x86/x64,windows-virtualprotecta PE x86/x64. - check_
input_ metadata - ROB-06: decide whether
pathmay be read at all, from its metadata alone — BEFORE a byte is allocated. - endian_
name "little"or"big", as--infospells 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 --infopipeline over in-memory bytes.new_baseis the already-parsed--basevalue (parse errors are usage errors on the caller side).- info_
json - 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 - Parse the Linux chain parameters (
ECO-04/CHLX-07). - load_
target - Load
bytesinto aTarget;rawforces 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/0Xprefix. - 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/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 Chain IR as JSON, plus the
assumptionsobject 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 --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 ECO-04: the feasibility report, with COMPUTED relaxations.- plan_
json --plan-chain’s document.- prepare_
view - Build the scan view for
target, applying--archslice selection,--baserebase and--sectionselection. - read_
input_ file - ROB-06: stat, then read. Never
std::fs::reada path the caller has not bounded. - request_
options - Turn a
ScanRequestinto engineScanOptions, with no budget and no cancellation. - request_
options_ with request_optionswith aScanBudgetwired in.- resolve_
arch - CORE-03/CORE-05 — resolve
--archagainst a loaded target. - run_
scan_ engine - PERF-05: run the engine, choosing the bounded (streaming-sink) entry
point when
--max-gadgets/--max-memoryasked for one. - scan_
bytes - Full scan pipeline over in-memory bytes: options → load → view → scan.
- scan_
bytes_ cancellable 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 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 --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 - 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 - 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/--thumbvalidation. - Section
Entry - Build the scan view for
target, applying--baserebase and Selected-section table entry: (name, vaddr, size) — used for the JSONsectionfield lookup.