Skip to main content

Crate hexspell

Crate hexspell 

Source
Expand description

§HexSpell

HexSpell is a collection of helpers for inspecting and mutating executable formats. It focuses on providing a small, predictable API that mirrors the underlying file layout so that programs can tweak headers or sections without rebuilding the whole file. The opt-in write feature enables builders and transactional editing for each enabled format, including lossless PE resource serialization.

The crate is split into dedicated modules for the PE, ELF, and Mach-O formats. Each module exposes types for reading a binary from disk, modifying its fields in place, and writing the result back. Common building blocks such as field::Field and shared error definitions live in sibling modules.

Additional prose documentation is in docs/guide.md and docs/layout.md.

§Feature modes

Defaults enable std, pe, elf, macho, and the common helper interface. Disable defaults and select individual formats for no_std plus alloc. The write feature enables generation/editing without enabling any formats. Combine it with pe, elf, or macho; it also works without std. The independent opt-in pe-reconstruct feature with pe enables PE::from_memory_image for converting RVA-addressed snapshots to file layout. Core fields, errors, and byte utilities are always available. Owned buffers and parsed tables require an allocator; pe::view::PeHeaders does not allocate.

use hexspell::pe::view::PeHeaders;
let bytes = include_bytes!("../tests/samples/sample1.exe");
let headers = PeHeaders::parse(bytes).unwrap();
assert!(headers.coff.number_of_sections.value > 0);

§Examples

Read a PE image and inspect the entry point:

use hexspell::pe::PE;

let pe = PE::from_file("tests/samples/sample1.exe").unwrap();
println!("arch: {}", pe.architecture());
println!("entry: {:#x}", pe.optional_header.entry_point.value);

Patch a header field in place (Field carries the real file offset):

use hexspell::pe::PE;

let mut pe = PE::from_file("tests/samples/sample1.exe").unwrap();
let entry_rva = pe.optional_header.entry_point.value;
assert_eq!(pe.optional_header.entry_point.size, 4);
pe.optional_header
    .entry_point
    .update(&mut pe.buffer, entry_rva)
    .unwrap();

Lazy parsers expose imports, exports, and other data directories on demand:

use hexspell::pe::PE;

let pe = PE::from_file("tests/samples/sample1.exe").unwrap();
let imports = pe.imports().unwrap();
assert!(imports
    .dlls
    .iter()
    .any(|dll| dll.dll_name.eq_ignore_ascii_case("KERNEL32.dll")));

ELF endianness comes from ei_data; use elf::ELF::byte_order when patching:

use hexspell::elf::ELF;

let elf = ELF::from_file("tests/samples/linux").unwrap();
let order = elf.byte_order().unwrap();
let text = elf.section_index_by_name(".text").unwrap();
assert_eq!(elf.section_name(text).unwrap(), ".text");
assert_eq!(order, hexspell::field::ByteOrder::Little);

Mach-O segments and linked dylibs:

use hexspell::macho::MachO;

let macho = MachO::from_file("tests/samples/machO-OSX-x86-ls").unwrap();
assert!(!macho.segments.is_empty());
let dylibs = macho.linked_dylibs().unwrap();
assert!(dylibs.iter().any(|path| path.contains("libSystem")));

Write the patched buffer back to disk:

use hexspell::pe::PE;

let pe = PE::from_file("tests/samples/sample1.exe").unwrap();
pe.write_file("out.exe").unwrap();

Modules§

elf
Utilities for parsing and rewriting ELF binaries.
errors
Error types shared across the crate.
field
Abstraction for editable fields inside binary buffers.
macho
Facilities for reading and modifying Mach-O binaries.
pe
Executable Formats
reloc
Per-format relocation listing helpers.
strings
Cross-format NUL-terminated string helpers.
utils
Helper routines for safely reading integers from byte slices.
validation
Cross-format validation: file-range overlap detection, VA/file-offset translation, and lightweight consistency checks.
write
Minimal write/layout planning helpers (P2).