Skip to main content

Crate rf_scan

Crate rf_scan 

Source
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: addROPGadgets lines 137-145, addJOPGadgets lines 217-274, addSYSGadgets lines 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 passCleanX86 port.

Structs§

Gadget
One gadget. Text is produced once at the output boundary.
ScanOptions
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-aware mean 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 --callPreceded predicate over Gadget::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 of scan_binary so 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 sink with the RAW traversal-order gadget stream (before dedup/filters/sort — run post_process on the collected result to finish the pipeline).
scan_bounded
Convenience wrapper: cancellable + bounded scan through a BoundedSink, finished by post_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_binary drives the same per-anchor routine over its work list (in parallel when ScanOptions::parallel is set).