Skip to main content

hexspell/
lib.rs

1//! # HexSpell
2//!
3//! HexSpell is a collection of helpers for inspecting and mutating executable formats. It focuses
4//! on providing a small, predictable API that mirrors the underlying file layout so that programs
5//! can tweak headers or sections without rebuilding the whole file.
6//! The opt-in `write` feature enables builders and transactional editing for each
7//! enabled format, including lossless PE resource serialization.
8//!
9//! The crate is split into dedicated modules for the **PE**, **ELF**, and **Mach-O** formats. Each
10//! module exposes types for reading a binary from disk, modifying its fields in place, and writing
11//! the result back. Common building blocks such as [`field::Field`] and shared error definitions
12//! live in sibling modules.
13//!
14//! Additional prose documentation is in [`docs/guide.md`](https://github.com/M3str3/HexSpell/blob/main/docs/guide.md)
15//! and [`docs/layout.md`](https://github.com/M3str3/HexSpell/blob/main/docs/layout.md).
16//!
17//! # Feature modes
18//!
19//! Defaults enable `std`, `pe`, `elf`, `macho`, and the `common` helper interface.
20//! Disable defaults and select individual formats for `no_std` plus `alloc`.
21//! The `write` feature enables generation/editing without enabling any formats.
22//! Combine it with `pe`, `elf`, or `macho`; it also works without `std`.
23//! The independent opt-in `pe-reconstruct` feature with `pe` enables
24//! `PE::from_memory_image` for converting RVA-addressed snapshots to file layout.
25//! Core fields, errors, and byte utilities are always available. Owned buffers
26//! and parsed tables require an allocator; `pe::view::PeHeaders` does not allocate.
27//!
28//! ```
29//! # #[cfg(feature = "pe")]
30//! # {
31//! use hexspell::pe::view::PeHeaders;
32//! let bytes = include_bytes!("../tests/samples/sample1.exe");
33//! let headers = PeHeaders::parse(bytes).unwrap();
34//! assert!(headers.coff.number_of_sections.value > 0);
35//! # }
36//! ```
37//!
38//! # Examples
39//!
40//! Read a PE image and inspect the entry point:
41//!
42//! ```
43//! # #[cfg(all(feature = "std", feature = "pe"))]
44//! # {
45//! use hexspell::pe::PE;
46//!
47//! let pe = PE::from_file("tests/samples/sample1.exe").unwrap();
48//! println!("arch: {}", pe.architecture());
49//! println!("entry: {:#x}", pe.optional_header.entry_point.value);
50//! # }
51//! ```
52//!
53//! Patch a header field in place (`Field` carries the real file offset):
54//!
55//! ```
56//! # #[cfg(all(feature = "std", feature = "pe"))]
57//! # {
58//! use hexspell::pe::PE;
59//!
60//! let mut pe = PE::from_file("tests/samples/sample1.exe").unwrap();
61//! let entry_rva = pe.optional_header.entry_point.value;
62//! assert_eq!(pe.optional_header.entry_point.size, 4);
63//! pe.optional_header
64//!     .entry_point
65//!     .update(&mut pe.buffer, entry_rva)
66//!     .unwrap();
67//! # }
68//! ```
69//!
70//! Lazy parsers expose imports, exports, and other data directories on demand:
71//!
72//! ```
73//! # #[cfg(all(feature = "std", feature = "pe"))]
74//! # {
75//! use hexspell::pe::PE;
76//!
77//! let pe = PE::from_file("tests/samples/sample1.exe").unwrap();
78//! let imports = pe.imports().unwrap();
79//! assert!(imports
80//!     .dlls
81//!     .iter()
82//!     .any(|dll| dll.dll_name.eq_ignore_ascii_case("KERNEL32.dll")));
83//! # }
84//! ```
85//!
86//! ELF endianness comes from `ei_data`; use `elf::ELF::byte_order` when patching:
87//!
88//! ```
89//! # #[cfg(all(feature = "std", feature = "elf"))]
90//! # {
91//! use hexspell::elf::ELF;
92//!
93//! let elf = ELF::from_file("tests/samples/linux").unwrap();
94//! let order = elf.byte_order().unwrap();
95//! let text = elf.section_index_by_name(".text").unwrap();
96//! assert_eq!(elf.section_name(text).unwrap(), ".text");
97//! assert_eq!(order, hexspell::field::ByteOrder::Little);
98//! # }
99//! ```
100//!
101//! Mach-O segments and linked dylibs:
102//!
103//! ```
104//! # #[cfg(all(feature = "std", feature = "macho"))]
105//! # {
106//! use hexspell::macho::MachO;
107//!
108//! let macho = MachO::from_file("tests/samples/machO-OSX-x86-ls").unwrap();
109//! assert!(!macho.segments.is_empty());
110//! let dylibs = macho.linked_dylibs().unwrap();
111//! assert!(dylibs.iter().any(|path| path.contains("libSystem")));
112//! # }
113//! ```
114//!
115//! Write the patched buffer back to disk:
116//!
117//! ```no_run
118//! # #[cfg(all(feature = "std", feature = "pe"))]
119//! # {
120//! use hexspell::pe::PE;
121//!
122//! let pe = PE::from_file("tests/samples/sample1.exe").unwrap();
123//! pe.write_file("out.exe").unwrap();
124//! # }
125//! ```
126
127#![cfg_attr(not(feature = "std"), no_std)]
128
129extern crate alloc;
130
131// Standard
132pub mod errors;
133pub mod field;
134#[cfg(feature = "common")]
135pub mod reloc;
136#[cfg(feature = "common")]
137pub mod strings;
138#[cfg(all(not(feature = "common"), any(feature = "pe", feature = "elf")))]
139mod strings;
140pub mod utils;
141#[cfg(feature = "common")]
142pub mod validation;
143#[cfg(feature = "common")]
144pub mod write;
145
146#[cfg(feature = "elf")]
147pub mod elf; // ELF
148#[cfg(feature = "macho")]
149pub mod macho;
150/// Executable Formats
151/// ==================
152#[cfg(feature = "pe")]
153pub mod pe; // PE (Portable Executable) // Mach-O