Files
reverse-engineering-anything/docs/specs/native/elf-debug-link/spec.md
T
Matt Van Hornandgensokyo-dev 54e3918d1c feat(elf): report separate debug-file linkage and verify a candidate debug file
Add offline ELF separate-debug linkage inspection with explicit candidate verification, bounded streaming, canonical parser limits and preserved complete/partial Evidence provenance.

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

3.9 KiB

ELF separate debug-file linkage

Problem and outcome

A stripped ELF often names a separate debug file through .gnu_debuglink, .gnu_debugaltlink, or its GNU build-id. REA reports ELF notes and layout, but it has no workflow that answers which debug file an image names or whether a file the caller already has is that debug file. An agent has to guess from file names.

This feature adds inspect_elf_debug_link and inspect-elf-debug-link. They read one selected ELF32 or ELF64 image, report its debug-file linkage, and, when the caller supplies one candidate file, check whether the candidate matches.

ELF debug files describes the current behavior and limitations. This directory is the feature specification, implementation plan and task list. The guide does not replace these files.

Requirements

  1. The image is a local ELF32 or ELF64 file, read through the stable artifact read. It is never executed. Nothing is searched for on the filesystem or the network.
  2. .gnu_debuglink reports its NUL-terminated file name and the CRC32 that follows the 4-byte padding, in the image endianness.
  3. .gnu_debugaltlink reports its NUL-terminated file name and the raw build-id bytes that follow it.
  4. The GNU build-id is read from PT_NOTE and SHT_NOTE tables through the existing ELF note parser. The same build-id from both tables is one observation. Distinct build-ids are listed and none is selected.
  5. .gnu_debugdata reports presence, file offset, stored size, and whether the first six bytes are the xz magic. The payload is not decoded.
  6. lookup_paths lists the conventional GNU/Linux strings derived from the build-id, the debuglink name, and the alternate build-id. These strings are not opened. A debuglink name that is empty, ., .., or contains a path separator does not produce the directory-derived strings.
  7. A missing named section is observed absence only when section names are complete. Incomplete names make it unknown. A malformed or truncated section is malformed, not absence.
  8. With a candidate, the CRC32 over the whole candidate and the image and candidate GNU build-ids are compared. Any mismatch is does_not_match. A match with no mismatch is matches. If neither check can run, the status is cannot_verify. The candidate's .debug_info and .symtab presence is reported.
  9. The candidate is streamed in bounded chunks. Candidates within max_file_bytes are also decoded for sections and build-id. Larger ones get CRC32 and SHA-256 over the whole file and an ELF header decode only. A missing, unreadable, changed, or over-limit candidate returns cannot_verify with candidate_unreadable, and the image linkage is still reported. A candidate that exceeds the max_entries or ELF decoding budget keeps the image linkage and the CRC32 check; its build-id check is unavailable with candidate_build_id_unknown, and sections that were not decoded are unknown.
  10. Names, build-ids and note scans are bounded: 4096-byte names, 256-byte build-ids, and a max_entries note budget. Target-derived names and lookup paths are marked untrusted.
  11. MCP requires absolute paths through absoluteLocalPathStringSchema, and the advertised schema carries that constraint. The CLI resolves relative paths against the working directory.

Acceptance

  • Unit tests cover each section layout, both endiannesses, malformed and truncated sections, conflicting build-ids, and lookup path derivation.
  • Service tests cover candidate match, mismatch, unreadable, oversized, and late cancellation.
  • CLI acceptance, filesystem boundary, and MCP boundary tests exercise the public contract, including the absolute-path schema.

Non-goals

  • Searching debug directories or debuginfod for a candidate.
  • Decoding the .gnu_debugdata xz payload.
  • Loading DWARF from the candidate.