Introducing a new way to review your PRs.

Read the announcement

morluto / rea

Reverse engineer anything with agents, from app behavior down to native binaries.

View on GitHub

27 documents · Updated Nov 20, 2026

docs / uefi-firmware-inspection

UEFI firmware inspection

UEFI firmware inspection turns a local flash image into evidence about its firmware volumes, firmware files, sections, compressed child streams, AMD PSP directory candidates, and AMI NVRAM stores. It is a static workflow: it reads and hashes the image, preserves byte locations and limits, and does not run firmware or claim what a device did at runtime. It is a child of Firmware and embedded analysis and relates to Artifact and application analysis.

Inspection model

The UEFI workflow accepts one stable local image and produces an identity-bound observation. The image digest, parser identity, source ranges, coverage state, integrity notes, and limitations travel with the result so a later investigation can tell mapped bytes from unknown bytes.

The main investigation outputs are:

OutputInvestigation question
Flash mapWhere are plausible firmware volumes and other mapped regions?
Volume and file recordsWhat firmware files exist inside each supported volume?
Section recordsWhich payloads, names, nested volumes, and compression carriers belong to each file?
Integrity and unknown regionsWhich declared boundaries or checks disagree with the observed bytes?
NVRAM recordsWhich AMI variable stores and linked variables are present?
Extraction filesWhich selected bytes can be published with hashes and source lineage?

The broad flow moves from an image snapshot to structural records and then to either retained Evidence or selected output files.

flowchart LR
    I[Local UEFI image] --> S[Stable identity and hash]
    S --> M[Volume, FFS, section, and PSP map]
    S --> N[AMI NVRAM map]
    M --> E[Evidence with coverage and limits]
    M --> X[Selected extraction]
    X --> E

Firmware image cartography

Volume discovery

The parser searches the image for plausible PI firmware volume headers. A header must have a usable extent, block map, and supported FFS2 or FFS3 file-system identity before the image can be admitted as UEFI; a stray _FVH string is not enough. The result records the volume offset, declared and observed lengths, file-system GUID, block map, erase polarity, revision, and header checksum observation.

The first mapped volume also gives a high-level entry basis. The result distinguishes a volume at the image start, an AMD PSP directory found before the first volume, a later scan hit, and an unknown basis. PSP entries retain declared locations as unverified observations rather than treating them as proof of an image range.

References: src/…/UefiFormatProbe.ts• L9-42 src/…/FirmwareVolume.ts• L36-70 src/…/FirmwareVolume.ts• L72-269 src/…/UefiAnalysisProvider.ts• L373-431

Volume and FFS records

Each supported volume is mapped to its firmware file system (FFS) files. An FFS record carries its GUID, type, size, alignment, state flags, source offset, digest, user-interface name when available, and integrity observation. Header or file checksum mismatches remain visible in the record; they do not silently remove the file.

An unsupported volume file-system GUID stays in the volume map but its body is not walked as FFS. Truncated extents, invalid states, non-erased alignment bytes, pad files, and leftover bytes become explicit unknown regions or coverage gaps. This keeps an opaque vendor area different from an empty area.

References: src/…/UefiImageScan.ts• L318-489 src/…/UefiImageScan.ts• L493-715 src/…/FfsFile.ts• L25-67 src/…/FfsFile.ts• L215-254

Section chains

Section parsing explains the content carried by sectioned FFS files. It records section type, declared and observed length, framing state, payload digest, parent path, and compression classification. User-interface sections can supply a bounded display name, while firmware-volume-image sections can lead to nested volume maps.

Nested records keep logical parent paths and source streams. A source stream identifies the carrier whose offsets are being used, so an offset inside decoded data is not confused with an offset in the original flash image. A decoded stream can contain more sections or volumes, and the parser continues only within the selected depth and byte limits.

References: src/…/FfsSections.ts• L22-62 src/…/FfsSections.ts• L150-293 src/…/UefiImageScan.ts• L717-949

Compression carriers

The workflow recognizes several common UEFI compression carriers. It can decode custom LZMA, LZMA with x86 filtering, and AMD zlib streams, then scan the decoded bytes for child sections or volumes. EFI standard compression, unknown GUID handlers, reserved guided attributes, and other unsupported carriers remain named gaps rather than being treated as empty content.

Extraction can publish a recognized but undecoded carrier as a raw compressed blob when requested. Decoded files include a derivation from the carrier and retain the decoded stream identity, which lets an investigator follow the evidence without inventing an original-image range for decoded bytes.

References: src/…/FfsSections.ts• L100-147 src/…/UefiImageScan.ts• L952-1060 src/…/uefiFirmwareAnalysis.ts• L102-122 src/…/uefiFirmwareAnalysis.ts• L475-500

NVRAM stores

NVRAM means non-volatile variable storage. The NVRAM workflow targets AMI NVAR stores, including factory-default containers such as StdDefaults, and reports their physical record structure without interpreting variable data.

Each variable record can show its name, attributes, raw next-record displacement, inline GUID or GUID-table index, data range, data digest, nesting depth, and parent offset. The result flattens nested chains while retaining the parent relationship. The data bytes remain opaque; a digest proves which bytes were observed but does not explain their settings or semantics.

The scanner finds bounded active NVAR chains in the raw image. It reports malformed records, incomplete links, depth limits, store limits, and the absence of recognized AMI stores as limitations. A complete scan with no stores means that no valid AMI NVAR chain was found within the scan rules; it is not proof that the image has no other variable format.

References: src/…/UefiNvram.ts• L6-23 src/…/UefiNvram.ts• L56-81 src/…/UefiNvram.ts• L226-367 src/…/uefiFirmwareAnalysis.ts• L370-396

Firmware extraction

Extraction materializes selected firmware bytes into a new output directory. The selection can be the whole image, one volume, one FFS file, or one section; selecting a container includes its descendants. Each published file has a digest, source range, source stream, parent path, media type when known, and a derivation when decoding produced it.

The result separates published files from extraction gaps. Gaps identify unsupported compression, unknown handlers, depth limits, unparsed regions, size limits, or pad files. A partial result is still useful because it states what was published and what needs another probe. An extracted PE32 payload can be passed to open_binary for native analysis; extraction itself does not execute it.

Publication uses an absent destination and verifies file size and digest before commit. It does not overwrite an existing directory, publish special file types, or assign runtime addresses to extracted bytes.

References: src/…/UefiAnalysisProvider.ts• L86-127 src/…/UefiAnalysisProvider.ts• L495-714 src/…/UefiPublication.ts• L40-120 src/…/uefiToolContracts.ts• L40-65

Analysis limits

The parser bounds input, structure, recursion, decoding, publication, and time. These bounds protect the investigation from large or hostile images, but they also define when coverage becomes partial.

AreaDefault or fixed boundaryMeaning
Input image128 MiBThe admitted image window cannot exceed this size.
Volume and file counts512 volumes; 20,000 FFS filesCaller values can increase these within fixed maxima.
Nested depth3Sections and child volumes beyond the selected depth become gaps.
Structural records100,000Shared parsing work stops with partial coverage when reached.
Decoded data128 MiB total; 64 MiB per LZMA streamDecoding cannot consume unbounded expanded data.
Operation time60 secondsThe complete provider operation has one deadline.
Extraction output256 MiB and 10,000 filesPublication stops at the selected output budget.
NVRAM scan64 stores and depth 2AMI store and nested-chain values can be raised only within their maxima.

Coverage is therefore part of the finding. Unknown regions, integrity mismatches, unsupported file systems, undecoded carriers, and budget gaps must be read with the coverage and limitations fields rather than as negative findings.

References: src/…/uefiLimits.ts• L1-31 src/…/uefiFirmwareAnalysis.ts• L166-267 src/…/UefiImageScan.ts• L151-165 src/…/UefiAnalysisProvider.ts• L255-370

Access workflows

CLI workflows

The CLI exposes the same UEFI service used by MCP. It accepts a local image for inspection or NVRAM mapping, and it accepts an output directory plus an optional volume, FFS-file, or section offset for extraction.

GoalCommand
Map volumes, files, sections, PSP candidates, and unknown regionsrea inspect-uefi-firmware <path>
Map AMI NVRAM stores and variablesrea inspect-uefi-nvram <path>
Extract the whole image or a selected targetrea extract-uefi-firmware <path> <output_directory>

Extraction offsets are mutually exclusive. A decoded target can also require --source-stream; this prevents the same numeric offset in two streams from selecting the wrong record. JSON output carries the same Evidence result and coverage fields as the MCP route.

References: src/…/uefiCommands.ts• L19-67 src/…/uefiCommands.ts• L69-155 src/…/UefiAnalysisService.ts• L12-33

MCP workflows

MCP clients call inspect_uefi_firmware, extract_uefi_firmware, and inspect_uefi_nvram. Each call uses the UEFI contract and returns Evidence with the image identity, parser identity, findings, source locations, coverage, and limitations.

An MCP client can also call open_binary and inspect_artifact to place a UEFI image in the general artifact inventory. That inventory exposes volumes and FFS files as navigable artifact occurrences. It does not expand FFS sections or nested compression; the dedicated UEFI inspection tool supplies those deeper findings. Extracted executable payloads can then move into the native workflows described by the related artifact page.

References: src/…/uefiToolContracts.ts• L13-83 src/…/serviceToolBindings.ts• L700-710 src/…/UefiArtifactReader.ts• L46-184 src/…/UefiArtifactReader.ts• L237-260

Static evidence boundaries

UEFI results describe bytes and format relationships. They do not emulate boot, validate a platform's hardware bindings, decrypt protected content, prove a cryptographic signature, establish that a PSP entry points to a usable address, or identify the variable state used by a live machine. Checksum and digest fields are integrity observations, not trust decisions.

Format admission also has a deliberate discovery boundary. The resolver checks a bounded image prefix for a plausible aligned volume. An image whose first usable volume lies beyond that prefix may remain unrecognized even if a later full scan could find it. This is an admission limit, not evidence that the image lacks a UEFI volume.

References: src/…/UefiFormatProbe.ts• L15-70 src/…/UefiPspDirectory.ts• L10-19 src/…/UefiPspDirectory.ts• L103-143 src/…/UefiAnalysisProvider.ts• L420-431 src/…/UefiAnalysisProvider.ts• L481-492

Change checklist

When these files or sections are changed, remember to consider these:

  • Keep UEFI admission rules aligned with the image scanner and the artifact resolver so a valid image is not admitted to one route and rejected by another.
  • Keep volume, FFS, section, decoded-stream, and NVRAM offsets tied to the same source identity and logical parent rules.
  • Keep unsupported carriers and malformed ranges represented in both coverage and extraction gaps; do not turn a skipped range into an absent finding.
  • Keep CLI offset selectors, source_stream, MCP schemas, and target selection rules aligned when extraction targeting changes.
  • Keep artifact inventory limits and dedicated UEFI inspection limits distinct so a shallow inventory is not presented as a full section scan.
  • Keep parser findings, publication hashes, source ranges, and Evidence provenance aligned when extraction output changes.

Important failure modes

TriggerConsequenceGuard
The image contains _FVH text but no plausible aligned supported volume headerThe image is not admitted as UEFIRequire the full volume plausibility checks rather than signature text alone
A volume has an unsupported file-system GUIDThe volume remains visible but its FFS body is unparsedUse the dedicated limitation and inspect the raw range with another tool if needed
A checksum, length, state, or section frame is invalidThe affected record or range is retained with an integrity note or gapTreat the observation as partial evidence and do not infer a valid executable payload
A compressed section has no supported handler or exceeds decode limitsThe carrier remains visible and extraction is partialPublish the raw carrier when useful and follow the reported gap
A target offset occurs in more than one source streamExtraction is refused as ambiguousSelect the matching source_stream explicitly
The source changes during the read or is not a stable regular fileThe operation fails before trusted Evidence is publishedReacquire a stable local image
A scan or output budget is reachedFindings stop with partial coverage or a size gapRaise the bounded caller limit only within its maximum or inspect a smaller target
The output directory already existsExtraction does not overwrite prior materialChoose a new absent destination
NVRAM bytes use a non-AMI variable formatNo valid AMI NVAR store is reportedUse a format-specific variable parser and do not treat the result as proof of no variables

Key files

FileWhy to read it
src/…/uefiFirmwareAnalysis.tsDefines the public request and result language for image inspection, extraction, and AMI NVRAM findings.
src/…/uefiLimits.tsDefines the resource boundaries that control complete and partial coverage.
src/…/UefiImageScan.tsShows the end-to-end structural map from firmware volumes through FFS files, sections, nested streams, unknown regions, and integrity notes.
src/…/FirmwareVolume.tsShows what makes a volume header plausible and how supported and unsupported file systems are separated.
src/…/FfsSections.tsDefines section framing, guided carriers, nested content, and supported compression classes.
src/…/UefiNvram.tsDefines AMI NVAR discovery, link chains, nested defaults, and opaque data handling.
src/…/UefiAnalysisProvider.tsConnects stable image identity, scanning, decoding, extraction selection, limits, and Evidence.
src/…/UefiArtifactReader.tsShows the shallow UEFI view used by the general artifact inventory.
src/…/uefiToolContracts.tsDefines the MCP and CLI capability descriptions and their public schemas.
src/…/uefiCommands.tsDefines the one-shot CLI commands and extraction offset selection.
src/…/UefiPublication.tsDefines safe, hash-checked extraction publication and rollback behavior.
tests/…/uefiFirmware.test.tsDemonstrates the expected findings across CLI, MCP, artifact inventory, extraction, limits, and AMI NVRAM.