Files
reverse-engineering-anything/docs/specs/native/dwarf-units/spec.md
T
Matt Van Hornandgensokyo-dev 637e4cb60c feat(native): inspect DWARF compile units offline
Add bounded offline DWARF compilation-unit inspection with source provenance, explicit coverage, caller-selected controls and shared ELF compression framing.

Assisted-by: Suika (gensokyo-skills:suika-scatter-gather-planning)
Co-authored-by: gensokyo-dev <342580529+gensokyo-dev@users.noreply.github.com>
2026-11-17 10:04:46 +00:00

3.8 KiB

DWARF compile-unit inspection

Problem and outcome

Learning what a native binary was built from currently needs a deep provider or GNU objdump through inspect_with_objdump, which returns -W text the caller has to parse. Add inspect_dwarf_units / inspect-dwarf-units, a built-in reader of DWARF 2 through 5 compile units in one selected local ELF, Mach-O or PE image. It returns structured unit facts with no provider installed and never executes the target.

Requirements

  • Read compile-unit headers and the unit-level DIE only. Each unit reports version, unit type when the header has one, address size, name, comp_dir, producer, language code and DWARF 5 language name, dwo_name (DW_AT_dwo_name or DW_AT_GNU_dwo_name), stmt_list and whether DW_AT_low_pc is present.
  • Each attribute carries an explicit present, absent, unresolved or unknown state. A value that cannot be trusted is never returned as a fact.
  • Locate .debug_info, .debug_abbrev, .debug_str, .debug_line_str and .debug_str_offsets by container. Mach-O sections are read only from the __DWARF segment, by file range rather than VM mapping. Decompress ELF SHF_COMPRESSED zlib and zstd, and GNU .zdebug_* and Mach-O __zdebug_* zlib, within a fixed 256 MiB decompressed allowance; a larger declared size fails the call.
  • Bound DWARF 5 strx indexes to their .debug_str_offsets contribution and apply DW_AT_str_offsets_base regardless of attribute order. Decode chained DW_FORM_indirect within the unit. An unknown form becomes a unit issue that names the form code.
  • Identify ELF relocation sections by type and sh_info target. In an ET_REL image with unapplied debug relocations, relocated fields stay unresolved; when .debug_abbrev holds more than one table, abbrev_offset is null, the unit reports unapplied_relocation and its DIE is not read.
  • Page units with offset and limit (default 32, maximum 256). Bound the walk (100,000 units), abbreviation entries (8,192) and attributes (256), retained string bytes (64 KiB), unit issues (32) and the input read (512 MiB). Decompression attempts and abbreviation parsing share aggregate work allowances. Form reads and DW_FORM_indirect hops share a 1,048,576-step allowance per walk; exhaustion is a decode_budget unit issue with partial coverage.
  • Report coverage.status from the shared coverage vocabulary (complete, or partial with a reason) and debug_info as present or absent. absent does not establish that a separate debug file is absent; ELF and PE limitations name whether .gnu_debuglink was observed. A .dwo object is partial because .debug_info.dwo is not read.
  • A universal Mach-O requires architecture; the value is rejected for every other image. MCP requires an absolute path.

Acceptance

Unit, provider, boundary, MCP and CLI acceptance tests cover DWARF 2 through 5, 64-bit offsets, compressed sections, split skeletons, unknown forms, truncated units, abbreviation budgets, relocatable objects and the decompressed-size allowance. npm run verify:dwarf-units builds owned C fixtures and compares every unit's version, name, comp_dir, producer and dwo_name with llvm-dwarfdump across Mach-O objects and linked ELF and PE images, and checks fixed expectations for an ELF relocatable object, an ld.lld -r merge and a .dwo object. The verification record lists the variants run and those skipped.

Out of scope

Line tables, types, functions, child DIEs and location expressions; following .dwo files, .gnu_debuglink or build-id links; decoding .gnu_debuglink contents or GNU build-id notes; applying relocations; opening .dSYM bundles; and target execution.