fix(elf): retain readable build IDs beside compressed notes (#12674)

This commit is contained in:
morluto authored and GitHub committed 2026-11-20 02:02:45 +00:00
1 parent 460517d1b7
commit 0fcbfe83dc
7 files changed
+246 -70

No files matched your search

+4
View File
@@ -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:
@@ -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 &&
+45
View File
@@ -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 = <T extends ElfNoteSpan>(
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";
};
};
+29 -12
View File
@@ -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<typeof parseElfNotes>;
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"],
+48 -11
View File
@@ -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<ElfNotes["entries"][number], "index">;
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<typeof toEntry>[] = [];
const parsed: ElfNoteEntry[] = [];
let unreadCompressedNotes = false;
const examined = { count: 0 };
const noteSections = [];
const compressedNoteRanges = new Set<string>();
@@ -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<ElfNotes["entries"][number], "index"> => {
): ElfNoteEntry => {
const little = header.byteOrder === "little";
const linuxCore = isLinuxCoreProfile(header);
const typeName = elfNoteTypeName(note.owner, note.type, linuxCore);
+3 -43
View File
@@ -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 = <T extends NoteSpan>(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. */
+113
View File
@@ -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,
},
});
}
},
);