Files
reverse-engineering-anything/src/application/binary/TargetFormatVocabularies.test.ts
T
bartman081523andmorluto d380dc2409 feat(uefi): add pure-TypeScript UEFI firmware analysis tools (#12342)
* 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>
2026-11-19 21:19:35 +00:00

208 lines
6.3 KiB
TypeScript

import { describe, expect, expectTypeOf, it } from "vitest";
import {
analysisSnapshotSchema,
snapshotTarget,
} from "../../domain/analysisSnapshot.js";
import type { BinaryTarget } from "../../domain/binaryTargetTypes.js";
import { openBinaryInputSchema } from "../../contracts/sessionLifecycleInputs.js";
import { createEvidence, parseEvidence } from "../../domain/evidence.js";
import {
createImmutableEvidenceBundle,
parseEvidenceBundle,
} from "../../domain/evidenceBundle.js";
import type {
BINARY_TARGET_FORMAT_KINDS,
TargetFormat,
} from "../../domain/targetFormats.js";
import { binaryTargetSummary } from "./BinaryTargetSummary.js";
/**
* One admitted target per format. A format added to `BinaryTarget` fails
* compilation here until it has a fixture, and the cases below then require
* every vocabulary that persists or projects targets to accept it.
*/
type TargetFixtures = {
readonly [Format in TargetFormat]: BinaryTarget & {
readonly format: Format;
readonly kind: (typeof BINARY_TARGET_FORMAT_KINDS)[Format];
};
};
const identity = { path: "/fixture/target", sha256: "a".repeat(64) } as const;
const archive = { ...identity, kind: "archive" } as const;
const artifact = { ...identity, kind: "artifact" } as const;
const TARGETS: TargetFixtures = {
"mach-o": {
...identity,
kind: "executable",
format: "mach-o",
architecture: "arm64",
availableArchitectures: ["arm64"],
},
"mach-o-universal": {
...identity,
kind: "executable",
format: "mach-o-universal",
architecture: "arm64",
availableArchitectures: ["x86_64", "arm64"],
universalSlice: { offset: 0x4000, size: 0x4000 },
},
elf: {
...identity,
kind: "executable",
format: "elf",
architecture: "x86_64",
availableArchitectures: ["x86_64"],
},
pe: {
...identity,
kind: "executable",
format: "pe",
architecture: "x86_64",
availableArchitectures: ["x86_64"],
executableRole: "application",
managed: false,
},
"dos-mz": {
...identity,
kind: "executable",
format: "dos-mz",
architecture: "x86",
availableArchitectures: ["x86"],
},
"dos-com": {
...identity,
kind: "executable",
format: "dos-com",
architecture: "x86",
availableArchitectures: ["x86"],
},
// A raw-only family: detected formats must not admit it.
"raw-binary": {
...identity,
kind: "executable",
format: "raw-binary",
architecture: "m68k",
availableArchitectures: ["m68k"],
entryPoint: "0x1000",
entryPointSource: "0x1000",
},
"gamecube-dol": {
...identity,
kind: "executable",
format: "gamecube-dol",
architecture: "powerpc",
availableArchitectures: ["powerpc"],
byteOrder: "big",
bits: 32,
entryPoint: "0x80003100",
entryPointSource: "dol-header",
dol: {
sections: [],
bss: { address: 0, size: 0 },
bssOverlaps: [],
bssGaps: [],
entryPoint: 0x8000_3100,
},
},
"analysis-database": {
...identity,
kind: "database",
format: "analysis-database",
},
zip: { ...archive, format: "zip" },
ipa: { ...archive, format: "ipa" },
apk: { ...archive, format: "apk" },
msix: { ...archive, format: "msix" },
appx: { ...archive, format: "appx" },
hap: { ...archive, format: "hap" },
hsp: { ...archive, format: "hsp" },
"app-pack": { ...archive, format: "app-pack" },
asar: { ...archive, format: "asar" },
ines: { ...archive, format: "ines" },
"godot-pck": { ...archive, format: "godot-pck" },
unityfs: { ...archive, format: "unityfs" },
wxapkg: { ...archive, format: "wxapkg" },
uimage: { ...archive, format: "uimage" },
"android-boot-image": { ...archive, format: "android-boot-image" },
"android-ota-payload": { ...archive, format: "android-ota-payload" },
uf2: { ...archive, format: "uf2" },
dfuse: { ...archive, format: "dfuse" },
dmg: { ...archive, format: "dmg" },
pkg: { ...archive, format: "pkg" },
"intel-hex": { ...archive, format: "intel-hex" },
srec: { ...archive, format: "srec" },
"esp-image": { ...archive, format: "esp-image" },
"esp-flash-image": {
...archive,
format: "esp-flash-image",
espFlash: { selected: true, flashOffset: null, partitionTableOffset: null },
},
fit: { ...archive, format: "fit" },
"ntfs-mft": { ...archive, format: "ntfs-mft" },
plist: { ...artifact, format: "plist" },
javascript: { ...artifact, format: "javascript" },
"source-map": { ...artifact, format: "source-map" },
uefi: { ...artifact, format: "uefi" },
};
const provider = { id: "fixture", name: "Fixture", version: "1" } as const;
const roundTrip = (value: unknown): unknown =>
JSON.parse(JSON.stringify(value));
describe("target format vocabularies", () => {
it("defines a target type for every canonical format", () => {
expectTypeOf<BinaryTarget["format"]>().toEqualTypeOf<TargetFormat>();
});
it.each(Object.values(TARGETS))(
"persists and projects $format targets",
(target) => {
const evidence = createEvidence(target, provider, {
operation: "fixture",
parameters: {},
result: { observed: true },
});
expect(parseEvidence(roundTrip(evidence)).subject).toMatchObject({
identity: {
format: target.format,
architecture: target.architecture ?? null,
},
});
const bundle = createImmutableEvidenceBundle([evidence]);
expect(parseEvidenceBundle(roundTrip(bundle)).artifacts).toEqual([
{
digest: { sha256: target.sha256 },
format: target.format,
architecture: target.architecture ?? null,
},
]);
expect(
analysisSnapshotSchema.shape.target.parse(
roundTrip(snapshotTarget(target)),
),
).toMatchObject({
kind: target.kind,
identity: { format: target.format },
});
expect(binaryTargetSummary(target)).toMatchObject({
format: target.format,
kind: target.kind,
});
},
);
it.each(openBinaryInputSchema.shape.format.unwrap().options)(
"admits the caller-selected %s hint only as its own target format",
(hint) => {
// An ESP flash dump is the one caller-selected format read as an archive.
expect(TARGETS[hint]).toMatchObject({
format: hint,
kind: hint === "esp-flash-image" ? "archive" : "executable",
});
},
);
});