mirror of
https://github.com/morluto/rea.git
synced 2026-11-22 06:25:44 +00:00
* feat(uefi): add pure-TS UEFI firmware volume/FFS parser with inspect/extract tools
Add a dependency-free rea-uefi provider that maps AMI/Aptio flash images:
- inspect_uefi_firmware: aligned _FVH discovery, volume-relative FFS walking,
guided section/compression classification, conservative PSP-directory probing,
embedded-volume rescan and leftover-region classification; incremental SHA-256
and explicit integrity notes.
- extract_uefi_firmware: whole-image/volume/FFS-file/section extraction with
LZMA-custom/LZMAF86 and AMD-zlib decoding, SafeOutputTree staging, derivations
and extraction_gaps.
- UefiArtifactReader + 'uefi' format wiring across inventory/domain/contracts
so parsed volumes and extracted PE32/TE files hand off to deep-provider
analysis (open_binary -> Ghidra).
* feat(uefi): add inspect_uefi_nvram for AMI NVRAM variable stores
Add a pure-TypeScript tool that maps the vendor AMI NVRAM variable stores
(factory-default "StdDefaults" and peers) inside a flash image:
- scan the raw image for NVAR entry chains ("NVAR" + u16 total size +
u32 attribute 0x8[23]FFFFFF + state + NUL-terminated name + data),
- recurse into a container entry whose data is itself an NVAR chain, so the
StdDefaults setup variables surface as depth/parent_offset rows,
- report attributes, state, data range, SHA-256 and trailing padding per entry.
Verified against B550 AORUS Elite V2 FId: one StdDefaults store at 0x37090 with
the 11 expected nested variables (Setup, PlatformLang, AMITSESetup, XhciDID,
GcSensorVarName, PCI_COMMON, SioSetupData, UsbSupport, NetworkStackVar,
SecureBootSetup, Setup). Exposed as MCP tool and inspect-uefi-nvram CLI command.
* fix(uefi): address review on checksums, compression, guided sections, NVRAM bounds
- FFS file checksum: verify the two's-complement invariant (payload sum +
stored byte == 0 mod 256) instead of comparing sums, and encode the correct
complement in the fixture builder.
- Compression sections (type 0x01): use the 9-byte header and classify EFI
standard compression instead of 'none', so extraction reports a gap rather
than publishing compressed bytes as a raw section.
- GUID-defined sections: derive GUID/data-offset/attributes from the parsed
common header size (compact or extended) and reject out-of-range payload
offsets.
- AMI NVRAM: bound recursive chains to the enclosing container's data end and
report partial coverage when a valid nested chain is cut by max_depth.
* fix(uefi): bound decode memory, serialize operations, enforce deadline, mark truncation
- LZMA worker: enforce max_output_bytes while decoding through a bounded output
sink, so an oversized stream is rejected during expansion instead of after a
full decompression plus a second Buffer copy.
- Provider: serialize admitted operations (the promised single decode-worker
lane must not become one worker per overlapping call) and apply one
whole-request deadline that covers every decode stage, not a fresh per-stream
timer. close() drains the queue and the resource scope.
- Scan: track truncated sections of known type and report coverage partial
instead of complete when a section declares more bytes than are present.
* fix(uefi): cancellable queue, timeout surfacing, availability and reader omissions
- Queue: check the caller signal before enqueue and when a job reaches the head,
and race the queued promise against abort so a cancelled wait returns
immediately instead of blocking behind the active request.
- Deadline: track the internal deadline and return AnalysisTimeoutError instead
of the AnalysisCancelledError that runOwnedCommand reports for any external
abort, preserving the real failure reason for CLI/MCP callers.
- CapabilityInventory: treat inspect_uefi_nvram like the other bundled rea-uefi
tools so discovery does not demand Unblob for it.
- UefiArtifactReader: report image truncation through onOmission so inventory
coverage reflects the unread suffix even when no volume was found.
* fix(uefi): limit early cancellation to unstarted jobs and preserve timeout cleanup
- #raceWithAbort only returns early for jobs that have not started; once a
request is running, await it so worker cleanup and completed output are
preserved instead of being discarded by a bare cancellation.
- Reclassify a deadline-induced cancellation as AnalysisTimeoutError while
keeping its cause and cleanup observations, and never override a different
primary failure.
* docs(licenses): record UEFI decoder dependency notices
* fix(uefi): preserve stream provenance and bound firmware analysis
* feat(uefi): decode LZMAF86 guided sections
* fix(uefi): validate publication before commit and order decoder cleanup
* fix(uefi): preserve unsupported volumes and extraction gaps
---------
Co-authored-by: morluto <76467478+morluto@users.noreply.github.com>
157 lines
4.9 KiB
TypeScript
157 lines
4.9 KiB
TypeScript
import type { Logger } from "pino";
|
|
import { z } from "zod";
|
|
|
|
import { UefiAnalysisService } from "../application/uefi/UefiAnalysisService.js";
|
|
import { createUefiAnalysisProvider } from "../composition/uefi.js";
|
|
import { UEFI_TOOL_CONTRACTS } from "../contracts/uefi/uefiToolContracts.js";
|
|
import { AnalysisInputError } from "../domain/analysisErrorCore.js";
|
|
import { projectAnalysisError } from "../domain/analysisErrorProjection.js";
|
|
import type { UefiOperation } from "../domain/uefi/uefiFirmwareAnalysis.js";
|
|
import { UEFI_PROVIDER_IDENTITY } from "../uefi/UefiProviderIdentity.js";
|
|
import { contractNamed } from "./contractCliDescription.js";
|
|
import {
|
|
inspectWithService,
|
|
registerContractCommand,
|
|
} from "./contractCommand.js";
|
|
import { cliDecimalField } from "./options.js";
|
|
import type { CliInstance } from "./types.js";
|
|
|
|
const FLASH_PATH = { description: "Local UEFI firmware image" };
|
|
const OFFSET_OPTIONS = {
|
|
volumeOffset: "volume",
|
|
fileOffset: "ffs-file",
|
|
sectionOffset: "section",
|
|
} as const;
|
|
const targetOffset = cliDecimalField(z.number().int().nonnegative().optional());
|
|
|
|
/** One-shot UEFI firmware CLI commands backed by the same workflows as MCP. */
|
|
export const registerUefiCommands = (
|
|
cli: CliInstance,
|
|
logger: Logger,
|
|
): void => {
|
|
const service = new UefiAnalysisService(createUefiAnalysisProvider());
|
|
const run = (operation: UefiOperation) =>
|
|
inspectWithService(
|
|
() => ({
|
|
inspect: (input, options) => service.execute(operation, input, options),
|
|
close: () => service.close(),
|
|
}),
|
|
UEFI_PROVIDER_IDENTITY.id,
|
|
);
|
|
|
|
registerContractCommand(
|
|
cli,
|
|
logger,
|
|
contractNamed(UEFI_TOOL_CONTRACTS, "inspect_uefi_firmware"),
|
|
{
|
|
description:
|
|
"Map UEFI firmware volumes, FFS files and sections of a flash image",
|
|
positionals: ["path"],
|
|
callerPaths: ["path"],
|
|
fields: { path: FLASH_PATH },
|
|
},
|
|
run("inspect_uefi_firmware"),
|
|
);
|
|
registerContractCommand(
|
|
cli,
|
|
logger,
|
|
contractNamed(UEFI_TOOL_CONTRACTS, "inspect_uefi_nvram"),
|
|
{
|
|
description:
|
|
"Map AMI NVRAM variable stores (for example StdDefaults) of a flash image",
|
|
positionals: ["path"],
|
|
callerPaths: ["path"],
|
|
fields: { path: FLASH_PATH },
|
|
},
|
|
run("inspect_uefi_nvram"),
|
|
);
|
|
|
|
const extraction = contractNamed(
|
|
UEFI_TOOL_CONTRACTS,
|
|
"extract_uefi_firmware",
|
|
);
|
|
const extract = run(extraction.name);
|
|
registerContractCommand(
|
|
cli,
|
|
logger,
|
|
extraction,
|
|
{
|
|
description:
|
|
"Extract selected UEFI firmware bytes with provenance and decode gaps",
|
|
positionals: ["path", "output_directory"],
|
|
callerPaths: ["path", "output_directory"],
|
|
fields: {
|
|
path: FLASH_PATH,
|
|
output_directory: {
|
|
description: "Absent output directory; parent must exist",
|
|
},
|
|
},
|
|
handlerFields: ["target"],
|
|
cliOptions: {
|
|
volumeOffset: targetOffset.describe(
|
|
"Extract one firmware volume at this byte offset",
|
|
),
|
|
fileOffset: targetOffset.describe(
|
|
"Extract one FFS file at this byte offset",
|
|
),
|
|
sectionOffset: targetOffset.describe(
|
|
"Extract one section at this byte offset",
|
|
),
|
|
sourceStream: z
|
|
.string()
|
|
.optional()
|
|
.describe(
|
|
"Carrier logical path for a decoded offset, or flash for the original image. Requires one target offset.",
|
|
),
|
|
},
|
|
},
|
|
async (input, context) => {
|
|
const options = context.cliOptions;
|
|
const selectors = (
|
|
Object.keys(OFFSET_OPTIONS) as (keyof typeof OFFSET_OPTIONS)[]
|
|
).flatMap((key) => {
|
|
const offset = options[key];
|
|
return offset === undefined
|
|
? []
|
|
: [{ kind: OFFSET_OPTIONS[key], offset }];
|
|
});
|
|
const selected = selectors[0];
|
|
const source = options.sourceStream;
|
|
const refuse = (key: string, message: string) =>
|
|
projectAnalysisError(
|
|
new AnalysisInputError(extraction.name, undefined, [
|
|
{ path: [key], reason: "invalid_value", message },
|
|
]),
|
|
);
|
|
|
|
if (selectors.length > 1)
|
|
return refuse(
|
|
"volumeOffset",
|
|
"--volume-offset, --file-offset and --section-offset are mutually exclusive.",
|
|
);
|
|
if (source !== undefined && selected === undefined)
|
|
return refuse(
|
|
"sourceStream",
|
|
"--source-stream requires one target offset.",
|
|
);
|
|
|
|
return extract(
|
|
{
|
|
...input,
|
|
target:
|
|
selected === undefined
|
|
? { kind: "whole-image" }
|
|
: {
|
|
kind: selected.kind,
|
|
offset: selected.offset,
|
|
...(source === undefined
|
|
? {}
|
|
: { source_stream: source === "flash" ? null : source }),
|
|
},
|
|
},
|
|
context,
|
|
);
|
|
},
|
|
);
|
|
};
|