Expand description
rf-scan — the gadget scanning engine (multi-arch, parallel).
Pipeline: memchr-accelerated anchor scan (tables ported from ROPgadget’s
gadgets.py) → clean-decode validity (total decoded size == end - start) → passClean port → output dedup by gadget text
(first-occurrence-wins in deterministic traversal order: section → table
(ROP/JOP/SYS) → anchor pattern → anchor-hit offset → depth, decided by
the trie index) → post-dedup filters (--only, --badbytes) →
alphabetical sort. --range truncates sections pre-scan; --offset
slides vaddrs at emission without affecting disassembly.
Dispatch (scan_binary over impl rf_core::Image): x86/x64 → iced-x86
(x86); all other architectures → capstone (cs). Scanning runs
over slices of each anchor’s hit list — overlapping byte ranges of the
region — optionally under rayon with deterministic output
(ScanOptions::parallel).
The “per-start decode cache” this crate was once described by is gone
(PERF-03): it had a 0.8% hit rate and cost more than the decodes it
avoided. On the fixed-width architectures a single resumable region
decode (cs::RegionIndex) replaces it and answers each candidate with
an array lookup; on x86/x64 each candidate is simply decoded, over
exactly its own bytes.
§Getting started
scan_binary takes anything that implements rf_core::Image and a
ScanOptions, and hands back the finished listing: deduplicated,
filtered and sorted the way ROPgadget sorts it.
use rf_core::{Arch, Endianness, RawBinary};
use rf_scan::{scan_binary, ScanOptions};
// A real caller loads a file with `rf_core::Binary::load`. These bytes
// are `xor eax, eax ; ret` followed by `pop rdi ; ret`.
let image = RawBinary::new(&[0x31, 0xc0, 0xc3, 0x5f, 0xc3], Arch::X64, Endianness::Little);
let opts = ScanOptions {
depth: 4,
..ScanOptions::default()
};
let gadgets = scan_binary(&image, &opts)?;
let texts: Vec<String> = gadgets.iter().map(|g| g.text()).collect();
assert!(texts.iter().any(|t| t == "pop rdi ; ret"));
assert!(texts.iter().any(|t| t == "xor eax, eax ; ret"));
// The listing is sorted and deduplicated.
let mut sorted = texts.clone();
sorted.sort();
assert_eq!(texts, sorted);§Filtering
Filters are engine options, not a post-pass over the listing, because
several of them (align, cfg_aware) change which candidate starts are
generated at all:
use rf_core::{Arch, Endianness, RawBinary};
use rf_scan::{scan_binary, ScanOptions};
let image = RawBinary::new(&[0x31, 0xc0, 0xc3, 0x5f, 0xc3], Arch::X64, Endianness::Little);
let opts = ScanOptions {
depth: 4,
// ROPgadget `--only`: every mnemonic must be in this set.
only: Some(["pop".to_string(), "ret".to_string()].into_iter().collect()),
..ScanOptions::default()
};
let texts: Vec<String> = scan_binary(&image, &opts)?.iter().map(|g| g.text()).collect();
// `xor eax, eax ; ret` is gone: `xor` is not in the set.
assert_eq!(texts, vec!["pop rdi ; ret".to_string(), "ret".to_string()]);§Bounding and cancelling a scan
scan_binary is unbounded and uncancellable by construction — it
resets the budget fields before it runs, so no caller can be surprised
by one. To bound a scan, use scan_bounded; to stop one from another
thread, put a CancelToken in the options and use either
scan_bounded or scan_binary_into, which are the two entry points
that observe it.
use rf_core::{Arch, Endianness, RawBinary};
use rf_scan::{scan_bounded, CancelToken, Error, ScanOptions};
let image = RawBinary::new(&[0x31, 0xc0, 0xc3, 0x5f, 0xc3], Arch::X64, Endianness::Little);
let cancel = CancelToken::new();
cancel.cancel(); // in practice: from another thread, or on a timeout
let opts = ScanOptions {
depth: 4,
cancel,
max_gadgets: Some(1_000_000),
..ScanOptions::default()
};
assert!(matches!(scan_bounded(&image, &opts), Err(Error::Cancelled)));§Streaming
For a listing too large to hold, implement GadgetSink and call
scan_binary_into, which never builds a Vec. The stream is in raw
traversal order: run post_process over what you collected if you
want the deduplicated, sorted listing.
§Semver policy
Covered by semver from 1.0: the signatures of scan_binary,
scan_binary_into, scan_bounded, post_process and
scan_section; the GadgetSink trait; and the fields of
ScanOptions and Gadget.
Not covered, and free to change in a patch release: the exact
disassembly text in Gadget::insns and Gadget::text — it is
whatever iced-x86 and the linked capstone print, both of which drift
between releases, which is why tests/parity.py re-measures it rather
than asserting it; which gadgets a given binary yields (a decode fix
changes the set, and that is the point of a fix); and the text of any
Error. Adding a field to ScanOptions is a minor release, so
construct it with ..ScanOptions::default() rather than exhaustively.
Pin rf-scan = "1".
See docs/API-STABILITY.md in the repository for the workspace-wide
statement.
Re-exports§
pub use anchors::TableKind;pub use cancel::CancelToken;pub use cancel::Error;pub use detail::Access;pub use detail::Detailer;pub use detail::InsnDetail;pub use detail::InsnGroups;pub use detail::MemRef;pub use detail::Operand;pub use detail::OperandInfo;pub use sink::BoundedSink;pub use sink::GadgetSink;pub use sink::VecSink;pub use trie::GadgetTrie;
Modules§
- anchors
- Anchor tables for all architectures, ported faithfully from ROPgadget’s
ropgadget/gadgets.py(x86:addROPGadgetslines 137-145,addJOPGadgetslines 217-274,addSYSGadgetslines 407-420; other arches: lines 147-202, 275-392, 422-479). - cancel
- Cooperative cancellation and the scan-time resource budget.
- cs
- Capstone decode path for the fixed-width ISAs (everything except
x86/x64, which uses iced-x86 in
crate::x86). - detail
- Per-instruction semantic metadata from capstone detail mode (ECO-05).
- sink
- The output sink (PERF-05).
- trie
- The suffix-trie gadget index (PERF-10 / CLAIM-07).
- x86
- x86/x64 instruction decoding (iced-x86) and the
passCleanX86port.
Structs§
- Gadget
- One gadget. Text is produced once at the output boundary.
- Scan
Options - Scanner configuration.
Constants§
- PREV_
BYTES gadgets.py:57—PREV_BYTES = 9.
Functions§
- capstone_
version - The capstone C library this build is linked against, as
"major.minor". - ibt_
applicable - Does
--cfg-awaremean anything for this binary? True when the image is x86/x64 AND at least one IBT landing pad (endbr32/endbr64) appears in an executable region. When this is false the flag can only ever remove gadgets, and the caller is expected to warn instead of silently returning a shorter list (CRIT-01’s “promised scan-time warning”). - is_
call_ preceded - ROPgadget’s
--callPrecededpredicate overGadget::prev(options.py:100-112). The engine captures the bytes; this is the test the CLI applies to them, kept here so the two halves cannot drift apart. - post_
process - Dedup (text, first-wins) → –only → –range → –badbytes → –cfg-aware →
alphabetical sort, matching
core.py:87-95+options.py:22-33. Split out ofscan_binaryso it can be unit-tested on synthetic gadgets. - scan_
binary - Scan a loaded binary of any supported architecture. Dispatch: x86/x64 →
iced-x86 path; every other
Arch→ the capstone path. - scan_
binary_ into - Cancellable, budgeted scan: drives
sinkwith the RAW traversal-order gadget stream (before dedup/filters/sort — runpost_processon the collected result to finish the pipeline). - scan_
bounded - Convenience wrapper: cancellable + bounded scan through a
BoundedSink, finished bypost_process. - scan_
section - Scan one executable buffer (x86/x64, serial). Gadgets are appended in
traversal order. This is the serial per-section entry point used by
tests;
scan_binarydrives the same per-anchor routine over its work list (in parallel whenScanOptions::parallelis set).