# 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.
[](https://github.com/hexomethyl/elfex/actions/workflows/ci.yml)
[](https://opensource.org/licenses/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
```toml
[dependencies]
elfex = "0.1"
```
For `no_std + alloc`:
```toml
[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
| `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
```rust,no_run
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
```rust,no_run
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:
```text
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:
```rust,no_run
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
```rust,no_run
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
| `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
```bash
# 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:
```bash
cargo +nightly fuzz run fuzz-elf-parse
cargo +nightly fuzz run fuzz-elf-headers
```
A corpus generation script uses
[Melkor](https://github.com/IOActive/Melkor_ELF_Fuzzer) to produce
domain-aware mutated ELFs as seed inputs:
```bash
# 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](LICENSE).