fix(uefi): share inspection and extraction scan limits (#12538)

* fix(uefi): share inspection and extraction scan limits

* test(uefi): prove extraction honors the FFS file limit
This commit is contained in:
morluto authored and GitHub committed 2026-11-19 22:05:16 +00:00
1 parent 0efd54e1c1
commit 9d0502bc51
5 files changed
+143 -45

No files matched your search

+4 -1
View File
@@ -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
@@ -1,6 +1,6 @@
{
"schemas": {
"input compact": "0b5c3f51ba380be5",
"input compact": "d78773a7ca2051f5",
"output compact": "4bda7c3651bfc579"
},
"patterns": {
+28 -32
View File
@@ -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()
+5 -11
View File
@@ -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,
+105
View File
@@ -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<Buffer>(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) }]);
}
},
);