Skip to main content

rf_core/
arch.rs

1//! Shared architecture contract between rf-core (loaders) and rf-scan
2//! (multi-arch scan engine). Pinned in Phase 1 so the loader workstream and
3//! the scanner workstream can proceed independently.
4//!
5//! The variant set mirrors ROPgadget's architecture support
6//! (ropgadget/gadgets.py): x86, x64, ARM (ARM + Thumb), ARM64, MIPS,
7//! PowerPC, SPARC, RISC-V — 32/64-bit and endianness variants where
8//! ROPgadget distinguishes them.
9
10/// Target architecture + mode of a loaded binary.
11///
12/// A loaded image's architecture always came from the file — the loaders
13/// refuse an unrecognised machine type rather than defaulting to one — so
14/// this is a fact about the input, never a guess.
15///
16/// ```
17/// use rf_core::Arch;
18///
19/// assert_eq!(Arch::from_slice_name("aarch64"), Some(Arch::Arm64));
20/// assert_eq!(Arch::Arm64.slice_name(), "arm64");
21/// assert_eq!(Arch::Arm64.addr_size(), 8);
22/// assert!(!Arch::Arm64.is_x86_family());
23/// ```
24#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
25pub enum Arch {
26    /// 32-bit x86 (i386). Decoded by iced-x86.
27    X86,
28    /// 64-bit x86 (x86-64 / amd64). Decoded by iced-x86.
29    X64,
30    /// 32-bit ARM in A32 (ARM) mode.
31    Arm,
32    /// 32-bit ARM in T32 (Thumb) mode — `--thumb` / `--rawMode thumb`.
33    ArmThumb,
34    /// 64-bit ARM (AArch64).
35    Arm64,
36    /// 32-bit MIPS, either endianness.
37    Mips32,
38    /// 64-bit MIPS, either endianness.
39    Mips64,
40    /// 32-bit PowerPC.
41    Ppc32,
42    /// 64-bit PowerPC.
43    Ppc64,
44    /// 32-bit SPARC (V8).
45    Sparc,
46    /// 64-bit SPARC.
47    Sparc64,
48    /// SPARC V9.
49    SparcV9,
50    /// 32-bit RISC-V.
51    RiscV32,
52    /// 64-bit RISC-V.
53    RiscV64,
54}
55
56impl Arch {
57    /// Address width in bytes (4 or 8). Used by bad-byte address packing.
58    pub fn addr_size(self) -> usize {
59        use Arch::*;
60        match self {
61            X64 | Arm64 | Mips64 | Ppc64 | Sparc64 | SparcV9 | RiscV64 => 8,
62            _ => 4,
63        }
64    }
65
66    /// True for x86/x64 — the variable-length ISA scanned with iced-x86.
67    pub fn is_x86_family(self) -> bool {
68        matches!(self, Arch::X86 | Arch::X64)
69    }
70
71    /// Canonical short name, matching what `lipo -archs` and `otool` print
72    /// for a Mach-O slice. This is the spelling `--arch` should accept and
73    /// echo back when selecting a fat-Mach-O slice (CORE-03).
74    pub fn slice_name(self) -> &'static str {
75        use Arch::*;
76        match self {
77            X86 => "i386",
78            X64 => "x86_64",
79            Arm => "arm",
80            ArmThumb => "thumb",
81            Arm64 => "arm64",
82            Mips32 => "mips",
83            Mips64 => "mips64",
84            Ppc32 => "ppc",
85            Ppc64 => "ppc64",
86            Sparc => "sparc",
87            Sparc64 => "sparc64",
88            SparcV9 => "sparcv9",
89            RiscV32 => "riscv32",
90            RiscV64 => "riscv64",
91        }
92    }
93
94    /// Parse an architecture name for `--arch`. Case-insensitive, and it
95    /// accepts the common aliases as well as [`slice_name`](Self::slice_name)
96    /// (so `arm64`, `aarch64` and `arm64e` all select the ARM64 slice).
97    pub fn from_slice_name(name: &str) -> Option<Arch> {
98        use Arch::*;
99        let n = name.trim().to_ascii_lowercase();
100        Some(match n.as_str() {
101            "x86" | "i386" | "i486" | "i586" | "i686" | "x86_32" | "x86-32" => X86,
102            "x64" | "x86_64" | "x86-64" | "amd64" | "x86_64h" => X64,
103            "arm" | "armv6" | "armv7" | "armv7s" | "armv7k" | "arm32" => Arm,
104            "thumb" | "armv7-thumb" | "thumb2" => ArmThumb,
105            "arm64" | "aarch64" | "arm64e" | "arm64_32" | "armv8" => Arm64,
106            "mips" | "mips32" => Mips32,
107            "mips64" => Mips64,
108            "ppc" | "powerpc" | "ppc32" => Ppc32,
109            "ppc64" | "powerpc64" => Ppc64,
110            "sparc" | "sparc32" => Sparc,
111            "sparc64" => Sparc64,
112            "sparcv9" | "sparc9" => SparcV9,
113            "riscv32" | "riscv-32" | "rv32" => RiscV32,
114            "riscv64" | "riscv-64" | "rv64" => RiscV64,
115            _ => return None,
116        })
117    }
118}
119
120/// Byte order of the target.
121///
122/// Decided by the container (`EI_DATA`, the Mach-O magic, the PE machine
123/// type) or, for a raw blob, by `--rawEndian`. x86 is always
124/// [`Endianness::Little`].
125#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
126pub enum Endianness {
127    /// Least significant byte first.
128    Little,
129    /// Most significant byte first (big-endian MIPS, PowerPC, SPARC).
130    Big,
131}
132
133/// Format-agnostic view of a loaded executable image, consumed by rf-scan.
134///
135/// Every loader (ELF, PE, Mach-O, Universal slice, Raw) implements this.
136/// Semantics match ROPgadget:
137/// - [`Image::exec_scan_regions`] — the regions the scanner walks (ROPgadget
138///   parity: executable *program headers/segments*).
139/// - [`Image::exec_sections`] — named executable *sections*, used by the
140///   Phase 2 `--section` filter.
141///
142/// # Example
143///
144/// Every loader — including [`crate::RawBinary`], which needs no container
145/// at all — answers the same six questions:
146///
147/// ```
148/// use rf_core::{Arch, Endianness, Image, RawBinary};
149///
150/// // `pop rdi ; ret`, treated as a flat x86-64 blob.
151/// let mut blob = RawBinary::new(&[0x5f, 0xc3], Arch::X64, Endianness::Little);
152/// assert_eq!(Image::arch(&blob), Arch::X64);
153/// assert_eq!(blob.addr_size(), 8);
154/// assert_eq!(blob.image_base(), 0);
155/// assert_eq!(blob.exec_scan_regions().len(), 1);
156///
157/// // `--base 0x400000`: every vaddr slides, the base becomes the new one.
158/// blob.rebase(0x40_0000);
159/// assert_eq!(blob.image_base(), 0x40_0000);
160/// assert_eq!(blob.exec_scan_regions()[0].vaddr, 0x40_0000);
161/// ```
162pub trait Image {
163    /// The architecture the bytes are decoded as.
164    fn arch(&self) -> Arch;
165    /// The byte order the bytes are decoded with.
166    fn endianness(&self) -> Endianness;
167    /// Address width in bytes, 4 or 8. Defaults to [`Arch::addr_size`].
168    fn addr_size(&self) -> usize {
169        self.arch().addr_size()
170    }
171    /// Preferred load address (PE ImageBase, ELF min PT_LOAD p_vaddr,
172    /// Mach-O __TEXT segment vmaddr, Raw 0).
173    fn image_base(&self) -> u64;
174    /// The image's entry point, as an address in the current (possibly
175    /// rebased) view.
176    fn entry(&self) -> u64;
177    /// Named executable sections (for `--section` filtering).
178    fn exec_sections(&self) -> Vec<&crate::Section>;
179    /// ROPgadget-compatible scan regions actually walked by the scanner.
180    fn exec_scan_regions(&self) -> &[crate::Section];
181    /// Load-time rebase: shift all vaddrs so the image base becomes
182    /// `new_base` (the Phase 2 `--base` feature).
183    fn rebase(&mut self, new_base: u64);
184}