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.
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
(
.symtaband.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_debuglinksection. - 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
ReadAttrait. no_std + allocsupport. 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
[]
= "0.1"
For no_std + alloc:
[]
= { = "0.1", = 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 ElfFile;
let bytes = read?;
let file = parse?;
let image = file.image;
println!;
println!;
println!;
for lib in image.needed_libraries?
# Ok::
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 ElfImage;
# let raw_file_bytes: & = &;
# let mapped_image: & = &;
// Raw file: segment payloads are addressed by p_offset.
let raw = parse?;
// Loader-mapped image: segment payloads are addressed by p_vaddr.
let mapped = parse_mapped?;
// Preserve the actual load base for address-bearing structures such as GOT.
let relocated = parse_mapped_at?;
assert_eq!;
assert_eq!;
# Ok::
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 ElfImage;
# let bytes: & = &;
let image = parse?;
// Convert an ioff to a file offset.
let file_offset = image.ioff_to_offset;
// Read bytes at an image-relative offset.
let code = image.read_at_ioff;
# Ok::
Building an image
use ;
let image = new
.machine
.elf_type
.entry
.add_load
.build;
let raw_file = image.try_build?;
assert!;
# Ok::
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
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:
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
# Then fuzz with the Melkor-seeded corpus
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.