elfsym

Documentation

Overview

Package elfsym provides ELF symbol resolution and SONAME parsing primitives shared across language-specific injectors (inject/python, future inject/nodejs, etc.). Pure stdlib (debug/elf + regexp); no CGO, no external dependencies.

Index

• func FirstLoadVaddr(path string) (uint64, error)
• func IsPython312Plus(major, minor int) bool
• func ParseLibpythonSONAME(path string) (major, minor int, ok bool)
• func ResolveSymbols(path string, names []string) (map[string]uint64, error)

Functions

func FirstLoadVaddr

func FirstLoadVaddr(path string) (uint64, error)

FirstLoadVaddr returns the p_vaddr of the PT_LOAD segment that covers file offset 0 (the segment with the ELF header). Combined with the start address of the matching /proc/<pid>/maps entry, this gives the load bias:

load_bias = mapping_start - FirstLoadVaddr(path)
abs_addr  = load_bias + sym.Value

For typical PIE shared libraries / PIE executables (p_vaddr == 0), load_bias collapses to mapping_start and the formula matches the long-standing convention. For non-PIE ET_EXEC binaries — Ubuntu /usr/bin/python3.12 has p_vaddr = 0x400000 and ships absolute symbol values — load_bias correctly resolves to 0, leaving sym.Value untouched. Without this correction, doubling mapping_start onto an already-absolute symbol drops RIP into garbage on remote call.

func IsPython312Plus

func IsPython312Plus(major, minor int) bool

IsPython312Plus reports whether the given (major, minor) version is at least 3.12 — the minimum CPython version that ships sys.activate_stack_trampoline.

func ParseLibpythonSONAME

func ParseLibpythonSONAME(path string) (major, minor int, ok bool)

ParseLibpythonSONAME extracts the major and minor version from a libpython shared-library path. It accepts either a bare basename or a full path; only the basename is matched against the libpython regex. Returns (major, minor, true) on a successful match; (0, 0, false) otherwise.

func ResolveSymbols

func ResolveSymbols(path string, names []string) (map[string]uint64, error)

ResolveSymbols opens the ELF file at path and resolves each symbol name in names to its file-offset value (the symbol's st_value). Returned map only contains entries for symbols that were found; missing symbols are silently absent. The caller adds the runtime load base to each value to compute the remote process's address.

.dynsym is searched first (the dynamic symbol table is always present in shared libraries and required at runtime). If a name is not found there AND .symtab is present (i.e. binary not stripped), .symtab is searched as a fallback. This matters for some Python distributions that intentionally strip non-API symbols from .dynsym but leave .symtab intact.

Returns os.ErrNotExist (wrapped) if path does not exist; other errors are wrapped with context.