mirror of
https://github.com/morluto/rea.git
synced 2026-11-18 04:34:13 +00:00
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>
3.9 KiB
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
- 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.
.gnu_debuglinkreports its NUL-terminated file name and the CRC32 that follows the 4-byte padding, in the image endianness..gnu_debugaltlinkreports its NUL-terminated file name and the raw build-id bytes that follow it.- The GNU build-id is read from
PT_NOTEandSHT_NOTEtables 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. .gnu_debugdatareports presence, file offset, stored size, and whether the first six bytes are the xz magic. The payload is not decoded.lookup_pathslists 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.- A missing named section is observed absence only when section names are
complete. Incomplete names make it
unknown. A malformed or truncated section ismalformed, not absence. - 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 ismatches. If neither check can run, the status iscannot_verify. The candidate's.debug_infoand.symtabpresence is reported. - The candidate is streamed in bounded chunks. Candidates within
max_file_bytesare 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 returnscannot_verifywithcandidate_unreadable, and the image linkage is still reported. A candidate that exceeds themax_entriesor ELF decoding budget keeps the image linkage and the CRC32 check; its build-id check isunavailablewithcandidate_build_id_unknown, and sections that were not decoded areunknown. - Names, build-ids and note scans are bounded: 4096-byte names, 256-byte
build-ids, and a
max_entriesnote budget. Target-derived names and lookup paths are marked untrusted. - 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_debugdataxz payload. - Loading DWARF from the candidate.