diff --git a/docs/guides/firmware/firmware-analysis.md b/docs/guides/firmware/firmware-analysis.md index 83eb55adf9..e170329c09 100644 --- a/docs/guides/firmware/firmware-analysis.md +++ b/docs/guides/firmware/firmware-analysis.md @@ -60,7 +60,10 @@ Use `inspect_uefi_firmware` and `inspect_uefi_nvram` from MCP with ``` Extraction also accepts `ffs-file`, `section`, and `whole-image` targets. -Volume, file, and section targets include mapped descendants. Unparsed ranges +Volume, file, and section targets include mapped descendants. If inspection +raised `max_volumes`, `max_files`, or `max_depth`, use the same values for +extraction. The equivalent CLI options are `--max-volumes`, `--max-files`, and +`--max-depth`. Unparsed ranges within the selection appear in `extraction_gaps` and make extraction partial. The gap names the owning volume, file, or section and its source stream. Bytes outside the file and volume headers that occupy an FFS alignment span diff --git a/scripts/verify/advertised-schemas/tools/extract_uefi_firmware.json b/scripts/verify/advertised-schemas/tools/extract_uefi_firmware.json index 9da10e3d43..cf7193add9 100644 --- a/scripts/verify/advertised-schemas/tools/extract_uefi_firmware.json +++ b/scripts/verify/advertised-schemas/tools/extract_uefi_firmware.json @@ -1,6 +1,6 @@ { "schemas": { - "input compact": "0b5c3f51ba380be5", + "input compact": "d78773a7ca2051f5", "output compact": "4bda7c3651bfc579" }, "patterns": { diff --git a/src/domain/uefi/uefiFirmwareAnalysis.ts b/src/domain/uefi/uefiFirmwareAnalysis.ts index f72a16c4eb..25f996ea63 100644 --- a/src/domain/uefi/uefiFirmwareAnalysis.ts +++ b/src/domain/uefi/uefiFirmwareAnalysis.ts @@ -168,33 +168,37 @@ export const uefiFfsFileRecordSchema = z.strictObject({ sections: z.array(uefiSectionRecordSchema), }); +const firmwareScanLimits = { + max_depth: z + .number() + .int() + .min(1) + .max(UEFI_FIRMWARE_LIMITS.maxDepth) + .default(UEFI_FIRMWARE_LIMITS.defaultMaxDepth) + .describe( + "Nesting depth for sections and volumes inside compressed payloads", + ), + max_volumes: z + .number() + .int() + .min(1) + .max(UEFI_FIRMWARE_LIMITS.maxVolumes) + .default(UEFI_FIRMWARE_LIMITS.defaultMaxVolumes) + .describe("Maximum firmware volumes mapped before partial coverage"), + max_files: z + .number() + .int() + .min(1) + .max(UEFI_FIRMWARE_LIMITS.maxFiles) + .default(UEFI_FIRMWARE_LIMITS.defaultMaxFiles) + .describe("Maximum FFS files mapped before partial coverage"), +} as const; + /** Explicit UEFI firmware inspection and extraction intent, engine-independent. */ export const uefiInputSchemas = { inspect_uefi_firmware: z.strictObject({ ...target, - max_depth: z - .number() - .int() - .min(1) - .max(UEFI_FIRMWARE_LIMITS.maxDepth) - .default(UEFI_FIRMWARE_LIMITS.defaultMaxDepth) - .describe( - "Nesting depth for sections and volumes inside compressed payloads", - ), - max_volumes: z - .number() - .int() - .min(1) - .max(UEFI_FIRMWARE_LIMITS.maxVolumes) - .default(UEFI_FIRMWARE_LIMITS.defaultMaxVolumes) - .describe("Maximum firmware volumes mapped before partial coverage"), - max_files: z - .number() - .int() - .min(1) - .max(UEFI_FIRMWARE_LIMITS.maxFiles) - .default(UEFI_FIRMWARE_LIMITS.defaultMaxFiles) - .describe("Maximum FFS files mapped before partial coverage"), + ...firmwareScanLimits, }), extract_uefi_firmware: z.strictObject({ ...target, @@ -223,15 +227,7 @@ export const uefiInputSchemas = { }), ]) .default({ kind: "whole-image" }), - max_depth: z - .number() - .int() - .min(1) - .max(UEFI_FIRMWARE_LIMITS.maxDepth) - .default(UEFI_FIRMWARE_LIMITS.defaultMaxDepth) - .describe( - "Nesting depth for sections and volumes inside compressed payloads", - ), + ...firmwareScanLimits, max_output_bytes: z .number() .int() diff --git a/src/uefi/UefiAnalysisProvider.ts b/src/uefi/UefiAnalysisProvider.ts index 4a067c67c6..f60c76c771 100644 --- a/src/uefi/UefiAnalysisProvider.ts +++ b/src/uefi/UefiAnalysisProvider.ts @@ -341,17 +341,11 @@ export class UefiAnalysisProvider implements UefiAnalysisPort { } const scan = await scanUefiImage( snapshot.bytes, - request.operation === "inspect_uefi_firmware" - ? { - maxDepth: request.input.max_depth, - maxVolumes: request.input.max_volumes, - maxFiles: request.input.max_files, - } - : { - maxDepth: request.input.max_depth, - maxVolumes: UEFI_FIRMWARE_LIMITS.defaultMaxVolumes, - maxFiles: UEFI_FIRMWARE_LIMITS.defaultMaxFiles, - }, + { + maxDepth: request.input.max_depth, + maxVolumes: request.input.max_volumes, + maxFiles: request.input.max_files, + }, ({ payload, format, maxOutputBytes }) => this.#decodeStream( request.operation, diff --git a/tests/acceptance/uefiFirmware.test.ts b/tests/acceptance/uefiFirmware.test.ts index 62681c7223..5ae4cc5077 100644 --- a/tests/acceptance/uefiFirmware.test.ts +++ b/tests/acceptance/uefiFirmware.test.ts @@ -22,6 +22,7 @@ import { import { connectLocalToolsMcp } from "../fixtures/localToolsMcp.js"; import { parseMcpToolError } from "../fixtures/mcpToolError.js"; import { createTestTempDirectory } from "../fixtures/temporaryDirectory.js"; +import { cliTest } from "../support/cli/cliFixture.js"; const execute = promisify(execFile); const cli = fileURLToPath(new URL("../../scripts/rea.mjs", import.meta.url)); @@ -482,3 +483,107 @@ it("publishes distinct AMI NVAR link, attributes, GUID index and data digest", a }, ]); }); + +cliTest( + "shares volume and file scan limits across MCP and CLI extraction", + async ({ cli: command }) => { + const root = await createTestTempDirectory("rea-uefi-scan-limit-"); + const path = join(root, "many-volumes.fd"); + const empty = buildFv({ files: [], blockSize: 128 }).buffer; + const payload = Buffer.from("last firmware file"); + const last = buildFv({ + blockSize: 128, + files: [ + buildFfsFile({ + guid: DRIVER_GUID, + typeCode: 1, + payload: Buffer.from("first firmware file"), + }), + buildFfsFile({ + guid: "12345678-1234-4321-aaaa-bbbbbbbbbbbb", + typeCode: 1, + payload, + }), + ], + }).buffer; + await writeFile( + path, + Buffer.concat([...Array(512).fill(empty), last]), + ); + + const { call } = await connectLocalToolsMcp(); + const observed = await call("inspect_uefi_firmware", { + path, + max_volumes: 513, + max_files: 2, + }); + expect(observed.isError, JSON.stringify(observed.content)).not.toBe(true); + const inspection = uefiResultSchemas.inspect_uefi_firmware.parse( + parseEvidence(observed.structuredContent).normalized_result, + ); + const volume = inspection.firmware_volumes.at(-1); + expect(volume?.offset).toBe(empty.length * 512); + const offset = volume?.ffs_files[1]?.offset; + if (offset === undefined) + throw new Error("Inspection omitted the second FFS file"); + const extractMcp = (maxFiles: number) => + call("extract_uefi_firmware", { + path, + output_directory: join(root, `mcp-out-${maxFiles}`), + max_volumes: 513, + max_files: maxFiles, + target: { kind: "ffs-file", offset, source_stream: null }, + }); + const extractCli = (maxFiles: number) => + command.run({ + arguments: [ + "extract-uefi-firmware", + path, + join(root, `cli-out-${maxFiles}`), + "--file-offset", + String(offset), + "--source-stream", + "flash", + "--max-volumes", + "513", + "--max-files", + String(maxFiles), + "--json", + ], + }); + const refused = { + code: "invalid_request", + details: { + issues: [ + { + path: ["target"], + reason: "invalid_value", + message: `No mapped ffs-file at 0x${offset.toString(16)} in the selected stream.`, + }, + ], + }, + }; + expect(parseMcpToolError(await extractMcp(1)).error).toMatchObject(refused); + const cliRefusal = await extractCli(1); + expect(cliRefusal.exitCode).not.toBe(0); + expect(cliRefusal.json).toMatchObject(refused); + + const extraction = await extractMcp(2); + expect(extraction.isError, JSON.stringify(extraction.content)).not.toBe( + true, + ); + const cliExtraction = await extractCli(2); + expect(cliExtraction.exitCode, cliExtraction.stderr).toBe(0); + for (const evidence of [extraction.structuredContent, cliExtraction.json]) { + const result = uefiResultSchemas.extract_uefi_firmware.parse( + parseEvidence(evidence).normalized_result, + ); + expect(result.selection).toMatchObject({ + offset, + target_kind: "ffs-file", + }); + expect(result.coverage).toBe("complete"); + expect(result.files).toMatchObject([{ sha256: sha256(payload) }]); + } + }, +);