diff --git a/docs/devicetree.md b/docs/devicetree.md index a53ac09fb6..0485fef1b2 100644 --- a/docs/devicetree.md +++ b/docs/devicetree.md @@ -6,6 +6,13 @@ other versions return `unsupported_target`. Corrupt recognized blobs return `invalid_request`, and exhausted budgets return `resource_constraint` without partial success. +[DTSpec ยง5.4.1](https://devicetree-specification.readthedocs.io/en/stable/flattened-format.html#lexical-structure) +requires zero padding after structure node names and property values. For +example, [libfdt's node rename](https://github.com/dgibson/dtc/blob/c954f9dd835764ec69d3d9afb467c4541b47b66d/libfdt/fdt_rw.c#L253-L273) +can leave bytes from the old name after the new terminator. REA reports the +count and first file offset of nonzero padding while retaining the tree's +observations when all fields fit. + ```bash rea inspect-devicetree /artifacts/board.dtb --json rea inspect-devicetree /artifacts/board.dtb --detail summary --evidence_output /artifacts/board-evidence.json --json diff --git a/docs/fit-images.md b/docs/fit-images.md index a99210d906..4f6fff8f64 100644 --- a/docs/fit-images.md +++ b/docs/fit-images.md @@ -30,7 +30,9 @@ that contains `/images` is treated as a FIT. The container format is `fit`. Recognition is a probe. The complete devicetree parse decides, so a file whose prefix declares `/images` but whose structure is malformed fails as a -malformed FIT rather than falling back to plain classification. +malformed FIT rather than falling back to plain classification. FIT inventory +reports nonzero structure alignment padding using the shared +[devicetree rules](devicetree.md). ## Images and metadata diff --git a/src/artifacts/fit/FitStructure.ts b/src/artifacts/fit/FitStructure.ts index 73104a5f0b..713ac7c647 100644 --- a/src/artifacts/fit/FitStructure.ts +++ b/src/artifacts/fit/FitStructure.ts @@ -557,7 +557,7 @@ const fitConfigurations = ( return { default_configuration: defaultConfiguration, configurations }; }; -const parseFit = (fdt: Buffer, path: string): Devicetree => { +const parseFit = (fdt: Buffer, path: string) => { try { // The artifact field is only echoed back; the reader binds the carrier hash. return parseDevicetree( @@ -595,7 +595,7 @@ export const readFitStructure = ( path: string, fileSize: number, ): FitStructure => { - const tree = parseFit(fdt, path); + const { report: tree, structureLimitations } = parseFit(fdt, path); const byPath = new Map(tree.nodes.map((node) => [node.path, node])); const children = new Map(); for (const node of tree.nodes) { @@ -627,7 +627,7 @@ export const readFitStructure = ( `FIT images declare ${String(declared)} bytes, exceeding this file's ${String(budget)}-byte expansion budget`, { boundary: "memory" }, ); - const facts: FitFacts = { fdt, limitations: [] }; + const facts: FitFacts = { fdt, limitations: [...structureLimitations] }; return { images, limitations: facts.limitations, diff --git a/src/domain/firmware/devicetreeParser.test.ts b/src/domain/firmware/devicetreeParser.test.ts index 2a14e4bc04..d3a3450836 100644 --- a/src/domain/firmware/devicetreeParser.test.ts +++ b/src/domain/firmware/devicetreeParser.test.ts @@ -24,7 +24,7 @@ const parse = (b: Buffer, limits = {}) => sha256: createHash("sha256").update(b).digest("hex"), }, inspectDevicetreeInputSchema.parse({ path: "/board.dtb", ...limits }), - ); + ).report; describe("flattened devicetree", () => { it.each([16, 17])( "decodes v%s with derived facts and unresolved references", diff --git a/src/domain/firmware/devicetreeParser.ts b/src/domain/firmware/devicetreeParser.ts index 5cd79c2216..73d7981819 100644 --- a/src/domain/firmware/devicetreeParser.ts +++ b/src/domain/firmware/devicetreeParser.ts @@ -35,7 +35,7 @@ export const parseDevicetree = ( bytes: Buffer, artifact: Devicetree["artifact"], input: InspectDevicetreeInput, -): Devicetree => { +): { report: Devicetree; structureLimitations: readonly string[] } => { if (bytes.length > input.max_file_bytes) throw devicetreeLimitFailure("max_file_bytes", input.max_file_bytes); const { @@ -98,6 +98,16 @@ export const parseDevicetree = ( if (cursor > structEnd - n) malformed("Truncated FDT structure token or property"); }; + let nonzeroPaddingBytes = 0; + let firstNonzeroPadding: number | undefined; + const observePadding = (start: number, end: number) => { + // Callers admit the aligned extent before observing its padding. + for (let offset = start; offset < end; offset++) { + if (bytes[offset] === 0) continue; + nonzeroPaddingBytes += 1; + firstNonzeroPadding ??= offset; + } + }; while (cursor < structEnd) { need(4); const offset = cursor, @@ -109,8 +119,10 @@ export const parseDevicetree = ( if (nodes.length >= input.max_nodes) throw devicetreeLimitFailure("max_nodes", input.max_nodes); const name = text(cursor, structEnd); - cursor = align(name.next); - need(0); + const next = align(name.next); + need(next - cursor); + observePadding(name.next, next); + cursor = next; const parent = stack.at(-1); if ( name.value.includes("/") || @@ -144,9 +156,11 @@ export const parseDevicetree = ( const length = u32(cursor), nameoff = u32(cursor + 4); cursor += 8; - const next = align(cursor + length); + const end = cursor + length; + const next = align(end); // Every open node needs an END_NODE token, followed by FDT_END. need(next - cursor + (stack.length + 1) * 4); + observePadding(end, next); if (++properties > input.max_properties) throw devicetreeLimitFailure("max_properties", input.max_properties); if (nameoff >= header.size_dt_strings) @@ -232,7 +246,15 @@ export const parseDevicetree = ( return s?.length === 1 ? (s[0] ?? null) : null; }; const handles = new Map(); + // An editor can leave nonzero padding without changing the parsed fields. + const structureLimitations = + firstNonzeroPadding === undefined + ? [] + : [ + `FDT structure padding contains ${String(nonzeroPaddingBytes)} nonzero ${nonzeroPaddingBytes === 1 ? "byte" : "bytes"}. The first is at file offset ${String(firstNonzeroPadding)}.`, + ]; const limitations = [ + ...structureLimitations, "Raw property previews are limited to 256 bytes; offsets and lengths identify complete values in the hashed artifact.", "Phandle references cover only single-cell interrupt-parent, remote-endpoint and msi-parent; binding-specific arrays and overlays are not resolved.", ]; @@ -337,7 +359,7 @@ export const parseDevicetree = ( }); } } - return { + const report: Devicetree = { artifact, header, reservations, @@ -361,4 +383,5 @@ export const parseDevicetree = ( }, limitations, }; + return { report, structureLimitations }; }; diff --git a/src/firmware/devicetree/DevicetreeProvider.ts b/src/firmware/devicetree/DevicetreeProvider.ts index acbf17c2f8..ffd58a7a32 100644 --- a/src/firmware/devicetree/DevicetreeProvider.ts +++ b/src/firmware/devicetree/DevicetreeProvider.ts @@ -61,17 +61,16 @@ export class DevicetreeProvider implements DevicetreePort { undefined, this.#resources, ); - return ok( - parseDevicetree( - snapshot.bytes, - { - path: input.path, - sha256: snapshot.sha256, - bytes: snapshot.bytes.length, - }, - input, - ), + const { report } = parseDevicetree( + snapshot.bytes, + { + path: input.path, + sha256: snapshot.sha256, + bytes: snapshot.bytes.length, + }, + input, ); + return ok(report); }); } catch (cause) { return err(devicetreeFailure(cause, input, snapshot)); diff --git a/tests/acceptance/devicetreeCli.test.ts b/tests/acceptance/devicetreeCli.test.ts index a58fbccf87..0318022a30 100644 --- a/tests/acceptance/devicetreeCli.test.ts +++ b/tests/acceptance/devicetreeCli.test.ts @@ -2,6 +2,7 @@ import { readFile, writeFile } from "node:fs/promises"; import { join } from "node:path"; import { expect } from "vitest"; import { z } from "zod"; +import { fitFixture } from "../../src/artifacts/fit/FitImage.fixture.js"; import { toolContract } from "../../src/contracts/toolContracts.js"; import { createEvidence } from "../../src/domain/evidence.js"; import { @@ -13,6 +14,110 @@ import { createTestTempDirectory } from "../fixtures/temporaryDirectory.js"; import { connectLocalToolsMcp } from "../fixtures/localToolsMcp.js"; import { cliTest } from "../support/cli/cliFixture.js"; +const paddingDiagnostic = /FDT structure padding contains/iu; + +cliTest( + "retains DTB facts and reports both nonzero padding placements", + async ({ cli }) => { + const root = await createTestTempDirectory("rea-dtb-padding-"); + const path = join(root, "board.dtb"); + const zeroPadded = devicetreeFixture({ + name: "", + properties: { model: Buffer.from([0x78, 0]) }, + children: [{ name: "a" }], + }); + const nonzeroPadded = Buffer.from(zeroPadded); + const start = nonzeroPadded.readUInt32BE(8); + // Two-byte model value rounded up to four, then a child named "a". + const propertyPadding = start + 22; + nonzeroPadded[propertyPadding] = 1; + // libfdt's in-place rename from "abc" to "a" leaves the former 'c'. + nonzeroPadded[start + 30] = 0x63; + + const inspect = async (bytes: Buffer) => { + await writeFile(path, bytes); + const result = await cli.run({ + arguments: ["inspect-devicetree", path, "--json"], + }); + expect(result.exitCode, result.stderr).toBe(0); + return toolContract("inspect_devicetree").outputSchema.parse(result.json); + }; + const control = await inspect(zeroPadded); + expect(control.limitations).not.toEqual( + expect.arrayContaining([expect.stringMatching(paddingDiagnostic)]), + ); + const observed = await inspect(nonzeroPadded); + const diagnostic = `FDT structure padding contains 2 nonzero bytes. The first is at file offset ${String(propertyPadding)}.`; + expect(observed.limitations).toContain(diagnostic); + expect(observed.normalized_result).toMatchObject({ + summary: { model: "x" }, + nodes: expect.arrayContaining([expect.objectContaining({ path: "/a" })]), + coverage: { + status: "complete", + examined_nodes: 2, + examined_properties: 1, + }, + limitations: expect.arrayContaining([diagnostic]), + }); + + const { call } = await connectLocalToolsMcp(); + const reply = await call("inspect_devicetree", { path }); + expect(reply.isError).not.toBe(true); + const mcp = toolContract("inspect_devicetree").outputSchema.parse( + reply.structuredContent, + ); + expect(mcp.limitations).toContain(diagnostic); + expect(mcp.normalized_result).toEqual(observed.normalized_result); + expect((await readFile(path)).equals(nonzeroPadded)).toBe(true); + }, +); + +cliTest( + "reports FIT structure padding without losing image inventory", + async ({ cli }) => { + const root = await createTestTempDirectory("rea-fit-padding-"); + const path = join(root, "boot.itb"); + const bytes = fitFixture({ + images: [{ name: "kernel", data: Buffer.from([1, 2, 3, 4]) }], + }); + const inspect = () => + cli.run({ arguments: ["inspect-artifact", path, "--json"] }); + + await writeFile(path, bytes); + const control = await inspect(); + expect(control.exitCode, control.stderr).toBe(0); + expect(control.json).not.toMatchObject({ + limitations: expect.arrayContaining([ + expect.stringMatching(paddingDiagnostic), + ]), + }); + + const rootNamePadding = bytes.readUInt32BE(8) + 5; + bytes[rootNamePadding] = 1; + await writeFile(path, bytes); + const observed = await inspect(); + expect(observed.exitCode, observed.stderr).toBe(0); + expect(observed.json).toMatchObject({ + limitations: expect.arrayContaining([ + `FDT structure padding contains 1 nonzero byte. The first is at file offset ${String(rootNamePadding)}.`, + ]), + normalized_result: { + coverage: { status: "complete-within-substeps" }, + observations: expect.arrayContaining([ + expect.objectContaining({ + kind: "root-manifest", + value: expect.objectContaining({ + root_format: "fit", + occurrence_count: 2, + }), + }), + ]), + }, + }); + expect((await readFile(path)).equals(bytes)).toBe(true); + }, +); + cliTest( "rejects ambiguous Devicetree node paths in correctly hashed Evidence", async ({ cli }) => {