From 459553b901ec4ef27db58e1c933f033d5e6e02a3 Mon Sep 17 00:00:00 2001 From: morluto <76467478+morluto@users.noreply.github.com> Date: Mon, 16 Nov 2026 07:53:42 +0800 Subject: [PATCH] fix(evidence)!: require ESP flash_dump and PE unsigned attribute OIDs (#11595) * fix(evidence)!: require ESP flash_dump and PE unsigned attribute OIDs Both fields were optional only for Evidence recorded before REA reported them (6.8.0 and earlier). Every producer writes them: the ESP image reader and facts builder write `flash_dump` (null unless the file is a flash dump read from a later address), and the PE certificate parser writes `unsigned_attribute_oids` (null when the signer has none). They are now required and nullable, and the inspection hint no longer branches on an absent `flash_dump`. The ESP acceptance test that read pre-6.9 inventory Evidence now checks that such Evidence is refused. A call-path comment called Evidence without relationship coverage "legacy"; providers that report no coverage still produce it, so the comment now says so. BREAKING CHANGE: inline inventory Evidence for an ESP image root without `format_metadata.flash_dump`, and PE certificate Evidence whose signers lack `unsigned_attribute_oids`, are refused as invalid input. Recreate the observation with the current REA. Refs #10510 * test(certificates): refuse a signer without unsigned_attribute_oids; update the guide --- docs/pe-certificates.md | 6 +-- src/domain/artifactFormatMetadata.ts | 6 +-- src/domain/artifactInspection.ts | 3 +- src/domain/callPath.ts | 5 +- src/domain/native/peCertificates.ts | 5 +- src/native/pe/PeCertificateParser.test.ts | 21 ++++++++ .../artifactComparisonEspImage.test.ts | 54 +++++++------------ 7 files changed, 51 insertions(+), 49 deletions(-) diff --git a/docs/pe-certificates.md b/docs/pe-certificates.md index c0c61c56a9..a13e0286d7 100644 --- a/docs/pe-certificates.md +++ b/docs/pe-certificates.md @@ -53,9 +53,9 @@ Encoded order is kept, and values are copied as decoded, without RFC 4514 escaping or RDN reversal, so a name of only single-valued RDNs still places `, ` between attributes. -Each signer reports `unsigned_attribute_oids`: null means the field was absent, -and an array lists the types when present. Older retained Evidence may omit the -field. Unsigned attribute contents, including nested signatures and timestamp +Each signer reports `unsigned_attribute_oids`: null means the signer has no +unsigned attributes, and an array lists their types. Evidence that omits the +field (written before REA 6.9.0) is refused; recreate the observation. Unsigned attribute contents, including nested signatures and timestamp tokens, are not decoded; their presence makes coverage partial and adds a limitation. Certificate and signer counts refer to the outer SignedData. diff --git a/src/domain/artifactFormatMetadata.ts b/src/domain/artifactFormatMetadata.ts index f23fce1bd3..5b5c91dd19 100644 --- a/src/domain/artifactFormatMetadata.ts +++ b/src/domain/artifactFormatMetadata.ts @@ -547,13 +547,11 @@ export const espImageMetadataSchema = z.strictObject({ * `flash_offset`, and a partition table sits at `table_file_offset`, where * that origin puts the default `0x8000`. Reopen the file as * `esp-flash-image` with that `flash_offset`. Null otherwise, and in the - * nested facts of a flash layout. Absent from Evidence recorded before REA - * reported it; its graph digest covers the record without the field. + * nested facts of a flash layout. */ flash_dump: z .strictObject({ flash_offset: uint32, table_file_offset: offset }) - .nullable() - .exactOptional(), + .nullable(), }); export type EspImageMetadata = z.infer; diff --git a/src/domain/artifactInspection.ts b/src/domain/artifactInspection.ts index dc3ca9a661..a51c0b70ac 100644 --- a/src/domain/artifactInspection.ts +++ b/src/domain/artifactInspection.ts @@ -382,9 +382,8 @@ const espFlashDumpProbes = ( ({ logical_path }) => logical_path === ".", )?.format_metadata; if (root?.kind !== "esp-image") return []; - // Evidence recorded before REA reported the origin has no hint to offer. const dump = root.flash_dump; - if (dump === null || dump === undefined) return []; + if (dump === null) return []; const offset = offsetText(dump.flash_offset); return [ { diff --git a/src/domain/callPath.ts b/src/domain/callPath.ts index 38d097b6f4..c613afc77e 100644 --- a/src/domain/callPath.ts +++ b/src/domain/callPath.ts @@ -314,8 +314,9 @@ const inspectSearch = ({ incompleteExpandedCoverage = true; } // Explicit, Evidence-bound relationship coverage owns completeness; - // generic provider/dossier limitations remain contextual. Legacy Evidence - // without that metadata retains its conservative limitation-based rule. + // generic provider/dossier limitations remain contextual. Evidence from + // a provider that reports no relationship coverage keeps the + // conservative limitation-based rule. // The search only expands callee edges, so coverage that is unknown // solely because callers are unobservable does not make the searched // callee closure incomplete; the caller caveat stays in limitations. diff --git a/src/domain/native/peCertificates.ts b/src/domain/native/peCertificates.ts index 50cf558bf6..8e43b2b82a 100644 --- a/src/domain/native/peCertificates.ts +++ b/src/domain/native/peCertificates.ts @@ -100,9 +100,8 @@ const signerInfoSchema = z.strictObject({ .regex(/^[0-9a-f]*$/) .nullable(), authenticated_attributes: z.boolean(), - // Optional for Evidence recorded before unsigned attributes were observed. - // Null means the field was absent; an array means it was present. - unsigned_attribute_oids: z.array(z.string()).nullable().optional(), + // Null means the signer has no unsigned attributes; an array lists them. + unsigned_attribute_oids: z.array(z.string()).nullable(), }); const pkcs7Schema = z.strictObject({ diff --git a/src/native/pe/PeCertificateParser.test.ts b/src/native/pe/PeCertificateParser.test.ts index a75b7bf867..2b7b03aed1 100644 --- a/src/native/pe/PeCertificateParser.test.ts +++ b/src/native/pe/PeCertificateParser.test.ts @@ -106,6 +106,27 @@ it("reports unsigned attribute OIDs and incomplete nested coverage", () => { } }); +// The parser always reports the field (null when absent), so a report that +// omits it is refused at that field rather than read as unknown. +it("refuses a signer that omits unsigned_attribute_oids", () => { + const report = parse(peCertificateFixture(false)); + const [entry] = report.entries; + const [signer] = entry?.pkcs7?.signers ?? []; + if (entry?.pkcs7 === undefined || entry.pkcs7 === null || !signer) + throw new Error("Fixture has no PKCS#7 signer"); + const { unsigned_attribute_oids: _omitted, ...withoutField } = signer; + const refused = peCertificatesSchema.safeParse({ + ...report, + entries: [{ ...entry, pkcs7: { ...entry.pkcs7, signers: [withoutField] } }], + }); + expect(refused.success).toBe(false); + expect(refused.error?.issues).toContainEqual( + expect.objectContaining({ + path: ["entries", 0, "pkcs7", "signers", 0, "unsigned_attribute_oids"], + }), + ); +}); + it.each([false, true])( "rejects a misaligned certificate table (PE32+ = %s)", (plus) => { diff --git a/tests/acceptance/artifactComparisonEspImage.test.ts b/tests/acceptance/artifactComparisonEspImage.test.ts index 2c297871b8..826cee0a67 100644 --- a/tests/acceptance/artifactComparisonEspImage.test.ts +++ b/tests/acceptance/artifactComparisonEspImage.test.ts @@ -71,20 +71,27 @@ it("reports an ESP segment whose load address alone changed", async () => { expect(same.changes).toEqual([]); }); -/** The inventory as REA recorded it before ESP image roots had `flash_dump`. */ +/** An ESP image inventory without `flash_dump`, as releases before 6.9 wrote it. */ const withoutFlashDump = (source: Evidence): Evidence => { return historicalInventoryEvidence( source, (occurrence) => { if (occurrence.format_metadata?.kind !== "esp-image") return occurrence; const { flash_dump: _dump, ...historical } = occurrence.format_metadata; - return { ...occurrence, format_metadata: historical }; + // The current type requires the field this record omits. + return { + ...occurrence, + format_metadata: historical as typeof occurrence.format_metadata, + }; }, "observed", ); }; -it("reads and compares ESP image Evidence recorded before flash_dump", async () => { +// Every ESP image root records `flash_dump` (null when the file is not a +// flash dump read from a later address), so an inventory without it is +// refused rather than read as one with unknown origin. +it("refuses ESP image inventory Evidence without flash_dump", async () => { const root = await createTestTempDirectory("rea-esp-historical-"); const path = join(root, "app.bin"); await writeFile(path, espImage({ segments: ESP32C3_APP_SEGMENTS })); @@ -99,40 +106,17 @@ it("reads and compares ESP image Evidence recorded before flash_dump", async () .substeps.find(({ operation }) => operation === "inventory_artifact") ?.evidence, ); - const historical = withoutFlashDump(current); - const recorded = JSON.stringify(historical); - const rootMetadata = (evidence: Evidence) => - artifactInventoryResultSchema - .parse(evidence.normalized_result) - .occurrences.find(({ logical_path }) => logical_path === ".") - ?.format_metadata; - expect(rootMetadata(current)).toMatchObject({ - kind: "esp-image", - flash_dump: null, - }); - expect(rootMetadata(historical)).not.toHaveProperty("flash_dump"); + const rootMetadata = artifactInventoryResultSchema + .parse(current.normalized_result) + .occurrences.find( + ({ logical_path }) => logical_path === ".", + )?.format_metadata; + expect(rootMetadata).toMatchObject({ kind: "esp-image", flash_dump: null }); const compared = await call("compare_artifacts", { - left: historical, + left: withoutFlashDump(current), right: current, }); - expect(compared.isError, JSON.stringify(compared)).not.toBe(true); - expect( - artifactComparisonResultSchema.parse( - parseEvidence(compared.structuredContent).normalized_result, - ), - ).toMatchObject({ status: "unchanged", changes: [] }); - - const viewed = await call("inspect_analysis_view", { - source: { kind: "inline", evidence: historical }, - view: { kind: "summary" }, - }); - expect(viewed.isError, JSON.stringify(viewed)).not.toBe(true); - const summary = artifactInventorySummaryViewResultSchema.parse( - parseEvidence(viewed.structuredContent).normalized_result, - ).summary; - expect(summary.root_format_metadata).toMatchObject({ kind: "esp-image" }); - expect(summary.root_format_metadata).not.toHaveProperty("flash_dump"); - // Reading the record leaves the graph its digest covers unchanged. - expect(JSON.stringify(historical)).toBe(recorded); + expect(compared.isError).toBe(true); + expect(JSON.stringify(compared.content)).toContain("flash_dump"); });