From 0fcbfe83dc269e666a4b9621d6d814e87f8d8368 Mon Sep 17 00:00:00 2001 From: morluto <76467478+morluto@users.noreply.github.com> Date: Thu, 19 Nov 2026 21:02:45 -0500 Subject: [PATCH] fix(elf): retain readable build IDs beside compressed notes (#12674) --- docs/guides/native/elf-debug-link.md | 4 + .../binaryDiagnostics/ElfDebugLinkService.ts | 8 +- src/domain/native/elfNoteLayout.ts | 45 +++++++ src/native/elf/ElfDebugLink.ts | 41 +++++-- src/native/elf/ElfNoteParser.ts | 59 +++++++-- src/native/hardening/ElfHardening.ts | 46 +------ tests/acceptance/elfDebugLinkCli.test.ts | 113 ++++++++++++++++++ 7 files changed, 246 insertions(+), 70 deletions(-) diff --git a/docs/guides/native/elf-debug-link.md b/docs/guides/native/elf-debug-link.md index 892e6f08f5..dec76a99dc 100644 --- a/docs/guides/native/elf-debug-link.md +++ b/docs/guides/native/elf-debug-link.md @@ -38,6 +38,10 @@ bytes that follow it. `build_id` reports the GNU build-id from `PT_NOTE` and Distinct build-ids stay in `ids` and none is selected. `sources` lists each contributing GNU build-id note with its table kind and index and the note and descriptor file ranges. +When compressed note storage prevents a complete scan, `build_id.status` +is `unknown`. Readable build IDs and their locations stay in `ids` and +`sources`. The report needs a complete build ID to derive an image build-ID +lookup path or compare against a candidate. `lookup_paths` lists conventional GNU/Linux strings: diff --git a/src/application/binaryDiagnostics/ElfDebugLinkService.ts b/src/application/binaryDiagnostics/ElfDebugLinkService.ts index f652dde246..210b010d27 100644 --- a/src/application/binaryDiagnostics/ElfDebugLinkService.ts +++ b/src/application/binaryDiagnostics/ElfDebugLinkService.ts @@ -265,13 +265,13 @@ const buildIdConsistent = (buildId: ElfDebugLink["build_id"]): boolean => { buildId.reason === null ); if (buildId.status === "unknown") - // An oversized build-id keeps the bounded ids read beside it. + // Unsupported storage and oversized notes can coexist with readable IDs. return ( buildId.hex === null && (buildId.reason === "build_id_exceeds_limit" || - (buildId.ids.length === 0 && - (buildId.reason === "note_tables_malformed" || - buildId.reason === "note_tables_unsupported"))) + buildId.reason === "note_tables_unsupported" || + (buildId.reason === "note_tables_malformed" && + buildId.ids.length === 0)) ); return ( buildId.hex === null && diff --git a/src/domain/native/elfNoteLayout.ts b/src/domain/native/elfNoteLayout.ts index 06d4aca2b5..ddb17569d9 100644 --- a/src/domain/native/elfNoteLayout.ts +++ b/src/domain/native/elfNoteLayout.ts @@ -69,3 +69,48 @@ export const readElfNoteFrame = ( /** A short remainder after the last aligned note may be zero padding. */ export const isElfNotePadding = (bytes: Uint8Array): boolean => bytes.every((byte) => byte === 0); + +export type ElfNoteSpan = { readonly offset: number; readonly size: number }; + +export const sortElfNoteSpans = ( + spans: readonly T[], +): T[] => + spans.filter(({ size }) => size > 0).toSorted((a, b) => a.offset - b.offset); + +/** + * Overlap queries over spans sorted once. A section table can hold hundreds of + * thousands of headers, so a query must not rescan the spans. + */ +export const elfNoteSpanOverlapIndex = (spans: readonly ElfNoteSpan[]) => { + const sorted: ElfNoteSpan[] = []; + for (const span of sortElfNoteSpans(spans)) { + const previous = sorted.at(-1); + if ( + previous !== undefined && + span.offset <= previous.offset + previous.size + ) + sorted[sorted.length - 1] = { + offset: previous.offset, + size: Math.max( + previous.size, + span.offset + span.size - previous.offset, + ), + }; + else sorted.push(span); + } + return ({ offset, size }: ElfNoteSpan): "none" | "covered" | "partial" => { + if (size <= 0) return "none"; + let low = 0; + let high = sorted.length; + while (low < high) { + const middle = (low + high) >>> 1; + if ((sorted[middle]?.offset ?? 0) < offset + size) low = middle + 1; + else high = middle; + } + const span = sorted[low - 1]; + if (span === undefined || span.offset + span.size <= offset) return "none"; + return span.offset <= offset && span.offset + span.size >= offset + size + ? "covered" + : "partial"; + }; +}; diff --git a/src/native/elf/ElfDebugLink.ts b/src/native/elf/ElfDebugLink.ts index 1d586928c0..2ff25b7840 100644 --- a/src/native/elf/ElfDebugLink.ts +++ b/src/native/elf/ElfDebugLink.ts @@ -39,7 +39,11 @@ import { readElfImage, readElfImageCooperative, } from "../../domain/native/elfImage.js"; -import { parseElfNotes, parseElfNotesCooperative } from "./ElfNoteParser.js"; +import { + ElfNoteStorageFailure, + parseElfNotes, + parseElfNotesCooperative, +} from "./ElfNoteParser.js"; import type { ZstandardFramePause } from "../../domain/compression/zstandardExactFrame.js"; import { sharedElfSectionNameDecoder, @@ -395,18 +399,20 @@ const observeBuildId = ( input: InspectElfDebugLinkInput, preparedNotes?: PreparedNotes, ): ObservedBuildId => { - let notes: ReturnType; + let entries: ElfNoteStorageFailure["readableEntries"]; + let unsupportedStorage: ElfNoteStorageFailure | undefined; try { if (preparedNotes !== undefined && !preparedNotes.ok) throw preparedNotes.error; - notes = + entries = ( preparedNotes?.value ?? parseElfNotes( bytes, artifact, buildIdNoteInput(artifact, input), BUILD_ID_NOTE_OPTIONS, - ); + ) + ).entries; } catch (cause) { if ( isRethrownBudget(cause) || @@ -418,19 +424,24 @@ const observeBuildId = ( "note_tables_malformed", `ELF note tables could not be decoded: ${cause.message}`, ); - if (cause instanceof BinaryFormatFailure) + if (cause instanceof ElfNoteStorageFailure) { + unsupportedStorage = cause; + entries = cause.readableEntries; + } else if (cause instanceof BinaryFormatFailure) { return unknownBuildId( cause.kind === "unsupported" ? "note_tables_unsupported" : "note_tables_malformed", `ELF note tables could not be decoded: ${cause.message}`, ); - throw cause; + } else { + throw cause; + } } const ids: string[] = []; const sources: BuildId["sources"] = []; let oversized = false; - for (const entry of notes.entries) { + for (const entry of entries) { if (entry.owner !== "GNU" || entry.type !== GNU_BUILD_ID_NOTE_TYPE) continue; // The parser leaves oversized descriptors undecoded, so judge the raw size. @@ -449,18 +460,23 @@ const observeBuildId = ( descriptor: entry.descriptor.location, }); } - // An oversized note leaves the identity unknown, but the bounded ids and - // their note locations that were read stay as evidence. - if (oversized) + // Retain readable ids and their note locations when identity is incomplete. + if (unsupportedStorage !== undefined || oversized) return { buildId: { status: "unknown", hex: null, ids, sources, - reason: "build_id_exceeds_limit", + reason: + unsupportedStorage === undefined + ? "build_id_exceeds_limit" + : "note_tables_unsupported", }, - limitation: "A GNU build-id exceeds 256 bytes and was not copied.", + limitation: + unsupportedStorage === undefined + ? "A GNU build-id exceeds 256 bytes and was not copied." + : unsupportedStorage.message, }; if (ids.length === 0) return { @@ -498,6 +514,7 @@ const sectionsNamed = ( const BUILD_ID_NOTE_OPTIONS = { maxGnuBuildIdBytes: MAX_ELF_DEBUG_ALT_BUILD_ID_BYTES, + retainReadableNotes: true, }; const buildIdNoteInput = ( artifact: Report["artifact"], diff --git a/src/native/elf/ElfNoteParser.ts b/src/native/elf/ElfNoteParser.ts index 44297f9ac0..0aeffde87e 100644 --- a/src/native/elf/ElfNoteParser.ts +++ b/src/native/elf/ElfNoteParser.ts @@ -18,6 +18,7 @@ import { ELF_NOTE_HEADER_BYTES, elfNoteAlignment as noteAlignment, elfNoteSectionStorage, + elfNoteSpanOverlapIndex, isElfNotePadding, readElfNoteFrame, type ElfNoteAlignment, @@ -648,6 +649,19 @@ const decodeCore = ( export interface ElfNoteParseOptions { /** Leave larger GNU build-ids undecoded; `descsz` still reports their size. */ readonly maxGnuBuildIdBytes?: number; + /** Retain readable notes on the unsupported result for debug-link evidence. */ + readonly retainReadableNotes?: boolean; +} + +type ElfNoteEntry = Omit; + +const COMPRESSED_NOTE_MESSAGE = + "Compressed ELF note sections are unsupported; descriptor file offsets require uncompressed note storage."; + +export class ElfNoteStorageFailure extends BinaryFormatFailure { + constructor(readonly readableEntries: readonly ElfNoteEntry[]) { + super("unsupported", COMPRESSED_NOTE_MESSAGE); + } } const ANDROID_IDENT_SLOT_BYTES = 64; @@ -842,7 +856,8 @@ const parseElfNoteSteps = function* ( ); } const tables: ElfNotes["tables"] = []; - const parsed: ReturnType[] = []; + const parsed: ElfNoteEntry[] = []; + let unreadCompressedNotes = false; const examined = { count: 0 }; const noteSections = []; const compressedNoteRanges = new Set(); @@ -872,6 +887,19 @@ const parseElfNoteSteps = function* ( compressedNoteRanges.add(`${offset}:${size}`); } } + const fileEnd = BigInt(bytes.length); + const compressedOverlap = + options.retainReadableNotes === true && compressedNoteRanges.size > 0 + ? elfNoteSpanOverlapIndex( + noteSections.flatMap(({ offset, size, storage }) => + storage === "compressed" && + offset <= fileEnd && + size <= fileEnd - offset + ? [{ offset: Number(offset), size: Number(size) }] + : [], + ), + ) + : undefined; if (phnum !== 0) { if (phoff < header.headerSize) return fail("ELF program header table overlaps the native header."); @@ -893,11 +921,13 @@ const parseElfNoteSteps = function* ( return fail("ELF offset or size exceeds a safe integer."); const fileOffset = Number(program.offset); const fileSize = Number(program.fileSize); - // An exact program alias does not turn compressed storage into a note - // stream. The section still owns the unsupported-storage outcome. + // Compressed storage owns the unsupported outcome. A partial scan + // keeps facts only from independently framed ranges. if ( - compressedNoteRanges.size > 0 && - compressedNoteRanges.has(`${program.offset}:${program.fileSize}`) + (compressedNoteRanges.size > 0 && + compressedNoteRanges.has(`${program.offset}:${program.fileSize}`)) || + (compressedOverlap !== undefined && + compressedOverlap({ offset: fileOffset, size: fileSize }) !== "none") ) { reader.require(fileOffset, fileSize); continue; @@ -940,11 +970,17 @@ const parseElfNoteSteps = function* ( const fileOffset = Number(offset); const fileSize = Number(size); reader.require(fileOffset, fileSize); - if (storage === "compressed") - throw new BinaryFormatFailure( - "unsupported", - "Compressed ELF note sections are unsupported; descriptor file offsets require uncompressed note storage.", - ); + if (storage === "compressed") { + if (options.retainReadableNotes !== true) + throw new BinaryFormatFailure("unsupported", COMPRESSED_NOTE_MESSAGE); + unreadCompressedNotes = true; + continue; + } + if ( + compressedOverlap !== undefined && + compressedOverlap({ offset: fileOffset, size: fileSize }) !== "none" + ) + continue; if (declaredAlignment > BigInt(Number.MAX_SAFE_INTEGER)) return fail("ELF offset or size exceeds a safe integer."); const alignment = noteAlignment(Number(declaredAlignment)); @@ -972,6 +1008,7 @@ const parseElfNoteSteps = function* ( )) parsed.push(toEntry(note, "section", index, header, text, fdo)); } + if (unreadCompressedNotes) throw new ElfNoteStorageFailure(parsed); const absent = tables.length === 0; return { artifact, @@ -1061,7 +1098,7 @@ const toEntry = ( header: ElfFixedHeader, text: TextBudget, fdo: FdoDecodeBudget, -): Omit => { +): ElfNoteEntry => { const little = header.byteOrder === "little"; const linuxCore = isLinuxCoreProfile(header); const typeName = elfNoteTypeName(note.owner, note.type, linuxCore); diff --git a/src/native/hardening/ElfHardening.ts b/src/native/hardening/ElfHardening.ts index b3145ef760..f2c89efb3a 100644 --- a/src/native/hardening/ElfHardening.ts +++ b/src/native/hardening/ElfHardening.ts @@ -45,6 +45,9 @@ import { import { elfNoteAlignment, elfNoteSectionStorage, + elfNoteSpanOverlapIndex as overlapIndex, + sortElfNoteSpans as byOffset, + type ElfNoteSpan as NoteSpan, } from "../../domain/native/elfNoteLayout.js"; import { MAX_INSPECT_ELF_NOTE_ENTRIES } from "../../domain/native/elfNotes.js"; import { @@ -759,49 +762,6 @@ const noteTable = ( return { offset, size, alignment }; }; -type NoteSpan = { readonly offset: number; readonly size: number }; - -const byOffset = (spans: readonly T[]): T[] => - spans.filter(({ size }) => size > 0).toSorted((a, b) => a.offset - b.offset); - -/** - * Overlap queries over spans sorted once. A section table can hold hundreds of - * thousands of headers, so a query must not rescan the spans. - */ -const overlapIndex = (spans: readonly NoteSpan[]) => { - const sorted: NoteSpan[] = []; - for (const span of byOffset(spans)) { - const previous = sorted.at(-1); - if ( - previous !== undefined && - span.offset <= previous.offset + previous.size - ) - sorted[sorted.length - 1] = { - offset: previous.offset, - size: Math.max( - previous.size, - span.offset + span.size - previous.offset, - ), - }; - else sorted.push(span); - } - return ({ offset, size }: NoteSpan): "none" | "covered" | "partial" => { - if (size <= 0) return "none"; - let low = 0; - let high = sorted.length; - while (low < high) { - const middle = (low + high) >>> 1; - if ((sorted[middle]?.offset ?? 0) < offset + size) low = middle + 1; - else high = middle; - } - const span = sorted[low - 1]; - if (span === undefined || span.offset + span.size <= offset) return "none"; - return span.offset <= offset && span.offset + span.size >= offset + size - ? "covered" - : "partial"; - }; -}; - type NoteOverlap = "uncovered" | "cut" | "framing"; /** Effective alignment at a table boundary, or `null` when tables there disagree. */ diff --git a/tests/acceptance/elfDebugLinkCli.test.ts b/tests/acceptance/elfDebugLinkCli.test.ts index cf00f7a96d..57ba6179bd 100644 --- a/tests/acceptance/elfDebugLinkCli.test.ts +++ b/tests/acceptance/elfDebugLinkCli.test.ts @@ -10,6 +10,11 @@ import { FIXTURE_BUILD_ID_HEX, FIXTURE_DEBUG_NAME, } from "../../src/native/elf/ElfDebugLink.fixture.js"; +import { + compressedElfNoteSectionFixture, + gnuBuildIdNote, + withElf64DirectSectionCount, +} from "../../src/native/elf/ElfNotes.fixture.js"; import { createTestTempDirectory } from "../fixtures/temporaryDirectory.js"; import { cliTest } from "../support/cli/cliFixture.js"; @@ -163,3 +168,111 @@ cliTest("reports a non-ELF file as invalid input", async ({ cli }) => { details: { operation: "inspect_elf_debug_link" }, }); }); + +cliTest( + "retains separate readable build IDs beside compressed ELF notes", + async ({ cli }) => { + const root = await createTestTempDirectory( + "rea-elf-debug-link-note-storage-", + ); + const candidatePath = join(root, "candidate.debug"); + const compressed = withElf64DirectSectionCount( + compressedElfNoteSectionFixture(64, true, "both"), + 4, + ); + const buildId = "a1".repeat(20); + const program = gnuBuildIdNote(buildId); + const section = gnuBuildIdNote(buildId); + await writeFile( + candidatePath, + elfDebugCandidateFixture({ buildIdHex: buildId }), + ); + const programOffset = compressed.length; + const sectionOffset = programOffset + program.length; + const mixed = Buffer.concat([compressed, program, section]); + + // Point the existing PT_NOTE at the readable program range rather than + // its initial alias of the compressed section, which is still section 1. + mixed.writeBigUInt64LE(BigInt(programOffset), 64 + 8); + mixed.writeBigUInt64LE(BigInt(program.length), 64 + 32); + mixed.writeBigUInt64LE(BigInt(program.length), 64 + 40); + mixed.writeBigUInt64LE(4n, 64 + 48); + // Add a readable section after the compressed section in directory order. + const row = Number(mixed.readBigUInt64LE(40)) + 3 * 64; + mixed.writeUInt32LE(1, row); + mixed.writeUInt32LE(7, row + 4); + mixed.writeBigUInt64LE(BigInt(sectionOffset), row + 24); + mixed.writeBigUInt64LE(BigInt(section.length), row + 32); + mixed.writeBigUInt64LE(4n, row + 48); + const withAlias = Buffer.from(mixed); + const compressedRow = row - 2 * 64; + const compressedOffset = withAlias.readBigUInt64LE(compressedRow + 24); + const compressedBytes = withAlias.readBigUInt64LE(compressedRow + 32); + // The relocated section directory leaves this program header slot free. + // Its range starts inside compressed storage, so it provides no note. + const aliasHeader = 64 + 56; + withAlias.writeUInt16LE(2, 56); + withAlias.fill(0, aliasHeader, aliasHeader + 56); + withAlias.writeUInt32LE(4, aliasHeader); + withAlias.writeBigUInt64LE(compressedOffset + 4n, aliasHeader + 8); + withAlias.writeBigUInt64LE(compressedBytes - 4n, aliasHeader + 32); + withAlias.writeBigUInt64LE(compressedBytes - 4n, aliasHeader + 40); + withAlias.writeBigUInt64LE(4n, aliasHeader + 48); + + for (const [name, image] of [ + ["mixed-notes", mixed], + ["partial-alias", withAlias], + ] as const) { + const path = join(root, name); + await writeFile(path, image); + const result = await cli.run({ + arguments: [ + "inspect-elf-debug-link", + path, + "--candidate-path", + candidatePath, + "--json", + ], + }); + expect(result.exitCode, JSON.stringify(result.json)).toBe(0); + const report = debugLinkContract.outputSchema.parse( + result.json, + ).normalized_result; + expect(report.build_id).toMatchObject({ + status: "unknown", + reason: "note_tables_unsupported", + hex: null, + ids: [buildId], + sources: [ + { + hex: buildId, + table_kind: "program", + table_index: 0, + note: { offset: programOffset, bytes: program.length }, + descriptor: { offset: programOffset + 16, bytes: 20 }, + }, + { + hex: buildId, + table_kind: "section", + table_index: 3, + note: { offset: sectionOffset, bytes: section.length }, + descriptor: { offset: sectionOffset + 16, bytes: 20 }, + }, + ], + }); + expect(report.coverage.status).toBe("partial"); + expect(report.lookup_paths.some(({ kind }) => kind === "build_id")).toBe( + false, + ); + expect(report.verification).toMatchObject({ + status: "cannot_verify", + build_id: { + status: "unavailable", + reason: "binary_build_id_unknown", + binary_hex: null, + candidate_hex: buildId, + }, + }); + } + }, +);