HexSpell
A lightweight, dependency-free Rust library for parsing and patching PE, ELF, and Mach-O executables.
Overview
HexSpell is a small parsing library for executable binaries. It has no runtime dependencies — only the Rust standard library — so it stays easy to embed, audit, and ship.
Parse PE, ELF, and Mach-O files (including FAT Mach-O), read headers and tables, and write changes back to disk when you need to patch an executable.
- Zero dependencies — no external crates at runtime.
- Lightweight — focused on parsing and patching; no heavy framework around the formats.
- Multi-format — PE (Windows), ELF (Linux), and Mach-O (macOS) in one crate.
- Parse and patch — read entry points, sections, imports, exports, and more; update headers and write the file back with
write_file. - Structural edits — insert sections and load segments, sync layout, apply relocations.
- PE generation (
writefeature withpe) — construct x86/x64 EXEs and DLLs from section bytes, with imports, exports, relocations, TLS, and resources. - PE memory reconstruction (
pe-reconstructwithpe) — convert a contiguous RVA-addressed snapshot into a file-aligned PE withPE::from_memory_image. See the reconstruction guide. - Resource editing (
writefeature withpe) — edit lossless owned trees transactionally; helpers for manifests, strings, versions, and icons. - ELF and Mach-O writers (
elf,write,macho,write) — owned construction, checked layouts, scoped dynamic linking, TLS/unwind metadata and transactional custom-data/FAT edits; Mach-O uses external signing. See the generation guide and validation matrix. - Signature containers (
writewithpe,elf, ormacho) — edit PE certificate tables, Linux appended PKCS#7 trailers, and Mach-O signature blobs for external signers. See the signing guide. - Lazy parsers — imports, exports, TLS, exceptions, symbols, and other tables parsed on demand.
- Endianness-aware — ELF and Mach-O byte order handled via
ByteOrder.
See docs/coverage.md for exactly what is modeled per format.
See the PE generation guide and
the pe_hello, pe_dll, and Windows pe_dll_load examples for construction and validation.
Formats (pe, elf, macho) and the public helper interface (common) have
independent default-enabled features. The opt-in write feature enables construction
and editing for the selected formats without enabling any formats itself. Use
features = ["write"] with defaults, or default-features = false, features = ["elf", "write"] for just the ELF writer with no_std + alloc.
See feature selection and 1.2.2 migration.
Installation
Or add it manually to Cargo.toml:
[]
= "1.0"
Quick start
use PE;
ELF and Mach-O follow the same pattern (ELF::from_file, MachO::from_file). For big-endian
binaries, use Field::update_with with the format's byte_order().
Examples
Reading key header fields per format:
use PE;
let pe = PEfrom_file.unwrap;
println!;
println!;
println!;
println!;
use ELF;
let elf = ELFfrom_file.unwrap;
println!;
println!;
println!;
use MachO;
let macho = from_file.unwrap;
println!;
println!;
println!;
Inserting a new PE section (for example, to inject code):
use PE;
use ;
let mut pe = PEfrom_file.unwrap;
pe.insert_section
.unwrap;
// Point the entry to the start of the new section.
let new_va = pe.sections.last.unwrap.virtual_address.value;
pe.optional_header
.entry_point
.update
.unwrap;
pe.write_file.unwrap;
More runnable examples and per-format walkthroughs live in the user guide.
Documentation
- User guide — design principles, per-format examples, error handling.
- Layout accessors —
field()/field_mut()on ELF/Mach-O layout enums. - Coverage matrix — what is modeled vs not, per format.
- ELF and Mach-O creation and editing plan — supported writer profiles, implementation milestones, and validation gates.
- Changelog — notable changes per release.
Contributing
Issues and pull requests are welcome — open an issue to
report a bug or discuss a change. Contributors and agents should follow the conventions in
AGENTS.md (tests required, cargo fmt + cargo test before finishing, no runtime
dependencies).
Test coverage
Install cargo-llvm-cov and the LLVM tools for your Rust toolchain:
For a Nix-managed toolchain, provide matching LLVM tools through LLVM_COV
and LLVM_PROFDATA if the shell does not include llvm-tools-preview.
Collect coverage and generate local reports:
Open coverage/html/index.html to inspect covered and uncovered library lines.
Reports stay in the ignored coverage/ directory; nothing is uploaded.
No minimum percentage is enforced.
Coverage includes unit and integration tests with all features, including write.
It excludes test/example/benchmark source files from the reported totals; doctests,
ignored tests, fuzz harnesses, and platform-specific runtime acceptance scripts are
not measured. This is separate from the format coverage matrix.
License
Distributed under the terms of the MIT License. See LICENSE for details.
no_std support
The std feature is enabled by default and preserves the file I/O APIs.
Disable default features for no_std + alloc:
[]
= { = "https://github.com/CaddyGlow/HexSpell", = false, = ["pe", "elf", "macho", "common"] }
In this mode, PE, ELF and Mach-O parsing from buffers, field edits, layout
operations and validation remain available. from_file, write_file, file-based
Mach-O FAT helpers, and FileParseError::Io require std. Errors implement
core::error::Error in both modes.
Owned buffers, strings and parsed tables require an allocator supplied by the
application. The borrowed pe::view::PeHeaders API does not allocate; this is not
an allocator-free configuration of the entire crate.
use PeHeaders;
Validate both modes with cargo test and cargo test --no-default-features.
cargo check --no-default-features --target thumbv7em-none-eabi checks a target
without a standard library.
Read-only parsing can borrow existing bytes with PE::from_slice, ELF::from_slice, and MachO::from_slice, avoiding a full file copy. Use owned from_buffer or from_file inputs for editing.
For allocation-free header-only inspection, use pe::view::PeHeaders, elf::view::ElfHeaders, or macho::view::MachHeaders (thin Mach-O). Referenced tables are inspected on demand.
Read-only directory inspection can stream PE imports, exports, base relocations, and debug records without collecting tables. ELF entry views and Mach-O command and FAT views avoid temporary allocations. Borrowed name accessors preserve owned editing support. Version 1.2.0 changes relocation and import-descriptor access; see the migration guide.
Fuzzing harnesses, corpus generation, and crash replay are documented in fuzz/README.md.