Files
reverse-engineering-anything/docs
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
..
…

Documentation directory

REA documentation is organized by reader task and document owner. This directory links every authored guide; the site also serves separate product pages. The VitePress documentation source is this docs/ tree.

Getting started

Native binaries

JavaScript and Electron

Browser and captured websites

Android applications

Apple applications

.NET assemblies

Firmware

HarmonyOS packages

WebAssembly

EVM contracts

Databases and recorded packets

Process capture and instrumentation

Signal recordings

Provider setup and formats

Contracts and evidence

Development and verification

Release migrations

Architecture and authoring

Machine-owned documentation

Path Owner and update command
public/product-catalog.json Ignored contract projection; npm run docs:generate
verification/managed-conformance-*.json Ignored managed conformance projections; npm run evidence:generate
error-contract.schema.json Tracked schema from contracts; npm run docs:error-schema
user-visible-errors.csv Generated error code and category per domain and provider-owned error case; npm run docs:error-schema
releases/<version>.contributions.json Durable release contribution record; follow the release guide
assets/ Shared authored images referenced by guides

Do not edit generated catalogs or evidence to change product facts. Change their canonical contracts or producer and regenerate. Historical release records retain the exact commit messages and references from the release they describe.

Additional guides