Skip to main content

Crate rf_core

Crate rf_core 

Source
Expand description

rf-core — binary loading (ELF, PE, Mach-O, Universal, Raw via goblin), the section model, and rebasing.

All malformed input produces a structured Error — the loaders never panic.

The loader refuses rather than fabricates. If a container declares a machine type rop-finder cannot disassemble, Binary::load and the per-format parse functions return Error::UnsupportedArch (ELF) or Error::Unsupported (PE, Mach-O) instead of guessing an architecture. That is why Image::arch is infallible: by the time a caller holds an image, its architecture came from the file, never from a fallback.

Declared vs materialised. Section::size is the size the file declares (p_memsz/sh_size, SizeOfRawData, Mach-O section.size), which is what the parity oracle reports and trims --range against; Section::bytes is clamped to what the file actually contains, and the total materialised per view is bounded so a header table cannot multiply a small file into gigabytes of copies.

Mitigations and symbols (ECO-06). Every loader also reports what a checksec run would tell you — ElfBinary::mitigations, PeBinary::mitigations, MachOBinary::mitigations, RawBinary::mitigations — as {name: {enabled, evidence, detail}} where enabled is the tri-state Enabled. A reader that cannot see the deciding bytes answers Enabled::Unknown with a stated reason rather than defaulting to a boolean. ElfBinary::symbols adds the .dynsym/.symtab listing, with the GOT slot (and, where provable, the PLT stub) of every PLT-called import. See the mitigations module for the report contract and the divergences from checksec.sh.

Section model: names and flags come from each format’s section headers (ELF SHF_EXECINSTR, PE IMAGE_SCN_MEM_EXECUTE, Mach-O instruction attributes). Scan regions mirror ROPgadget’s loaders: executable PT_LOAD segments for ELF, executable sections for PE/Mach-O/Raw.

§Getting started

Binary::load sniffs the container and hands back a LoadedBinary; every variant’s payload implements Image, which is the whole contract rf_scan needs in order to scan it.

use rf_core::{Arch, Binary, Endianness, Image, LoadedBinary, RawBinary};

// A real caller starts from a file:
//     let bytes = std::fs::read("/bin/ls")?;
//     let loaded = Binary::load(&bytes)?;
// A doctest starts from a flat blob, which needs no container at all.
// These two bytes are `pop rdi ; ret`.
let blob = RawBinary::new(&[0x5f, 0xc3], Arch::X64, Endianness::Little);
let loaded = LoadedBinary::Raw(blob);

// Format-agnostic questions go through `Image`.
let image: &dyn Image = match &loaded {
    LoadedBinary::Elf(b) => b,
    LoadedBinary::Pe(b) => b,
    LoadedBinary::MachO(b) => b,
    LoadedBinary::Raw(b) => b,
    LoadedBinary::Universal(_) => panic!("pick a slice first"),
};
assert_eq!(image.arch(), Arch::X64);
assert_eq!(image.addr_size(), 8);

// The regions a scanner walks. For ELF these are the executable
// PT_LOAD segments; for PE/Mach-O/Raw the executable sections.
let total: u64 = image.exec_scan_regions().iter().map(|s| s.size).sum();
assert_eq!(total, 2);

§Semver policy

Covered by semver from 1.0: the item signatures below, the variants of Arch, Format and LoadedBinary, the fields of Section, and the Image trait’s method set.

Not covered, and free to change in a patch release: the exact text of any Error or Mitigation::evidence string, the contents of a mitigation report for a given file (a better reader may turn an Enabled::Unknown into a decided answer), the order of Mitigations::names beyond the guarantee that it is stable within a release, and anything marked #[doc(hidden)]. Adding an Arch or Format variant is a minor release — match exhaustively at your own risk. Pin rf-core = "1".

See docs/API-STABILITY.md in the repository for the workspace-wide statement.

Re-exports§

pub use mitigations::Enabled;
pub use mitigations::Mitigation;
pub use mitigations::Mitigations;

Modules§

mitigations
Exploit-mitigation reporting (ECO-06).

Structs§

Binary
Entry point mirroring ROPgadget’s loader dispatch (binary.py).
ElfBinary
A parsed ELF binary.
MachOBinary
A parsed Mach-O binary (single architecture slice).
ModeDivergence
A disagreement between the width rop-finder decodes an ELF with and the width the parity oracle decodes it with (CORE-07).
PeBinary
A parsed PE binary.
PeImport
One imported symbol, resolved to its IAT slot location.
RawBinary
A flat blob treated as one executable region (ROPgadget --rawArch).
Section
A loadable, named view of executable or data bytes.
SliceInfo
What a fat container holds, per usable slice. This is the metadata the CLI needs to implement --arch (list the choices, name the one it picked, and say what it refused to guess between).
Symbol
One symbol.
UniversalBinary
A fat Mach-O (“Universal”) container: one MachOBinary per architecture slice.

Enums§

Arch
Target architecture + mode of a loaded binary.
ElfClass
ELF class (32- or 64-bit).
Endianness
Byte order of the target.
Error
Errors returned by the binary loader. Never a panic.
Format
Detected container format.
LoadedBinary
A loaded binary of any supported format.
SymbolTable
Which table a symbol came from.

Traits§

Image
Format-agnostic view of a loaded executable image, consumed by rf-scan.