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}