diff --git a/docs/elf-dependencies.md b/docs/elf-dependencies.md index 182a9190c0..931c11c082 100644 --- a/docs/elf-dependencies.md +++ b/docs/elf-dependencies.md @@ -33,9 +33,11 @@ Linux kernel modules. Core dumps are not this inventory; use ## Observations The inline Evidence result contains the artifact path, SHA-256, and byte length. -`needed[]` lists every `DT_NEEDED` string in dynamic-table order, including -duplicate names. `dynamic.soname` is the `DT_SONAME` string when that tag is -present. `dynamic.rpath` and `dynamic.runpath` keep the raw `DT_RPATH` / +`needed[]` lists every `DT_NEEDED` entry in dynamic-table order, including +duplicate names. An unreadable name stays null and retains its string-table +index. If that index has no backed string location, its diagnostic points to +the dynamic-table entry. `dynamic.soname` is the `DT_SONAME` string when that +tag is present. `dynamic.rpath` and `dynamic.runpath` keep the raw `DT_RPATH` / `DT_RUNPATH` string, the `:`-split entries without dropping empties, and any `$ORIGIN`, `$LIB`, or `$PLATFORM` tokens as written, including `${...}` forms. Those tokens are not expanded against the host filesystem. diff --git a/src/domain/elfStringTable.ts b/src/domain/elfStringTable.ts index 18b3cb5e52..bfed8675c5 100644 --- a/src/domain/elfStringTable.ts +++ b/src/domain/elfStringTable.ts @@ -45,6 +45,14 @@ export const observeElfStringTableEntry = ( }; /** Project admitted source bytes without inferring an original text encoding. */ -export const elfStringTableText = ( +export function elfStringTableText( + observed: Extract, +): string; +export function elfStringTableText( observed: ElfStringTableObservation, -): string | null => observed.bytes?.toString("latin1") ?? null; +): string | null; +export function elfStringTableText( + observed: ElfStringTableObservation, +): string | null { + return observed.bytes?.toString("latin1") ?? null; +} diff --git a/src/native/elf/ElfDependencyParser.ts b/src/native/elf/ElfDependencyParser.ts index 829316a4b9..c6ae4f7d81 100644 --- a/src/native/elf/ElfDependencyParser.ts +++ b/src/native/elf/ElfDependencyParser.ts @@ -254,13 +254,22 @@ const typeName = (type: number): ElfDependencyImport["type"] => { } }; -interface CString { - readonly name: string | null; - readonly truncated: boolean; - readonly outside: boolean; - /** No NUL within the scan window; the string may continue past it. */ - readonly limited: boolean; -} +type CString = + | { + readonly state: "terminated"; + readonly name: string; + readonly location: number; + } + | { + readonly state: "unterminated" | "scan-limit"; + readonly name: null; + readonly location: number; + } + | { + readonly state: "outside" | "table-unavailable"; + readonly name: null; + readonly location: null; + }; /** * Longest ELF string scanned for its terminator. Each string is hashed and @@ -268,12 +277,27 @@ interface CString { */ const ELF_STRING_SCAN_BYTES = 65536; -/** Why an unreadable string has no name, short of being outside or empty. */ -const unreadString = (observed: Pick): string => - observed.limited +const unreadString = (limited: boolean): string => + limited ? `has no terminator within the ${String(ELF_STRING_SCAN_BYTES)}-byte string scan limit` : "is unterminated"; +const unreadDynamicString = ( + label: string, + observed: CString, + offset?: number, +): string => { + const index = offset === undefined ? "" : ` ${String(offset)}`; + if (observed.state === "table-unavailable") + return `${label} string offset${index} could not be read because the dynamic string table is unavailable`; + if (observed.state === "outside") + return `${label} string offset${index} is outside the dynamic string table`; + const field = `${label} string${offset === undefined ? "" : ` at offset${index}`}`; + if (observed.state === "terminated") return `${field} is empty`; + const table = offset === undefined ? " in the dynamic string table" : ""; + return `${field} ${unreadString(observed.state === "scan-limit")}${table}`; +}; + /** * Dynamic string table reads share one scan and retained-text budget fixed by * the admitted image length. Each offset is scanned and decoded once; every @@ -285,7 +309,7 @@ class DynamicStrings { readonly #retained: Budget; constructor( - readonly table: Buffer, + readonly table: { readonly bytes: Buffer; readonly offset: number } | null, readonly limit: number, ) { this.#scanned = new Budget(limit); @@ -309,34 +333,37 @@ class DynamicStrings { } read(offset: number): CString { + if (this.table === null) + return { state: "table-unavailable", name: null, location: null }; const cached = this.#cache.get(offset); if (cached !== undefined) { this.retain(cached.name); return cached; } const observed = observeElfStringTableEntry( - this.table, + this.table.bytes, offset, ELF_STRING_SCAN_BYTES, ); this.#charge("scanned", observed.examinedBytes); let entry: CString; if (observed.state === "outside") - entry = { name: null, truncated: false, outside: true, limited: false }; + entry = { state: "outside", name: null, location: null }; else if (observed.state === "truncated") entry = { + state: + observed.examinedBytes === ELF_STRING_SCAN_BYTES + ? "scan-limit" + : "unterminated", name: null, - truncated: true, - outside: false, - limited: observed.examinedBytes === ELF_STRING_SCAN_BYTES, + location: this.table.offset + offset, }; else { this.#charge("retained", observed.contentBytes); entry = { + state: "terminated", name: elfStringTableText(observed), - truncated: false, - outside: false, - limited: false, + location: this.table.offset + offset, }; } this.#cache.set(offset, entry); @@ -359,9 +386,7 @@ const searchPath = ( issues.push({ code: "name_unreadable", location, - message: observed.outside - ? "Search-path string offset is outside the dynamic string table" - : `Search-path string ${unreadString(observed)} in the dynamic string table`, + message: unreadDynamicString("Search-path", observed), }); return null; } @@ -746,16 +771,22 @@ export const readElfDependenciesSteps = function* ( const table = reader.range(dynamic.offset, dynamic.bytes, "PT_DYNAMIC"); const unique = new Map(); const addresses = new Map(); - const neededOffsets: number[] = []; + const neededEntries: { + readonly nameOffset: number; + readonly sourceOffset: number; + }[] = []; const walked = walkElfDynamicTable( table, { bits, littleEndian: reader.little }, UNIQUE_DYNAMIC_TAGS, - ({ tag, value, singleton }) => { + ({ tag, value, offset, singleton }) => { if (tag === DT_NEEDED) { - neededOffsets.push(asNumber(value, "DT_NEEDED")); + neededEntries.push({ + nameOffset: asNumber(value, "DT_NEEDED"), + sourceOffset: dynamic.offset + offset, + }); charge( - neededOffsets.length, + neededEntries.length, input.max_needed, MAX_INSPECT_ELF_DEPENDENCY_NEEDED, "DT_NEEDED entries", @@ -886,7 +917,7 @@ export const readElfDependenciesSteps = function* ( : null)); if ( dynstrTable === null && - (ambiguousStrings || neededOffsets.length > 0 || unique.has(DT_SONAME)) + (ambiguousStrings || neededEntries.length > 0 || unique.has(DT_SONAME)) ) issues.push({ code: "table_unavailable", @@ -897,13 +928,20 @@ export const readElfDependenciesSteps = function* ( }); const dynstr = new DynamicStrings( dynstrTable === null - ? Buffer.alloc(0) - : reader.range(dynstrTable.offset, dynstrTable.size, "DT_STRTAB"), + ? null + : { + bytes: reader.range( + dynstrTable.offset, + dynstrTable.size, + "DT_STRTAB", + ), + offset: dynstrTable.offset, + }, bytes.length, ); - const needed: ElfDependencyNeeded[] = neededOffsets.map( - (name_offset, index) => { - const observed = dynstr.read(name_offset); + const needed: ElfDependencyNeeded[] = neededEntries.map( + ({ nameOffset, sourceOffset }, index) => { + const observed = dynstr.read(nameOffset); const name = observed.name === null || observed.name.length === 0 ? null @@ -911,14 +949,10 @@ export const readElfDependenciesSteps = function* ( if (name === null) issues.push({ code: "name_unreadable", - location: hex((dynstrTable?.offset ?? 0) + name_offset), - message: observed.outside - ? `DT_NEEDED string offset ${String(name_offset)} is outside the dynamic string table` - : observed.truncated || observed.name === null - ? `DT_NEEDED string at offset ${String(name_offset)} ${unreadString(observed)}` - : `DT_NEEDED string at offset ${String(name_offset)} is empty`, + location: hex(observed.location ?? sourceOffset), + message: unreadDynamicString("DT_NEEDED", observed, nameOffset), }); - return { index, name, name_offset }; + return { index, name, name_offset: nameOffset }; }, ); const sonameOffset = unique.get(DT_SONAME); @@ -1114,11 +1148,7 @@ const namedString = ( issues.push({ code: "name_unreadable", location: label, - message: observed.outside - ? `${label} string offset is outside the dynamic string table` - : observed.truncated || observed.name === null - ? `${label} string ${unreadString(observed)} in the dynamic string table` - : `${label} string is empty`, + message: unreadDynamicString(label, observed), }); return null; } @@ -1146,9 +1176,7 @@ const parseInterpreter = ( issues.push({ code: "name_unreadable", location: hex(interp.offset), - message: `PT_INTERP path ${unreadString({ - limited: interp.bytes > ELF_STRING_SCAN_BYTES, - })}`, + message: `PT_INTERP path ${unreadString(interp.bytes > ELF_STRING_SCAN_BYTES)}`, }); return { status: "unreadable", path: null, location: interp }; } diff --git a/tests/acceptance/elfDependenciesCli.test.ts b/tests/acceptance/elfDependenciesCli.test.ts index 90e6b727df..9cb04cf3e8 100644 --- a/tests/acceptance/elfDependenciesCli.test.ts +++ b/tests/acceptance/elfDependenciesCli.test.ts @@ -116,3 +116,92 @@ cliTest( expect(JSON.stringify(result.json)).toContain("inspect_kernel_module"); }, ); + +for (const tableAvailable of [true, false]) { + cliTest( + `keeps DT_NEEDED diagnostics at known file bytes (string table available: ${tableAvailable})`, + async ({ cli }) => { + const root = await createTestTempDirectory( + "rea-elf-dependencies-name-location-", + ); + const path = join(root, "program"); + const badOffset = 0x10000; + const image = elfDependencyFixture({ + bits: 64, + little: true, + stripped: true, + wideNameOffset: badOffset, + needed: ["outside", "", "libc.so.6"], + }); + // This fixture writes PT_DYNAMIC as the last header and the needed + // records first. Read their file positions independently of the report. + const lastHeader = + Number(image.readBigUInt64LE(32)) + + (image.readUInt16LE(56) - 1) * image.readUInt16LE(54); + const dynamicOffset = Number(image.readBigUInt64LE(lastHeader + 8)); + let tableEntry = dynamicOffset; + while (image.readBigInt64LE(tableEntry) !== 5n) tableEntry += 16; + const tableOffset = Number(image.readBigUInt64LE(tableEntry + 8)); + if (!tableAvailable) + image.writeBigUInt64LE(BigInt(image.length + 16), tableEntry + 8); + await writeFile(path, image); + + const result = await cli.run({ + arguments: ["inspect-elf-dependencies", path, "--json"], + }); + expect(result.exitCode, JSON.stringify(result.json)).toBe(0); + const report = dependenciesContract.outputSchema.parse( + result.json, + ).normalized_result; + if (!("needed" in report)) + throw new Error("Expected an inline ELF dependency inventory"); + expect(report.coverage.status).toBe("partial"); + expect(report.needed).toMatchObject([ + { name: null, name_offset: badOffset }, + { name: null, name_offset: 0 }, + { name: tableAvailable ? "libc.so.6" : null }, + ]); + const diagnostics = report.issues.filter( + ({ code, message }) => + code === "name_unreadable" && message.startsWith("DT_NEEDED "), + ); + expect(diagnostics[0]).toMatchObject({ + location: `0x${dynamicOffset.toString(16)}`, + message: tableAvailable + ? "DT_NEEDED string offset 65536 is outside the dynamic string table" + : "DT_NEEDED string offset 65536 could not be read because the dynamic string table is unavailable", + }); + expect(diagnostics[1]?.location).toBe( + `0x${(tableAvailable ? tableOffset : dynamicOffset + 16).toString(16)}`, + ); + if (tableAvailable) { + expect(report.issues).toContainEqual({ + code: "name_unreadable", + location: "DT_SONAME", + message: + "DT_SONAME string offset is outside the dynamic string table", + }); + expect(report.dynamic.runpath?.raw).toBe("$ORIGIN/../lib"); + } else { + for (const location of [ + "DT_SONAME", + "DT_RUNPATH", + "vn_file", + "vna_name", + "vda_name", + "dynsym[1]", + ]) { + expect(report.issues, location).toContainEqual( + expect.objectContaining({ + code: "name_unreadable", + location, + message: expect.stringContaining( + "dynamic string table is unavailable", + ), + }), + ); + } + } + }, + ); +}