elfex 0.2.0

A no_std-friendly parser, editor, and builder for raw and mapped ELF executable images
Documentation
  • Coverage
  • 100%
    478 out of 478 items documented0 out of 216 items with examples
  • Size
  • Source code size: 229.4 kB This is the summed size of all the files inside the crates.io package for this release.
  • Documentation size: 4.2 MB This is the summed size of all files generated by rustdoc for all configured targets
  • Ø build duration
  • this release: 3s Average build duration of successful builds.
  • all releases: 2s Average build duration of successful builds in releases after 2024-10-23.
  • Links
  • hexomethyl/elfex
    0 0 0
  • crates.io
  • Dependencies
  • Versions
  • Owners
  • coconutbird hexomethyl

Elfex

Elfex is a no_std-friendly parser, editor, and builder for ELF executable images. It deliberately distinguishes byte-for-byte files from images already mapped by a loader, because their virtual-address-to-source translations are different.

CI License: MIT

What it supports

  • Raw ELF files, loader-mapped images, and mapped images relocated to a runtime base.
  • ELF32 and ELF64 headers, checked image-relative offset conversion, segment layout, zero-filled virtual tails, and trailing bytes.
  • Program headers (segments), section headers, string tables, symbol tables (.symtab and .dynsym), and the dynamic table.
  • REL and RELA relocations with per-architecture kind and width classification for x86 and x86-64.
  • GNU notes (build-id), TLS metadata, and the .gnu_debuglink section.
  • Lossless raw-file round trips through ElfFile, including trailing bytes beyond the last structure when the layout is unchanged.
  • Strict malformed-input checks, fallible builders, structural validation, and positional I/O via the ReadAt trait.
  • no_std + alloc support. No third-party dependencies.

Elfex targets ELF executable images such as executables (ET_EXEC), shared objects (ET_DYN), and core dumps (ET_CORE). Relocatable object files (ET_REL) are parsed but receive no special link-time support. DWARF debug info parsing is intentionally out of scope; pass section bytes to a DWARF crate such as gimli.

Installation

[dependencies]
elfex = "0.1"

For no_std + alloc:

[dependencies]
elfex = { version = "0.1", default-features = false }

Elfex 0.1 requires Rust 1.88 or newer.

The default std feature adds filesystem helpers, FileReader, and standard I/O error conversion. Parsing, building, mapped-image handling, validation, and in-memory readers remain available without it.

Core types

Type Use it for
ElfFile A complete raw file whose trailing bytes must be preserved
ElfImage A normalized executable image parsed from raw or loader-mapped bytes
ElfHeaders Header-only inspection without loading segment payloads
ElfBuilder Constructing a new executable image

Quick start

use elfex::ElfFile;

let bytes = std::fs::read("example")?;
let file = ElfFile::parse(&bytes)?;
let image = file.image();

println!("64-bit: {}", image.is_64bit());
println!("entry point: {:#x}", image.entry_point());
println!("image base: {:#x}", image.image_base());

for lib in image.needed_libraries()? {
    println!("needs {lib}");
}
# Ok::<(), elfex::Error>(())

Use ElfImage::parse(raw_bytes) when trailing bytes do not need to survive rebuilding, or ElfFile::parse(raw_bytes) when they do.

Raw files versus mapped images

use elfex::ElfImage;

# let raw_file_bytes: &[u8] = &[];
# let mapped_image: &[u8] = &[];
// Raw file: segment payloads are addressed by p_offset.
let raw = ElfImage::parse(raw_file_bytes)?;

// Loader-mapped image: segment payloads are addressed by p_vaddr.
let mapped = ElfImage::parse_mapped(mapped_image)?;

// Preserve the actual load base for address-bearing structures such as GOT.
let relocated = ElfImage::parse_mapped_at(mapped_image, 0x7f00_0000_0000)?;

assert_eq!(raw.runtime_image_base(), raw.image_base());
assert_eq!(relocated.runtime_image_base(), 0x7f00_0000_0000);
# Ok::<(), elfex::Error>(())

ElfImage::to_mapped_image() creates loader-style bytes at the preferred image base. to_mapped_image_at(base) also applies supported relative relocations for a different runtime base.

For a remote process or another random-access source, implement ReadAt and use:

ElfImage::read_from(&reader, source_offset)
ElfImage::read_mapped_from(&reader, source_offset, runtime_image_base)

Image-relative offsets

ELF has no RVA. Elfex defines an image-relative offset ioff = vaddr - image_base as the uniform addressing model:

use elfex::ElfImage;

# let bytes: &[u8] = &[];
let image = ElfImage::parse(bytes)?;

// Convert an ioff to a file offset.
let file_offset = image.ioff_to_offset(0x1000);

// Read bytes at an image-relative offset.
let code = image.read_at_ioff(0x1000, 16);
# Ok::<(), elfex::Error>(())

Building an image

use elfex::{ElfBuilder, ElfType, Machine, SegmentFlags};

let image = ElfBuilder::new()
    .machine(Machine::X86_64)
    .elf_type(ElfType::Exec)
    .entry(0x40_1000)
    .add_load(
        0x40_1000,
        SegmentFlags(SegmentFlags::READ | SegmentFlags::EXECUTE),
        vec![0xf4; 256],
    )
    .build();

let raw_file = image.try_build()?;
assert!(!raw_file.is_empty());
# Ok::<(), elfex::Error>(())

Builders are fallible. Prefer try_build() when input or edits are not fully trusted.

Module layout

Module Contents
elf ElfImage container with parse, inspect, build, edit, and validate submodules
elf_file ElfFile lossless wrapper preserving trailing bytes
header ELF and program/section header types, ElfHeaders for header-only inspection
program Program headers, Segment, SegmentType, SegmentFlags
section Section headers, Section, SectionType, SectionFlags
symbol Symbol, SymbolTable, bind/type/visibility enums
reloc RelocationEntry, RelocationSection, architecture-aware kind/width
dynamic DynamicTable, DynamicEntry, DynTag constants
notes GNU note parsing (build-id, ABI tag)
tls TlsInfo extracted from PT_TLS
validation Structural validation result types
reader Positional ReadAt trait and in-memory/file readers
builder ElfBuilder fluent construction API

Nested implementation modules use Rust's modern module.rs plus module/child.rs layout; the older module/mod.rs form is intentionally not used.

Development

# Full check matrix
cargo fmt --check
cargo clippy --all-features --all-targets -- -D warnings
cargo clippy --no-default-features --all-targets -- -D warnings
cargo test --all-features
cargo test --no-default-features
cargo doc --no-deps --all-features
cargo doc --no-deps --no-default-features

Warnings are denied by the package manifest, so the policy also applies to direct Cargo commands.

Fuzzing

Fuzz targets live under fuzz/ and can be run with cargo-fuzz on Linux/macOS or WSL:

cargo +nightly fuzz run fuzz-elf-parse
cargo +nightly fuzz run fuzz-elf-headers

A corpus generation script uses Melkor to produce domain-aware mutated ELFs as seed inputs:

# Generate 500 mutations per seed (default); override with COUNT=N
fuzz/melkor/generate-corpus.sh

# Then fuzz with the Melkor-seeded corpus
cargo +nightly fuzz run fuzz-elf-parse fuzz/corpus/fuzz-elf-parse

The script clones and builds Melkor automatically on first run. It compiles a minimal seed ELF (64-bit, and 32-bit if gcc -m32 is available), then runs Melkor with all metadata mutation categories (-A). The mutated files are deposited into fuzz/corpus/ for each fuzz target.

License

Licensed under the MIT License.