woodelf

Pure-Python ELF file parser and editor. Reads and rewrites 32/64-bit ELF binaries via a small set of editor classes, each scoped to one structural region of the file (header, section headers, symbols, dynamic entries, …).

Requires GNU binutils (objcopy, objdump, readelf) on PATH, plus hexdump and sh. Python ≥ 3.9.

Install

pip install -e .

Quick start

import woodelf
from woodelf import (
    ElfHeaderEditor,
    SectionHeaderEditor,
    SymbolEditor,
    DynamicEntryEditor,
    SECTION,
)

elf = woodelf.parse("/path/to/binary")

# Inspect the ELF header
hdr = ElfHeaderEditor(elf).read_elf_header()
print(hdr.typ, hex(hdr.entry))

# Walk section headers
for sh in SectionHeaderEditor(elf).read_section_header_table():
    print(sh.name, hex(sh.addr), sh.siz)

# Mutate a symbol's value, then save to a new path
syms_editor = SymbolEditor(elf, SECTION.SYMTAB)
syms = syms_editor.read_symbol_table()
main = next(s for s in syms if s.name == "main")
main.value = 0x401234
syms_editor.write_symbol_table(syms)

elf.write("/path/to/output")

API

from woodelf import (
    parse, Elf, MalformedElfError, SECTION, gnu_hash,
    ElfHeaderEditor, SectionHeaderEditor, ProgramHeaderEditor,
    SymbolEditor, StrTabEditor, DynamicEntryEditor, SymbolVersionEditor,
)

parse(path, toolchain_path=None, prefix='') -> Elf | None

Open and parse an ELF file. Returns None if the file isn't an ELF (bad magic, truncated e_ident). toolchain_path / prefix let woodelf shell out to a cross-toolchain (prefix + 'readelf', prefix + 'objcopy', …) when needed — useful for embedded targets.

Elf

Handle to a parsed ELF. The class itself exposes file-level concerns; structural elements are accessed through their respective editors (see below).

Editors

Each editor stages mutations against one region of the ELF. Read methods return element objects (ElfHeader, SectionHeader, Symbol, DynamicEntry, …); write methods serialize them back. Most write paths are in-place (direct file I/O); content-changing writes (e.g. resizing a section) go through objcopy --update-section, which appends a new revision to elf.revisions.

Elements

Concrete types returned by the editors (see woodelf.elements):

• Header: ElfHeader, E_Ident
• Sections / segments: SectionHeader, SectionHeaderTable, ProgramHeader
• Symbols: Symbol, SymbolTable (with defined_symbols() / needed_symbols() filters)
• Dynamic linker: DynamicEntry
• Symbol versioning: Verdef, Verdaux, Verneed, Vernaux, Version, VerdefTable, VerneedTable, VerauxTable, VersionTable
• Hashing: GNU hash via woodelf.gnu_hash(name)

Errors

MalformedElfError — raised when the file fails structural validation (e.g. a section header table that runs past the end of the file).