rf_core/lib.rs
1//! rf-core — binary loading (ELF, PE, Mach-O, Universal, Raw via goblin),
2//! the section model, and rebasing.
3//!
4//! All malformed input produces a structured [`Error`] — the loaders never
5//! panic.
6//!
7//! **The loader refuses rather than fabricates.** If a container declares a
8//! machine type rop-finder cannot disassemble, [`Binary::load`] and the
9//! per-format `parse` functions return [`Error::UnsupportedArch`] (ELF) or
10//! [`Error::Unsupported`] (PE, Mach-O) instead of guessing an architecture.
11//! That is why [`Image::arch`] is infallible: by the time a caller holds an
12//! image, its architecture came from the file, never from a fallback.
13//!
14//! **Declared vs materialised.** [`Section::size`] is the size the file
15//! *declares* (`p_memsz`/`sh_size`, `SizeOfRawData`, Mach-O `section.size`),
16//! which is what the parity oracle reports and trims `--range` against;
17//! [`Section::bytes`] is clamped to what the file actually contains, and the
18//! total materialised per view is bounded so a header table cannot multiply
19//! a small file into gigabytes of copies.
20//!
21//! **Mitigations and symbols (ECO-06).** Every loader also reports what a
22//! `checksec` run would tell you — [`ElfBinary::mitigations`],
23//! [`PeBinary::mitigations`], [`MachOBinary::mitigations`],
24//! [`RawBinary::mitigations`] — as `{name: {enabled, evidence, detail}}`
25//! where `enabled` is the tri-state [`Enabled`]. A reader that cannot see
26//! the deciding bytes answers [`Enabled::Unknown`] with a stated reason
27//! rather than defaulting to a boolean. [`ElfBinary::symbols`] adds the
28//! `.dynsym`/`.symtab` listing, with the GOT slot (and, where provable, the
29//! PLT stub) of every PLT-called import. See the [`mitigations`] module for
30//! the report contract and the divergences from `checksec.sh`.
31//!
32//! Section model: names and flags come from each format's section headers
33//! (ELF `SHF_EXECINSTR`, PE `IMAGE_SCN_MEM_EXECUTE`, Mach-O instruction
34//! attributes). Scan regions mirror ROPgadget's loaders: executable
35//! `PT_LOAD` *segments* for ELF, executable *sections* for PE/Mach-O/Raw.
36//!
37//! # Getting started
38//!
39//! [`Binary::load`] sniffs the container and hands back a [`LoadedBinary`];
40//! every variant's payload implements [`Image`], which is the whole
41//! contract [`rf_scan`](https://docs.rs/rf-scan) needs in order to scan it.
42//!
43//! ```
44//! use rf_core::{Arch, Binary, Endianness, Image, LoadedBinary, RawBinary};
45//!
46//! // A real caller starts from a file:
47//! // let bytes = std::fs::read("/bin/ls")?;
48//! // let loaded = Binary::load(&bytes)?;
49//! // A doctest starts from a flat blob, which needs no container at all.
50//! // These two bytes are `pop rdi ; ret`.
51//! let blob = RawBinary::new(&[0x5f, 0xc3], Arch::X64, Endianness::Little);
52//! let loaded = LoadedBinary::Raw(blob);
53//!
54//! // Format-agnostic questions go through `Image`.
55//! let image: &dyn Image = match &loaded {
56//! LoadedBinary::Elf(b) => b,
57//! LoadedBinary::Pe(b) => b,
58//! LoadedBinary::MachO(b) => b,
59//! LoadedBinary::Raw(b) => b,
60//! LoadedBinary::Universal(_) => panic!("pick a slice first"),
61//! };
62//! assert_eq!(image.arch(), Arch::X64);
63//! assert_eq!(image.addr_size(), 8);
64//!
65//! // The regions a scanner walks. For ELF these are the executable
66//! // PT_LOAD segments; for PE/Mach-O/Raw the executable sections.
67//! let total: u64 = image.exec_scan_regions().iter().map(|s| s.size).sum();
68//! assert_eq!(total, 2);
69//! ```
70//!
71//! # Semver policy
72//!
73//! Covered by semver from 1.0: the item signatures below, the variants of
74//! [`Arch`], [`Format`] and [`LoadedBinary`], the fields of [`Section`],
75//! and the [`Image`] trait's method set.
76//!
77//! **Not** covered, and free to change in a patch release: the exact text
78//! of any [`Error`] or [`Mitigation::evidence`] string, the *contents* of a
79//! mitigation report for a given file (a better reader may turn an
80//! [`Enabled::Unknown`] into a decided answer), the order of
81//! [`Mitigations::names`] beyond the guarantee that it is stable within a
82//! release, and anything marked `#[doc(hidden)]`. Adding an [`Arch`] or
83//! [`Format`] variant is a minor release — match exhaustively at your own
84//! risk. Pin `rf-core = "1"`.
85//!
86//! See `docs/API-STABILITY.md` in the repository for the workspace-wide
87//! statement.
88
89#![forbid(unsafe_code)]
90// ENG-08: every public item carries documentation. This lint is the gate
91// that keeps it that way.
92#![warn(missing_docs)]
93
94mod arch;
95mod binary;
96mod elf;
97mod elf_info;
98mod error;
99mod macho;
100mod macho_info;
101pub mod mitigations;
102mod pe;
103mod pe_info;
104mod raw;
105mod symbols;
106mod universal;
107mod util;
108
109pub use arch::{Arch, Endianness, Image};
110pub use binary::{Binary, Format, LoadedBinary};
111pub use elf::{ElfBinary, ElfClass, ModeDivergence, Section};
112pub use error::Error;
113pub use macho::MachOBinary;
114pub use mitigations::{Enabled, Mitigation, Mitigations};
115pub use pe::{PeBinary, PeImport};
116pub use raw::RawBinary;
117pub use symbols::{Symbol, SymbolTable};
118pub use universal::{SliceInfo, UniversalBinary};