mirror of
https://github.com/morluto/rea.git
synced 2026-11-19 21:23:45 +00:00
Co-authored-by: ShuaixinHuang <197200901+ShuaixinHuang@users.noreply.github.com>
108 lines
6.6 KiB
Markdown
108 lines
6.6 KiB
Markdown
# Native initializer and finalizer functions
|
|
|
|
## Problem and outcome
|
|
|
|
Analysts reviewing a native image need the functions it declares to run before
|
|
`main` and at exit, without executing it or opening a disassembler provider.
|
|
`inspect_native_initializers` / `inspect-native-initializers` lists the
|
|
initializer and finalizer slots of one local ELF or Mach-O image, with each
|
|
slot's location, resolved target and how that target was obtained. The
|
|
[user guide](../../../guides/native/native-initializers.md) documents the result.
|
|
|
|
## Requirements
|
|
|
|
- Accept one local ELF32, ELF64, thin Mach-O or universal Mach-O image. A
|
|
universal Mach-O requires `architecture` to select one slice; other inputs
|
|
reject it. The CLI resolves relative paths; MCP requires an absolute path.
|
|
- ELF sources, in order: `DT_PREINIT_ARRAY`, `DT_INIT`, `DT_INIT_ARRAY`, legacy
|
|
`.ctors`, `DT_FINI`, `DT_FINI_ARRAY`, legacy `.dtors`. Without the dynamic tag,
|
|
fall back to `SHT_*_ARRAY` sections or `.init_array*` / `.fini_array*` /
|
|
`.preinit_array` names. Mach-O sources are sections typed
|
|
`S_MOD_INIT_FUNC_POINTERS`, `S_INIT_FUNC_OFFSETS` and
|
|
`S_MOD_TERM_FUNC_POINTERS`.
|
|
- Resolve values through RELATIVE and RELR dynamic relocations, then section
|
|
REL / RELA records for slots no dynamic relocation covers, then the stored
|
|
word when relocation coverage is known. Mach-O uses chained-fixup rebases,
|
|
`LC_DYLD_INFO` rebases (reported separately), `MH_OBJECT` section
|
|
relocations and `__init_offsets` image-base offsets. Anything else is
|
|
`unresolved`, never a stored zero.
|
|
- Resolve `SHN_XINDEX` through a uniquely linked, complete `SHT_SYMTAB_SHNDX`
|
|
table. Keep actual section indices separate from raw absolute/common/reserved
|
|
markers. Unreadable extensions preserve unknowns and independent ordinary symbols.
|
|
- Relocation coverage is per slot. A slot that a dynamic or section relocation
|
|
only partly overwrites or writes more than once is `unresolved`, and so is an
|
|
absolute relocation against an `STT_GNU_IFUNC` resolver. On 32-bit ARM the
|
|
Thumb bit is cleared for target section and file-offset lookup only. A slot with no
|
|
relocation found is `unresolved` when a dynamic table, or a section table
|
|
that could reach it, was not fully read; such a `.ctors` slot is not dropped
|
|
as a sentinel. A `COPY` relocation covers the bytes of its symbol's size and
|
|
a TLS descriptor two words. The size comes from the dynamic symbol table for
|
|
a dynamic record and from the table's linked symbols for a section record of
|
|
a linked image; an unread size leaves coverage unknown. A linked image's
|
|
section record that writes memory with no file bytes covers only the slots
|
|
it overlaps there when its extent is established, by a fixed width or a
|
|
`COPY` size, and otherwise leaves its table not fully read. A
|
|
linked image's non-`SHF_ALLOC` relocation sections were
|
|
applied at link time and are not reapplied. A Mach-O stored pointer word is
|
|
used only when no undecoded bind stream or external relocation could
|
|
replace it.
|
|
- Relocatable objects (`ET_REL`) report section-relative offsets and say so.
|
|
- `.ctors` / `.dtors` sentinels are 0 and all ones at the image's pointer width;
|
|
they are omitted and counted in a limitation.
|
|
- `DT_INIT` / `DT_FINI` have no slot pointer: their slot is the dynamic value
|
|
field, and `slot_va` / `slot_section` are null when that field is outside
|
|
every load segment.
|
|
- Names are exact untrusted file text marked `observed-untrusted`. A target is
|
|
named only by a defined symbol whose value equals it, or by the import name
|
|
of an unresolved symbolic relocation or chained bind. An unreadable name
|
|
(missing string table or offset outside it) is reported as no name and makes
|
|
the report `incomplete`.
|
|
- Bounds: 64 MiB default file budget (512 MiB maximum); 65536 slots in total;
|
|
65536 symbols across all ELF symbol tables; 65536 symbols across all
|
|
Mach-O `LC_SYMTAB` commands; 1048576 section relocation records across all
|
|
relocation sections; 1024-byte names. Reaching a bound makes the report
|
|
`incomplete` with a limitation.
|
|
- Legacy Mach-O bind lookup permits at most 4096 candidate runs per query
|
|
and twice the file byte count across image queries. Exhaustion leaves
|
|
affected pointers unresolved; stream parsing and slot batches yield.
|
|
- Limitations are bounded: at most 24 distinct image observations, repeated
|
|
per-row reasons reported once with a count, and at most 40 lines in total.
|
|
- Section lookups for slot and target addresses use an index built once per
|
|
image, so their cost does not grow with headers times slots.
|
|
- Paging uses `offset` / `limit` (default 64, maximum 4096) over a stable
|
|
ordered index. `coverage.examined_entries` counts every slot read, including
|
|
omitted sentinels; `total_entries` is set only when the inventory is complete.
|
|
`coverage.status` is `partial` when declared slots or names were examined but
|
|
not reported (budgets, unreadable arrays, withheld names) and `unknown` when
|
|
completeness cannot be determined (relocation, fixup, symbol or mapping
|
|
coverage, duplicate or unterminated dynamic tags); unknown wins when both
|
|
occur.
|
|
- Malformed headers, multiple `PT_DYNAMIC` segments and truncated dynamic
|
|
sections fail without partial success. Cancellation is honored during slot
|
|
collection, the section relocation walk and the dynamic relocation walk,
|
|
which yields to other work at the shared reader's step boundaries.
|
|
|
|
## Acceptance
|
|
|
|
Parser tests cover ELF64 PIE (RELA, RELR, imports, `DT_INIT` / `DT_FINI`),
|
|
ELF32 REL in-place addends, `ET_REL` section relocations and sentinels,
|
|
unsupported relocation machines, slot, symbol and relocation budgets,
|
|
over-long names, tallied repeated observations, a near-maximal section table
|
|
with a full slot budget, cancellation in the relocation walks, skipped section
|
|
relocation tables, partly overwritten slots, `COPY` and TLS descriptor extents,
|
|
section `COPY` records sized by their symbol, section records that write
|
|
memory without file bytes, retained link-time
|
|
relocations, unreadable names, Mach-O chained fixups, `LC_DYLD_INFO` rebases, 32-bit images
|
|
with undecoded binds, `MH_OBJECT` section relocations, `__init_offsets`, the
|
|
shared and repeated `LC_SYMTAB` budget, and universal slices. CLI acceptance, filesystem boundary
|
|
and MCP boundary tests exercise the public workflows and Evidence output.
|
|
|
|
## Out of scope
|
|
|
|
Executing the image or proving that a listed address runs; runtime ordering
|
|
(file order is reported); disassembling initializer bodies; PE/COFF TLS
|
|
callbacks; Android packed relocations and machines other than x86-64, i386,
|
|
AArch64 and 32-bit ARM for relocation decoding; Mach-O fixup decoding for
|
|
images other than little-endian 64-bit arm64 and x86-64, and legacy
|
|
`LC_DYSYMTAB` external relocations.
|