* refactor(native)!: report native initializer coverage as partial or unknown instead of incomplete inspect_native_initializers coverage.status was `incomplete` for both a known gap (slot budget, unreadable arrays, withheld names) and undetermined coverage (relocation, fixup, symbol or mapping coverage, duplicate or unterminated dynamic tags). The scans now record which one each observation causes and the report uses the shared coverage status: `partial` for a known gap, `unknown` when completeness cannot be determined, unknown winning when both occur. The top-level `status` keeps `parsed` / `incomplete`. BREAKING CHANGE: inspect_native_initializers `coverage.status` reports `partial` or `unknown` instead of `incomplete`. Treat both as not complete; `partial` means declared slots or names were left unreported, `unknown` means the report could not establish completeness. * fix(native): report a withheld object-file relocation symbol name as partial coverage nameAt labelled every name over the budget as unknown coverage. In an MH_OBJECT the relocation symbol it reads is the reported entry's own import or defined name, so withholding it is a known gap. The caller now states the effect: the object-file relocation symbol is partial (and is read only when the entry reports it), the LC_SYMTAB address index stays unknown (#11500).
6.4 KiB
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 documents the result.
Requirements
- Accept one local ELF32, ELF64, thin Mach-O or universal Mach-O image. A
universal Mach-O requires
architectureto 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 toSHT_*_ARRAYsections or.init_array*/.fini_array*/.preinit_arraynames. Mach-O sources are sections typedS_MOD_INIT_FUNC_POINTERS,S_INIT_FUNC_OFFSETSandS_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_INFOrebases (reported separately),MH_OBJECTsection relocations and__init_offsetsimage-base offsets. Anything else isunresolved, never a stored zero. - 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 anSTT_GNU_IFUNCresolver. On 32-bit ARM the Thumb bit is cleared for target section and file-offset lookup only. A slot with no relocation found isunresolvedwhen a dynamic table, or a section table that could reach it, was not fully read; such a.ctorsslot is not dropped as a sentinel. ACOPYrelocation 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 aCOPYsize, and otherwise leaves its table not fully read. A linked image's non-SHF_ALLOCrelocation 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/.dtorssentinels are 0 and all ones at the image's pointer width; they are omitted and counted in a limitation.DT_INIT/DT_FINIhave no slot pointer: their slot is the dynamic value field, andslot_va/slot_sectionare 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 reportincomplete. - 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_SYMTABcommands; 1048576 section relocation records across all relocation sections; 1024-byte names. Reaching a bound makes the reportincompletewith 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_entriescounts every slot read, including omitted sentinels;total_entriesis set only when the inventory is complete.coverage.statusispartialwhen declared slots or names were examined but not reported (budgets, unreadable arrays, withheld names) andunknownwhen completeness cannot be determined (relocation, fixup, symbol or mapping coverage, duplicate or unterminated dynamic tags); unknown wins when both occur. - Malformed headers, multiple
PT_DYNAMICsegments 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.