From d380dc2409904edf058db0444a2a9eb29f827d4d Mon Sep 17 00:00:00 2001 From: bartman081523 Date: Thu, 19 Nov 2026 22:19:35 +0100 Subject: [PATCH] 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> --- THIRD_PARTY_NOTICES.md | 4 + docs/guides/firmware/firmware-analysis.md | 89 + licenses/npm-dependencies.txt | 17 +- licenses/npm-runtime-notices.txt | 140 +- package-lock.json | 31 + package.json | 1 + scripts/lib/module-layers.mjs | 13 + scripts/lib/test-projects.mjs | 2 +- .../tools/extract_uefi_firmware.json | 9 + .../tools/inspect_uefi_firmware.json | 9 + .../tools/inspect_uefi_nvram.json | 9 + src/application/BinaryTargetResolver.ts | 3 + .../binary/TargetFormatVocabularies.test.ts | 1 + src/application/uefi/UefiAnalysisService.ts | 35 + src/artifacts/artifactFormats.test.ts | 3 +- src/artifacts/artifactFormats.ts | 8 + .../inventory/ArtifactGraphConstruction.ts | 1 + src/artifacts/inventory/classify.ts | 2 + src/cli.ts | 2 + src/cli/cliCommandRegistrations.ts | 6 + src/cli/uefiCommands.ts | 156 ++ src/composition/capabilityDeclarations.ts | 6 + src/composition/capabilityServices.ts | 10 + src/composition/uefi.ts | 6 + src/contracts/toolContracts.ts | 2 + src/contracts/toolFamilies.ts | 5 + src/contracts/toolFamilyIds.ts | 1 + src/contracts/uefi/uefiToolContracts.ts | 84 + src/domain/analysisErrorBase.ts | 2 + src/domain/artifactGraph.ts | 2 + src/domain/targetFormats.ts | 1 + src/domain/uefi/uefiFirmwareAnalysis.ts | 542 ++++++ src/domain/uefi/uefiLimits.ts | 31 + src/ports/uefi/UefiAnalysisPort.ts | 24 + src/resources/ArtifactReader.ts | 1 + src/server/createServer.ts | 2 + src/server/serviceToolBindings.ts | 7 + src/uefi/FfsFile.test.ts | 110 ++ src/uefi/FfsFile.ts | 258 +++ src/uefi/FfsSections.test.ts | 146 ++ src/uefi/FfsSections.ts | 277 +++ src/uefi/FirmwareVolume.test.ts | 131 ++ src/uefi/FirmwareVolume.ts | 370 ++++ src/uefi/UefiAnalysisProvider.test.ts | 1610 +++++++++++++++++ src/uefi/UefiAnalysisProvider.ts | 926 ++++++++++ src/uefi/UefiArtifactReader.test.ts | 245 +++ src/uefi/UefiArtifactReader.ts | 456 +++++ src/uefi/UefiBytes.ts | 88 + src/uefi/UefiCodeTables.ts | 136 ++ src/uefi/UefiFailures.ts | 124 ++ src/uefi/UefiFormatProbe.ts | 71 + src/uefi/UefiGuid.test.ts | 62 + src/uefi/UefiGuid.ts | 52 + src/uefi/UefiImageScan.test.ts | 489 +++++ src/uefi/UefiImageScan.ts | 971 ++++++++++ src/uefi/UefiLzmaProtocol.ts | 37 + src/uefi/UefiLzmaWorker.ts | 168 ++ src/uefi/UefiNvram.test.ts | 224 +++ src/uefi/UefiNvram.ts | 341 ++++ src/uefi/UefiProviderIdentity.ts | 5 + src/uefi/UefiPspDirectory.ts | 117 ++ src/uefi/UefiPublication.ts | 122 ++ src/uefi/UefiX86BranchFilter.ts | 55 + tests/acceptance/uefiFirmware.test.ts | 484 +++++ tests/boundary/uefi/lzmaWorker.test.ts | 136 ++ tests/conformance/providerCapabilityCases.ts | 1 + tests/fixtures/uefiImage.ts | 289 +++ tests/support/providerLifecycleCoverage.ts | 37 + 68 files changed, 9801 insertions(+), 4 deletions(-) create mode 100644 scripts/verify/advertised-schemas/tools/extract_uefi_firmware.json create mode 100644 scripts/verify/advertised-schemas/tools/inspect_uefi_firmware.json create mode 100644 scripts/verify/advertised-schemas/tools/inspect_uefi_nvram.json create mode 100644 src/application/uefi/UefiAnalysisService.ts create mode 100644 src/cli/uefiCommands.ts create mode 100644 src/composition/uefi.ts create mode 100644 src/contracts/uefi/uefiToolContracts.ts create mode 100644 src/domain/uefi/uefiFirmwareAnalysis.ts create mode 100644 src/domain/uefi/uefiLimits.ts create mode 100644 src/ports/uefi/UefiAnalysisPort.ts create mode 100644 src/uefi/FfsFile.test.ts create mode 100644 src/uefi/FfsFile.ts create mode 100644 src/uefi/FfsSections.test.ts create mode 100644 src/uefi/FfsSections.ts create mode 100644 src/uefi/FirmwareVolume.test.ts create mode 100644 src/uefi/FirmwareVolume.ts create mode 100644 src/uefi/UefiAnalysisProvider.test.ts create mode 100644 src/uefi/UefiAnalysisProvider.ts create mode 100644 src/uefi/UefiArtifactReader.test.ts create mode 100644 src/uefi/UefiArtifactReader.ts create mode 100644 src/uefi/UefiBytes.ts create mode 100644 src/uefi/UefiCodeTables.ts create mode 100644 src/uefi/UefiFailures.ts create mode 100644 src/uefi/UefiFormatProbe.ts create mode 100644 src/uefi/UefiGuid.test.ts create mode 100644 src/uefi/UefiGuid.ts create mode 100644 src/uefi/UefiImageScan.test.ts create mode 100644 src/uefi/UefiImageScan.ts create mode 100644 src/uefi/UefiLzmaProtocol.ts create mode 100644 src/uefi/UefiLzmaWorker.ts create mode 100644 src/uefi/UefiNvram.test.ts create mode 100644 src/uefi/UefiNvram.ts create mode 100644 src/uefi/UefiProviderIdentity.ts create mode 100644 src/uefi/UefiPspDirectory.ts create mode 100644 src/uefi/UefiPublication.ts create mode 100644 src/uefi/UefiX86BranchFilter.ts create mode 100644 tests/acceptance/uefiFirmware.test.ts create mode 100644 tests/boundary/uefi/lzmaWorker.test.ts create mode 100644 tests/fixtures/uefiImage.ts diff --git a/THIRD_PARTY_NOTICES.md b/THIRD_PARTY_NOTICES.md index 1b2c7dc927..eddba66743 100644 --- a/THIRD_PARTY_NOTICES.md +++ b/THIRD_PARTY_NOTICES.md @@ -23,6 +23,10 @@ notices supplied with the software you actually obtain or redistribute. | Windows native addon | The release addon is compiled with MinGW-w64 and statically links GCC runtime libraries. Preserve the [MinGW-w64 runtime notices](licenses/MinGW-w64-runtime.txt), [GPLv3 text](licenses/GPL-3.0.txt), and [GCC Runtime Library Exception 3.1](licenses/GCC-Runtime-Library-Exception-3.1.txt). The exception governs eligible compiled combinations; it does not relicense the runtime itself under MIT. The Node-API build headers are from Node 22.19.0; its [original license and component notices](licenses/Node-22.19.0-LICENSE.txt) are retained. Node itself is supplied by the user. Snapshot provenance and release-toolchain review requirements are in [licenses/README.md](licenses/README.md). | | Dinosaur website example | Selected excerpts from [wayou/t-rex-runner](https://github.com/wayou/t-rex-runner/tree/5455bfa408ec6b707c7300ff194b7390733a766d), derived from Chromium's dinosaur game. The website retains the [original BSD-3-Clause notices](website/public/assets/licenses/dinosaur.txt), including Chromium authors and wayou. This asset is not part of the npm runtime. | +The UEFI x86 BCJ decoder is adapted from Igor Pavlov's public-domain +[Bra86.c](https://github.com/tianocore/edk2/blob/556dcfb466e9f05affeaff881d738807f8156d3c/MdeModulePkg/Library/LzmaCustomDecompressLib/Sdk/C/Bra86.c), +as used by EDK II's LZMAF86 handler. + Two locked runtime releases, [`clean-git-ref@2.0.1`](https://github.com/TheSavior/clean-git-ref/tree/bf3c8afc8032bcdc6a53634c18b601dc6df478fb) (declared Apache-2.0) and [`minimisted@2.0.1`](https://github.com/kt3k/minimisted/tree/95fdfb8d6efb9546c1117854fe3a58105f6332ce) (declared MIT), omit a full license/copyright document in their published archives and inspected upstream release sources. Their runtime notice diff --git a/docs/guides/firmware/firmware-analysis.md b/docs/guides/firmware/firmware-analysis.md index 89a743aac3..b269b9b35e 100644 --- a/docs/guides/firmware/firmware-analysis.md +++ b/docs/guides/firmware/firmware-analysis.md @@ -26,6 +26,95 @@ MCP, summary delivery and selected supporting facts. Its real-data verification covers a pair of OpenWrt FIT releases; it does not establish comparison of decoded root filesystems or arbitrary firmware formats. +## UEFI flash images and AMI NVRAM + +The bundled UEFI tools map PI firmware volumes, FFS files and sections in local +flash images. They also report plausible AMD PSP directory tables and scan for +AMI NVAR chains such as `StdDefaults`. They run independently of Binwalk and +Unblob. FFS file and section discovery applies to FFS2 and FFS3 volumes. +Volumes with other file-system GUIDs retain their header and extent, with the +body reported as unparsed. REA checks the volume header and block map against +the declared volume extent. FFS traversal accounts for volume extensions and +retains valid files after an unusable file header. A truncated file body +does not receive a verified checksum verdict. + +```sh +rea inspect-uefi-firmware /path/to/flash.bin --json +rea inspect-uefi-nvram /path/to/flash.bin --json +rea extract-uefi-firmware /path/to/flash.bin /path/to/new-output \ + --volume-offset 4096 --source-stream flash --json +``` + +Use `inspect_uefi_firmware` and `inspect_uefi_nvram` from MCP with +`{"path":"/path/to/flash.bin"}`. To extract a mapped flash-backed volume: + +```json +{ + "name": "extract_uefi_firmware", + "arguments": { + "path": "/path/to/flash.bin", + "output_directory": "/path/to/new-output", + "target": { "kind": "volume", "offset": 4096, "source_stream": null } + } +} +``` + +Extraction also accepts `ffs-file`, `section`, and `whole-image` targets. +Volume, file, and section targets include mapped descendants. 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. +A gap in one volume leaves a fully extracted sibling's coverage complete. +Erased padding alone does not make a mapped volume partial. A whole-image +request that maps no volumes reports a gap with no published payloads. +A decoded record's +offset starts at zero in the stream named by `source_stream`. Pass that carrier +logical path when extracting by offset. For the original image, use MCP +`source_stream: null` or CLI `--source-stream flash` to disambiguate offsets. +Files carved directly from the image have an `original_file_range`. Decoded +files have a null original range and retain their byte range in the named +stream. Read `derivations` to trace each decoded stream back to its carrier. + +LZMA-custom, LZMAF86, and AMD-zlib can yield nested volumes or section chains. +The LZMAF86 worker reverses the x86 branch filter before mapping decoded bytes. +A decoder limit makes inspection partial and appears as a size gap in +extraction. When decoded bytes lack confirmed framing, extraction retains the +decoded stream and reports its unparsed range. When the common section header +bounds a malformed section, extraction reports that section's range and keeps +later valid sections selectable. Leaf payload ranges exclude type-specific +header fields. Nonzero bytes between aligned sections appear as a gap and +later sections remain selectable. +Readable guided section streams are mapped directly when the section does +not require processing. Guided integrity and authentication remain unverified. +EFI standard compression and unsupported guided handlers make inspection +partial and produce extraction gaps. Set MCP `include_compressed` to false or pass +`--no-include-compressed` to omit undecoded carriers. PSP tables require a matching directory checksum. Failed checks stay in +the candidate list, and entry locations remain unverified declarations. NVAR results report names, data ranges and hashes, +raw 24-bit record-relative links (with `0xffffff` for terminal links), and +8-bit attributes. A named record holds either a GUID-table index or an inline +GUID. Data-only records have neither. Links remain observations and variable +contents are retained as byte ranges. A nested NVAR chain can begin with a +framed inactive record. The scan continues past framed inactive entries and +reports partial coverage for incomplete successors. + +UEFI operations accept up to 128 MiB per image, with a shared limit of 100,000 +structural records. Artifact inventory applies the same ceiling to volume +candidates and their block maps. Inventory reports unknown coverage when +a volume exceeds the readable range, the file walk meets an unparsed suffix, +or a scan limit is reached. +The nesting depth defaults to 3 for firmware and 2 for NVAR. Decoding is limited to 64 MiB per stream and 128 MiB across one operation. +An admitted operation has a 60-second deadline covering input, parsing, +decoding, and staging. Owned cleanup can continue past the deadline. Extraction +defaults to 10,000 files and 256 MiB of published file bytes in a fresh path +with an existing parent. Review `coverage`, `limitations`, and +`extraction_gaps` before relying on completeness. + +The separate `open_binary` flash admission path requires a signature in the +first MiB and an aligned, structurally plausible FFS2 or FFS3 volume in the +bounded scan. Flash admission provides an artifact inventory. For executable +analysis, pass the returned path of an extracted PE32 payload to +`open_binary` and choose a provider that supports its format and architecture. +Runtime addresses remain unknown. + ## Caller-supplied tools Provide existing tools using absolute executable paths, scoped to your shell: diff --git a/licenses/npm-dependencies.txt b/licenses/npm-dependencies.txt index f5515c1356..c2987813d1 100644 --- a/licenses/npm-dependencies.txt +++ b/licenses/npm-dependencies.txt @@ -2,7 +2,7 @@ REA npm dependency inventory Prepared from the root package-lock.json; refresh this inventory when locked dependencies change. License identifiers are upstream lockfile declarations, not a legal assessment. Runtime includes transitive and optional platform packages; development includes build, test and website tooling. -Locked package entries: 969; runtime: 171. +Locked package entries: 972; runtime: 174. Full runtime copyright/license/NOTICE texts: npm-runtime-notices.txt. @algolia/abtesting@1.25.0 | development | MIT @@ -2000,6 +2000,11 @@ algoliasearch@5.59.0 | development | MIT Package: https://www.npmjs.com/package/algoliasearch/v/5.59.0 Archive: https://registry.npmjs.org/algoliasearch/-/algoliasearch-5.59.0.tgz Integrity: sha512-wUXzaeI7B526W4y1gFg3lcxgDZ67XSgRJIiellYWOas/pLpO7rOtxm9Gr2E/C8aiSDXIgx1q5TdSsvK67Uakqw== +amdefine@0.1.1 | runtime | BSD-3-Clause AND MIT + Lockfile path: node_modules/amdefine + Package: https://www.npmjs.com/package/amdefine/v/0.1.1 + Archive: https://registry.npmjs.org/amdefine/-/amdefine-0.1.1.tgz + Integrity: sha512-cE/769sItEDt5sSdqmrWMsat+XaA5FJiEou+ZwlY7ef/Jf/517k6nYyUIRPR2o/QbpBg4FiYXj9GyRGNg5f/bg== angular-html-parser@10.11.0 | development | MIT Lockfile path: node_modules/angular-html-parser Package: https://www.npmjs.com/package/angular-html-parser/v/10.11.0 @@ -3275,6 +3280,16 @@ lru-cache@11.5.3 | development | BlueOak-1.0.0 Package: https://www.npmjs.com/package/lru-cache/v/11.5.3 Archive: https://registry.npmjs.org/lru-cache/-/lru-cache-11.5.3.tgz Integrity: sha512-U4N8FgzmWxc8k1VH8Kr6lQg18U7Fjvby6wXHVRX/ZZ7IwWbRMgrRbP0Wrb5q5NVinryp4SQampHKdvtecItxUg== +lzma-purejs@0.9.3 | runtime | BSD + Lockfile path: node_modules/lzma-purejs + Package: https://www.npmjs.com/package/lzma-purejs/v/0.9.3 + Archive: https://registry.npmjs.org/lzma-purejs/-/lzma-purejs-0.9.3.tgz + Integrity: sha512-6VPTP6dEwoEeXYxK9/9ZsUH8zD/lGdTCKenEv2C4mrZkp111CttGYVVrLTcCY6BM+dnADTMrARnG8PZQctJUeg== +commander@2.0.0 | runtime | UNDECLARED + Lockfile path: node_modules/lzma-purejs/node_modules/commander + Package: https://www.npmjs.com/package/commander/v/2.0.0 + Archive: https://registry.npmjs.org/commander/-/commander-2.0.0.tgz + Integrity: sha512-qebjpyeaA/nJ4w3EO2cV2++/zEkccPnjWogzA2rff+Lk8ILI75vULeTmyd4wPxWdKwtP3J+G39IXVZadh0UHyw== magic-string@1.4.3 | development | MIT Lockfile path: node_modules/magic-string Package: https://www.npmjs.com/package/magic-string/v/1.4.3 diff --git a/licenses/npm-runtime-notices.txt b/licenses/npm-runtime-notices.txt index 66cbe5d355..9b7d61b730 100644 --- a/licenses/npm-runtime-notices.txt +++ b/licenses/npm-runtime-notices.txt @@ -1,7 +1,7 @@ REA third-party npm runtime copyright, license and NOTICE texts Collected from integrity-verified locked npm archives. Release-specific supplements and upstream notice gaps are identified in their entries. External engines are separately obtained; see THIRD_PARTY_NOTICES.md. -Runtime dependency fingerprint (SHA-256): e400a6f327db9b91f6f4860cc6742b061e95097d04e2075b887810907cfee38c +Runtime dependency fingerprint (SHA-256): c88607d402fe40b71d340fde84956b8a9516966ebe22a1faeb6bc35db251c3c6 ===== @babel/helper-string-parser@8.0.6 ===== Declared license: MIT @@ -10497,3 +10497,141 @@ FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. + +===== amdefine@0.1.1 ===== +Declared license: BSD-3-Clause AND MIT +Archive: https://registry.npmjs.org/amdefine/-/amdefine-0.1.1.tgz +Integrity: sha512-cE/769sItEDt5sSdqmrWMsat+XaA5FJiEou+ZwlY7ef/Jf/517k6nYyUIRPR2o/QbpBg4FiYXj9GyRGNg5f/bg== +Scope: npm runtime dependency, including optional platform packages. + +--- package/LICENSE --- + +amdefine is released under two licenses: new BSD, and MIT. You may pick the +license that best suits your development needs. The text of both licenses are +provided below. + + +The "New" BSD License: +---------------------- + +Copyright (c) 2011, The Dojo Foundation +All rights reserved. + +Redistribution and use in source and binary forms, with or without +modification, are permitted provided that the following conditions are met: + + * Redistributions of source code must retain the above copyright notice, this + list of conditions and the following disclaimer. + * Redistributions in binary form must reproduce the above copyright notice, + this list of conditions and the following disclaimer in the documentation + and/or other materials provided with the distribution. + * Neither the name of the Dojo Foundation nor the names of its contributors + may be used to endorse or promote products derived from this software + without specific prior written permission. + +THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND +ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED +WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE +DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE +FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR +SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER +CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, +OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. + + + +MIT License +----------- + +Copyright (c) 2011, The Dojo Foundation + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in +all copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN +THE SOFTWARE. + +===== commander@2.0.0 ===== +Declared license: UNDECLARED +Archive: https://registry.npmjs.org/commander/-/commander-2.0.0.tgz +Integrity: sha512-qebjpyeaA/nJ4w3EO2cV2++/zEkccPnjWogzA2rff+Lk8ILI75vULeTmyd4wPxWdKwtP3J+G39IXVZadh0UHyw== +Scope: npm runtime dependency, including optional platform packages. +The package manifest has no license field. The locked archive README contains the MIT notice below. + +--- package/Readme.md (license section) --- + +## License + +(The MIT License) + +Copyright (c) 2011 TJ Holowaychuk <tj@vision-media.ca> + +Permission is hereby granted, free of charge, to any person obtaining +a copy of this software and associated documentation files (the +'Software'), to deal in the Software without restriction, including +without limitation the rights to use, copy, modify, merge, publish, +distribute, sublicense, and/or sell copies of the Software, and to +permit persons to whom the Software is furnished to do so, subject to +the following conditions: + +The above copyright notice and this permission notice shall be +included in all copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND, +EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF +MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. +IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY +CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, +TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE +SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. + +===== lzma-purejs@0.9.3 ===== +Declared license: BSD +Archive: https://registry.npmjs.org/lzma-purejs/-/lzma-purejs-0.9.3.tgz +Integrity: sha512-6VPTP6dEwoEeXYxK9/9ZsUH8zD/lGdTCKenEv2C4mrZkp111CttGYVVrLTcCY6BM+dnADTMrARnG8PZQctJUeg== +Scope: npm runtime dependency, including optional platform packages. +The package manifest declares BSD. The license text below is preserved from the locked archive README. + +--- package/README.md (license section) --- + +## License + +> Copyright (c) 2011 Gary Linscott +> +> Copyright (c) 2011-2012 Juan Mellado +> +> Copyright (c) 2013 C. Scott Ananian +> +> All rights reserved. +> +> Permission is hereby granted, free of charge, to any person obtaining a copy +> of this software and associated documentation files (the "Software"), to deal +> in the Software without restriction, including without limitation the rights +> to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +> copies of the Software, and to permit persons to whom the Software is +> furnished to do so, subject to the following conditions: +> +> The above copyright notice and this permission notice shall be included in +> all copies or substantial portions of the Software. +> +> THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +> IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +> FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +> AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +> LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +> OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN +> THE SOFTWARE. diff --git a/package-lock.json b/package-lock.json index 32633f8fe8..345a8ef5e2 100644 --- a/package-lock.json +++ b/package-lock.json @@ -36,6 +36,7 @@ "isomorphic-git": "1.38.7", "jsonc-parser": "3.3.1", "lossless-json": "4.3.1", + "lzma-purejs": "0.9.3", "openpgp": "6.3.2", "parse5": "8.0.1", "pino": "10.4.0", @@ -6067,6 +6068,15 @@ "node": ">= 14.0.0" } }, + "node_modules/amdefine": { + "version": "0.1.1", + "resolved": "https://registry.npmjs.org/amdefine/-/amdefine-0.1.1.tgz", + "integrity": "sha512-cE/769sItEDt5sSdqmrWMsat+XaA5FJiEou+ZwlY7ef/Jf/517k6nYyUIRPR2o/QbpBg4FiYXj9GyRGNg5f/bg==", + "license": "BSD-3-Clause AND MIT", + "engines": { + "node": ">=0.4.2" + } + }, "node_modules/angular-html-parser": { "version": "10.11.0", "resolved": "https://registry.npmjs.org/angular-html-parser/-/angular-html-parser-10.11.0.tgz", @@ -9388,6 +9398,27 @@ "node": "20 || >=22" } }, + "node_modules/lzma-purejs": { + "version": "0.9.3", + "resolved": "https://registry.npmjs.org/lzma-purejs/-/lzma-purejs-0.9.3.tgz", + "integrity": "sha512-6VPTP6dEwoEeXYxK9/9ZsUH8zD/lGdTCKenEv2C4mrZkp111CttGYVVrLTcCY6BM+dnADTMrARnG8PZQctJUeg==", + "license": "BSD", + "dependencies": { + "amdefine": "~0.1.0", + "commander": "~2.0.0" + }, + "bin": { + "lzmajs": "bin/lzmajs" + } + }, + "node_modules/lzma-purejs/node_modules/commander": { + "version": "2.0.0", + "resolved": "https://registry.npmjs.org/commander/-/commander-2.0.0.tgz", + "integrity": "sha512-qebjpyeaA/nJ4w3EO2cV2++/zEkccPnjWogzA2rff+Lk8ILI75vULeTmyd4wPxWdKwtP3J+G39IXVZadh0UHyw==", + "engines": { + "node": ">= 0.6.x" + } + }, "node_modules/magic-string": { "version": "1.4.3", "resolved": "https://registry.npmjs.org/magic-string/-/magic-string-1.4.3.tgz", diff --git a/package.json b/package.json index cc4cb923b1..5042fa0441 100644 --- a/package.json +++ b/package.json @@ -398,6 +398,7 @@ "isomorphic-git": "1.38.7", "jsonc-parser": "3.3.1", "lossless-json": "4.3.1", + "lzma-purejs": "0.9.3", "openpgp": "6.3.2", "parse5": "8.0.1", "pino": "10.4.0", diff --git a/scripts/lib/module-layers.mjs b/scripts/lib/module-layers.mjs index 24e33e6b1f..7709b8b2a0 100644 --- a/scripts/lib/module-layers.mjs +++ b/scripts/lib/module-layers.mjs @@ -91,6 +91,7 @@ export const UNIT_LAYERS = Object.freeze( "rust", "signals", "sqlite", + "uefi", "v8", "wasm", ]), @@ -286,6 +287,11 @@ export const ENTRY_FILES = Object.freeze( electron: ["ElectronFuseProvider.ts", "ElectronFuseProviderIdentity.ts"], erlang: ["BeamProvider.ts", "ErlangBeamProviderIdentity.ts"], evm: ["EvmoleInterfaceProvider.ts", "EvmoleProviderIdentity.ts"], + uefi: [ + "UefiAnalysisProvider.ts", + "UefiProviderIdentity.ts", + "UefiFormatProbe.ts", + ], firmware: [ "FirmwareCommand.ts", "FirmwareProvider.ts", @@ -419,6 +425,13 @@ const isEntryFile = (unit, target) => * still is. Keep the list short and say why. */ export const PROVIDER_DEPENDENCIES = Object.freeze([ + Object.freeze({ + from: "artifacts", + to: "uefi", + files: Object.freeze(["UefiArtifactReader.ts", "UefiFormatProbe.ts"]), + reason: + "artifact inventory uses the UEFI provider's format admission and FV/FFS reader", + }), Object.freeze({ from: "inspector", to: "browser", diff --git a/scripts/lib/test-projects.mjs b/scripts/lib/test-projects.mjs index ef3b0b1b31..73d5a8c1e0 100644 --- a/scripts/lib/test-projects.mjs +++ b/scripts/lib/test-projects.mjs @@ -19,7 +19,7 @@ export const SOURCE_TEST_PROJECTS = [ group: "source", include: [ "src/*.test.ts", - "src/{android,apkSignature,apktool,jeb,adb,artifacts,browser,compression,config,cutter,desktop,dotnet,electron,erlang,evm,firmware,flutter,frida,pcap,ghidra,go,gpu,hopper,hopperPaths,ida,inspector,java,javascript,kuna,main,native,nuget,process,providers,python,reference,resources,rust,server,sqlite,v8,wasm,windows}/**/*.test.ts", + "src/{android,apkSignature,apktool,jeb,adb,artifacts,browser,compression,config,cutter,desktop,dotnet,electron,erlang,evm,firmware,flutter,frida,pcap,ghidra,go,gpu,hopper,hopperPaths,ida,inspector,java,javascript,kuna,main,native,nuget,process,providers,python,reference,resources,rust,server,sqlite,uefi,v8,wasm,windows}/**/*.test.ts", ], }, { diff --git a/scripts/verify/advertised-schemas/tools/extract_uefi_firmware.json b/scripts/verify/advertised-schemas/tools/extract_uefi_firmware.json new file mode 100644 index 0000000000..9da10e3d43 --- /dev/null +++ b/scripts/verify/advertised-schemas/tools/extract_uefi_firmware.json @@ -0,0 +1,9 @@ +{ + "schemas": { + "input compact": "0b5c3f51ba380be5", + "output compact": "4bda7c3651bfc579" + }, + "patterns": { + "input": ["^[^\\x00]*$"] + } +} diff --git a/scripts/verify/advertised-schemas/tools/inspect_uefi_firmware.json b/scripts/verify/advertised-schemas/tools/inspect_uefi_firmware.json new file mode 100644 index 0000000000..f2865f019d --- /dev/null +++ b/scripts/verify/advertised-schemas/tools/inspect_uefi_firmware.json @@ -0,0 +1,9 @@ +{ + "schemas": { + "input compact": "5e39a8d246d4707b", + "output compact": "4bda7c3651bfc579" + }, + "patterns": { + "input": ["^[^\\x00]*$"] + } +} diff --git a/scripts/verify/advertised-schemas/tools/inspect_uefi_nvram.json b/scripts/verify/advertised-schemas/tools/inspect_uefi_nvram.json new file mode 100644 index 0000000000..1a44a7a488 --- /dev/null +++ b/scripts/verify/advertised-schemas/tools/inspect_uefi_nvram.json @@ -0,0 +1,9 @@ +{ + "schemas": { + "input compact": "0b09538337a8f816", + "output compact": "4bda7c3651bfc579" + }, + "patterns": { + "input": ["^[^\\x00]*$"] + } +} diff --git a/src/application/BinaryTargetResolver.ts b/src/application/BinaryTargetResolver.ts index d9d3da36a7..a3b0eff5fa 100644 --- a/src/application/BinaryTargetResolver.ts +++ b/src/application/BinaryTargetResolver.ts @@ -1,3 +1,4 @@ +import { probeUefiFlashImage } from "../uefi/UefiFormatProbe.js"; import { BINARY_TARGET_FORMAT_KINDS, type TargetFormatHint, @@ -500,6 +501,7 @@ const readOpenedBinaryTarget = async ( targetKind === "database" || (targetKind === undefined && artifactFormat !== "ines" && + artifactFormat !== "uefi" && artifactFormat !== "plist" && path.toLowerCase().endsWith(".hop")) ) @@ -801,6 +803,7 @@ const detectArtifactFormat = async ( )) ) return "dmg"; + if (await probeUefiFlashImage(handle, signal)) return "uefi"; // XML property lists can use archive-specific suffixes such as .archive. // The named-format check above keeps .js, .map, and .asar classifications. const xmlProbe = createXmlPlistSignatureProbe(); diff --git a/src/application/binary/TargetFormatVocabularies.test.ts b/src/application/binary/TargetFormatVocabularies.test.ts index a23bd3d962..2cfca51003 100644 --- a/src/application/binary/TargetFormatVocabularies.test.ts +++ b/src/application/binary/TargetFormatVocabularies.test.ts @@ -145,6 +145,7 @@ const TARGETS: TargetFixtures = { 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; diff --git a/src/application/uefi/UefiAnalysisService.ts b/src/application/uefi/UefiAnalysisService.ts new file mode 100644 index 0000000000..4b53b6a3f9 --- /dev/null +++ b/src/application/uefi/UefiAnalysisService.ts @@ -0,0 +1,35 @@ +import type { ExecutionOptions } from "../../ports/AnalysisProvider.js"; +import type { UefiAnalysisPort } from "../../ports/uefi/UefiAnalysisPort.js"; +import { + uefiRequestSchema, + type UefiOperation, +} from "../../domain/uefi/uefiFirmwareAnalysis.js"; +import type { AnalysisError } from "../../domain/analysisErrorBase.js"; +import type { Evidence } from "../../domain/evidence.js"; +import { executeProviderOperation } from "../ProviderOperationExecution.js"; +import type { Result } from "../../domain/result.js"; + +/** Shared CLI/MCP admission, execution, and Evidence composition for UEFI. */ +export class UefiAnalysisService { + constructor(readonly provider: UefiAnalysisPort) {} + + close(): Promise { + return this.provider.close?.() ?? Promise.resolve(); + } + + /** Run one caller-selected UEFI request and retain image identity inline. */ + execute( + operation: UefiOperation, + input: unknown, + options?: ExecutionOptions, + ): Promise> { + return executeProviderOperation( + operation, + input, + options, + uefiRequestSchema, + this.provider, + "observed", + ); + } +} diff --git a/src/artifacts/artifactFormats.test.ts b/src/artifacts/artifactFormats.test.ts index 7d0e50794a..11ee9bd22e 100644 --- a/src/artifacts/artifactFormats.test.ts +++ b/src/artifacts/artifactFormats.test.ts @@ -43,7 +43,8 @@ type FormatsWithReaders = | "dfuse" | "esp-flash-image" | "fit" - | "ntfs-mft"; + | "ntfs-mft" + | "uefi"; const readerFormatsMatch: Equal = true; diff --git a/src/artifacts/artifactFormats.ts b/src/artifacts/artifactFormats.ts index ed52d10315..d3fa6c0b91 100644 --- a/src/artifacts/artifactFormats.ts +++ b/src/artifacts/artifactFormats.ts @@ -43,6 +43,7 @@ import type { NodeSeaAdmission } from "./nodeSea/NodeSeaAdmission.js"; import { NodeSeaArtifactReader } from "./NodeSeaArtifactReader.js"; import type { PyInstallerAdmission } from "./pyinstaller/PyInstallerAdmission.js"; import { PyInstallerArtifactReader } from "./PyInstallerArtifactReader.js"; +import { UefiArtifactReader } from "../uefi/UefiArtifactReader.js"; import { Uf2ArtifactReader } from "./Uf2ArtifactReader.js"; import { NtfsMftArtifactReader } from "./NtfsMftArtifactReader.js"; import { AndroidOtaPayloadArtifactReader } from "./AndroidOtaPayloadArtifactReader.js"; @@ -396,6 +397,13 @@ const NON_ZIP_FORMATS = { "gamecube-dol": described("gamecube-dol", plain), hopper: described("hopper", plain), "analysis-database": described("analysis-database", plain), + uefi: described("uefi", { + ...plain, + retainClassifiedSource: true, + absentInventory: "unavailable", + createReader: (path, options) => + new UefiArtifactReader(path, sourceOf(options)), + }), plist: described("plist", plain), entitlements: described("entitlements", plain), directory: container("directory", { diff --git a/src/artifacts/inventory/ArtifactGraphConstruction.ts b/src/artifacts/inventory/ArtifactGraphConstruction.ts index 948bd43239..51f32fe5e8 100644 --- a/src/artifacts/inventory/ArtifactGraphConstruction.ts +++ b/src/artifacts/inventory/ArtifactGraphConstruction.ts @@ -597,6 +597,7 @@ const artifactRoleForFormat = ( kind: "container", format: zipPackageFormatForPath(path) ?? format, }; + if (format === "uefi") return { kind: "resource", format }; if (format === "plist") return { kind: "plist", format }; if (artifactFormatDescriptor(format)?.roleContainer === true) return { kind: "container", format }; diff --git a/src/artifacts/inventory/classify.ts b/src/artifacts/inventory/classify.ts index 3afe236ae8..8f2fcba755 100644 --- a/src/artifacts/inventory/classify.ts +++ b/src/artifacts/inventory/classify.ts @@ -1,3 +1,4 @@ +import { probeUefiFlashImage } from "../../uefi/UefiFormatProbe.js"; import { ParseFailureError } from "../../domain/parseFailure.js"; import { artifactOperationCause, @@ -393,6 +394,7 @@ const classifyRootFormat = async ( (await hasDiskImageSignature(archiveBytes, read)) ) return "dmg"; + if (await probeUefiFlashImage(handle, signal)) return "uefi"; const pck = await embeddedProbes.godotPck(evidence.prefix); if (pck !== undefined) return { kind: "godot-pck", source, location: pck }; // A C3 or S3 dump begins with its bootloader, so the layout is located diff --git a/src/cli.ts b/src/cli.ts index dbc01d356d..bc14021cb0 100644 --- a/src/cli.ts +++ b/src/cli.ts @@ -39,6 +39,7 @@ import * as sqliteModule from "./cli/sqliteCommands.js"; import * as artifactModule from "./cli/artifactCommands.js"; import * as managedModule from "./cli/managedCommands.js"; import * as firmwareModule from "./cli/firmwareCommands.js"; +import * as uefiModule from "./cli/uefiCommands.js"; import * as androidModule from "./cli/androidCommands.js"; import * as pcapModule from "./cli/pcapCommands.js"; import * as flutterModule from "./cli/flutterCommands.js"; @@ -97,6 +98,7 @@ const CLI_COMMAND_MODULES: CliCommandModules = { artifact: artifactModule, managed: managedModule, firmware: firmwareModule, + uefi: uefiModule, android: androidModule, pcap: pcapModule, flutter: flutterModule, diff --git a/src/cli/cliCommandRegistrations.ts b/src/cli/cliCommandRegistrations.ts index 131e592649..290223770e 100644 --- a/src/cli/cliCommandRegistrations.ts +++ b/src/cli/cliCommandRegistrations.ts @@ -206,6 +206,11 @@ export const CLI_COMMAND_REGISTRATIONS = { context.environment, ), ), + uefi: plain( + () => import("./uefiCommands.js"), + (module, context) => + module.registerUefiCommands(context.cli, context.logger), + ), android: plain( () => import("./androidCommands.js"), (module, context) => @@ -461,6 +466,7 @@ const CLI_FAMILY_REGISTRATIONS: { ], managed: ["managed"], firmware: ["firmware"], + uefi: ["uefi"], android: ["android"], pcap: ["pcap"], flutter: ["flutter"], diff --git a/src/cli/uefiCommands.ts b/src/cli/uefiCommands.ts new file mode 100644 index 0000000000..8317b97243 --- /dev/null +++ b/src/cli/uefiCommands.ts @@ -0,0 +1,156 @@ +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, + ); + }, + ); +}; diff --git a/src/composition/capabilityDeclarations.ts b/src/composition/capabilityDeclarations.ts index 94c23e702a..1a8c2462f9 100644 --- a/src/composition/capabilityDeclarations.ts +++ b/src/composition/capabilityDeclarations.ts @@ -1,4 +1,5 @@ // oxlint-disable max-lines -- Keep the exhaustive static provenance bindings together; this table has no execution or host-availability logic. +import { UEFI_PROVIDER_IDENTITY } from "../uefi/UefiProviderIdentity.js"; import type { ProviderIdentity } from "../ports/AnalysisProvider.js"; import type { TOOL_CONTRACTS, @@ -316,6 +317,11 @@ export const CAPABILITY_DECLARATIONS = { providerBinding(UNBLOB_PROVIDER_IDENTITY, ["extract_firmware"]), ], }, + uefiAnalysis: { + providers: [ + providerBinding(UEFI_PROVIDER_IDENTITY, { group: "UEFI_TOOL_CONTRACTS" }), + ], + }, flutter: { providers: [ providerBinding(FLUTTER_PROVIDER_IDENTITY, { diff --git a/src/composition/capabilityServices.ts b/src/composition/capabilityServices.ts index 9ec135d36c..23219d5385 100644 --- a/src/composition/capabilityServices.ts +++ b/src/composition/capabilityServices.ts @@ -1,3 +1,6 @@ +import { UefiAnalysisService } from "../application/uefi/UefiAnalysisService.js"; +import type { UefiAnalysisPort } from "../ports/uefi/UefiAnalysisPort.js"; +import { createUefiAnalysisProvider } from "./uefi.js"; import type { OptionalProviderLoadFailures } from "../ports/OptionalObservationProviders.js"; import { locateWiresharkTool, @@ -148,6 +151,7 @@ export interface CapabilityServiceOptions { readonly mavenGradleMetadata?: MavenGradleMetadataService; readonly electronFuses?: ElectronFuseService; readonly recordedCrash?: RecordedCrashService; + readonly uefiAnalysis?: UefiAnalysisPort; readonly firmwareAnalysis?: FirmwareAnalysisPort; readonly javascriptRecovery?: JavaScriptRecoveryPort; readonly webModuleTrace?: WebModuleTraceService; @@ -482,6 +486,12 @@ const modules = { }, }), ), + uefiAnalysis: service( + ({ options }) => + new UefiAnalysisService( + options.uefiAnalysis ?? createUefiAnalysisProvider(), + ), + ), gdbSessions: capability( ({ providerEnvironment, platform }) => createGdbSessionManager(providerEnvironment, { platform }), diff --git a/src/composition/uefi.ts b/src/composition/uefi.ts new file mode 100644 index 0000000000..49585e59d4 --- /dev/null +++ b/src/composition/uefi.ts @@ -0,0 +1,6 @@ +import type { UefiAnalysisPort } from "../ports/uefi/UefiAnalysisPort.js"; +import { UefiAnalysisProvider } from "../uefi/UefiAnalysisProvider.js"; + +/** Construct one UEFI provider; it needs no external tools. */ +export const createUefiAnalysisProvider = (): UefiAnalysisPort => + new UefiAnalysisProvider(); diff --git a/src/contracts/toolContracts.ts b/src/contracts/toolContracts.ts index 0b61a70dfb..6609854e13 100644 --- a/src/contracts/toolContracts.ts +++ b/src/contracts/toolContracts.ts @@ -1,3 +1,4 @@ +import { UEFI_TOOL_CONTRACTS } from "./uefi/uefiToolContracts.js"; import { ANALYSIS_SETTINGS_TOOL_CONTRACTS } from "./analysisSettingsContracts.js"; import { GPU_TOOL_CONTRACTS } from "./gpu/gpuToolContracts.js"; import { CAPTURE_TOOL_CONTRACTS } from "./captures/captureToolContracts.js"; @@ -89,6 +90,7 @@ const CATALOG_CONTRACT_GROUPS = { JEB_TOOL_CONTRACTS, ADB_TOOL_CONTRACTS, FIRMWARE_TOOL_CONTRACTS, + UEFI_TOOL_CONTRACTS, MANAGED_WORKFLOW_TOOL_CONTRACTS, BROWSER_PROVIDER_TOOL_CONTRACTS, ELECTRON_TOOL_CONTRACTS, diff --git a/src/contracts/toolFamilies.ts b/src/contracts/toolFamilies.ts index 007c49b47d..63ca172979 100644 --- a/src/contracts/toolFamilies.ts +++ b/src/contracts/toolFamilies.ts @@ -74,6 +74,11 @@ export const TOOL_FAMILY_DEFINITIONS = [ surface: "firmware-provider", contracts: TOOL_CONTRACT_GROUPS.FIRMWARE_TOOL_CONTRACTS, }, + { + id: "uefi", + surface: "firmware-provider", + contracts: TOOL_CONTRACT_GROUPS.UEFI_TOOL_CONTRACTS, + }, { id: "android", surface: "android-provider", diff --git a/src/contracts/toolFamilyIds.ts b/src/contracts/toolFamilyIds.ts index 4cc3aa7c53..fe4117bf07 100644 --- a/src/contracts/toolFamilyIds.ts +++ b/src/contracts/toolFamilyIds.ts @@ -12,6 +12,7 @@ export const TOOL_FAMILY_IDS = [ "artifact", "managed", "firmware", + "uefi", "android", "pcap", "flutter", diff --git a/src/contracts/uefi/uefiToolContracts.ts b/src/contracts/uefi/uefiToolContracts.ts new file mode 100644 index 0000000000..365749f3d8 --- /dev/null +++ b/src/contracts/uefi/uefiToolContracts.ts @@ -0,0 +1,84 @@ +import { + uefiInputSchemas, + uefiResultSchemas, +} from "../../domain/uefi/uefiFirmwareAnalysis.js"; +import type { ToolContract } from "../toolContractTypes.js"; +import { evidenceResultOf } from "../toolOutputSchemaPrimitives.js"; +import { + evidenceEffects, + toolEffects, + toolContractMetadata, +} from "../toolEffects.js"; + +/** Pure-TS UEFI firmware cartography and extraction with one owned LZMA lane. */ +export const UEFI_TOOL_CONTRACTS = [ + { + name: "inspect_uefi_firmware", + cli: true, + availability: "standalone", + ...toolContractMetadata( + "inspect_uefi_firmware", + toolEffects({ + mutatesSession: true, + launchesProcess: true, + writesFilesystem: true, + }), + ), + kind: "firmware-provider", + description: + "Map PI firmware volumes, FFS files, section chains, AMD PSP directory candidates and uncovered ranges in a local flash image. Report integrity observations and coverage limits. LZMA-custom, LZMAF86, and AMD-zlib streams can contain nested volumes or section chains. Decoded offsets are relative to the stream identified by source_stream. EFI standard compression and other unsupported handlers remain explicit limitations.", + inputSchema: uefiInputSchemas.inspect_uefi_firmware, + outputSchema: evidenceResultOf(uefiResultSchemas.inspect_uefi_firmware), + examples: [ + { + title: "Inspect firmware volumes", + input: { path: "/media/firmware/images/B550AORUSELITEV212.FIb" }, + }, + ], + }, + { + name: "extract_uefi_firmware", + cli: true, + availability: "standalone", + ...toolContractMetadata( + "extract_uefi_firmware", + toolEffects({ + mutatesSession: true, + launchesProcess: true, + writesFilesystem: true, + idempotent: false, + }), + ), + kind: "firmware-provider", + description: + "Extract FFS bodies and section payloads from a local UEFI image into an absent directory. A volume, file or section selection includes its descendants. Use source_stream with an offset from a decoded stream or when offsets are ambiguous. Results include SHA-256, source ranges and decode derivations; original_file_range is null for decoded bytes. Unsupported carriers are optional and decoding gaps remain visible. Pass an extracted PE32 file to open_binary for executable analysis.", + inputSchema: uefiInputSchemas.extract_uefi_firmware, + outputSchema: evidenceResultOf(uefiResultSchemas.extract_uefi_firmware), + examples: [ + { + title: "Extract firmware volumes", + input: { + path: "/media/firmware/images/B550AORUSELITEV212.FIb", + output_directory: "/tmp/uefi-output", + }, + }, + ], + }, + { + name: "inspect_uefi_nvram", + cli: true, + availability: "standalone", + ...toolContractMetadata("inspect_uefi_nvram", evidenceEffects), + kind: "firmware-provider", + description: + "Map valid AMI NVAR entries inside a local flash image, including nested factory defaults such as StdDefaults. Reports raw link displacements, attributes, inline GUIDs or GUID-table indices, data ranges and SHA-256 digests. Data-only records have no name or GUID reference. Links describe the image bytes. The parser walks physical records and reports the nesting depth and parent offset. No external tools or target execution are required.", + inputSchema: uefiInputSchemas.inspect_uefi_nvram, + outputSchema: evidenceResultOf(uefiResultSchemas.inspect_uefi_nvram), + examples: [ + { + title: "Inspect AMI NVRAM stores", + input: { path: "/media/firmware/images/B550AORUSELITEV212.FId" }, + }, + ], + }, +] as const satisfies readonly ToolContract[]; diff --git a/src/domain/analysisErrorBase.ts b/src/domain/analysisErrorBase.ts index 6547db55e3..fa7b48e44b 100644 --- a/src/domain/analysisErrorBase.ts +++ b/src/domain/analysisErrorBase.ts @@ -646,6 +646,7 @@ import type { ElectronPagePartialObservation, } from "./javascript/electronObservation.js"; import type { AndroidPartialObservation } from "./android/androidPartialObservation.js"; +import type { UefiPartialObservation } from "./uefi/uefiFirmwareAnalysis.js"; import type { FirmwarePartialObservation } from "./firmware/firmwareAnalysis.js"; import type { AdbActivityStartPartialObservation, @@ -740,6 +741,7 @@ export type AnalysisPartialObservation = | RecordedCrashPartialObservation | AndroidPartialObservation | FirmwarePartialObservation + | UefiPartialObservation | NativeUiObservationResult | InspectSignature | InspectMacho diff --git a/src/domain/artifactGraph.ts b/src/domain/artifactGraph.ts index e8f6fd366d..1dfdf5a806 100644 --- a/src/domain/artifactGraph.ts +++ b/src/domain/artifactGraph.ts @@ -75,6 +75,7 @@ export const ARTIFACT_FORMAT_IDS = [ "uimage", "android-boot-image", "android-ota-payload", + "uefi", "javascript-bundle", "source-map", "mach-o-universal", @@ -119,6 +120,7 @@ const artifactContentFormatSchema = artifactFormatSchema.extract([ "uimage", "android-boot-image", "android-ota-payload", + "uefi", "intel-hex", "srec", "esp-image", diff --git a/src/domain/targetFormats.ts b/src/domain/targetFormats.ts index c1cd07f59a..009c7e3d78 100644 --- a/src/domain/targetFormats.ts +++ b/src/domain/targetFormats.ts @@ -37,6 +37,7 @@ export const BINARY_TARGET_FORMAT_KINDS = { "ntfs-mft": "archive", plist: "artifact", javascript: "artifact", + uefi: "artifact", "source-map": "artifact", } as const; diff --git a/src/domain/uefi/uefiFirmwareAnalysis.ts b/src/domain/uefi/uefiFirmwareAnalysis.ts new file mode 100644 index 0000000000..f72a16c4eb --- /dev/null +++ b/src/domain/uefi/uefiFirmwareAnalysis.ts @@ -0,0 +1,542 @@ +import { knownCoverageStatusSchema } from "../coverage.js"; +import { z } from "zod"; +import { isAbsolute } from "node:path"; +import type { JsonValue } from "../jsonValue.js"; +import { digestSchema } from "../digests.js"; +import { localPathStringSchema } from "../localPath.js"; +import { UEFI_FIRMWARE_LIMITS } from "./uefiLimits.js"; + +const bytes = z.number().int().min(0).max(Number.MAX_SAFE_INTEGER); +const range = z.strictObject({ offset: bytes, length: bytes.positive() }); +const target = { + path: localPathStringSchema + .refine(isAbsolute, { + message: + "path must be an absolute local firmware image path (for example /tmp/firmware.bin)", + }) + .describe( + "Absolute local UEFI firmware image; never executed. Relative paths are rejected.", + ), +}; + +/** Canonical display form of a UEFI GUID or the raw parse failure kind. */ +export const guidSchema = z + .string() + .regex(/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/u); + +/** FFS file type names; the numeric code is retained alongside every name. */ +export const ffsTypeNameSchema = z.enum([ + "raw", + "freeform", + "security-core", + "pei-core", + "dxe-core", + "peim", + "driver", + "combined-peim-driver", + "application", + "smm", + "firmware-volume-image", + "combined-smm-dxe", + "smm-core", + "mm-standalone", + "mm-core-standalone", + "pad", + "unknown", +]); +/** FFS file state observations after erase-polarity normalization. */ +export const ffsStateFlagSchema = z.enum([ + "header-construction", + "header-valid", + "data-valid", + "marked-for-update", + "deleted", + "header-invalid", +]); +/** Declared FFS integrity observations; mismatches are observations, not verdicts. */ +export const ffsChecksumVerdictSchema = z.enum([ + "valid", + "invalid", + "pad-file-unchecked", + "unchecked", +]); +/** FFS file types that carry sections in FFS2 layout. */ +export const sectionedFfsTypeNameSchema = ffsTypeNameSchema.exclude([ + "raw", + "freeform", +]); +const alignmentSchema = z.enum([ + "1", + "16", + "128", + "512", + "1024", + "4096", + "32768", + "65536", + "131072", + "262144", + "524288", + "1048576", + "2097152", + "4194304", + "8388608", + "16777216", +]); + +/** Section type names retained alongside their numeric codes. */ +export const uefiSectionTypeNameSchema = z.enum([ + "compression", + "guid-defined", + "disposable", + "pe32", + "pic", + "te", + "dxe-depex", + "version", + "user-interface", + "compatibility16", + "firmware-volume-image", + "freeform-subtype-guid", + "raw", + "pei-depex", + "mm-depex", + "unknown", +]); +/** + * Compression classification for guided or uncompressed sections; kinds that + * cannot be decoded are reported as gaps, never silently skipped. + */ +export const uefiCompressionSchema = z.union([ + z.strictObject({ kind: z.literal("none") }), + z.strictObject({ + kind: z.enum([ + "lzma-custom", + "lzmaf86", + "ami-zlib", + "tiano", + "efi-standard", + "unknown-compression", + "crc32-guided", + "unknown-guid", + ]), + guid: guidSchema.nullable(), + data_offset: bytes, + attributes: bytes.nullable(), + }), +]); + +/** null denotes the original image. A decoded stream is identified by its carrier. */ +const sourceStream = z.string().nullable(); + +/** One flat FFS section record; sub volumes stay linked by logical path. */ +export const uefiSectionRecordSchema = z.strictObject({ + logical_path: z.string(), + parent_logical_path: z.string(), + source_stream: sourceStream, + declared_length: bytes, + truncated: z.boolean(), + malformed: z.boolean(), + offset: bytes, + header_length: bytes, + length: bytes, + type_code: bytes, + type_name: uefiSectionTypeNameSchema, + sha256: digestSchema, + compression: uefiCompressionSchema, + sub_volumes: z.array(z.string()), +}); +/** One flat FFS file record inside its owning volume. */ +export const uefiFfsFileRecordSchema = z.strictObject({ + source_stream: sourceStream, + declared_length: bytes, + offset: bytes, + header_length: bytes, + length: bytes, + guid: guidSchema, + type_code: bytes, + type_name: ffsTypeNameSchema, + attributes: bytes, + alignment: alignmentSchema, + state: bytes, + state_flags: z.array(ffsStateFlagSchema), + checksum: ffsChecksumVerdictSchema, + ui_string: z.string().nullable(), + logical_path: z.string(), + volume_offset: bytes, + sha256: digestSchema, + sections: z.array(uefiSectionRecordSchema), +}); + +/** 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"), + }), + extract_uefi_firmware: z.strictObject({ + ...target, + output_directory: localPathStringSchema + .refine(isAbsolute, { + message: "output_directory must be an absolute local filesystem path", + }) + .describe("Absolute, absent output directory; parent must exist"), + target: z + .discriminatedUnion("kind", [ + z.strictObject({ kind: z.literal("whole-image") }), + z.strictObject({ + kind: z.literal("volume"), + offset: bytes, + source_stream: sourceStream.optional(), + }), + z.strictObject({ + kind: z.literal("ffs-file"), + offset: bytes, + source_stream: sourceStream.optional(), + }), + z.strictObject({ + kind: z.literal("section"), + offset: bytes, + source_stream: sourceStream.optional(), + }), + ]) + .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", + ), + max_output_bytes: z + .number() + .int() + .min(1) + .max(UEFI_FIRMWARE_LIMITS.maxOutputBytes) + .default(UEFI_FIRMWARE_LIMITS.defaultMaxOutputBytes) + .describe("Maximum total bytes of published files"), + max_output_files: z + .number() + .int() + .min(1) + .max(UEFI_FIRMWARE_LIMITS.maxOutputFiles) + .default(UEFI_FIRMWARE_LIMITS.defaultMaxOutputFiles) + .describe("Maximum number of published files"), + include_compressed: z + .boolean() + .default(true) + .describe( + "Publish recognized-but-undecodable compressed payloads as raw blobs; decoding gaps stay explicit", + ), + }), + inspect_uefi_nvram: z.strictObject({ + ...target, + max_stores: z + .number() + .int() + .min(1) + .max(1024) + .default(64) + .describe( + "Maximum AMI NVRAM variable stores reported before coverage turns partial", + ), + max_depth: z + .number() + .int() + .min(1) + .max(4) + .default(2) + .describe( + "Nesting depth for NVAR chains embedded in variable data (StdDefaults holds one nested chain)", + ), + }), +} as const; + +/** Supported UEFI firmware operations. */ +export type UefiOperation = keyof typeof uefiInputSchemas; +/** Correlated, validated UEFI firmware request. */ +export type UefiRequest = { + [Name in UefiOperation]: { + operation: Name; + input: z.infer<(typeof uefiInputSchemas)[Name]>; + }; +}[UefiOperation]; +/** Validate the operation with its exact input contract. */ +export const uefiRequestSchema = z.discriminatedUnion("operation", [ + z.strictObject({ + operation: z.literal("inspect_uefi_firmware"), + input: uefiInputSchemas.inspect_uefi_firmware, + }), + z.strictObject({ + operation: z.literal("extract_uefi_firmware"), + input: uefiInputSchemas.extract_uefi_firmware, + }), + z.strictObject({ + operation: z.literal("inspect_uefi_nvram"), + input: uefiInputSchemas.inspect_uefi_nvram, + }), +]); + +const parserSchema = z.strictObject({ + name: z.literal("rea-uefi"), + version: z.string(), +}); + +/** Completed UEFI result retained when cleanup cannot be confirmed. */ +export interface UefiPartialObservation { + readonly kind: "uefi"; + readonly result: JsonValue; + /** Completed producer data, artifact identity and analysis metadata. */ + readonly provenance?: JsonValue; +} + +/** How the flash image entry point was established for cartography. */ +const entryBasisSchema = z.enum([ + "fv-at-zero", + "amd-psp-first", + "scanned", + "unknown", +]); + +/** One mapped firmware volume with its flat FFS file records. */ +export const uefiVolumeRecordSchema = z.strictObject({ + source_stream: sourceStream, + parent_logical_path: z.string().nullable(), + logical_path: z.string(), + offset: bytes, + length: z.number().int().positive(), + declared_length: bytes, + depth: z.number().int().min(0), + parent_offset: bytes.nullable(), + sha256: digestSchema, + file_system_guid: guidSchema.nullable(), + signature: z.literal("_FVH"), + header_length: bytes, + attributes: bytes, + revision: z.number().int().min(0).max(255), + ext_header_offset: bytes.nullable(), + block_map: z.array(z.strictObject({ num_blocks: bytes, length: bytes })), + ffs_files: z.array(uefiFfsFileRecordSchema), +}); +/** One undecoded image region; classification stays an observation. */ +export const uefiUnknownRegionSchema = z.strictObject({ + source_stream: sourceStream, + offset: bytes, + length: z.number().int().positive(), + sha256: digestSchema.nullable(), + classification: z.enum([ + "no-fv-magic", + "unsupported-file-system", + "erased-ff", + "erased-00", + "sparse", + "unparsed-table", + "truncated", + ]), + erasure: z.enum(["0xff", "0x00", "none"]), +}); +/** One integrity observation; mismatches are recorded, never smoothed away. */ +export const uefiIntegrityRecordSchema = z.strictObject({ + kind: z.enum([ + "fv-checksum-mismatch", + "ffs-header-checksum-mismatch", + "ffs-file-checksum-mismatch", + "size-truncation", + "block-map-truncation", + "guid-parse-failure", + "declared-length-overflow", + ]), + logical_path: z.string(), + source_stream: sourceStream, + range, + detail: z.string(), +}); + +/** One AMI NVRAM variable entry; data bytes are referenced, never interpreted. */ +export const uefiNvramVariableRecordSchema = z.strictObject({ + offset: bytes, + name: z.string().nullable(), + attributes: z.number().int().min(0).max(0xff), + next: z + .number() + .int() + .min(0) + .max(0xffffff) + .describe( + "Raw record-relative link displacement. 0xffffff marks the end of the link chain.", + ), + guid_index: z.number().int().min(0).max(0xff).nullable(), + guid: guidSchema.nullable(), + depth: z.number().int().min(0), + parent_offset: bytes.nullable(), + data_offset: bytes, + data_length: bytes, + data_sha256: digestSchema, +}); +/** One top-level AMI NVRAM chain with its flattened nested variables. */ +export const uefiNvramStoreRecordSchema = z.strictObject({ + offset: bytes, + name: z.string().nullable(), + variables: z.array(uefiNvramVariableRecordSchema), + trailing_padding: bytes.nullable(), +}); + +/** Portable results retain observed boundaries, unknowns and integrity notes. */ +export const uefiResultSchemas = { + inspect_uefi_firmware: z.strictObject({ + parser: parserSchema, + input_size: bytes, + flash_image: z.strictObject({ + sha256: digestSchema, + size: bytes, + entry_basis: entryBasisSchema, + }), + firmware_volumes: z.array(uefiVolumeRecordSchema), + psp_tables: z.array( + z.strictObject({ + offset: bytes, + length: bytes, + table_magic: z.enum(["$PSP", "$PL2", "unknown"]), + total_entries: bytes.nullable(), + entries: z.array( + z.strictObject({ + type: bytes.nullable(), + declared_location: bytes.nullable(), + declared_location_raw: z.string(), + address_mode: z.number().int().min(0).max(3), + declared_size: bytes.nullable(), + image_offset: bytes.nullable(), + sha256: digestSchema.nullable(), + location_basis: z.literal("declared-unverified"), + }), + ), + entry_stride_basis: z.enum(["header-declared", "psp-16", "unknown"]), + }), + ), + psp_candidates: z.array( + z.strictObject({ + offset: bytes, + magic: z.string(), + reason: z.string(), + }), + ), + unknown_regions: z.array(uefiUnknownRegionSchema), + integrity: z.array(uefiIntegrityRecordSchema), + coverage: knownCoverageStatusSchema, + limitations: z.array(z.string()), + }), + extract_uefi_firmware: z.strictObject({ + parser: parserSchema, + selection: z.strictObject({ + offset: bytes, + length: bytes, + source_stream: sourceStream, + target_kind: z.enum(["whole-image", "volume", "ffs-file", "section"]), + }), + output_directory: z.string(), + coverage: knownCoverageStatusSchema, + files: z.array( + z.strictObject({ + relative_path: z.string(), + path: z.string(), + size: bytes, + sha256: digestSchema, + original_file_range: range.nullable(), + source_stream: sourceStream, + source_range: range, + runtime_address: z.null(), + media_type: z.string().nullable(), + source: z.enum([ + "raw-section", + "decompressed-lzma", + "decompressed-lzmaf86", + "decompressed-zlib", + "uncompressed-payload", + "compressed-passthrough", + ]), + parent_logical_path: z.string().nullable(), + }), + ), + derivations: z.array( + z.strictObject({ + parent_path: z.string(), + child_path: z.string().nullable(), + child_stream: z.string(), + parent_file_range: range.nullable(), + parent_stream: sourceStream, + parent_stream_range: range, + handler: z.string(), + }), + ), + extraction_gaps: z.array( + z.strictObject({ + kind: z.enum([ + "unsupported-compression", + "unknown-guid-handler", + "depth-limited", + "unparsed-region", + "size-truncated", + "pad-file", + ]), + logical_path: z.string(), + source_stream: sourceStream, + range: range.nullable(), + detail: z.string(), + }), + ), + diagnostics: z.string(), + published_bytes: bytes, + }), + inspect_uefi_nvram: z.strictObject({ + parser: parserSchema, + input_size: bytes, + image_sha256: digestSchema, + stores: z.array(uefiNvramStoreRecordSchema), + coverage: knownCoverageStatusSchema, + limitations: z.array(z.string()), + }), +} as const; + +/** Inferred record and result types shared by the engine, provider and contracts. */ +export type UefiVolumeRecord = z.infer; +export type UefiFfsFileRecord = z.infer; +export type UefiSectionRecord = z.infer; +export type UefiUnknownRegion = z.infer; +export type UefiIntegrityRecord = z.infer; +export type UefiInspectResult = z.infer< + (typeof uefiResultSchemas)["inspect_uefi_firmware"] +>; +export type UefiExtractResult = z.infer< + (typeof uefiResultSchemas)["extract_uefi_firmware"] +>; +export type UefiNvramVariableRecord = z.infer< + typeof uefiNvramVariableRecordSchema +>; +export type UefiNvramStoreRecord = z.infer; +export type UefiNvramInspectResult = z.infer< + (typeof uefiResultSchemas)["inspect_uefi_nvram"] +>; diff --git a/src/domain/uefi/uefiLimits.ts b/src/domain/uefi/uefiLimits.ts new file mode 100644 index 0000000000..f93e90cd63 --- /dev/null +++ b/src/domain/uefi/uefiLimits.ts @@ -0,0 +1,31 @@ +/** Budgets for the pure TypeScript UEFI firmware parser; every bound is explicit. */ +export const UEFI_FIRMWARE_LIMITS = { + /** Largest accepted firmware image; Gigabyte AMI images are 16 MiB. */ + inputBytes: 128 * 1024 * 1024, + /** Prefix bytes inspected for signature-based format admission. */ + scanProbeBytes: 1024 * 1024, + /** Maximum firmware volumes mapped before coverage turns partial. */ + maxVolumes: 1024, + defaultMaxVolumes: 512, + /** Maximum FFS files mapped before coverage turns partial. */ + maxFiles: 100_000, + defaultMaxFiles: 20_000, + /** Maximum nested section and sub-volume depth, clamped by caller input. */ + maxDepth: 5, + defaultMaxDepth: 3, + /** Maximum total bytes of staged extraction files. */ + maxOutputBytes: 256 * 1024 * 1024, + defaultMaxOutputBytes: 256 * 1024 * 1024, + maxOutputFiles: 10_000, + defaultMaxOutputFiles: 10_000, + /** Whole-operation deadline for parser and worker runs. */ + timeoutMs: 60_000, + /** Per-stream decompressed output ceiling for both decoders. */ + lzmaOutputBytes: 64 * 1024 * 1024, + /** Shared structural record ceiling per inspection or extraction. */ + scanRecords: 100_000, + /** Limit retained and traversed decoded data across all streams in an operation. */ + decodedBytes: 128 * 1024 * 1024, + /** Diagnostic text retained inline before truncation. */ + diagnosticBytes: 8 * 1024 * 1024, +} as const; diff --git a/src/ports/uefi/UefiAnalysisPort.ts b/src/ports/uefi/UefiAnalysisPort.ts new file mode 100644 index 0000000000..6730752dbc --- /dev/null +++ b/src/ports/uefi/UefiAnalysisPort.ts @@ -0,0 +1,24 @@ +import type { + AnalysisExecution, + ExecutionOptions, + ProviderAvailability, +} from "../AnalysisProvider.js"; +import type { UefiRequest } from "../../domain/uefi/uefiFirmwareAnalysis.js"; +import type { AnalysisError } from "../../domain/analysisErrorBase.js"; +import type { Result } from "../../domain/result.js"; + +/** + * Pure UEFI firmware analysis boundary: static flash-image mapping and + * budgeted extraction with one owned LZMA worker lane. + * Implementation details belong to the provider adapter. + */ +export interface UefiAnalysisPort { + /** Pure parsing; the provider is effectively always available. */ + inspectAvailability(signal?: AbortSignal): Promise; + /** The provider holds only short-lived per-request workers; safe to call always. */ + close(): Promise; + execute( + request: UefiRequest, + options?: ExecutionOptions, + ): Promise>; +} diff --git a/src/resources/ArtifactReader.ts b/src/resources/ArtifactReader.ts index 233dadc3be..348788ac4d 100644 --- a/src/resources/ArtifactReader.ts +++ b/src/resources/ArtifactReader.ts @@ -238,6 +238,7 @@ export interface ArtifactReader { | "uimage" | "android-boot-image" | "android-ota-payload" + | "uefi" | "pyinstaller" | "dotnet-bundle" | "bun-standalone" diff --git a/src/server/createServer.ts b/src/server/createServer.ts index 42096029bd..0f8bab3954 100644 --- a/src/server/createServer.ts +++ b/src/server/createServer.ts @@ -213,6 +213,7 @@ export const createServer = ( javascriptRecovery, artifactResources, reverseEngineering, + uefiAnalysis, firmwareAnalysis, gdbSessions, rizinDebugSessions, @@ -485,6 +486,7 @@ export const createServer = ( }, firmware: () => registerServiceTools(server, { firmwareAnalysis }, contractTools), + uefi: () => registerServiceTools(server, { uefiAnalysis }, contractTools), android: () => registerServiceTools( server, diff --git a/src/server/serviceToolBindings.ts b/src/server/serviceToolBindings.ts index 1babc82d70..cc6d988b82 100644 --- a/src/server/serviceToolBindings.ts +++ b/src/server/serviceToolBindings.ts @@ -1,3 +1,4 @@ +import type { UefiAnalysisService } from "../application/uefi/UefiAnalysisService.js"; import type { MavenGradleMetadataService } from "../application/java/MavenGradleMetadataService.js"; import type { NugetNupkgService } from "../application/nuget/NugetNupkgService.js"; @@ -701,6 +702,12 @@ const SERVICE_TOOL_BINDINGS = { "inspect_firmware_regions", "extract_firmware", ])) satisfies Bind, + uefiAnalysis: ((service) => + contractServiceBindings(service, [ + "inspect_uefi_firmware", + "extract_uefi_firmware", + "inspect_uefi_nvram", + ])) satisfies Bind, pcapAnalysis: ((service) => ({ ...contractServiceBindings(service, ["inspect_pcap_client"]), inspect_pcap_capture: { diff --git a/src/uefi/FfsFile.test.ts b/src/uefi/FfsFile.test.ts new file mode 100644 index 0000000000..7b422b9bf4 --- /dev/null +++ b/src/uefi/FfsFile.test.ts @@ -0,0 +1,110 @@ +import { Buffer } from "node:buffer"; +import { expect, it } from "vitest"; + +import { buildFfsFile } from "../../tests/fixtures/uefiImage.js"; +import { imageRegion } from "./UefiBytes.js"; +import { + readFfsHeader, + parseFfsFileHeader, + checkFfsFileData, +} from "./FfsFile.js"; + +it("parses a valid FFS2 driver file header", () => { + const file = buildFfsFile({ + guid: "17111111-2222-3333-4444-555555555555", + typeCode: 0x07, + payload: Buffer.from("payload-bytes"), + }); + const region = imageRegion(file, 0, file.length); + const header = parseFfsFileHeader(region, 0, true); + expect(header).not.toBeNull(); + expect(header?.nameGuid).toBe("17111111-2222-3333-4444-555555555555"); + expect(header?.typeCode).toBe(0x07); + expect(header?.headerLength).toBe(24); + expect(header?.declaredLength).toBe(24 + 13); + expect(header?.headerChecksumValid).toBe(true); + expect(header?.fileChecksumRequired).toBe(false); + expect(header?.rawState).toBe(0x38); + expect(header?.stateFlags).toEqual([ + "header-construction", + "header-valid", + "data-valid", + ]); +}); + +it("flags a deliberately broken header checksum", () => { + const file = buildFfsFile({ + guid: "18111111-2222-3333-4444-555555555555", + typeCode: 0x07, + payload: Buffer.from("x"), + breakHeaderChecksum: true, + }); + const region = imageRegion(file, 0, file.length); + expect(parseFfsFileHeader(region, 0, true)?.headerChecksumValid).toBe(false); +}); + +it("normalizes state bits under both erase polarities", () => { + const file = buildFfsFile({ + guid: "19111111-2222-3333-4444-555555555555", + typeCode: 0x07, + payload: Buffer.from("y"), + erasePolarity: false, + }); + const region = imageRegion(file, 0, file.length); + const header = parseFfsFileHeader(region, 0, false); + expect(header?.rawState).toBe(0x07); + expect(header?.stateFlags).toContain("data-valid"); +}); + +it("verifies the optional file-data checksum", () => { + const payload = Buffer.from("checksummed payload"); + const correct = buildFfsFile({ + guid: "1a111111-2222-3333-4444-555555555555", + typeCode: 0x07, + payload, + fileChecksum: "correct", + }); + const wrong = buildFfsFile({ + guid: "1b111111-2222-3333-4444-555555555555", + typeCode: 0x07, + payload, + fileChecksum: "wrong", + }); + for (const image of [correct, wrong]) { + const region = imageRegion(image, 0, image.length); + const header = parseFfsFileHeader(region, 0, true); + expect(header?.fileChecksumRequired).toBe(true); + if (header === null) throw new Error("Missing FFS header"); + expect(checkFfsFileData(region, header).verdict).toBe( + image === correct ? "valid" : "invalid", + ); + } +}); + +it.each([ + [0, 1], + [1, 16], + [2, 128], + [7, 65536], +])("decodes PI alignment index %i as %i bytes", (index, alignment) => { + const image = buildFfsFile({ + guid: "19111111-2222-3333-4444-555555555555", + typeCode: 0x01, + payload: Buffer.from("body"), + alignmentExponent: index, + }); + expect( + parseFfsFileHeader(imageRegion(image, 0, image.length), 0, true) + ?.dataAlignment, + ).toBe(alignment); +}); + +it("recognizes erased header windows per polarity", () => { + const eraseRegion = imageRegion(Buffer.alloc(64, 0xff), 0, 64); + expect(readFfsHeader(eraseRegion, 0, true)).toEqual({ kind: "end" }); + expect(readFfsHeader(eraseRegion, 0, false)).toMatchObject({ + kind: "unparsed", + }); + const zeroRegion = imageRegion(Buffer.alloc(64, 0x00), 0, 64); + expect(readFfsHeader(zeroRegion, 0, false)).toEqual({ kind: "end" }); +}); diff --git a/src/uefi/FfsFile.ts b/src/uefi/FfsFile.ts new file mode 100644 index 0000000000..f39ea7294a --- /dev/null +++ b/src/uefi/FfsFile.ts @@ -0,0 +1,258 @@ +import { BinaryReader } from "../domain/binaryContainer.js"; +import { Buffer } from "node:buffer"; +import { + absoluteOffset, + alignUp, + isWindowUniform, + type ScanRegion, +} from "./UefiBytes.js"; +import { formatGuidLittleEndian } from "./UefiGuid.js"; +import { FFS_ATTRIBUTE_MASKS, FFS_HEADER_LAYOUT } from "./UefiCodeTables.js"; + +const FFS_DATA_ALIGNMENT_EXPONENTS = [0, 4, 7, 9, 10, 12, 15, 16] as const; + +const STATE_BIT_NAMES: readonly (readonly [number, string])[] = [ + [0x01, "header-construction"], + [0x02, "header-valid"], + [0x04, "data-valid"], + [0x08, "marked-for-update"], + [0x10, "deleted"], + [0x20, "header-invalid"], +]; + +/** Normalized FFS file header observation before section walking. */ +export interface FfsFileHeader { + readonly absoluteBase: number; + readonly localBase: number; + readonly headerLength: number; + readonly declaredLength: number; + readonly observedLength: number; + readonly body: { readonly start: number; readonly end: number } | null; + readonly extentIssue: + | "unusable-header-state" + | "declared-length-below-header" + | "declared-length-truncates-region" + | null; + readonly nameGuid: string | null; + readonly typeCode: number; + readonly attributes: number; + readonly dataAlignment: number; + readonly rawState: number; + readonly stateFlags: readonly string[]; + readonly headerChecksumField: number; + readonly fileChecksumField: number; + readonly fileChecksumRequired: boolean; + readonly headerChecksumValid: boolean; + readonly implausibilities: readonly string[]; +} + +/** + * Parse one FFS header at a local position; null when the position cannot + * hold the minimum header. Checksum findings are observations on the header, + * not rejections — invalid files stay in the inventory with their notes. + */ +export function parseFfsFileHeader( + region: ScanRegion, + localBase: number, + erasePolarity: boolean, +): FfsFileHeader | null { + if ( + localBase < region.start || + localBase + FFS_HEADER_LAYOUT.length > region.end + ) { + return null; + } + const available = region.end - localBase; + const extended = available >= FFS_HEADER_LAYOUT.extendedLength; + const attributes = + region.buffer[localBase + FFS_HEADER_LAYOUT.attributesOffset] ?? 0; + const sizeB0 = region.buffer[localBase + FFS_HEADER_LAYOUT.sizeOffset] ?? 0; + const sizeB1 = + region.buffer[localBase + FFS_HEADER_LAYOUT.sizeOffset + 1] ?? 0; + const sizeB2 = + region.buffer[localBase + FFS_HEADER_LAYOUT.sizeOffset + 2] ?? 0; + const declaredCompact = sizeB0 | (sizeB1 << 8) | (sizeB2 << 16); + const largeFile = (attributes & FFS_ATTRIBUTE_MASKS.largeFile) !== 0; + const implausibilities: string[] = []; + + let headerLength: number = FFS_HEADER_LAYOUT.length; + let declaredLength = declaredCompact; + if (largeFile) { + const reader = new BinaryReader(region.buffer, true, "FFS file"); + if (!extended) return null; + headerLength = FFS_HEADER_LAYOUT.extendedLength; + const size = reader.word( + localBase + FFS_HEADER_LAYOUT.extendedSizeOffset, + 64, + ); + if (size > BigInt(Number.MAX_SAFE_INTEGER)) return null; + declaredLength = Number(size); + if (declaredCompact !== 0) + implausibilities.push("large-file-compact-size-is-nonzero"); + } + const rawState = + region.buffer[localBase + FFS_HEADER_LAYOUT.stateOffset] ?? 0; + const normalizedState = erasePolarity ? ~rawState & 0x3f : rawState & 0x3f; + const stateFlags = STATE_BIT_NAMES.filter( + ([bit]) => (normalizedState & bit) !== 0, + ).map(([, name]) => name); + // PI state is the highest set bit. An incomplete or invalid header supplies + // only its fixed extent; the stored size cannot consume the next file. + const state = stateFlags.at(-1); + const unusableState = + state === "header-construction" || state === "header-invalid"; + const extentIssue = unusableState + ? "unusable-header-state" + : declaredLength < headerLength + ? "declared-length-below-header" + : declaredLength > available + ? "declared-length-truncates-region" + : null; + if (extentIssue !== null) implausibilities.push(extentIssue); + const observedLength = unusableState + ? headerLength + : Math.min(Math.max(declaredLength, headerLength), available); + + const headerChecksumField = + region.buffer[localBase + FFS_HEADER_LAYOUT.integrityCheckOffset] ?? 0; + const fileChecksumField = + region.buffer[localBase + FFS_HEADER_LAYOUT.integrityCheckOffset + 1] ?? 0; + const fileChecksumRequired = + (attributes & FFS_ATTRIBUTE_MASKS.checksumValid) !== 0; + const headerChecksumValid = verifyFfsHeaderChecksum( + region.buffer, + localBase, + headerLength, + ); + + return { + absoluteBase: absoluteOffset(region, localBase), + localBase, + headerLength, + declaredLength, + observedLength, + body: + extentIssue === null || extentIssue === "declared-length-truncates-region" + ? { start: localBase + headerLength, end: localBase + observedLength } + : null, + extentIssue, + nameGuid: formatGuidLittleEndian( + region.buffer.subarray(localBase, localBase + 16), + 0, + ), + typeCode: region.buffer[localBase + FFS_HEADER_LAYOUT.typeOffset] ?? 0, + attributes, + dataAlignment: + 2 ** + ((attributes & FFS_ATTRIBUTE_MASKS.dataAlignment2) !== 0 + ? 17 + ((attributes & FFS_ATTRIBUTE_MASKS.dataAlignment) >> 3) + : (FFS_DATA_ALIGNMENT_EXPONENTS[ + (attributes & FFS_ATTRIBUTE_MASKS.dataAlignment) >> 3 + ] ?? 0)), + rawState, + stateFlags, + headerChecksumField, + fileChecksumField, + fileChecksumRequired, + headerChecksumValid, + implausibilities, + }; +} + +/** + * Header checksum: sum of all header bytes with the State byte and the + * IntegrityCheck.File byte set to zero must reach zero (mod 256). + */ +function verifyFfsHeaderChecksum( + buffer: Buffer, + localBase: number, + headerLength: number, +): boolean { + let total = 0; + for (let offset = 0; offset < headerLength; offset += 1) { + let byte = buffer[localBase + offset] ?? 0; + if ( + offset === FFS_HEADER_LAYOUT.stateOffset || + offset === FFS_HEADER_LAYOUT.integrityCheckOffset + 1 + ) { + byte = 0; + } + total = (total + byte) & 0xff; + } + return total === 0; +} + +/** Check the declared checksum only when the full file body is available. */ +export function checkFfsFileData(region: ScanRegion, header: FfsFileHeader) { + if (header.typeCode === 0xf0) + return { verdict: "pad-file-unchecked" } as const; + if ( + header.extentIssue !== null || + !header.fileChecksumRequired || + header.body === null + ) + return { verdict: "unchecked" } as const; + const { start, end } = header.body; + const length = end - start; + if (length === 0) return { verdict: "unchecked" } as const; + let total = header.fileChecksumField; + for (const byte of region.buffer.subarray(start, end)) { + total = (total + byte) & 0xff; + } + return total === 0 + ? ({ verdict: "valid" } as const) + : ({ + verdict: "invalid", + offset: absoluteOffset(region, start), + length, + } as const); +} + +/** Advance to the next 8-aligned FFS position after the observed extent. */ +export function nextFfsFileLocal( + header: FfsFileHeader, + volumeBase: number, +): number { + return ( + volumeBase + + alignUp(header.localBase + header.observedLength - volumeBase, 8) + ); +} + +type FfsHeaderRead = + | { readonly kind: "end" } + | { readonly kind: "limited" } + | { + readonly kind: "unparsed"; + readonly offset: number; + readonly length: number; + } + | { readonly kind: "file"; readonly header: FfsFileHeader }; + +/** Distinguish an erased tail from bytes the FFS walk cannot interpret. */ +export function readFfsHeader( + region: ScanRegion, + local: number, + erasePolarity: boolean, + reserve: () => boolean = () => true, +): FfsHeaderRead { + if (local >= region.end) return { kind: "end" }; + const erase = erasePolarity ? 0xff : 0; + const prefixEnd = Math.min(local + FFS_HEADER_LAYOUT.length, region.end); + if (isWindowUniform(region.buffer, local, prefixEnd, erase)) { + if ( + prefixEnd === region.end || + isWindowUniform(region.buffer, prefixEnd, region.end, erase) + ) + return { kind: "end" }; + } else { + if (!reserve()) return { kind: "limited" }; + const header = parseFfsFileHeader(region, local, erasePolarity); + if (header !== null) return { kind: "file", header }; + } + return { + kind: "unparsed", + offset: absoluteOffset(region, local), + length: region.end - local, + }; +} diff --git a/src/uefi/FfsSections.test.ts b/src/uefi/FfsSections.test.ts new file mode 100644 index 0000000000..8ee54bdaab --- /dev/null +++ b/src/uefi/FfsSections.test.ts @@ -0,0 +1,146 @@ +import { Buffer } from "node:buffer"; +import { expect, it } from "vitest"; + +import { + buildSection, + buildGuidedSection, + buildLzmaGuidedSection, +} from "../../tests/fixtures/uefiImage.js"; +import { imageRegion } from "./UefiBytes.js"; +import { + AMD_ZLIB_HEADER_LENGTH, + peelAmiZlibPayload, + walkSections, +} from "./FfsSections.js"; + +it("walks a two-section chain with clean payload windows", () => { + const ui = buildSection(0x15, Buffer.from("Module")); + const pe = buildSection(0x10, Buffer.from([0x4d, 0x5a, 0x90])); + const chain = Buffer.concat([ui, pe]); + const region = imageRegion(chain, 0, chain.length); + const walked = walkSections(region); + expect(walked.remainder).toBeNull(); + expect(walked.sections).toHaveLength(2); + const [uiDraft, peDraft] = walked.sections; + expect(uiDraft?.typeCode).toBe(0x15); + expect(uiDraft?.headerLength).toBe(4); + expect(uiDraft?.payload).toEqual({ start: 4, end: 4 + 6 }); + // The PE section starts after the first section's 4-byte chain alignment. + expect(peDraft?.payload).toEqual({ start: 16, end: 19 }); + expect(peDraft?.typeCode).toBe(0x10); +}); + +it("classifies a guided LZMA section through its definition GUID", () => { + const compressed = Buffer.from([ + 0x5d, 0x00, 0x00, 0x08, 0x00, 0x01, 0x02, 0x03, + ]); + const section = buildLzmaGuidedSection(compressed); + const region = imageRegion(section, 0, section.length); + const walked = walkSections(region); + const draft = walked.sections[0]; + expect(draft?.compression).toMatchObject({ + kind: "lzma-custom", + guid: "ee4e5898-3914-4259-9d6e-dc7bd79403cf", + dataOffset: 24, + attributes: 0, + }); + expect(draft?.payload).toEqual({ start: 24, end: 24 + compressed.length }); +}); + +it("classifies the AMI-zlib guided section and peels its AMD header", () => { + const stream = Buffer.from([0x78, 0xda, 0x01, 0x02, 0x03]); + const amdHeader = Buffer.alloc(AMD_ZLIB_HEADER_LENGTH, 0); + amdHeader.writeUInt32LE(stream.length, 0x14); + const section = buildGuidedSection({ + definitionGuid: "ce3233f5-2cd6-4d87-9152-4a238bb6d1c4", + body: Buffer.concat([amdHeader, stream]), + }); + const region = imageRegion(section, 0, section.length); + const walked = walkSections(region); + expect(walked.sections).toHaveLength(1); + const draft = walked.sections[0]; + expect(draft?.compression).toMatchObject({ + kind: "ami-zlib", + guid: "ce3233f5-2cd6-4d87-9152-4a238bb6d1c4", + dataOffset: 24, + attributes: 0, + }); + expect(draft?.payload).toEqual({ + start: 24, + end: 24 + AMD_ZLIB_HEADER_LENGTH + stream.length, + }); + const peeled = peelAmiZlibPayload(Buffer.concat([amdHeader, stream])); + expect(peeled).toEqual({ stream, declaredCompressedSize: stream.length }); + expect(peelAmiZlibPayload(Buffer.alloc(0x40, 0))).toBeNull(); +}); + +it("marks unknown definition GUIDs instead of guessing", () => { + const raw = Buffer.alloc(12, 0xab); + const section = buildGuidedSection({ + definitionGuid: "99999999-8888-7777-6666-555555555555", + body: raw, + }); + const region = imageRegion(section, 0, section.length); + const draft = walkSections(region).sections[0]; + if (draft?.compression.kind !== "unknown-guid") { + throw new Error( + `expected unknown-guid, got ${draft?.compression.kind ?? "none"}`, + ); + } + expect(draft.compression.attributes).toBe(0); + expect(draft?.payload).toEqual({ start: 24, end: 24 + 12 }); +}); + +it("records a truncated final section instead of inventing one", () => { + const ui = buildSection(0x15, Buffer.from("Module")); + const truncatedBody = Buffer.alloc(10, 0x77); + truncatedBody.writeUInt32LE(0xfff, 0); // declared far beyond the region + const truncated = Buffer.concat([ + Buffer.from([0xff, 0x0f, 0x00, 0x10]), // declared length 0xfff at size field + truncatedBody, + ]); + const chain = Buffer.concat([ui, truncated]); + const region = imageRegion(chain, 0, chain.length); + const walked = walkSections(region); + expect(walked.sections).toHaveLength(2); + const last = walked.sections[1]; + expect(last?.typeCode).toBe(0x10); + expect(last?.truncated).toBe(true); +}); + +it("returns no sections when the area is shorter than one header", () => { + const region = imageRegion(Buffer.from([2, 0, 0]), 0, 3); + expect(walkSections(region).sections).toHaveLength(0); +}); + +it("uses the extended common header for both guided and standard compression fields", () => { + const guided = Buffer.from( + "ffffff022000000098584eee143959429d6edc7bd79403cf1c00010001020304", + "hex", + ); + const standard = Buffer.from("ffffff01110000000a0000000101020304", "hex"); + for (const [section, expected] of [ + [guided, { kind: "lzma-custom", dataOffset: 28, attributes: 1 }], + [standard, { kind: "efi-standard", dataOffset: 13, attributes: null }], + ] as const) { + const record = walkSections(imageRegion(section, 0, section.length)) + .sections[0]; + expect(record?.compression).toMatchObject(expected); + expect(record?.payload).toEqual({ + start: expected.dataOffset, + end: section.length, + }); + } +}); + +it.each([20, 30])( + "rejects a guided payload offset %i outside the observed payload bounds", + (offset) => { + const section = buildLzmaGuidedSection(Buffer.from([0x11, 0x22])); + section.writeUIntLE(40, 0, 3); + section.writeUInt16LE(offset, 20); + const record = walkSections(imageRegion(section, 0, section.length)) + .sections[0]; + expect(record).toMatchObject({ malformed: true, payload: null }); + }, +); diff --git a/src/uefi/FfsSections.ts b/src/uefi/FfsSections.ts new file mode 100644 index 0000000000..f9c36b2d5c --- /dev/null +++ b/src/uefi/FfsSections.ts @@ -0,0 +1,277 @@ +import { BinaryReader } from "../domain/binaryContainer.js"; +import { Buffer } from "node:buffer"; +import { + absoluteOffset, + alignUp, + isWindowUniform, + type ScanRegion, +} from "./UefiBytes.js"; +import { formatGuidLittleEndian, GUID_LENGTH } from "./UefiGuid.js"; +import { + COMPRESSION_GUID_BY_DISPLAY, + SECTION_LAYOUT, +} from "./UefiCodeTables.js"; + +const GUIDED_PROCESSING_REQUIRED = 0x01; +const GUIDED_AUTH_STATUS_VALID = 0x02; +const SIGNED_SECTION_GUID = "0f9d89e8-9259-4f76-a5af-0c89e34023df"; + +export type UefiDecodeFormat = "lzma" | "lzmaf86" | "zlib"; + +type SectionContent = + | { kind: "leaf" | "ui" | "volume" } + | { kind: "stored-sections"; guidedIntegrityUnchecked: boolean } + | { kind: "decode"; format: UefiDecodeFormat } + | { + kind: "unsupported"; + gap: "unknown-guid-handler" | "unsupported-compression"; + }; + +/** Raw section observation before nesting resolution. */ +export interface SectionDraft { + readonly absoluteBase: number; + readonly headerLength: number; + readonly declaredLength: number; + /** Bytes actually covered inside the region (clamped on truncation). */ + readonly observedLength: number; + readonly truncated: boolean; + readonly malformed: boolean; + readonly content: SectionContent; + readonly typeCode: number; + readonly compression: + | { readonly kind: "none" } + | { + readonly kind: + | "lzma-custom" + | "lzmaf86" + | "ami-zlib" + | "tiano" + | "unknown-compression" + | "efi-standard" + | "crc32-guided" + | "unknown-guid"; + readonly guid: string | null; + readonly dataOffset: number; + readonly attributes: number | null; + }; + /** Payload window in this region's buffer, or null when malformed. */ + readonly payload: { readonly start: number; readonly end: number } | null; +} + +function readCommonHeader(reader: BinaryReader, start: number, end: number) { + if (start + SECTION_LAYOUT.commonLength > end) return null; + const compactSize = reader.u16(start) | (reader.u8(start + 2) << 16); + const extended = compactSize === SECTION_LAYOUT.largeSectionMarker; + const commonLength = extended + ? SECTION_LAYOUT.extendedLength + : SECTION_LAYOUT.commonLength; + if (start + commonLength > end) return null; + return { + commonLength, + declaredLength: extended + ? reader.u32(start + SECTION_LAYOUT.extendedSizeOffset) + : compactSize, + typeCode: reader.u8(start + SECTION_LAYOUT.typeOffset), + }; +} + +/** A bounded first frame establishes a section chain regardless of payload validity. */ +export function startsWithSectionFrame(region: ScanRegion): boolean { + const reader = new BinaryReader(region.buffer, true, "FFS sections"); + return hasBoundedFrame(reader, region.start, region.end); +} + +function hasBoundedFrame( + reader: BinaryReader, + start: number, + end: number, +): boolean { + const header = readCommonHeader(reader, start, end); + return ( + header !== null && + header.declaredLength >= header.commonLength && + header.declaredLength <= end - start + ); +} + +/** Read one PI section chain, with each child aligned relative to its stream. */ +export function walkSections( + region: ScanRegion, + reserve: () => boolean = () => true, +): { + sections: SectionDraft[]; + nonzeroPadding: { start: number; end: number }[]; + remainder: { kind: "limited" | "unparsed"; start: number } | null; +} { + const reader = new BinaryReader(region.buffer, true, "FFS sections"); + const sections: SectionDraft[] = []; + const nonzeroPadding: { start: number; end: number }[] = []; + const { start: localStart, end: localEnd } = region; + let cursor = localStart; + while (cursor + SECTION_LAYOUT.commonLength <= localEnd) { + if (!reserve()) + return { + sections, + nonzeroPadding, + remainder: { kind: "limited", start: cursor }, + }; + const header = readCommonHeader(reader, cursor, localEnd); + if (header === null) break; + const { commonLength, declaredLength, typeCode } = header; + // Even an undersized declaration has a common header we already observed. + const observedLength = Math.max( + commonLength, + Math.min(declaredLength, localEnd - cursor), + ); + const truncated = observedLength < declaredLength; + let headerLength: number = commonLength; + let compression: SectionDraft["compression"] = { kind: "none" }; + let content: SectionContent = { kind: "leaf" }; + if (typeCode === 0x03) + content = { kind: "stored-sections", guidedIntegrityUnchecked: false }; + else if (typeCode === 0x15) content = { kind: "ui" }; + else if (typeCode === 0x17) content = { kind: "volume" }; + let malformed = declaredLength < commonLength; + const fields = cursor + commonLength; + + if (typeCode === 0x01) { + headerLength += SECTION_LAYOUT.compressionFieldsLength; + malformed = observedLength < headerLength; + if (!malformed) { + const compressionType = reader.u8( + fields + SECTION_LAYOUT.compressionTypeFieldOffset, + ); + if (compressionType === 0) { + content = { + kind: "stored-sections", + guidedIntegrityUnchecked: false, + }; + malformed = reader.u32(fields) !== declaredLength - headerLength; + } else { + content = { kind: "unsupported", gap: "unsupported-compression" }; + compression = { + kind: + compressionType === 1 ? "efi-standard" : "unknown-compression", + guid: null, + dataOffset: headerLength, + attributes: null, + }; + } + } + } else if (typeCode === 0x02) { + headerLength += SECTION_LAYOUT.guidedFieldsLength; + malformed = observedLength < headerLength; + if (!malformed) { + const dataOffset = reader.u16( + fields + SECTION_LAYOUT.guidDataOffsetFieldOffset, + ); + malformed = dataOffset < headerLength || dataOffset > observedLength; + if (!malformed) { + const guid = formatGuidLittleEndian(region.buffer, fields); + headerLength = dataOffset; + const attributes = reader.u16( + fields + SECTION_LAYOUT.guidAttributesFieldOffset, + ); + const kind = + guid === null + ? "unknown-guid" + : (COMPRESSION_GUID_BY_DISPLAY[guid] ?? "unknown-guid"); + compression = { kind, guid, dataOffset, attributes }; + if ( + kind === "lzma-custom" || + kind === "lzmaf86" || + kind === "ami-zlib" + ) { + content = { + kind: "decode", + format: + kind === "ami-zlib" + ? "zlib" + : kind === "lzma-custom" + ? "lzma" + : "lzmaf86", + }; + } else if ( + (attributes & GUIDED_PROCESSING_REQUIRED) === 0 && + guid !== SIGNED_SECTION_GUID && + (kind === "crc32-guided" || + (kind === "unknown-guid" && + hasBoundedFrame( + reader, + cursor + dataOffset, + cursor + observedLength, + ))) + ) { + content = { + kind: "stored-sections", + guidedIntegrityUnchecked: + (attributes & GUIDED_AUTH_STATUS_VALID) !== 0, + }; + } else { + content = { + kind: "unsupported", + gap: + kind === "unknown-guid" + ? "unknown-guid-handler" + : "unsupported-compression", + }; + } + } + } + } else if (typeCode === 0x14 || typeCode === 0x18) { + headerLength += typeCode === 0x14 ? 2 : GUID_LENGTH; + malformed = observedLength < headerLength; + } + + sections.push({ + absoluteBase: absoluteOffset(region, cursor), + headerLength, + declaredLength, + observedLength, + truncated, + malformed, + content, + typeCode, + compression, + payload: malformed + ? null + : { start: cursor + headerLength, end: cursor + observedLength }, + }); + if (truncated) return { sections, nonzeroPadding, remainder: null }; + if (declaredLength < commonLength) { + cursor += commonLength; + break; + } + const end = cursor + declaredLength; + cursor = localStart + alignUp(end - localStart, 4); + const paddingEnd = Math.min(cursor, localEnd); + if (end < paddingEnd && !isWindowUniform(region.buffer, end, paddingEnd, 0)) + nonzeroPadding.push({ start: end, end: paddingEnd }); + } + return { + sections, + nonzeroPadding, + remainder: cursor < localEnd ? { kind: "unparsed", start: cursor } : null, + }; +} + +/** + * EFI_AMD_ZLIB_SECTION_HEADER (UEFITool ffs.h): a 0x100-byte header — + * 0x14 zero bytes, CompressedSize u32 LE, 0xE8 zero footer — sits between the + * GUID-defined header and the zlib-wrapped stream at payload offset 0x100. + */ +export const AMD_ZLIB_HEADER_LENGTH = 0x100; + +/** Peel the 0x100-byte AMD header off one ami-zlib payload, or null when short. */ +export function peelAmiZlibPayload( + payload: Buffer, +): { stream: Buffer; declaredCompressedSize: number } | null { + if (payload.length < AMD_ZLIB_HEADER_LENGTH) { + return null; + } + const payloadReader = new BinaryReader(payload, true, "AMD zlib section"); + return { + stream: payload.subarray(AMD_ZLIB_HEADER_LENGTH), + declaredCompressedSize: payloadReader.u32(0x14), + }; +} diff --git a/src/uefi/FirmwareVolume.test.ts b/src/uefi/FirmwareVolume.test.ts new file mode 100644 index 0000000000..99333e1ad5 --- /dev/null +++ b/src/uefi/FirmwareVolume.test.ts @@ -0,0 +1,131 @@ +import { Buffer } from "node:buffer"; +import { expect, it } from "vitest"; + +import { + buildFv, + buildImage, + buildFfsFile, +} from "../../tests/fixtures/uefiImage.js"; +import { imageRegion } from "./UefiBytes.js"; +import { + parseFirmwareVolumeHeader, + scanFirmwareVolumes, +} from "./FirmwareVolume.js"; + +const driverFile = (guid: string): Buffer => + buildFfsFile({ guid, typeCode: 0x07, payload: Buffer.from("body") }); + +it("parses a valid built volume header with verified checksum", () => { + const fv = buildFv({ + files: [driverFile("11111111-2222-3333-4444-555555555555")], + }); + const region = imageRegion(fv.buffer, 0, fv.buffer.length); + const header = parseFirmwareVolumeHeader(region, 0); + expect(header).not.toBeNull(); + expect(header?.declaredLength).toBe(fv.declaredLength); + expect(header?.headerLength).toBe(72); + expect(header?.attributes).toBe(0x800); + expect(header?.erasePolarity).toBe(true); + expect(header?.revision).toBe(2); + expect(header?.checksumValid).toBe(true); + expect(header?.fileSystemGuid).toBe("8c8ce578-8a3d-4f1c-9935-896185c32dd3"); + expect(header?.blockMap).toEqual([ + { numBlocks: expect.any(Number), blockLength: 0x1000 }, + ]); +}); + +it("flags a corrupted header byte as checksum mismatch but keeps the header", () => { + const fv = buildFv({ + files: [driverFile("12111111-2222-3333-4444-555555555555")], + }); + fv.buffer[55] = 3; // revision byte carries the corrupted word checksum + const region = imageRegion(fv.buffer, 0, fv.buffer.length); + const header = parseFirmwareVolumeHeader(region, 0); + expect(header?.revision).toBe(3); + expect(header?.checksumValid).toBe(false); +}); + +it("returns null when the signature is absent", () => { + const region = imageRegion(Buffer.alloc(64, 0x11), 0, 64); + expect(parseFirmwareVolumeHeader(region, 0)).toBeNull(); +}); + +it("discovers every volume in an image and rejects implausible _FVH hits", () => { + const fvA = buildFv({ + files: [driverFile("13111111-2222-3333-4444-555555555555")], + }); + const fvB = buildFv({ + files: [driverFile("14111111-2222-3333-4444-555555555555")], + }); + // Garbage _FVH text inside a payload: the preceding "header" has zero length, + // so the hit must be rejected, never silently mapped. + const garbage = Buffer.concat([ + Buffer.alloc(40, 0x41), + Buffer.from("_FVH", "ascii"), + Buffer.alloc(16, 0x42), + ]); + const image = buildImage({ volumes: [fvA.buffer, garbage, fvB.buffer] }); + const region = imageRegion(image, 0, image.length); + const scan = scanFirmwareVolumes(region, 16); + expect(scan.volumes).toHaveLength(2); + expect(scan.rejected).toHaveLength(1); + const firstOffset = scan.volumes[0]?.header.absoluteBase ?? -1; + const secondOffset = scan.volumes[1]?.header.absoluteBase ?? -1; + expect(secondOffset - firstOffset).toBeGreaterThan(0); + expect(scan.rejected[0]?.reason).not.toBe(""); +}); + +it("respects the maxVolumes budget while scanning", () => { + const fvA = buildFv({ + files: [driverFile("15111111-2222-3333-4444-555555555555")], + }); + const fvB = buildFv({ + files: [driverFile("16111111-2222-3333-4444-555555555555")], + }); + const image = buildImage({ volumes: [fvA.buffer, fvB.buffer] }); + const region = imageRegion(image, 0, image.length); + const scan = scanFirmwareVolumes(region, 1); + expect(scan.volumes).toHaveLength(1); +}); + +it("admits a supported aligned volume after an earlier foreign and unaligned volume", async () => { + const { admitUefiFlashImage } = await import("./UefiFormatProbe.js"); + const foreign = buildFv({ + files: [], + fileSystemGuid: "19111111-2222-3333-4444-555555555555", + }).buffer; + const ffs = buildFv({ files: [] }).buffer; + expect( + admitUefiFlashImage(Buffer.concat([foreign, Buffer.alloc(1), ffs])), + ).toBe(false); + expect( + admitUefiFlashImage( + Buffer.concat([foreign, Buffer.alloc(1), ffs, Buffer.alloc(15), ffs]), + ), + ).toBe(true); +}); + +it.each([ + { size: 64, blockLength: 64, reason: "header-exceeds-volume" }, + { size: 4096, blockLength: 2048, reason: "block-map-shorter-than-volume" }, + { size: 4096, blockLength: 0, reason: "block-map-empty-run" }, +])( + "rejects contradictory FV geometry ($reason)", + ({ size, blockLength, reason }) => { + const { buffer } = buildFv({ files: [] }); + buffer.writeBigUInt64LE(BigInt(size), 32); + buffer.writeUInt32LE(blockLength, 60); + const scan = scanFirmwareVolumes(imageRegion(buffer, 0, buffer.length), 4); + expect(scan.volumes).toEqual([]); + expect(scan.rejected).toMatchObject([{ reason }]); + }, +); + +it("does not use an FV beyond the signature search boundary to admit the image", async () => { + const { admitUefiFlashImage } = await import("./UefiFormatProbe.js"); + const prefix = Buffer.alloc(0x1000); + prefix.write("_FVH", 0, "ascii"); + const image = Buffer.concat([prefix, buildFv({ files: [] }).buffer]); + expect(admitUefiFlashImage(image, prefix.length)).toBe(false); + expect(admitUefiFlashImage(image)).toBe(true); +}); diff --git a/src/uefi/FirmwareVolume.ts b/src/uefi/FirmwareVolume.ts new file mode 100644 index 0000000000..6cd17a1a00 --- /dev/null +++ b/src/uefi/FirmwareVolume.ts @@ -0,0 +1,370 @@ +import { Budget } from "../domain/budget.js"; +import { UEFI_FIRMWARE_LIMITS } from "../domain/uefi/uefiLimits.js"; +import { BinaryReader } from "../domain/binaryContainer.js"; +import { Buffer } from "node:buffer"; +import { absoluteOffset, alignUp, type ScanRegion } from "./UefiBytes.js"; +import { + FFS2_FILE_SYSTEM_GUID, + FFS3_FILE_SYSTEM_GUID, + formatGuidLittleEndian, + GUID_LENGTH, +} from "./UefiGuid.js"; +import { + FV_ATTRIBUTE_ERASE_POLARITY, + FV_HEADER_LAYOUT, +} from "./UefiCodeTables.js"; + +import { parseFfsFileHeader } from "./FfsFile.js"; + +const FVH_SIGNATURE = 0x4856465f; // "_FVH" read as a little-endian word + +export interface FirmwareVolumeBlockMapEntry { + readonly numBlocks: number; + readonly blockLength: number; +} + +/** Verified-or-rejected firmware volume header observation. */ +export interface FirmwareVolumeHeader { + readonly localBase: number; + readonly absoluteBase: number; + readonly declaredLength: number; + readonly headerLength: number; + readonly firstFileLocal: number; + readonly attributes: number; + readonly erasePolarity: boolean; + readonly extHeaderOffset: number | null; + readonly revision: number; + readonly fileSystemGuid: string | null; + readonly fileSystem: "ffs2" | "ffs3" | "unsupported"; + readonly blockMap: readonly FirmwareVolumeBlockMapEntry[]; + readonly checksumValid: boolean; + /** Plausibility findings that gate the hit; empty when fully plausible. */ + readonly implausibilities: readonly string[]; +} + +/** Explain the unparsed body using the exact GUID reported by the header. */ +export const unsupportedVolumeBodyReason = ( + header: FirmwareVolumeHeader, +): string => + `Firmware volume at 0x${header.absoluteBase.toString(16)} has an unsupported file-system GUID (${header.fileSystemGuid ?? "unavailable"}); its body was not parsed.`; + +/** + * Parse one header at a local position. Returns null when the position cannot + * hold a structurally complete header (bounds or signature); returns header + * data plus implausibility findings otherwise. Mismatched declared checksums + * stay an observation, never a rejection. + */ +export function parseFirmwareVolumeHeader( + region: ScanRegion, + localHeaderBase: number, + reserve: () => boolean = () => true, +): FirmwareVolumeHeader | null { + const available = region.end - localHeaderBase; + if ( + localHeaderBase < region.start || + available < FV_HEADER_LAYOUT.minimumLength || + localHeaderBase + FV_HEADER_LAYOUT.minimumLength > region.end + ) { + return null; + } + const reader = new BinaryReader(region.buffer, true, "UEFI firmware volume"); + const signature = reader.u32( + localHeaderBase + FV_HEADER_LAYOUT.signatureOffset, + ); + if (signature !== FVH_SIGNATURE) { + return null; + } + const absoluteBase = absoluteOffset(region, localHeaderBase); + const headerLength = reader.u16( + localHeaderBase + FV_HEADER_LAYOUT.headerLengthOffset, + ); + const attributes = reader.u32( + localHeaderBase + FV_HEADER_LAYOUT.attributesOffset, + ); + const revision = + region.buffer[localHeaderBase + FV_HEADER_LAYOUT.revisionOffset] ?? 0; + const extHeaderRaw = reader.u16( + localHeaderBase + FV_HEADER_LAYOUT.extHeaderOffsetOffset, + ); + const declaredLengthValue = reader.word( + localHeaderBase + FV_HEADER_LAYOUT.fvLengthOffset, + 64, + ); + const declaredLength = Number(declaredLengthValue); + const implausibilities: string[] = []; + if ( + !Number.isSafeInteger(declaredLength) || + declaredLengthValue > BigInt(Number.MAX_SAFE_INTEGER) + ) { + return null; + } + if (headerLength < FV_HEADER_LAYOUT.minimumLength || headerLength % 2 !== 0) { + implausibilities.push("header-length-implausible"); + } + if (declaredLength < FV_HEADER_LAYOUT.minimumLength) { + implausibilities.push("declared-length-implausible"); + } + if (localHeaderBase + declaredLength > region.end) { + implausibilities.push("declared-length-truncates-region"); + } + if ( + headerLength > FV_HEADER_LAYOUT.minimumLength && + localHeaderBase + headerLength > region.end + ) { + implausibilities.push("header-length-truncates-region"); + } + + if (headerLength > declaredLength) + implausibilities.push("header-exceeds-volume"); + const volumeEnd = localHeaderBase + Math.min(declaredLength, available); + const blockMap: FirmwareVolumeBlockMapEntry[] = []; + const blockMapCapacity = Math.floor( + (headerLength - FV_HEADER_LAYOUT.blockMapOffset) / + FV_HEADER_LAYOUT.blockMapEntryLength, + ); + let blockMapTerminated = false; + for (let index = 0; index < blockMapCapacity; index += 1) { + const entryLocal = + localHeaderBase + + FV_HEADER_LAYOUT.blockMapOffset + + index * FV_HEADER_LAYOUT.blockMapEntryLength; + if (entryLocal + FV_HEADER_LAYOUT.blockMapEntryLength > volumeEnd) { + implausibilities.push("block-map-truncation"); + break; + } + const numBlocks = reader.u32(entryLocal); + const blockLength = reader.u32(entryLocal + 4); + if (numBlocks === 0 && blockLength === 0) { + blockMapTerminated = true; + break; + } + if (numBlocks === 0 || blockLength === 0) { + implausibilities.push("block-map-empty-run"); + break; + } + if (!reserve()) return null; + blockMap.push({ numBlocks, blockLength }); + } + if (!blockMapTerminated) { + implausibilities.push("block-map-terminator-missing"); + } + if (blockMapTerminated) { + const mapped = blockMap.reduce( + (total, entry) => + total + BigInt(entry.numBlocks) * BigInt(entry.blockLength), + 0n, + ); + if (mapped !== declaredLengthValue) + implausibilities.push( + mapped > declaredLengthValue + ? "block-map-exceeds-volume" + : "block-map-shorter-than-volume", + ); + } + + const erasePolarity = (attributes & FV_ATTRIBUTE_ERASE_POLARITY) !== 0; + let firstFileLocal = localHeaderBase + alignUp(headerLength, 8); + if (extHeaderRaw !== 0 && blockMapTerminated) { + const blockMapEnd = + FV_HEADER_LAYOUT.blockMapOffset + + (blockMap.length + 1) * FV_HEADER_LAYOUT.blockMapEntryLength; + const extStart = localHeaderBase + extHeaderRaw; + const extMinimumLength = GUID_LENGTH + 4; + if ( + extHeaderRaw < blockMapEnd || + extHeaderRaw % 4 !== 0 || + extStart + extMinimumLength > volumeEnd + ) { + implausibilities.push("extended-header-offset-implausible"); + } else { + const extLength = reader.u32(extStart + GUID_LENGTH); + const extEnd = extStart + extLength; + if (extLength < extMinimumLength || extEnd > volumeEnd) { + implausibilities.push("extended-header-length-implausible"); + } else if (extEnd > firstFileLocal) { + const pad = parseFfsFileHeader( + { ...region, end: volumeEnd }, + firstFileLocal, + erasePolarity, + ); + // GenFv places the extension in a pad file. Preserve that file when + // its validated body owns the entire extension. + if ( + pad?.typeCode !== 0xf0 || + !pad.headerChecksumValid || + pad.extentIssue !== null || + pad.body === null || + pad.body.start > extStart || + pad.body.end < extEnd + ) { + firstFileLocal = + localHeaderBase + alignUp(extEnd - localHeaderBase, 8); + } + } + } + } + const checksumValid = + localHeaderBase + headerLength <= volumeEnd && + verifyFirmwareVolumeChecksum(region.buffer, localHeaderBase, headerLength); + const fileSystemGuid = formatGuidLittleEndian( + region.buffer, + localHeaderBase + FV_HEADER_LAYOUT.fileSystemGuidOffset, + ); + return { + localBase: localHeaderBase, + absoluteBase, + declaredLength, + headerLength, + firstFileLocal, + attributes, + erasePolarity, + extHeaderOffset: extHeaderRaw === 0 ? null : extHeaderRaw, + revision, + fileSystemGuid, + fileSystem: + fileSystemGuid === FFS2_FILE_SYSTEM_GUID + ? "ffs2" + : fileSystemGuid === FFS3_FILE_SYSTEM_GUID + ? "ffs3" + : "unsupported", + blockMap, + checksumValid, + implausibilities, + }; +} + +/** Sum of 16-bit header words must reach zero (mod 2^16). */ +function verifyFirmwareVolumeChecksum( + buffer: Buffer, + localHeaderBase: number, + headerLength: number, +): boolean { + if ( + headerLength % 2 !== 0 || + localHeaderBase + headerLength > buffer.length + ) { + return false; + } + const checksumReader = new BinaryReader(buffer, true, "UEFI firmware volume"); + let total = 0; + for (let offset = 0; offset < headerLength; offset += 2) { + total = (total + checksumReader.u16(localHeaderBase + offset)) & 0xffff; + } + return total === 0; +} + +export interface FirmwareVolumeHit { + readonly header: FirmwareVolumeHeader; +} + +export interface RejectedFirmwareVolumeHit { + readonly absoluteBase: number; + readonly signatureLocal: number; + readonly reason: string; + readonly truncation?: { + readonly declaredLength: number; + readonly observedLength: number; + }; +} + +export interface FirmwareVolumeScanResult { + readonly volumes: readonly FirmwareVolumeHit[]; + readonly rejected: readonly RejectedFirmwareVolumeHit[]; + readonly limit: "candidates" | "structural-records" | null; +} + +/** + * Scan for `_FVH` hits with a shared reservation for candidate and block-map + * records. Keep plausible headers and distinguish rejected candidates from a + * stopped scan. Format admission applies its own alignment check. + */ +export function scanFirmwareVolumes( + region: ScanRegion, + maxCandidates: number, + options: { + /** Charge a record against the caller's operation-wide budget when supplied. */ + readonly reserve?: () => boolean; + readonly checkpoint?: () => void; + readonly skipNested?: boolean; + readonly signatureEnd?: number; + } = {}, +): FirmwareVolumeScanResult { + const volumes: FirmwareVolumeHit[] = []; + const rejected: RejectedFirmwareVolumeHit[] = []; + const signatureText = Buffer.from("_FVH", "ascii"); + let searchFrom = region.start; + const signatureEnd = Math.min(region.end, options.signatureEnd ?? region.end); + const searchable = region.buffer.subarray(0, signatureEnd); + const budget = new Budget(UEFI_FIRMWARE_LIMITS.scanRecords); + let limit: FirmwareVolumeScanResult["limit"] = null; + const reserve = (): boolean => { + options.checkpoint?.(); + if (options.reserve?.() ?? budget.tryCharge(1)) return true; + limit = "structural-records"; + return false; + }; + while (searchFrom < signatureEnd) { + const hitLocal = searchable.indexOf(signatureText, searchFrom); + if (hitLocal < 0 || hitLocal + 4 > signatureEnd) { + break; + } + if (volumes.length + rejected.length >= maxCandidates) { + limit = "candidates"; + break; + } + if (!reserve()) break; + searchFrom = hitLocal + 1; + const headerLocal = hitLocal - FV_HEADER_LAYOUT.signatureOffset; + if (headerLocal < region.start) { + rejected.push({ + absoluteBase: Math.max( + 0, + absoluteOffset(region, hitLocal) - FV_HEADER_LAYOUT.signatureOffset, + ), + signatureLocal: hitLocal, + reason: "header-precedes-region-start", + }); + continue; + } + const header = parseFirmwareVolumeHeader(region, headerLocal, reserve); + if (header === null) { + if (limit !== null) break; + rejected.push({ + absoluteBase: + absoluteOffset(region, hitLocal) - FV_HEADER_LAYOUT.signatureOffset, + signatureLocal: hitLocal, + reason: "header-unparseable", + }); + continue; + } + const reason = header.implausibilities[0]; + if (reason !== undefined) { + const truncated = + reason === "declared-length-truncates-region" || + reason === "header-length-truncates-region"; + rejected.push({ + absoluteBase: header.absoluteBase, + signatureLocal: hitLocal, + reason, + ...(truncated + ? { + truncation: { + declaredLength: Math.max( + header.declaredLength, + header.headerLength, + ), + observedLength: region.end - headerLocal, + }, + } + : {}), + }); + continue; + } + volumes.push({ header }); + if (options.skipNested || header.fileSystem === "unsupported") { + // Only supported volume bodies can supply nested candidates. + searchFrom = Math.max(searchFrom, headerLocal + header.declaredLength); + } + } + return { volumes, rejected, limit }; +} diff --git a/src/uefi/UefiAnalysisProvider.test.ts b/src/uefi/UefiAnalysisProvider.test.ts new file mode 100644 index 0000000000..ec1e39067c --- /dev/null +++ b/src/uefi/UefiAnalysisProvider.test.ts @@ -0,0 +1,1610 @@ +import { createHash } from "node:crypto"; +import { existsSync } from "node:fs"; +import { readFile, stat, writeFile } from "node:fs/promises"; +import { createRequire } from "node:module"; +import { join } from "node:path"; +import { fileURLToPath } from "node:url"; +import { deflateSync } from "node:zlib"; +import { expect, it, vi } from "vitest"; +import { SafeOutputTree } from "../resources/SafeOutputTree.js"; +import { SafeOutputTreeCreationFailure } from "../resources/SafeOutputTreeCreationFailure.js"; +import { OwnedFileHandle } from "../filesystem/OwnedFileHandle.js"; +import { PrivateRuntimeRoot } from "../process/PrivateRuntimeRoot.js"; +import { UEFI_FIRMWARE_LIMITS } from "../domain/uefi/uefiLimits.js"; +import { createDeferred } from "../../tests/fixtures/binarySession.js"; +import { createTestTempDirectory } from "../../tests/fixtures/temporaryDirectory.js"; +import { UefiAnalysisService } from "../application/uefi/UefiAnalysisService.js"; +import { AMD_ZLIB_HEADER_LENGTH } from "./FfsSections.js"; +import { + buildCompressionSection, + buildFfsFile, + buildFv, + buildGuidedSection, + buildImage, + buildLzmaGuidedSection, + buildSection, + guidBytes, +} from "../../tests/fixtures/uefiImage.js"; +import { UefiAnalysisProvider } from "./UefiAnalysisProvider.js"; +import { + uefiRequestSchema, + type UefiExtractResult, + type UefiRequest, + type UefiInspectResult, +} from "../domain/uefi/uefiFirmwareAnalysis.js"; + +/** Compiled worker lane; the unit tests without dist skip real decodes. */ +const distUefiLzmaWorker = fileURLToPath( + new URL("../../dist/uefi/UefiLzmaWorker.js", import.meta.url), +); +const lzmaPurescript = createRequire(import.meta.url)( + "lzma-purejs", +) as unknown as { + compressFile: (buffer: Buffer) => Uint8Array; +}; + +const GUID_DRIVER = "3c1b0309-0000-4444-8888-444488883333"; +const GUID_RAW = "1111aaaa-2222-4333-8444-555555555555"; +const GUID_PAD = "ffffffff-ffff-ffff-ffff-ffffffffffff"; +const GUID_GUIDED = "22224444-8888-4444-8888-444488884444"; +const GUID_AMD_ZLIB = "ce3233f5-2cd6-4d87-9152-4a238bb6d1c4"; + +const MODULE_A = Buffer.from("MODULE-APAYLOAD-B550-AORUS-ELITE-V2", "utf8"); +const RAW_BODY = Buffer.from("RAWFILEBODY-BYTES", "utf8"); +const GUIDED_BODY = Buffer.from("GUIDEDPAYLOAD-EE4E5898", "utf8"); + +const buildTestImage = ({ withGuided = true } = {}): Buffer => { + const driver = buildFfsFile({ + guid: GUID_DRIVER, + typeCode: 0x07, + payload: Buffer.concat([ + buildSection(0x10, MODULE_A), + ...(withGuided + ? [ + buildGuidedSection({ + definitionGuid: GUID_GUIDED, + body: GUIDED_BODY, + }), + ] + : []), + ]), + }); + const raw = buildFfsFile({ + guid: GUID_RAW, + typeCode: 0x01, + payload: RAW_BODY, + }); + const pad = buildFfsFile({ + guid: GUID_PAD, + typeCode: 0xf0, + payload: Buffer.alloc(0), + }); + const volume = buildFv({ files: [pad, driver, raw] }); + return buildImage({ volumes: [volume.buffer] }); +}; + +const writeTestImage = async (options?: { + readonly withGuided?: boolean; +}): Promise<{ + readonly imagePath: string; + readonly directory: string; +}> => { + const directory = await createTestTempDirectory("rea-uefi-provider-"); + const imagePath = join(directory, "image.fi"); + await writeFile(imagePath, buildTestImage(options)); + return { imagePath, directory }; +}; + +const sha256 = (bytes: Buffer): string => + createHash("sha256").update(bytes).digest("hex"); + +/** Schema-validated admission, identical to the shared provider execution. */ +const inspectRequest = (path: string) => + uefiRequestSchema.parse({ + operation: "inspect_uefi_firmware", + input: { path }, + }); + +const extractRequest = ( + path: string, + outputDirectory: string, + overrides?: { + readonly target?: Extract< + UefiRequest, + { operation: "extract_uefi_firmware" } + >["input"]["target"]; + readonly max_depth?: number; + readonly max_output_files?: number; + readonly include_compressed?: boolean; + }, +) => + uefiRequestSchema.parse({ + operation: "extract_uefi_firmware", + input: { path, output_directory: outputDirectory, ...overrides }, + }); + +const expectOk = < + T extends + | { readonly ok: true; readonly value: { readonly result: unknown } } + | { readonly ok: false; readonly error: unknown }, +>( + executed: T, +): Extract => { + if (!executed.ok) { + throw new Error(JSON.stringify(executed.error, null, 2)); + } + return executed as Extract; +}; + +it("maps a flash image into an inspect execution with volume and section coverage", async () => { + const { imagePath } = await writeTestImage(); + const provider = new UefiAnalysisProvider(); + const executed = expectOk( + await provider.execute(await inspectRequest(imagePath)), + ); + const result = executed.value.result as UefiInspectResult; + const image = await readFile(imagePath); + expect(result.parser.name).toBe("rea-uefi"); + expect(result.flash_image.sha256).toBe(sha256(image)); + expect(result.flash_image.entry_basis).toBe("fv-at-zero"); + expect(result.firmware_volumes).toHaveLength(1); + const volume0 = result.firmware_volumes[0]; + expect(volume0?.ffs_files.map((file) => file.type_name)).toContain("driver"); + expect(result.coverage).toBe("partial"); + expect(result.limitations.join(" ")).toContain("unknown-guid"); + expect(executed.value.subject?.sha256).toBe(sha256(image)); + await provider.close(); +}); + +it("extracts whole-image payloads with section provenance and published bytes", async () => { + // Without a guided section, everything requested is publishable: pad files + // stay in place by design, so they never downgrade coverage. + const { imagePath, directory } = await writeTestImage({ withGuided: false }); + const provider = new UefiAnalysisProvider(); + const executed = expectOk( + await provider.execute( + await extractRequest(imagePath, join(directory, "out")), + ), + ); + const result = executed.value.result as UefiExtractResult; + expect(result.selection.target_kind).toBe("whole-image"); + expect(result.coverage).toBe("complete"); + expect(result.derivations).toHaveLength(0); + const rawSection = result.files.find((file) => file.source === "raw-section"); + expect(rawSection?.size).toBe(MODULE_A.length); + const rawBytes = await readFile(rawSection?.path ?? ""); + expect(rawBytes.equals(MODULE_A)).toBe(true); + const rawBody = result.files.find( + (file) => file.source === "uncompressed-payload", + ); + expect((await readFile(rawBody?.path ?? "")).equals(RAW_BODY)).toBe(true); + expect(rawBody?.relative_path).not.toContain(":"); + const padGap = result.extraction_gaps.find((gap) => gap.kind === "pad-file"); + expect(padGap).toBeDefined(); + expect(result.published_bytes).toBe( + result.files.reduce((total, file) => total + file.size, 0), + ); +}); + +it("publishes the unknown-guid carrier and reports the decoding gap explicitly", async () => { + const { imagePath, directory } = await writeTestImage(); + const provider = new UefiAnalysisProvider(); + const executed = expectOk( + await provider.execute( + await extractRequest(imagePath, join(directory, "out")), + ), + ); + const result = executed.value.result as UefiExtractResult; + const guidedGap = result.extraction_gaps.find( + (gap) => gap.kind === "unknown-guid-handler", + ); + expect(guidedGap).toBeDefined(); + const carrier = result.files.find( + (file) => file.source === "compressed-passthrough", + ); + expect(carrier?.size).toBe(GUIDED_BODY.length); + expect((await readFile(carrier?.path ?? "")).equals(GUIDED_BODY)).toBe(true); +}); + +it("withholds carriers when include_compressed is disabled", async () => { + const { imagePath, directory } = await writeTestImage(); + const provider = new UefiAnalysisProvider(); + const executed = expectOk( + await provider.execute( + await extractRequest(imagePath, join(directory, "out"), { + include_compressed: false, + }), + ), + ); + const result = executed.value.result as UefiExtractResult; + expect( + result.files.find((file) => file.source === "compressed-passthrough"), + ).toBeUndefined(); + expect(result.coverage).toBe("partial"); +}); + +it("stops staging at the file budget and downgrades coverage", async () => { + const { imagePath, directory } = await writeTestImage(); + const provider = new UefiAnalysisProvider(); + const executed = expectOk( + await provider.execute( + await extractRequest(imagePath, join(directory, "out-tight"), { + max_output_files: 1, + }), + ), + ); + const result = executed.value.result as UefiExtractResult; + expect(result.files).toHaveLength(1); + expect(result.coverage).toBe("partial"); + expect( + result.extraction_gaps.some((gap) => gap.kind === "size-truncated"), + ).toBe(true); +}); + +it("rejects extraction scopes that do not match a scanned record", async () => { + const { imagePath, directory } = await writeTestImage(); + const provider = new UefiAnalysisProvider(); + const executed = await provider.execute( + await extractRequest(imagePath, join(directory, "out"), { + target: { kind: "volume", offset: 0xdeadbeef }, + }), + ); + expect(executed.ok).toBe(false); + if (executed.ok) return; + expect(executed.error._tag).toBe("AnalysisInputError"); +}); + +const lzmaWorkerAvailable = existsSync(distUefiLzmaWorker); + +it.skipIf(!lzmaWorkerAvailable)( + "decodes an LZMA-custom section through the owned worker and derives it", + async () => { + const decoded = Buffer.from("FVMAIN-DECODED-PAYLOAD-".repeat(64), "utf8"); + const directory = await createTestTempDirectory("rea-uefi-provider-"); + const compressed = lzmaPurescript.compressFile(decoded); + const driver = buildFfsFile({ + guid: GUID_DRIVER, + typeCode: 0x07, + payload: buildLzmaGuidedSection(Buffer.from(compressed)), + }); + const volume = buildFv({ files: [driver] }); + const imagePath = join(directory, "lzma-image.fi"); + await writeFile(imagePath, buildImage({ volumes: [volume.buffer] })); + const provider = new UefiAnalysisProvider(distUefiLzmaWorker); + const executed = expectOk( + await provider.execute( + await extractRequest(imagePath, join(directory, "out-lzma")), + ), + ); + const result = executed.value.result as UefiExtractResult; + const decodedFile = result.files.find( + (file) => file.source === "decompressed-lzma", + ); + expect(decodedFile?.size).toBe(decoded.length); + expect((await readFile(decodedFile?.path ?? "")).equals(decoded)).toBe( + true, + ); + expect(result.derivations).toHaveLength(1); + expect(result.derivations[0]?.handler.startsWith("lzma-purejs@0.9.")).toBe( + true, + ); + expect(result.extraction_gaps).toMatchObject([ + { + kind: "unparsed-region", + source_stream: result.derivations[0]?.child_stream, + range: { offset: 0, length: decoded.length }, + }, + ]); + expect(result.coverage).toBe("partial"); + }, + 45_000, +); + +it.skipIf(!lzmaWorkerAvailable)( + "restores an EDK II LZMAF86 section stream before mapping and extracting its PE payload", + async () => { + const pePayload = Buffer.from( + "4d5a90e80c00000090e9f1ffffff9090e8e9ff00009090c3e9", + "hex", + ); + // EDK II LzmaCompress -e --f86 at 556dcfb466e9f05affeaff881d738807f8156d3c, + // over buildSection(0x10, pePayload). Plain LZMA leaves different operands. + const compressed = Buffer.from( + "5d000000012000000000000000000e802f20d6bb0779fccd0af806e72f54b89b62db3e8de253e82174580000", + "hex", + ); + const file = buildFfsFile({ + guid: GUID_DRIVER, + typeCode: 0x07, + payload: buildGuidedSection({ + definitionGuid: "d42ae6bd-1352-4bfb-909a-ca72a6eae889", + body: compressed, + }), + }); + const directory = await createTestTempDirectory("rea-uefi-f86-"); + const imagePath = join(directory, "image.fi"); + await writeFile(imagePath, buildFv({ files: [file] }).buffer); + const provider = new UefiAnalysisProvider(distUefiLzmaWorker); + + const result = expectOk( + await provider.execute( + extractRequest(imagePath, join(directory, "out"), { + include_compressed: false, + }), + ), + ).value.result as UefiExtractResult; + expect(result.coverage).toBe("complete"); + expect(result.extraction_gaps).toEqual([]); + expect(result.derivations).toMatchObject([ + { + handler: expect.stringContaining("+x86-bcj"), + parent_file_range: { length: compressed.length }, + }, + ]); + const restored = result.files.find( + (entry) => entry.source === "decompressed-lzmaf86", + ); + const payload = result.files.find( + (entry) => entry.source === "raw-section", + ); + if (restored === undefined || payload === undefined) { + throw new Error( + "LZMAF86 extraction did not publish its stream and PE payload", + ); + } + expect( + (await readFile(restored.path)).equals(buildSection(0x10, pePayload)), + ).toBe(true); + expect((await readFile(payload.path)).equals(pePayload)).toBe(true); + expect(payload).toMatchObject({ + source_stream: restored.source_stream, + source_range: { offset: 4, length: pePayload.length }, + original_file_range: null, + }); + }, + 45_000, +); + +const amdZlibSection = (content: Buffer, suffix = Buffer.alloc(0)): Buffer => { + const stream = Buffer.concat([deflateSync(content), suffix]); + const amdHeader = Buffer.alloc(AMD_ZLIB_HEADER_LENGTH); + amdHeader.writeUInt32LE(stream.length, 0x14); + return buildGuidedSection({ + definitionGuid: GUID_AMD_ZLIB, + body: Buffer.concat([amdHeader, stream]), + }); +}; + +it("decodes nested zlib streams and preserves each carrier and PE byte range in scoped extraction", async () => { + const pe = Buffer.from("ZLIB-NESTED-PAYLOAD"); + const ui = buildSection(0x15, Buffer.from("Setup\0", "utf16le")); + const innerChain = Buffer.concat([ui, buildSection(0x10, pe)]); + const nestedInner = buildFfsFile({ + guid: GUID_RAW, + typeCode: 0x07, + payload: amdZlibSection(innerChain), + }); + const decoded = buildFv({ files: [nestedInner] }).buffer; + const directory = await createTestTempDirectory("rea-uefi-provider-"); + const driver = buildFfsFile({ + guid: GUID_DRIVER, + typeCode: 0x07, + payload: amdZlibSection(decoded), + }); + const volume = buildFv({ files: [driver] }); + const imagePath = join(directory, "zlib-image.fi"); + await writeFile(imagePath, buildImage({ volumes: [volume.buffer] })); + const provider = new UefiAnalysisProvider(); + + const inspected = expectOk( + await provider.execute(await inspectRequest(imagePath)), + ); + const inspectResult = inspected.value.result as UefiInspectResult; + expect(inspectResult.firmware_volumes).toHaveLength(2); + expect(inspectResult.firmware_volumes[1]?.logical_path).toContain( + "/zlib/FV@", + ); + + const nested = inspectResult.firmware_volumes[1]; + const module = nested?.ffs_files[0]; + const peSection = module?.sections.find( + (section) => section.type_name === "pe32", + ); + expect(module?.ui_string).toBe("Setup"); + expect(peSection?.offset).toBe(ui.length); + if (peSection?.source_stream == null) + throw new Error("PE lost its decoded source"); + + const ambiguous = await provider.execute( + extractRequest(imagePath, join(directory, "ambiguous"), { + target: { kind: "volume", offset: 0 }, + }), + ); + expect(ambiguous.ok).toBe(false); + if (!ambiguous.ok) expect(ambiguous.error._tag).toBe("AnalysisInputError"); + + const extracted = expectOk( + await provider.execute( + extractRequest(imagePath, join(directory, "scoped"), { + target: { + kind: "section", + offset: peSection.offset, + source_stream: peSection.source_stream, + }, + }), + ), + ).value.result as UefiExtractResult; + expect(extracted.files).toHaveLength(1); + const leaf = extracted.files[0]; + expect((await readFile(leaf?.path ?? "")).equals(pe)).toBe(true); + expect(leaf).toMatchObject({ + original_file_range: null, + source_stream: peSection.source_stream, + source_range: { offset: ui.length + 4, length: pe.length }, + }); + expect(extracted.derivations).toHaveLength(2); + const [outer, inner] = extracted.derivations; + expect(outer?.parent_file_range?.offset).toBe( + 72 + 24 + 24 + AMD_ZLIB_HEADER_LENGTH, + ); + expect(inner).toMatchObject({ + parent_file_range: null, + parent_stream: outer?.child_stream, + parent_stream_range: { offset: 72 + 24 + 24 + AMD_ZLIB_HEADER_LENGTH }, + child_stream: peSection.source_stream, + child_path: null, + }); + expect(extracted.coverage).toBe("complete"); + + const wrapper = inspectResult.firmware_volumes[0]?.ffs_files[0]; + for (const [kind, offset] of [ + ["volume", 0], + ["ffs-file", wrapper?.offset ?? -1], + ] as const) { + const scoped = expectOk( + await provider.execute( + extractRequest(imagePath, join(directory, kind), { + target: { kind, offset, source_stream: null }, + }), + ), + ).value.result as UefiExtractResult; + const published = scoped.files.find((file) => file.sha256 === sha256(pe)); + expect((await readFile(published?.path ?? "")).equals(pe)).toBe(true); + expect(scoped.coverage).toBe("complete"); + } +}); + +it("extracts embedded raw-file volume files and targets the nested volume by offset", async () => { + const holeInner = buildFfsFile({ + guid: "25111111-2222-3333-4444-555555555555", + typeCode: 0x07, + payload: buildSection(0x10, Buffer.from("HOLE-NESTED-PAYLOAD", "utf8")), + }); + const holeFv = buildFv({ files: [holeInner] }); + // Raw file body = full FV (zero vector first): the AMI ROM-hole pattern. + const hole = buildFfsFile({ + guid: "27111111-2222-3333-4444-555555555555", + typeCode: 0x01, + payload: holeFv.buffer, + }); + const volume = buildFv({ files: [hole] }); + const directory = await createTestTempDirectory("rea-uefi-provider-"); + const imagePath = join(directory, "hole-image.fi"); + await writeFile(imagePath, buildImage({ volumes: [volume.buffer] })); + const provider = new UefiAnalysisProvider(); + + const inspected = expectOk( + await provider.execute(await inspectRequest(imagePath)), + ); + const inspectResult = inspected.value.result as UefiInspectResult; + const nested = inspectResult.firmware_volumes.find((candidate) => + candidate.logical_path.includes("/embedded/FV@"), + ); + expect(nested).toBeDefined(); + expect(nested?.ffs_files).toHaveLength(1); + + const whole = expectOk( + await provider.execute( + await extractRequest(imagePath, join(directory, "out-all")), + ), + ); + const wholeResult = whole.value.result as UefiExtractResult; + const wholePayload = wholeResult.files.find( + (file) => + file.relative_path.includes("/embedded/FV@") && + file.relative_path.endsWith(".payload.bin"), + ); + expect(wholePayload?.source).toBe("raw-section"); + expect(wholePayload?.parent_logical_path?.includes("/embedded/FV@")).toBe( + true, + ); + expect( + (await readFile(wholePayload?.path ?? "")).equals( + Buffer.from("HOLE-NESTED-PAYLOAD"), + ), + ).toBe(true); + expect(wholeResult.coverage).toBe("complete"); + + const scoped = expectOk( + await provider.execute( + await extractRequest(imagePath, join(directory, "out-nested"), { + target: { kind: "volume", offset: nested?.offset ?? -1 }, + }), + ), + ); + const scopedResult = scoped.value.result as UefiExtractResult; + expect(scopedResult.files).toHaveLength(1); + expect( + (await readFile(scopedResult.files[0]?.path ?? "")).equals( + Buffer.from("HOLE-NESTED-PAYLOAD"), + ), + ).toBe(true); + await provider.close(); +}); + +it("validates requests through the service before execution", async () => { + const provider = new UefiAnalysisProvider(); + const service = new UefiAnalysisService(provider); + const rejected = await service.execute("inspect_uefi_firmware", { + path: "relative/image.fi", + }); + expect(rejected.ok).toBe(false); + if (rejected.ok) return; + expect(rejected.error._tag).toBe("AnalysisInputError"); +}); + +it("publishes repeated raw GUIDs under distinct portable paths and exposes unusable sections as gaps", async () => { + const directory = await createTestTempDirectory("rea-uefi-provider-"); + const imagePath = join(directory, "image.bin"); + const first = buildFfsFile({ + guid: GUID_RAW, + typeCode: 1, + payload: RAW_BODY, + }); + const second = buildFfsFile({ + guid: GUID_RAW, + typeCode: 1, + payload: Buffer.from("other raw bytes"), + }); + const standard = buildCompressionSection( + Buffer.from([0x01, 0x23, 0x45]), + 1, + 172, + ); + const truncated = Buffer.from([0xff, 0x0f, 0, 0x10, 0xde, 0xad]); + const driver = buildFfsFile({ + guid: GUID_DRIVER, + typeCode: 7, + payload: Buffer.concat([standard, truncated]), + }); + await writeFile( + imagePath, + buildFv({ files: [first, second, driver] }).buffer, + ); + const provider = new UefiAnalysisProvider(); + const result = expectOk( + await provider.execute( + extractRequest(imagePath, join(directory, "out"), { + include_compressed: false, + }), + ), + ).value.result as UefiExtractResult; + expect(result.coverage).toBe("partial"); + expect(result.files).toHaveLength(2); + expect( + new Set(result.files.map(({ relative_path }) => relative_path)).size, + ).toBe(2); + expect( + await Promise.all(result.files.map(({ path }) => readFile(path))), + ).toEqual([RAW_BODY, Buffer.from("other raw bytes")]); + expect(result.extraction_gaps).toMatchObject([ + { + kind: "unsupported-compression", + detail: expect.stringContaining("efi-standard"), + }, + { kind: "size-truncated", detail: expect.stringContaining("4095") }, + ]); +}); + +it("publishes valid siblings with truthful coverage for a zero declaration and an empty carrier", async () => { + const valid = buildSection(0x10, MODULE_A); + const emptyCarrier = buildCompressionSection(Buffer.alloc(0), 1, 4); + const zeroSize = Buffer.from([0, 0, 0, 0x10]); + const driver = buildFfsFile({ + guid: GUID_DRIVER, + typeCode: 7, + payload: Buffer.concat([valid, emptyCarrier, zeroSize]), + }); + const directory = await createTestTempDirectory("rea-uefi-provider-"); + const imagePath = join(directory, "image.fi"); + await writeFile(imagePath, buildFv({ files: [driver] }).buffer); + const provider = new UefiAnalysisProvider(); + const result = expectOk( + await provider.execute(extractRequest(imagePath, join(directory, "out"))), + ).value.result as UefiExtractResult; + expect(result.coverage).toBe("partial"); + expect(result.files).toHaveLength(1); + expect((await readFile(result.files[0]?.path ?? "")).equals(MODULE_A)).toBe( + true, + ); + expect(result.extraction_gaps).toMatchObject([ + { kind: "unsupported-compression", range: null }, + { + kind: "unparsed-region", + range: { + offset: 72 + 24 + valid.length + emptyCarrier.length, + length: zeroSize.length, + }, + detail: expect.stringContaining("declared 0 bytes, observed 4"), + }, + ]); +}); + +it("rolls back staged files if the receipts cannot form a valid extraction result", async () => { + const { imagePath, directory } = await writeTestImage({ withGuided: false }); + const provider = new UefiAnalysisProvider(); + const output = join(directory, "out"); + const write = SafeOutputTree.prototype.write; + const writing = vi + .spyOn(SafeOutputTree.prototype, "write") + .mockImplementationOnce(async function (this: SafeOutputTree, ...args) { + const receipt = await write.apply(this, args); + return { ...receipt, sha256: "invalid-receipt-digest" }; + }); + try { + const result = await provider.execute(extractRequest(imagePath, output)); + expect(result.ok).toBe(false); + expect(existsSync(output)).toBe(false); + } finally { + writing.mockRestore(); + await provider.close(); + } +}); + +it.skipIf(!lzmaWorkerAvailable)( + "retains the worker root across a failed descriptor retry and releases its child before root removal", + async () => { + const driver = buildFfsFile({ + guid: GUID_DRIVER, + typeCode: 7, + payload: buildLzmaGuidedSection( + Buffer.from(lzmaPurescript.compressFile(Buffer.from("worker output"))), + ), + }); + const directory = await createTestTempDirectory("rea-uefi-provider-"); + const imagePath = join(directory, "image.fi"); + await writeFile(imagePath, buildFv({ files: [driver] }).buffer); + const provider = new UefiAnalysisProvider(distUefiLzmaWorker); + const create = PrivateRuntimeRoot.create; + const closeHandle = OwnedFileHandle.prototype.close; + const closeRoot = PrivateRuntimeRoot.prototype.close; + let root: PrivateRuntimeRoot | undefined; + let outputHandle: OwnedFileHandle | undefined; + let denyDescriptor = true; + let denyRoot = true; + const creating = vi + .spyOn(PrivateRuntimeRoot, "create") + .mockImplementation(async (options) => { + const created = await create(options); + if (options?.prefix === "rea-uefi-lzma-") root = created; + return created; + }); + const closingHandle = vi + .spyOn(OwnedFileHandle.prototype, "close") + .mockImplementation(async function (this: OwnedFileHandle) { + const outputPath = + root === undefined ? undefined : join(root.path, "output.bin"); + if (outputPath !== undefined && this.handle.fd >= 0) { + const output = await stat(outputPath).catch(() => undefined); + const fd = await this.handle.stat(); + if ( + output !== undefined && + fd.dev === output.dev && + fd.ino === output.ino + ) { + outputHandle = this; + if (denyDescriptor) throw new Error("worker output close denied"); + } + } + return closeHandle.call(this); + }); + const closingRoot = vi + .spyOn(PrivateRuntimeRoot.prototype, "close") + .mockImplementation(async function (this: PrivateRuntimeRoot) { + if (this === root && denyRoot) + throw new Error("worker root removal denied"); + return closeRoot.call(this); + }); + + try { + const result = await provider.execute(inspectRequest(imagePath)); + if (result.ok || root === undefined || outputHandle === undefined) { + throw new Error("worker output descriptor failure was not exercised"); + } + expect(result.error.cleanupResources).toEqual( + expect.arrayContaining([root.path, join(root.path, "output.bin")]), + ); + await expect(provider.close()).rejects.toThrow( + /cleanup remains incomplete/i, + ); + expect(closingRoot.mock.contexts).not.toContain(root); + expect(existsSync(root.path)).toBe(true); + + denyDescriptor = false; + await expect(provider.close()).rejects.toThrow( + /cleanup remains incomplete/i, + ); + expect(outputHandle.handle.fd).toBe(-1); + expect(result.error.cleanupResources).toEqual([root.path]); + expect(existsSync(root.path)).toBe(true); + + denyRoot = false; + await expect(provider.close()).resolves.toBeUndefined(); + expect(existsSync(root.path)).toBe(false); + expect(result.error.cleanupIncomplete).toBe(false); + } finally { + creating.mockRestore(); + closingHandle.mockRestore(); + closingRoot.mockRestore(); + await provider.close(); + } + }, + 45_000, +); + +it("rolls back a tree acquired during failed publication setup without publishing", async () => { + const { imagePath, directory } = await writeTestImage(); + const provider = new UefiAnalysisProvider(); + const output = join(directory, "out"); + const create = SafeOutputTree.create.bind(SafeOutputTree); + const creation = vi + .spyOn(SafeOutputTree, "create") + .mockImplementationOnce(async (path) => { + throw new SafeOutputTreeCreationFailure( + new Error("setup failed"), + await create(path), + ); + }); + try { + const result = await provider.execute(extractRequest(imagePath, output)); + expect(result.ok).toBe(false); + if (!result.ok) + expect(result.error.diagnostics?.reason).toBe("setup failed"); + expect(existsSync(output)).toBe(false); + } finally { + creation.mockRestore(); + await provider.close(); + } +}); + +it("waits for committed output finalization during late cancellation and retries retained cleanup", async () => { + const { imagePath, directory } = await writeTestImage({ withGuided: false }); + const provider = new UefiAnalysisProvider(); + const output = join(directory, "out"); + const controller = new AbortController(); + const committed = createDeferred(); + const releaseFinalization = createDeferred(); + const commit = SafeOutputTree.prototype.commit; + const committing = vi + .spyOn(SafeOutputTree.prototype, "commit") + .mockImplementationOnce(async function (this: SafeOutputTree, signal) { + await commit.call(this, signal); + committed.resolve(); + await releaseFinalization.promise; + throw new Error("commit handle close failed"); + }); + const rollback = vi + .spyOn(SafeOutputTree.prototype, "rollback") + .mockRejectedValueOnce(new Error("close still denied")); + try { + let settled = false; + const executing = provider + .execute(extractRequest(imagePath, output), { signal: controller.signal }) + .finally(() => { + settled = true; + }); + await committed.promise; + const queued = new AbortController(); + const queuedWork = provider.execute(inspectRequest(imagePath), { + signal: queued.signal, + }); + queued.abort("queued stop"); + const queuedResult = await queuedWork; + expect(queuedResult).toMatchObject({ + ok: false, + error: { _tag: "AnalysisCancelledError", cause: "queued stop" }, + }); + controller.abort("late stop"); + const closing = provider.close(); + await Promise.resolve(); + expect(settled).toBe(false); + releaseFinalization.resolve(); + const result = await executing; + expect(result).toMatchObject({ + ok: false, + error: { + partialObservation: { + kind: "uefi", + result: { + output_directory: expect.any(String), + published_bytes: MODULE_A.length + RAW_BODY.length, + }, + }, + }, + }); + await closing; + expect(rollback).toHaveBeenCalledTimes(2); + if (!result.ok) expect(result.error.cleanupIncomplete).toBe(false); + expect(existsSync(output)).toBe(true); + } finally { + releaseFinalization.resolve(); + committing.mockRestore(); + rollback.mockRestore(); + await provider.close(); + } +}); + +it("preserves the timeout and failed rollback when the deadline expires before commit", async () => { + const { imagePath, directory } = await writeTestImage({ withGuided: false }); + const provider = new UefiAnalysisProvider(); + const output = join(directory, "out"); + const write = SafeOutputTree.prototype.write; + let expiredClock: ReturnType | undefined; + const writing = vi + .spyOn(SafeOutputTree.prototype, "write") + .mockImplementationOnce(async function (this: SafeOutputTree, ...args) { + const receipt = await write.apply(this, args); + const afterDeadline = performance.now() + UEFI_FIRMWARE_LIMITS.timeoutMs; + expiredClock = vi + .spyOn(performance, "now") + .mockReturnValue(afterDeadline); + return receipt; + }); + const rollback = vi + .spyOn(SafeOutputTree.prototype, "rollback") + .mockRejectedValueOnce(new Error("rollback denied")); + try { + const result = await provider.execute(extractRequest(imagePath, output)); + expect(result).toMatchObject({ + ok: false, + error: { + cleanupIncomplete: true, + cleanupPrimary: { + _tag: "AnalysisTimeoutError", + timeoutMs: UEFI_FIRMWARE_LIMITS.timeoutMs, + }, + }, + }); + await provider.close(); + expect(rollback).toHaveBeenCalledTimes(2); + expect(existsSync(output)).toBe(false); + } finally { + expiredClock?.mockRestore(); + writing.mockRestore(); + rollback.mockRestore(); + await provider.close(); + } +}); + +it.each([ + ["unrecognized", Buffer.from("unrecognized flash bytes")], + ["erased", Buffer.alloc(64, 0xff)], +])( + "reports a full-range gap for a %s image without volumes", + async (_name, bytes) => { + const directory = await createTestTempDirectory("rea-uefi-unparsed-"); + const path = join(directory, "image.fd"); + await writeFile(path, bytes); + const provider = new UefiAnalysisProvider(); + try { + const request = extractRequest(path, join(directory, "out")); + const result = expectOk(await provider.execute(request)).value + .result as UefiExtractResult; + expect(result).toMatchObject({ + coverage: "partial", + files: [], + extraction_gaps: [ + { + kind: "unparsed-region", + logical_path: "flash", + source_stream: null, + range: { offset: 0, length: bytes.length }, + }, + ], + }); + } finally { + await provider.close(); + } + }, +); + +it("scopes a short non-erased FFS suffix to its own volume", async () => { + const raw = buildFfsFile({ + guid: GUID_RAW, + typeCode: 1, + payload: Buffer.alloc(3992, 0x42), + }); + const damaged = buildFv({ files: [raw] }).buffer; + damaged.fill(0x22, 0xff8); + const sibling = buildFv({ + files: [ + buildFfsFile({ + guid: GUID_DRIVER, + typeCode: 7, + payload: buildSection(0x10, MODULE_A), + }), + ], + }).buffer; + const directory = await createTestTempDirectory("rea-uefi-scoped-tail-"); + const path = join(directory, "image.fd"); + await writeFile(path, Buffer.concat([damaged, sibling])); + + const provider = new UefiAnalysisProvider(); + try { + const extract = async (name: string, offset: number) => + expectOk( + await provider.execute( + extractRequest(path, join(directory, name), { + target: { kind: "volume", offset }, + }), + ), + ).value.result as UefiExtractResult; + const intact = await extract("sibling", 0x1000); + expect(intact.coverage).toBe("complete"); + expect(intact.extraction_gaps).toEqual([]); + expect(intact.files.map(({ sha256 }) => sha256)).toEqual([ + sha256(MODULE_A), + ]); + + const parsed = await extract("damaged", 0); + expect(parsed.coverage).toBe("partial"); + expect(parsed.extraction_gaps).toMatchObject([ + { + kind: "unparsed-region", + logical_path: "flash/FV@0x0", + source_stream: null, + range: { offset: 0xff8, length: 8 }, + }, + ]); + } finally { + await provider.close(); + } +}); + +it("reports an incomplete section suffix for the containing file", async () => { + const section = buildSection(0x10, MODULE_A); + const file = buildFfsFile({ + guid: GUID_DRIVER, + typeCode: 7, + payload: Buffer.concat([section, Buffer.from([0x12, 0x34])]), + }); + const fv = buildFv({ files: [file] }); + const directory = await createTestTempDirectory("rea-uefi-scoped-section-"); + const path = join(directory, "image.fd"); + await writeFile(path, fv.buffer); + + const provider = new UefiAnalysisProvider(); + try { + const result = expectOk( + await provider.execute( + extractRequest(path, join(directory, "file"), { + target: { kind: "ffs-file", offset: fv.headerLength }, + }), + ), + ).value.result as UefiExtractResult; + expect(result.coverage).toBe("partial"); + expect(result.files.map(({ sha256 }) => sha256)).toEqual([ + sha256(MODULE_A), + ]); + expect(result.extraction_gaps).toMatchObject([ + { + kind: "unparsed-region", + source_stream: null, + range: { offset: fv.headerLength + 24 + section.length, length: 2 }, + }, + ]); + } finally { + await provider.close(); + } +}); + +it("limits coverage to the section that contains depth-limited children", async () => { + const raw = buildSection(0x10, MODULE_A); + const nested = buildSection(0x03, buildSection(0x03, raw)); + const driver = buildFfsFile({ + guid: GUID_DRIVER, + typeCode: 7, + payload: Buffer.concat([raw, nested]), + }); + const fv = buildFv({ files: [driver] }); + const directory = await createTestTempDirectory("rea-uefi-scoped-depth-"); + const path = join(directory, "image.fd"); + await writeFile(path, fv.buffer); + + const provider = new UefiAnalysisProvider(); + try { + const extract = async ( + name: string, + target: Extract< + UefiRequest, + { operation: "extract_uefi_firmware" } + >["input"]["target"], + ) => + expectOk( + await provider.execute( + extractRequest(path, join(directory, name), { + max_depth: 1, + target, + }), + ), + ).value.result as UefiExtractResult; + const offset = fv.headerLength + 24; + const sibling = await extract("sibling", { kind: "section", offset }); + expect(sibling.coverage).toBe("complete"); + expect(sibling.extraction_gaps).toEqual([]); + const enclosing = await extract("enclosed", { + kind: "section", + offset: offset + raw.length, + }); + expect(enclosing.coverage).toBe("partial"); + expect(enclosing.extraction_gaps).toMatchObject([ + { + kind: "depth-limited", + source_stream: null, + range: { offset: offset + raw.length + 8, length: raw.length }, + }, + ]); + } finally { + await provider.close(); + } +}); + +it("maps a decoded FV-image section and its PE32 sibling in the original chain", async () => { + const embedded = buildSection(0x17, buildFv({ files: [] }).buffer); + const peerBytes = Buffer.from("independently selectable PE32 body"); + const decoded = Buffer.concat([embedded, buildSection(0x10, peerBytes)]); + const file = buildFfsFile({ + guid: GUID_DRIVER, + typeCode: 7, + payload: amdZlibSection(decoded), + }); + const directory = await createTestTempDirectory( + "rea-uefi-mixed-decoded-chain-", + ); + const path = join(directory, "image.fd"); + await writeFile(path, buildFv({ files: [file] }).buffer); + + const provider = new UefiAnalysisProvider(); + try { + const inspection = expectOk(await provider.execute(inspectRequest(path))) + .value.result as UefiInspectResult; + const outer = inspection.firmware_volumes[0]?.ffs_files[0]?.sections; + const embeddedSection = outer?.find(({ type_code }) => type_code === 0x17); + const pe = outer?.find(({ type_code }) => type_code === 0x10); + expect(embeddedSection?.sub_volumes).toEqual([ + inspection.firmware_volumes[1]?.logical_path, + ]); + expect(pe).toMatchObject({ + offset: embedded.length, + source_stream: outer?.[0]?.logical_path, + }); + expect(inspection.coverage).toBe("complete"); + if (pe === undefined) throw new Error("decoded sibling was lost"); + + const extraction = expectOk( + await provider.execute( + extractRequest(path, join(directory, "out"), { + target: { + kind: "section", + offset: embedded.length, + source_stream: pe.source_stream, + }, + }), + ), + ).value.result as UefiExtractResult; + expect(extraction.coverage).toBe("complete"); + expect(extraction.extraction_gaps).toEqual([]); + expect(extraction.files).toMatchObject([ + { + sha256: sha256(peerBytes), + source_stream: pe.source_stream, + source_range: { offset: embedded.length + 4, length: peerBytes.length }, + }, + ]); + } finally { + await provider.close(); + } +}); + +it("uses common-header framing for an unknown decoded section and keeps its PE32 sibling selectable", async () => { + const unknown = buildSection(0x80, Buffer.from("vendor record")); + const pe = buildSection(0x10, MODULE_A); + const suffix = Buffer.from([0x12, 0x34]); + const file = buildFfsFile({ + guid: GUID_DRIVER, + typeCode: 7, + payload: amdZlibSection(Buffer.concat([unknown, pe, suffix])), + }); + const directory = await createTestTempDirectory("rea-uefi-unknown-frame-"); + const path = join(directory, "image.fd"); + await writeFile(path, buildFv({ files: [file] }).buffer); + + const provider = new UefiAnalysisProvider(); + try { + const inspected = expectOk(await provider.execute(inspectRequest(path))) + .value.result as UefiInspectResult; + const sections = inspected.firmware_volumes[0]?.ffs_files[0]?.sections; + expect(sections?.slice(1)).toMatchObject([ + { type_code: 0x80, type_name: "unknown", offset: 0 }, + { type_code: 0x10, type_name: "pe32", offset: unknown.length }, + ]); + expect(inspected.coverage).toBe("partial"); + const source = sections?.[0]?.logical_path; + if (source === undefined) throw new Error("decoded source was lost"); + + const selected = expectOk( + await provider.execute( + extractRequest(path, join(directory, "pe"), { + target: { + kind: "section", + offset: unknown.length, + source_stream: source, + }, + }), + ), + ).value.result as UefiExtractResult; + expect(selected.coverage).toBe("complete"); + expect(selected.files).toMatchObject([{ sha256: sha256(MODULE_A) }]); + + const whole = expectOk( + await provider.execute(extractRequest(path, join(directory, "whole"))), + ).value.result as UefiExtractResult; + expect(whole.extraction_gaps).toMatchObject([ + { + kind: "unparsed-region", + source_stream: source, + range: { offset: unknown.length + pe.length, length: suffix.length }, + }, + ]); + } finally { + await provider.close(); + } +}); + +it.each([ + { + name: "GUID-defined", + declaredLength: 24, + buildMalformedSection: () => { + const section = buildGuidedSection({ + definitionGuid: GUID_GUIDED, + body: Buffer.alloc(0), + }); + section.writeUInt16LE(20, 20); + return section; + }, + }, + { + name: "compression", + declaredLength: 9, + buildMalformedSection: () => buildCompressionSection(Buffer.alloc(0), 0, 1), + }, +])( + "retains decoded siblings after a malformed $name section", + async ({ buildMalformedSection, declaredLength }) => { + const malformed = buildMalformedSection(); + const file = buildFfsFile({ + guid: GUID_DRIVER, + typeCode: 7, + payload: amdZlibSection( + Buffer.concat([malformed, buildSection(0x10, MODULE_A)]), + ), + }); + const directory = await createTestTempDirectory( + "rea-uefi-malformed-frame-", + ); + const path = join(directory, "image.fd"); + await writeFile(path, buildFv({ files: [file] }).buffer); + + const provider = new UefiAnalysisProvider(); + try { + const inspected = expectOk(await provider.execute(inspectRequest(path))) + .value.result as UefiInspectResult; + const sections = inspected.firmware_volumes[0]?.ffs_files[0]?.sections; + const source = sections?.[0]?.logical_path; + if (source === undefined) throw new Error("decoded source was lost"); + expect(inspected.coverage).toBe("partial"); + expect(sections?.slice(1)).toMatchObject([ + { offset: 0, malformed: true, source_stream: source }, + { offset: malformed.length, type_name: "pe32", source_stream: source }, + ]); + + const whole = expectOk( + await provider.execute(extractRequest(path, join(directory, "whole"))), + ).value.result as UefiExtractResult; + expect(whole.extraction_gaps).toMatchObject([ + { + kind: "unparsed-region", + source_stream: source, + range: { offset: 0, length: declaredLength }, + }, + ]); + + const selected = expectOk( + await provider.execute( + extractRequest(path, join(directory, "pe"), { + target: { + kind: "section", + offset: malformed.length, + source_stream: source, + }, + }), + ), + ).value.result as UefiExtractResult; + expect(selected.coverage).toBe("complete"); + expect(selected.extraction_gaps).toEqual([]); + expect(selected.files).toMatchObject([{ sha256: sha256(MODULE_A) }]); + } finally { + await provider.close(); + } + }, +); + +const verifyOutputLimitCoverage = async ( + section: Buffer, + workerPath?: string, +) => { + const file = buildFfsFile({ + guid: GUID_DRIVER, + typeCode: 7, + payload: section, + }); + const vol = buildFv({ files: [file] }); + const directory = await createTestTempDirectory("rea-uefi-decode-limit-"); + const path = join(directory, "image.fd"); + await writeFile(path, vol.buffer); + const provider = new UefiAnalysisProvider(workerPath); + try { + const inspected = expectOk(await provider.execute(inspectRequest(path))) + .value.result as UefiInspectResult; + expect(inspected.coverage).toBe("partial"); + const extracted = expectOk( + await provider.execute( + extractRequest(path, join(directory, "out"), { + include_compressed: false, + }), + ), + ).value.result as UefiExtractResult; + expect(extracted.coverage).toBe("partial"); + expect(extracted.files).toEqual([]); + expect(extracted.extraction_gaps).toMatchObject([ + { + kind: "size-truncated", + source_stream: null, + detail: expect.stringMatching(/exceeds.*bytes/u), + }, + ]); + } finally { + await provider.close(); + } +}; + +it("keeps a real zlib output-limit failure distinct from unsupported compression", async () => { + const bytes = Buffer.alloc(UEFI_FIRMWARE_LIMITS.lzmaOutputBytes + 1); + buildFv({ files: [] }).buffer.copy(bytes); + await verifyOutputLimitCoverage(amdZlibSection(bytes)); +}); + +it.skipIf(!lzmaWorkerAvailable)( + "keeps the owned LZMA worker's declared output limit across its reply boundary", + async () => { + const header = Buffer.alloc(13); + header[0] = 0x5d; + header.writeUInt32LE(4096, 1); + header.writeBigUInt64LE( + BigInt(UEFI_FIRMWARE_LIMITS.lzmaOutputBytes + 1), + 5, + ); + await verifyOutputLimitCoverage( + buildLzmaGuidedSection(header), + distUefiLzmaWorker, + ); + }, +); + +it("extracts directly readable guided children regardless of a compression passthrough choice", async () => { + const child = buildSection(0x19, MODULE_A); + const crc = buildGuidedSection({ + definitionGuid: "fc1bcdb0-7d31-49aa-936a-a4600d9dd083", + body: child, + dataOffset: 28, + attributes: 2, + }); + const ordinary = buildGuidedSection({ + definitionGuid: GUID_GUIDED, + body: child, + }); + const file = buildFfsFile({ + guid: GUID_DRIVER, + typeCode: 7, + payload: Buffer.concat([crc, ordinary]), + }); + const directory = await createTestTempDirectory("rea-uefi-guided-stored-"); + const path = join(directory, "image.fd"); + await writeFile(path, buildFv({ files: [file] }).buffer); + const provider = new UefiAnalysisProvider(); + try { + const inspected = expectOk(await provider.execute(inspectRequest(path))) + .value.result as UefiInspectResult; + expect(inspected.coverage).toBe("complete"); + expect( + inspected.firmware_volumes[0]?.ffs_files[0]?.sections.map( + ({ type_name, compression }) => [type_name, compression.kind], + ), + ).toEqual([ + ["guid-defined", "crc32-guided"], + ["raw", "none"], + ["guid-defined", "unknown-guid"], + ["raw", "none"], + ]); + const result = expectOk( + await provider.execute( + extractRequest(path, join(directory, "out"), { + include_compressed: false, + }), + ), + ).value.result as UefiExtractResult; + expect(result.extraction_gaps).toEqual([]); + expect(result.files).toMatchObject([ + { source: "raw-section", sha256: sha256(MODULE_A) }, + { source: "raw-section", sha256: sha256(MODULE_A) }, + ]); + } finally { + await provider.close(); + } +}); + +it("publishes typed leaf payloads without their headers and scopes nonzero alignment bytes", async () => { + const guid = guidBytes(GUID_GUIDED); + const freeformPayload = Buffer.from([0x61]); + const versionPayload = Buffer.from("v\0", "utf16le"); + const freeform = buildSection(0x18, Buffer.concat([guid, freeformPayload])); + freeform.fill(0x77, 21); + const version = buildSection( + 0x14, + Buffer.concat([Buffer.from([0x34, 0x12]), versionPayload]), + ); + const file = buildFfsFile({ + guid: GUID_DRIVER, + typeCode: 7, + payload: Buffer.concat([freeform, version]), + }); + const fv = buildFv({ files: [file] }); + const directory = await createTestTempDirectory("rea-uefi-leaf-header-"); + const path = join(directory, "image.fd"); + await writeFile(path, fv.buffer); + const provider = new UefiAnalysisProvider(); + try { + const inspected = expectOk(await provider.execute(inspectRequest(path))) + .value.result as UefiInspectResult; + expect(inspected.firmware_volumes[0]?.ffs_files[0]?.sections).toMatchObject( + [ + { type_name: "freeform-subtype-guid", header_length: 20 }, + { type_name: "version", header_length: 6 }, + ], + ); + const result = expectOk( + await provider.execute(extractRequest(path, join(directory, "out"))), + ).value.result as UefiExtractResult; + expect(result.files).toMatchObject([ + { + source_range: { offset: 116, length: 1 }, + sha256: sha256(freeformPayload), + }, + { + source_range: { offset: 126, length: 4 }, + sha256: sha256(versionPayload), + }, + ]); + expect(result.extraction_gaps).toMatchObject([ + { kind: "unparsed-region", range: { offset: 117, length: 3 } }, + ]); + } finally { + await provider.close(); + } +}); + +it.each([ + { + name: "empty carrier", + section: buildGuidedSection({ + definitionGuid: GUID_AMD_ZLIB, + body: Buffer.alloc(0), + }), + message: "Empty zlib carrier", + }, + { + name: "unconsumed suffix", + section: amdZlibSection( + buildSection(0x19, MODULE_A), + Buffer.from("ordinary trailing bytes"), + ), + message: "declared compressed bytes", + }, +])( + "reports partial inspection and extraction for a supported codec with $name", + async ({ section, message }) => { + const file = buildFfsFile({ + guid: GUID_DRIVER, + typeCode: 7, + payload: section, + }); + const directory = await createTestTempDirectory("rea-uefi-codec-input-"); + const path = join(directory, "image.fd"); + await writeFile(path, buildFv({ files: [file] }).buffer); + const provider = new UefiAnalysisProvider(); + try { + const inspected = expectOk(await provider.execute(inspectRequest(path))) + .value.result as UefiInspectResult; + expect(inspected.coverage).toBe("partial"); + expect(inspected.limitations.join(" ")).toContain(message); + const result = expectOk( + await provider.execute( + extractRequest(path, join(directory, "out"), { + include_compressed: false, + }), + ), + ).value.result as UefiExtractResult; + expect(result.derivations).toEqual([]); + expect(result.files).toEqual([]); + expect(result.extraction_gaps).toMatchObject([ + { kind: "unparsed-region", detail: expect.stringContaining(message) }, + ]); + } finally { + await provider.close(); + } + }, +); + +it.each(["standalone", "pad-file"] as const)( + "walks FFS after a %s FV extension and preserves a sibling after an invalid header", + async (extendedHeader) => { + const invalid = buildFfsFile({ + guid: GUID_DRIVER, + typeCode: 1, + payload: Buffer.alloc(104), + }).subarray(0, 24); + invalid[23] = 0x1f; // Effective HEADER_INVALID with erase polarity one. + const sibling = buildFfsFile({ + guid: GUID_RAW, + typeCode: 1, + payload: RAW_BODY, + }); + const fv = buildFv({ files: [invalid, sibling], extendedHeader }); + const invalidOffset = extendedHeader === "standalone" ? 104 : 128; + const directory = await createTestTempDirectory( + "rea-uefi-ffs-after-metadata-", + ); + const path = join(directory, "image.fd"); + await writeFile(path, fv.buffer); + const provider = new UefiAnalysisProvider(); + try { + const inspected = expectOk(await provider.execute(inspectRequest(path))) + .value.result as UefiInspectResult; + const files = inspected.firmware_volumes[0]?.ffs_files; + expect( + files?.map(({ type_name, offset, length }) => [ + type_name, + offset, + length, + ]), + ).toEqual([ + ...(extendedHeader === "pad-file" ? [["pad", 72, 52]] : []), + ["raw", invalidOffset, 24], + ["raw", invalidOffset + 24, sibling.length], + ]); + const result = expectOk( + await provider.execute(extractRequest(path, join(directory, "out"))), + ).value.result as UefiExtractResult; + expect(result.files).toMatchObject([ + { + sha256: sha256(RAW_BODY), + source_range: { offset: invalidOffset + 48, length: RAW_BODY.length }, + }, + ]); + expect( + result.extraction_gaps.filter(({ kind }) => kind !== "pad-file"), + ).toMatchObject([ + { + kind: "unparsed-region", + range: { offset: invalidOffset, length: 24 }, + }, + ]); + } finally { + await provider.close(); + } + }, +); + +it.each([ + { checksum: 0, entryBasis: "scanned" }, + { checksum: 0x000c0001, entryBasis: "amd-psp-first" }, +])( + "uses a PSP directory for image provenance only after verifying its checksum ($entryBasis)", + async ({ checksum, entryBasis }) => { + const prefix = Buffer.alloc(0x1000, 0); + prefix.write("$PL2", 0, "ascii"); + prefix.writeUInt32LE(checksum, 4); + prefix.writeUInt32LE(1, 8); + const directory = await createTestTempDirectory("rea-uefi-psp-basis-"); + const path = join(directory, "image.fd"); + await writeFile( + path, + Buffer.concat([prefix, buildFv({ files: [] }).buffer]), + ); + const provider = new UefiAnalysisProvider(); + try { + const result = expectOk(await provider.execute(inspectRequest(path))) + .value.result as UefiInspectResult; + expect(result.flash_image.entry_basis).toBe(entryBasis); + expect(result.firmware_volumes[0]?.offset).toBe(prefix.length); + if (checksum === 0) + expect(result.psp_candidates).toMatchObject([ + { reason: "checksum-mismatch" }, + ]); + else + expect(result.psp_tables).toMatchObject([ + { + table_magic: "$PL2", + entries: [{ location_basis: "declared-unverified" }], + }, + ]); + } finally { + await provider.close(); + } + }, +); + +it("retains a signed guided section as opaque when its processing flag is clear", async () => { + const child = buildSection(0x19, Buffer.from("stored data")); + const section = buildGuidedSection({ + definitionGuid: "0f9d89e8-9259-4f76-a5af-0c89e34023df", + body: child, + attributes: 0, + }); + const file = buildFfsFile({ + guid: GUID_DRIVER, + typeCode: 7, + payload: section, + }); + const directory = await createTestTempDirectory("rea-uefi-signed-opaque-"); + const path = join(directory, "image.fd"); + await writeFile(path, buildFv({ files: [file] }).buffer); + const provider = new UefiAnalysisProvider(); + try { + const inspected = expectOk(await provider.execute(inspectRequest(path))) + .value.result as UefiInspectResult; + expect(inspected.coverage).toBe("partial"); + expect( + inspected.firmware_volumes[0]?.ffs_files[0]?.sections.map( + ({ type_name }) => type_name, + ), + ).toEqual(["guid-defined"]); + const extracted = expectOk( + await provider.execute( + extractRequest(path, join(directory, "out"), { + include_compressed: false, + }), + ), + ).value.result as UefiExtractResult; + expect(extracted.files).toEqual([]); + expect(extracted.extraction_gaps).toMatchObject([ + { + kind: "unknown-guid-handler", + range: { offset: 120, length: child.length }, + }, + ]); + } finally { + await provider.close(); + } +}); diff --git a/src/uefi/UefiAnalysisProvider.ts b/src/uefi/UefiAnalysisProvider.ts new file mode 100644 index 0000000000..4a067c67c6 --- /dev/null +++ b/src/uefi/UefiAnalysisProvider.ts @@ -0,0 +1,926 @@ +import { nodeCodecResult } from "../kernel/nodeCodecResult.js"; +import type { UefiDecodeFormat } from "./FfsSections.js"; +import { sha256Hex } from "../kernel/sha256Hex.js"; +import { hostRangeErrorKind } from "../domain/parseFailure.js"; +import { errorMessage } from "../kernel/errorMessage.js"; +import { randomUUID } from "node:crypto"; +import { writeFile } from "node:fs/promises"; +import { inflate } from "node:zlib"; +import { promisify } from "node:util"; +import { join } from "node:path"; +import { fileURLToPath } from "node:url"; +import { + ArtifactResourceScope, + readStableArtifact, + AnalysisCleanupLease, + AnalysisCleanupLeaseGroup, +} from "../resources/index.js"; +import { + createAnalysisExecution, + type AnalysisExecution, + type ExecutionOptions, + type ProviderAvailability, +} from "../ports/AnalysisProvider.js"; +import type { UefiAnalysisPort } from "../ports/uefi/UefiAnalysisPort.js"; +import { + cancelledBy, + carriedReason, + AnalysisInputError, + AnalysisTimeoutError, +} from "../domain/analysisErrorCore.js"; +import { analysisErrorWithCleanupDependencies } from "../domain/analysisErrorCleanup.js"; +import { ProviderCleanupError } from "../domain/providerCleanupError.js"; +import { jsonValueSchema } from "../domain/jsonValue.js"; +import type { AnalysisError } from "../domain/analysisErrorBase.js"; +import type { Result } from "../domain/result.js"; +import { UEFI_FIRMWARE_LIMITS } from "../domain/uefi/uefiLimits.js"; +import { + uefiResultSchemas, + type UefiExtractResult, + type UefiInspectResult, + type UefiNvramInspectResult, + type UefiRequest, +} from "../domain/uefi/uefiFirmwareAnalysis.js"; +import { + OwnedCommandFailure, + runOwnedCommand, +} from "../process/OwnedCommand.js"; +import { + processInspectionFailure, + retainProcessInspectionCleanup, +} from "../providers/OwnedCommandCleanup.js"; +import { PrivateRuntimeRoot } from "../process/PrivateRuntimeRoot.js"; +import type { + UefiImageScanSummary, + UefiDecodeResult, + UefiPayload, +} from "./UefiImageScan.js"; +import { scanUefiImage } from "./UefiImageScan.js"; +import { scanAmiNvramStores } from "./UefiNvram.js"; +import { uefiFailureDialect } from "./UefiFailures.js"; +import { classifyProviderFailure } from "../providers/classifyProviderFailure.js"; +import { + publishUefiFiles, + type UefiPublicationEntry, +} from "./UefiPublication.js"; + +import { lzmaReplySchema } from "./UefiLzmaProtocol.js"; +import { UEFI_PROVIDER_IDENTITY } from "./UefiProviderIdentity.js"; + +const inflateBounded = promisify(inflate); + +const hex = (value: number): string => `0x${value.toString(16)}`; + +const targetInputError = (message: string): AnalysisInputError => + new AnalysisInputError("extract_uefi_firmware", { cause: undefined }, [ + { path: ["target"], reason: "invalid_value", message }, + ]); + +type ExtractInput = Extract< + UefiRequest, + { operation: "extract_uefi_firmware" } +>["input"]; +type ExtractedFile = UefiExtractResult["files"][number]; +type ExtractionRange = UefiPayload["range"]; + +/** Offsets are scoped to the scanner's exact stream and may repeat across streams. */ +const selectTarget = ( + scan: UefiImageScanSummary, + target: ExtractInput["target"], +) => { + if (target.kind === "whole-image") { + return { + offset: 0, + length: scan.inputSize, + logical_path: "flash", + source_stream: null, + }; + } + const matches = (record: { + offset: number; + source_stream: string | null; + }): boolean => + record.offset === target.offset && + (target.source_stream === undefined || + record.source_stream === target.source_stream); + const records = + target.kind === "volume" + ? scan.volumes + : target.kind === "ffs-file" + ? scan.volumes.flatMap((volume) => volume.ffs_files) + : scan.volumes.flatMap((volume) => + volume.ffs_files.flatMap((file) => file.sections), + ); + const selected = records.filter(matches); + const record = selected[0]; + if (record === undefined) { + throw targetInputError( + `No mapped ${target.kind} at ${hex(target.offset)} in the selected stream.`, + ); + } + if (selected.length > 1) { + throw targetInputError( + `The ${target.kind} offset ${hex(target.offset)} appears in multiple streams. Select one with source_stream: ${selected.map(({ source_stream }) => JSON.stringify(source_stream)).join(", ")}.`, + ); + } + return record; +}; + +/** + * Pure TypeScript UEFI provider: static flash-image cartography plus budgeted + * extraction. LZMA payloads decode through one owned, freshly spawned node + * worker per stream; budgets are enforced by the worker reply contract. No + * prlimit wrapper and no external tools are involved. + */ +export class UefiAnalysisProvider implements UefiAnalysisPort { + #closing = false; + #tail: Promise = Promise.resolve(); + readonly #resources = new ArtifactResourceScope(); + readonly #workerModulePath: string; + + constructor( + workerModulePath: string = fileURLToPath( + new URL("./UefiLzmaWorker.js", import.meta.url), + ), + ) { + this.#workerModulePath = workerModulePath; + } + + async inspectAvailability(): Promise { + return { + status: "available", + code: null, + reason: null, + diagnostics: { + decoder: "lzma-purejs (owned worker)", + external_tools: "none", + }, + }; + } + + async close(): Promise { + this.#closing = true; + await this.#tail.catch(() => undefined); + await this.#resources.close(); + } + + async execute( + request: UefiRequest, + options?: ExecutionOptions, + ): Promise> { + if (this.#closing) { + return { + ok: false, + error: new AnalysisInputError(request.operation, { cause: undefined }, [ + { + path: [], + reason: "invalid_value", + message: "rea-uefi provider is closed; construct a new provider.", + }, + ]), + }; + } + // Admit one operation at a time so the advertised single decode-worker lane + // cannot become one worker per overlapping call. + const signal = options?.signal; + if (signal?.aborted) return this.#cancelled(request, signal.reason); + const started = { value: false }; + const queued = this.#serialize(async () => { + started.value = true; + // A queued request cancelled while waiting must not run behind the active + // one; skip it when it reaches the head of the queue. + if (signal?.aborted) return this.#cancelled(request, signal.reason); + return this.#executeWithDeadline(request, options); + }); + // Let a caller stop waiting on a not-yet-started request immediately. + return signal === undefined + ? queued + : this.#raceWithAbort(queued, request, signal, started); + } + + #cancelled( + request: UefiRequest, + reason: unknown, + ): Result { + return { + ok: false, + error: cancelledBy(request.operation, carriedReason(reason)), + }; + } + + #raceWithAbort( + queued: Promise>, + request: UefiRequest, + signal: AbortSignal, + started: { value: boolean }, + ): Promise> { + if (signal.aborted && !started.value) { + return Promise.resolve(this.#cancelled(request, signal.reason)); + } + return new Promise>((resolve) => { + const onAbort = () => { + // Only a not-yet-started job may return early; a started job must finish + // so its cleanup and completed work are preserved. + if (!started.value) resolve(this.#cancelled(request, signal.reason)); + }; + signal.addEventListener("abort", onAbort, { once: true }); + queued.then( + (result) => { + signal.removeEventListener("abort", onAbort); + resolve(result); + }, + (cause: unknown) => { + signal.removeEventListener("abort", onAbort); + resolve({ + ok: false, + error: classifyProviderFailure( + cause, + uefiFailureDialect(request.operation, request.input.path), + ), + }); + }, + ); + }); + } + + #serialize(task: () => Promise): Promise { + const run = this.#tail.then(task, task); + this.#tail = run.then( + () => undefined, + () => undefined, + ); + return run; + } + + /** Bound the whole request with one deadline, including every decode stage. */ + async #executeWithDeadline( + request: UefiRequest, + options?: ExecutionOptions, + ): Promise> { + const controller = new AbortController(); + const timeoutMs = UEFI_FIRMWARE_LIMITS.timeoutMs; + const deadline = performance.now() + timeoutMs; + const deadlineReason = new AnalysisTimeoutError( + request.operation, + timeoutMs, + ); + const expire = () => controller.abort(deadlineReason); + const timer = setTimeout(expire, timeoutMs); + const parent = options?.signal; + const onParentAbort = () => + controller.abort( + cancelledBy(request.operation, carriedReason(parent?.reason)), + ); + if (parent?.aborted) onParentAbort(); + else parent?.addEventListener("abort", onParentAbort, { once: true }); + const checkpoint = (): void => { + if (performance.now() >= deadline) expire(); + controller.signal.throwIfAborted(); + }; + try { + return { + ok: true, + value: await this.#executeWithSignal( + request, + controller.signal, + checkpoint, + ), + }; + } catch (cause: unknown) { + return { + ok: false, + error: classifyProviderFailure( + cause, + uefiFailureDialect(request.operation, request.input.path), + ), + }; + } finally { + clearTimeout(timer); + parent?.removeEventListener("abort", onParentAbort); + } + } + + async #executeWithSignal( + request: UefiRequest, + signal: AbortSignal, + checkpoint: () => void, + ): Promise { + const finishObservation = (value: AnalysisExecution): AnalysisExecution => { + try { + checkpoint(); + return value; + } catch (cause: unknown) { + throw classifyProviderFailure( + cause, + uefiFailureDialect(request.operation, request.input.path), + ).retainPartialObservation({ + kind: "uefi", + result: value.result, + provenance: jsonValueSchema.parse(value.subject), + }); + } + }; + return this.#resources.run(async () => { + checkpoint(); + const snapshot = await readStableArtifact( + request.input.path, + UEFI_FIRMWARE_LIMITS.inputBytes, + signal, + undefined, + this.#resources, + ); + checkpoint(); + if (request.operation === "inspect_uefi_nvram") { + const value = this.#inspectNvram( + request, + snapshot.sha256, + snapshot.bytes, + checkpoint, + ); + return finishObservation(value); + } + 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, + }, + ({ payload, format, maxOutputBytes }) => + this.#decodeStream( + request.operation, + payload, + format, + maxOutputBytes, + signal, + ), + checkpoint, + ); + checkpoint(); + if (request.operation === "extract_uefi_firmware") { + return this.#extract( + request, + snapshot.sha256, + scan, + signal, + checkpoint, + ); + } + return finishObservation(this.#inspect(request, snapshot.sha256, scan)); + }); + } + + #inspect( + request: Extract, + imageSha256: string, + scan: UefiImageScanSummary, + ): AnalysisExecution { + const firstVolume = scan.volumes[0]; + const entryBasis = + firstVolume === undefined + ? ("unknown" as const) + : firstVolume.offset === 0 + ? ("fv-at-zero" as const) + : scan.pspTables.some((table) => table.offset < firstVolume.offset) + ? ("amd-psp-first" as const) + : ("scanned" as const); + const result: UefiInspectResult = + uefiResultSchemas.inspect_uefi_firmware.parse({ + parser: { name: "rea-uefi", version: UEFI_PROVIDER_IDENTITY.version }, + input_size: scan.inputSize, + flash_image: { + sha256: imageSha256, + size: scan.inputSize, + entry_basis: entryBasis, + }, + firmware_volumes: scan.volumes, + psp_tables: scan.pspTables.map((table) => ({ + offset: table.offset, + length: table.length, + table_magic: table.tableMagic, + total_entries: table.totalEntries, + entries: table.entries.map((entry) => ({ + type: entry.type, + declared_location: entry.declaredLocation, + declared_location_raw: entry.declaredLocationRaw, + address_mode: entry.addressMode, + declared_size: entry.declaredSize, + image_offset: entry.imageOffset, + sha256: entry.sha256, + location_basis: entry.locationBasis, + })), + entry_stride_basis: table.entryStrideBasis, + })), + psp_candidates: scan.pspCandidates, + unknown_regions: scan.unknownRegions, + integrity: scan.integrity, + coverage: scan.coverage, + limitations: [...scan.limitations], + }); + return createAnalysisExecution(result, UEFI_PROVIDER_IDENTITY, { + subject: { + path: request.input.path, + sha256: imageSha256, + format: "file", + }, + locations: [{ kind: "artifact-path", path: request.input.path }], + limitations: [ + ...scan.limitations, + "Static cartography only; no executable code is loaded or emulated.", + ], + }); + } + + /** AMI NVRAM stores are parsed from the raw image; no firmware-volume walk needed. */ + #inspectNvram( + request: Extract, + imageSha256: string, + image: Buffer, + checkpoint: () => void, + ): AnalysisExecution { + const scan = scanAmiNvramStores( + image, + request.input.max_stores, + request.input.max_depth, + checkpoint, + ); + const result: UefiNvramInspectResult = + uefiResultSchemas.inspect_uefi_nvram.parse({ + parser: { name: "rea-uefi", version: UEFI_PROVIDER_IDENTITY.version }, + input_size: image.length, + image_sha256: imageSha256, + stores: scan.stores.map((store) => ({ + offset: store.offset, + name: store.name, + variables: store.variables.map((variable) => { + checkpoint(); + return { + offset: variable.offset, + name: variable.name, + attributes: variable.attributes, + next: variable.next, + guid_index: variable.guidIndex, + guid: variable.guid, + depth: variable.depth, + parent_offset: variable.parentOffset, + data_offset: variable.dataOffset, + data_length: variable.dataLength, + data_sha256: sha256Hex( + image.subarray( + variable.dataOffset, + variable.dataOffset + variable.dataLength, + ), + ), + }; + }), + trailing_padding: store.trailingPadding, + })), + coverage: scan.coverage, + limitations: [...scan.limitations], + }); + return createAnalysisExecution(result, UEFI_PROVIDER_IDENTITY, { + subject: { + path: request.input.path, + sha256: imageSha256, + format: "file", + }, + locations: [{ kind: "artifact-path", path: request.input.path }], + limitations: [ + ...scan.limitations, + "Static AMI NVRAM parsing only; variable bytes are reported, never interpreted or executed.", + ], + }); + } + + async #extract( + request: Extract, + imageSha256: string, + scan: UefiImageScanSummary, + signal: AbortSignal, + checkpoint: () => void, + ): Promise { + const input = request.input; + const selection = selectTarget(scan, input.target); + const includes = (path: string) => + path === selection.logical_path || + path.startsWith(`${selection.logical_path}/`); + const gaps: UefiExtractResult["extraction_gaps"] = []; + const derivations: UefiExtractResult["derivations"] = []; + const plan: UefiPublicationEntry[] = []; + const emittedStreams = new Set(); + let stagedBytes = 0; + + const gap = ( + kind: UefiExtractResult["extraction_gaps"][number]["kind"], + logical_path: string, + source_stream: string | null, + range: ExtractionRange | null, + detail: string, + ): void => { + gaps.push({ + kind, + logical_path, + source_stream, + range: range !== null && range.length > 0 ? range : null, + detail, + }); + }; + + const stage = ( + logicalPath: string, + suffix: string, + payload: UefiPayload, + source: ExtractedFile["source"], + parentLogicalPath: string | null, + mediaType: string | null = null, + ): string | null => { + checkpoint(); + if (payload.bytes.length === 0) return null; + if ( + plan.length >= input.max_output_files || + stagedBytes + payload.bytes.length > input.max_output_bytes + ) { + gap( + "size-truncated", + logicalPath, + payload.sourceStream, + payload.range, + `Output file or byte limit prevented publication of ${logicalPath}.`, + ); + return null; + } + // Logical labels retain ':' and brackets. Output paths use portable + // characters and distinguish repeated GUIDs by their observed file offset. + const relativePath = `${logicalPath.replaceAll(":", "-").replaceAll("[", "-").replaceAll("]", "")}.${suffix}.bin`; + stagedBytes += payload.bytes.length; + plan.push({ + relativePath, + bytes: payload.bytes, + facts: { + original_file_range: + payload.sourceStream === null ? payload.range : null, + source_stream: payload.sourceStream, + source_range: payload.range, + runtime_address: null, + media_type: mediaType, + source, + parent_logical_path: parentLogicalPath, + }, + }); + return relativePath; + }; + + const recordDerivation = (stream: string | null): void => { + if (stream === null || emittedStreams.has(stream)) return; + const decoded = scan.decodedStreams.get(stream); + if (decoded === undefined) + throw new Error(`Missing decoded source ${stream}.`); + const { carrier, format, decoderVersion } = decoded; + recordDerivation(carrier.sourceStream); + emittedStreams.add(stream); + const child = includes(stream) + ? stage( + stream, + "decoded", + { + bytes: decoded.bytes, + sourceStream: stream, + range: { offset: 0, length: decoded.bytes.length }, + }, + `decompressed-${format}`, + stream, + ) + : null; + derivations.push({ + parent_path: stream, + parent_file_range: carrier.sourceStream === null ? carrier.range : null, + parent_stream: carrier.sourceStream, + parent_stream_range: carrier.range, + child_path: child, + child_stream: stream, + handler: `${format === "zlib" ? "node-zlib" : "lzma-purejs"}@${decoderVersion}${format === "lzmaf86" ? "+x86-bcj" : ""}`, + }); + }; + + for (const volume of scan.volumes) { + for (const file of volume.ffs_files) { + checkpoint(); + if (includes(file.logical_path)) { + recordDerivation(file.source_stream); + const raw = scan.payloads.get(file.logical_path); + if (raw !== undefined) { + stage(file.logical_path, "body", raw, "uncompressed-payload", null); + } + } + for (const section of file.sections) { + if (!includes(section.logical_path)) continue; + checkpoint(); + if (section.truncated || section.malformed) continue; + const path = section.logical_path; + recordDerivation(section.source_stream); + const payload = scan.payloads.get(path); + const carrier = scan.compressedCarriers.get(path); + if (scan.decodedStreams.has(path)) { + recordDerivation(path); + } else if (carrier !== undefined && input.include_compressed) { + stage( + path, + "compressed", + carrier, + "compressed-passthrough", + section.parent_logical_path, + ); + } else if ( + payload !== undefined && + section.sub_volumes.length === 0 + ) { + stage( + path, + "payload", + payload, + "raw-section", + section.parent_logical_path, + section.type_code === 0x10 + ? "application/vnd.microsoft.portable-executable" + : null, + ); + } + } + } + } + + for (const omission of scan.omissions) { + if (!includes(omission.logical_path)) continue; + checkpoint(); + recordDerivation(omission.source_stream); + gaps.push(omission); + } + if (scan.volumes.length === 0 && gaps.length === 0) { + gap( + "unparsed-region", + selection.logical_path, + selection.source_stream, + { offset: selection.offset, length: selection.length }, + "No firmware volumes were mapped in the input image.", + ); + } + + const publication = await publishUefiFiles({ + outputDirectory: input.output_directory, + operation: request.operation, + entries: plan, + resources: this.#resources, + signal, + checkpoint, + buildResult: (outputRoot, files) => + uefiResultSchemas.extract_uefi_firmware.parse({ + parser: { name: "rea-uefi", version: UEFI_PROVIDER_IDENTITY.version }, + selection: { + offset: selection.offset, + length: selection.length, + source_stream: selection.source_stream, + target_kind: input.target.kind, + }, + output_directory: outputRoot, + coverage: gaps.some(({ kind }) => kind !== "pad-file") + ? "partial" + : "complete", + files, + derivations, + extraction_gaps: gaps, + diagnostics: `${scan.volumes.length} volumes mapped; ${derivations.length} stream derivation(s), ${gaps.length} gap(s); wrote ${files.length} file(s).`, + published_bytes: files.reduce((total, file) => total + file.size, 0), + }), + }); + const { result } = publication; + if (publication.failure !== undefined) { + throw publication.failure.retainPartialObservation({ + kind: "uefi", + result: jsonValueSchema.parse(result), + provenance: { path: input.path, sha256: imageSha256 }, + }); + } + return createAnalysisExecution(result, UEFI_PROVIDER_IDENTITY, { + subject: { path: input.path, sha256: imageSha256, format: "file" }, + locations: [{ kind: "artifact-path", path: input.path }], + limitations: + input.target.kind === "whole-image" + ? scan.limitations + : gaps + .filter(({ kind }) => kind !== "pad-file") + .slice(0, 512) + .map(({ detail }) => detail), + }); + } + + async #decodeStream( + operation: UefiRequest["operation"], + payload: Buffer, + format: UefiDecodeFormat, + maxOutputBytes: number, + signal: AbortSignal, + ): Promise { + signal.throwIfAborted(); + if (format === "zlib") { + try { + const { buffer: bytes, consumedBytes } = nodeCodecResult( + await inflateBounded(payload, { + info: true, + maxOutputLength: maxOutputBytes, + }), + ); + if (consumedBytes !== payload.length) + return { + ok: false, + reason: "format", + message: `AMD zlib stream used ${consumedBytes} of ${payload.length} declared compressed bytes.`, + }; + return { + ok: true, + outcome: { + bytes, + decoderVersion: process.versions.zlib ?? "unknown", + }, + }; + } catch (cause: unknown) { + const limit = hostRangeErrorKind(cause) === "host-capacity"; + return { + ok: false, + reason: limit ? "output-limit" : "decoder", + message: limit + ? `zlib output exceeds the configured or host buffer ceiling of ${maxOutputBytes} bytes: ${errorMessage(cause)}` + : errorMessage(cause), + }; + } + } + const root = await PrivateRuntimeRoot.create({ prefix: "rea-uefi-lzma-" }); + const files = new ArtifactResourceScope(); + let worker: OwnedCommandFailure | undefined; + const rootLease = AnalysisCleanupLease.forCloseOwner( + { + async close() { + if (worker?.cleanupOwner !== undefined) { + const stopped = await worker.cleanupOwner.stop(); + if (stopped.status === "incomplete") + throw new Error(stopped.reason); + worker = undefined; + } + await files.close(); + await root.close(); + }, + get cleanupResources() { + return [ + ...new Set([ + ...(worker?.resources ?? []), + ...files.cleanupResources, + root.path, + ]), + ]; + }, + }, + root.path, + ); + const workspace = { + kind: "lease", + resource: root.path, + lease: rootLease, + } as const; + const decode = async (): Promise => { + const payloadPath = join(root.path, "payload.bin"); + const outputPath = join(root.path, "output.bin"); + const replyPath = join(root.path, "reply.json"); + const requestPath = join(root.path, "request.json"); + await writeFile(payloadPath, payload, { flag: "wx", mode: 0o600 }); + await writeFile( + requestPath, + JSON.stringify({ + format, + payload_path: payloadPath, + output_path: outputPath, + reply_path: replyPath, + max_output_bytes: maxOutputBytes, + }), + { flag: "wx", mode: 0o600 }, + ); + const { NODE_OPTIONS: _ambientNodeOptions, ...environment } = process.env; + await runOwnedCommand( + { + command: process.execPath, + arguments: [ + "--max-old-space-size=256", + "--disable-wasm-trap-handler", + this.#workerModulePath, + requestPath, + ], + cwd: root.path, + expectedCommand: null, + runId: `rea-uefi-lzma-${randomUUID()}`, + hostEnvironment: environment, + }, + { + timeoutMs: UEFI_FIRMWARE_LIMITS.timeoutMs, + diagnosticBytes: UEFI_FIRMWARE_LIMITS.diagnosticBytes, + }, + { signal }, + ); + const replyFile = await readStableArtifact( + replyPath, + UEFI_FIRMWARE_LIMITS.diagnosticBytes, + signal, + undefined, + files, + ); + const reply = lzmaReplySchema.parse( + JSON.parse(replyFile.bytes.toString("utf8")), + ); + if (!reply.ok) { + return reply; + } + signal.throwIfAborted(); + const decoded = await readStableArtifact( + outputPath, + maxOutputBytes, + signal, + undefined, + files, + ); + if ( + decoded.sha256 !== reply.output.sha256 || + decoded.bytes.length !== reply.output.bytes + ) { + return { + ok: false, + reason: "decoder", + message: `LZMA worker output digest mismatch (${reply.output.sha256}).`, + }; + } + return { + ok: true, + outcome: { + bytes: decoded.bytes, + decoderVersion: reply.lzma_version, + }, + }; + }; + + let outcome: UefiDecodeResult | undefined; + let primary: AnalysisError | undefined; + try { + outcome = await decode(); + } catch (cause: unknown) { + primary = classifyProviderFailure( + cause, + uefiFailureDialect(operation, root.path), + ); + const preparation = processInspectionFailure(cause); + if (preparation !== undefined) { + primary = retainProcessInspectionCleanup( + preparation, + primary, + this.#resources, + operation, + ); + } + if ( + cause instanceof OwnedCommandFailure && + cause.cleanupOwner !== undefined + ) { + worker = cause; + this.#resources.retain(workspace); + new AnalysisCleanupLeaseGroup(primary, [rootLease]); + throw primary; + } + } + const cleanup = (reason: string, cause?: unknown) => { + const failure = new ProviderCleanupError( + UEFI_PROVIDER_IDENTITY.id, + rootLease.cleanupResources ?? [root.path], + { reason }, + { cause, operation }, + ); + new AnalysisCleanupLeaseGroup(failure, [rootLease]); + return primary === undefined + ? failure + : analysisErrorWithCleanupDependencies(primary, failure, operation); + }; + if (files.hasPending) { + this.#resources.retain(workspace); + throw cleanup( + "Worker output descriptors must close before the temporary root can be removed.", + ); + } + const released = await this.#resources.release(workspace); + if (released.kind === "failed") + throw cleanup(errorMessage(released.cause), released.cause); + if (primary !== undefined) throw primary; + signal.throwIfAborted(); + if (outcome === undefined) throw new Error("UEFI decoder did not settle."); + return outcome; + } +} diff --git a/src/uefi/UefiArtifactReader.test.ts b/src/uefi/UefiArtifactReader.test.ts new file mode 100644 index 0000000000..9ed1bc9020 --- /dev/null +++ b/src/uefi/UefiArtifactReader.test.ts @@ -0,0 +1,245 @@ +import { writeFile } from "node:fs/promises"; +import { join } from "node:path"; +import { Readable } from "node:stream"; + +import { describe, expect, it, vi } from "vitest"; +import { OwnedFileHandle } from "../filesystem/OwnedFileHandle.js"; + +import { + buildFfsFile, + buildFv, + buildImage, +} from "../../tests/fixtures/uefiImage.js"; +import { createTestTempDirectory } from "../../tests/fixtures/temporaryDirectory.js"; +import type { + ArtifactEntry, + ArtifactTraversalOptions, +} from "../resources/ArtifactReader.js"; +import { UefiArtifactReader } from "./UefiArtifactReader.js"; + +const DRIVER_GUID = "9e21fd93-9c72-4c15-8c4b-e77f9db8d4d2"; + +/** Erased lead-in, one block-aligned volume, one payload FFS file. */ +const buildReaderImage = (): Buffer => { + const payloadFile = buildFfsFile({ + guid: DRIVER_GUID, + typeCode: 0x07, + payload: Buffer.from("driver bytes", "ascii"), + }); + const volume = buildFv({ files: [payloadFile] }); + return Buffer.concat([ + Buffer.alloc(0x1000, 0xff), + buildImage({ volumes: [volume.buffer] }), + ]); +}; + +const openReader = async (image: Buffer): Promise => { + const root = await createTestTempDirectory("rea-uefi-reader-"); + const path = join(root, "image.FIb"); + await writeFile(path, image); + return new UefiArtifactReader(path); +}; + +const collectEntries = async ( + reader: UefiArtifactReader, + options?: ArtifactTraversalOptions, +): Promise => { + const entries: ArtifactEntry[] = []; + for await (const entry of reader.entries(undefined, options)) { + entries.push(entry); + } + return entries; +}; + +const readAll = async (stream: Readable): Promise => { + const chunks: Buffer[] = []; + for await (const chunk of stream) chunks.push(chunk as Buffer); + return Buffer.concat(chunks); +}; + +describe("UefiArtifactReader", () => { + it("maps an erased lead-in, one volume directory, and its FFS file entries", async () => { + const reader = await openReader(buildReaderImage()); + const omissions: string[] = []; + const entries = await collectEntries(reader, { + onOmission: ({ path }) => omissions.push(path), + }); + expect(omissions).toEqual([]); + expect(entries.map((entry) => [entry.path, entry.kind])).toEqual([ + ["firmware-volume-0x1000", "directory"], + [`firmware-volume-0x1000/ffs-file-${DRIVER_GUID}.bin`, "file"], + ]); + const volume = entries[0]; + if (volume === undefined) throw new Error("reader produced no volume"); + const file = entries.at(1); + expect(volume).toMatchObject({ + declaredSize: 0x1000, + byteOffset: 0x1000, + }); + expect(volume.limitations.at(0)).toContain("PI firmware file system 2"); + expect(file).toMatchObject({ + declaredSize: 24 + "driver bytes".length, + byteOffset: 0x1048, + executable: false, + encrypted: false, + }); + await reader.close(); + }); + + it("opens an FFS entry and yields exactly its mapped bytes", async () => { + const image = buildReaderImage(); + const reader = await openReader(image); + const file = (await collectEntries(reader)).find( + (entry) => entry.kind === "file", + ); + if (file === undefined) throw new Error("reader produced no FFS entry"); + const bytes = await readAll(await reader.open(file)); + expect(bytes).toEqual(image.subarray(0x1048, 0x1048 + 24 + 12)); + await reader.close(); + }); + + it("retries an unconfirmed descriptor close while keeping reader admission closed", async () => { + const reader = await openReader(buildReaderImage()); + await collectEntries(reader); + + const close = vi + .spyOn(OwnedFileHandle.prototype, "close") + .mockRejectedValueOnce(new Error("transient descriptor close failure")); + try { + await expect(reader.close()).rejects.toMatchObject({ + cleanup: { + reason: expect.stringContaining("transient descriptor close failure"), + }, + }); + await expect(collectEntries(reader)).rejects.toThrow("reader is closed"); + await expect(reader.close()).resolves.toBeUndefined(); + expect(close).toHaveBeenCalledTimes(2); + const owner = close.mock.instances[1]; + if (!(owner instanceof OwnedFileHandle)) + throw new Error("close lost descriptor ownership"); + expect(owner.handle.fd).toBe(-1); + } finally { + close.mockRestore(); + await reader.close(); + } + }); + + it("refuses entries that were not produced by this reader", async () => { + const reader = await openReader(buildReaderImage()); + const entries = await collectEntries(reader); + const file = entries.find((entry) => entry.kind === "file"); + if (file === undefined) throw new Error("reader produced no FFS entry"); + await expect(reader.open({ ...file, declaredSize: 4096 })).rejects.toThrow( + /does not match this reader's inventory/u, + ); + await reader.close(); + }); +}); + +it("bounds aggregate block-map retention and reports the unvisited volume", async () => { + const volume = buildFv({ files: [], blockMapEntries: 8_000 }).buffer; + const reader = await openReader( + Buffer.concat(Array.from({ length: 13 }, () => volume)), + ); + const onOmission = vi.fn(); + const onCoverage = vi.fn(); + try { + const entries = await collectEntries(reader, { onOmission, onCoverage }); + expect(entries).toHaveLength(12); + expect(onOmission).toHaveBeenCalledWith({ + path: "volume-scan-limit", + kind: "unsupported", + }); + expect(onCoverage).toHaveBeenCalledWith({ + status: "unknown", + limitations: [expect.stringMatching(/structural record limit/i)], + }); + } finally { + await reader.close(); + } +}); + +it("retains a complete volume when a later declared volume extends past EOF", async () => { + const first = buildFv({ files: [] }).buffer; + const truncated = buildFv({ files: [] }).buffer.subarray(0, 1024); + const reader = await openReader(Buffer.concat([first, truncated])); + const onOmission = vi.fn(); + const onCoverage = vi.fn(); + try { + const entries = await collectEntries(reader, { onOmission, onCoverage }); + expect(entries.map(({ path }) => path)).toEqual(["firmware-volume-0x0"]); + expect(onOmission).toHaveBeenCalledWith({ + path: "firmware-volume-0x1000", + kind: "unsupported", + }); + expect(onCoverage).toHaveBeenCalledWith({ + status: "unknown", + limitations: [expect.stringMatching(/0x1000.*4096.*1024/u)], + }); + } finally { + await reader.close(); + } +}); + +it("reports an unreadable extended FFS header after a valid file", async () => { + const file = buildFfsFile({ + guid: DRIVER_GUID, + typeCode: 0x07, + payload: Buffer.alloc(3976), + }); + // The aligned file ends at 0xfe8. This following LARGE_FILE header has + // a complete compact prefix and no room for its eight-byte ExtendedSize. + const tail = Buffer.alloc(24, 0); + tail[19] = 0x01; + const image = buildFv({ files: [file, tail] }).buffer; + const reader = await openReader(image.subarray(0, 0x1000)); + const onOmission = vi.fn(); + const onCoverage = vi.fn(); + try { + const entries = await collectEntries(reader, { onOmission, onCoverage }); + expect(entries.map(({ path }) => path)).toEqual([ + "firmware-volume-0x0", + `firmware-volume-0x0/ffs-file-${DRIVER_GUID}.bin`, + ]); + expect(onOmission).toHaveBeenCalledWith({ + path: "firmware-volume-0x0/ffs-suffix-0xfe8", + kind: "unsupported", + }); + expect(onCoverage).toHaveBeenCalledWith({ + status: "unknown", + limitations: [expect.stringMatching(/0xfe8.*24/u)], + }); + } finally { + await reader.close(); + } +}); + +it("retains the readable prefix of a truncated FFS body and reports unknown coverage", async () => { + const file = buildFfsFile({ + guid: DRIVER_GUID, + typeCode: 0x07, + payload: Buffer.from("payload"), + }); + file.writeUIntLE(8192, 20, 3); + const reader = await openReader(buildFv({ files: [file] }).buffer); + const onOmission = vi.fn(); + const onCoverage = vi.fn(); + try { + const entries = await collectEntries(reader, { onOmission, onCoverage }); + const retained = entries.find(({ kind }) => kind === "file"); + expect(retained).toMatchObject({ byteOffset: 72, declaredSize: 4024 }); + if (retained === undefined) throw new Error("readable FFS bytes were lost"); + const bytes = await readAll(await reader.open(retained)); + expect(bytes.length).toBe(4024); + expect(onOmission).toHaveBeenCalledWith({ + path: retained.path, + kind: "unsupported", + }); + expect(onCoverage).toHaveBeenCalledWith({ + status: "unknown", + limitations: [expect.stringMatching(/0x48.*8192.*4024/u)], + }); + } finally { + await reader.close(); + } +}); diff --git a/src/uefi/UefiArtifactReader.ts b/src/uefi/UefiArtifactReader.ts new file mode 100644 index 0000000000..289097abe4 --- /dev/null +++ b/src/uefi/UefiArtifactReader.ts @@ -0,0 +1,456 @@ +import { lstat } from "node:fs/promises"; +import { Readable } from "node:stream"; + +import type { ArtifactCommand } from "../domain/artifactGraph.js"; +import { OwnedFileHandle } from "../filesystem/OwnedFileHandle.js"; +import { + NonRegularFileReadError, + RegularFileAdmissionFailure, + openRegularFile, + sameRegularFileState, + type StableRegularFileDescriptor, +} from "../filesystem/RegularFile.js"; +import { UEFI_FIRMWARE_LIMITS } from "../domain/uefi/uefiLimits.js"; +import { nextFfsFileLocal, readFfsHeader } from "./FfsFile.js"; +import { + scanFirmwareVolumes, + unsupportedVolumeBodyReason, + type FirmwareVolumeHeader, +} from "./FirmwareVolume.js"; +import { imageRegion } from "./UefiBytes.js"; +import { + ArtifactReaderFailure, + sameArtifactEntry, + type ArtifactEntry, + type ArtifactReader, + type ArtifactTraversalOptions, + assertArtifactReadActive, + readArtifactFileChunks, + streamChunkToBuffer, +} from "../resources/index.js"; + +const hex = (value: number): string => `0x${value.toString(16)}`; +const volumePath = (offset: number): string => `firmware-volume-${hex(offset)}`; + +const IMAGE_TRUNCATION_LIMITATION = + `The image exceeds the ${UEFI_FIRMWARE_LIMITS.inputBytes}-byte admission budget; ` + + "only the leading admission window is mapped."; + +const volumeLimitation = (header: FirmwareVolumeHeader): string => + header.fileSystem === "unsupported" + ? unsupportedVolumeBodyReason(header) + : `Firmware volume at ${hex(header.absoluteBase)} declares PI firmware file system ${header.fileSystem === "ffs2" ? "2 (FFS2)" : "3 (FFS3)"}; inspect_uefi_firmware maps its sections and compression.`; + +/** Read-only FV/FFS level adapter over one PI flash image. */ +export class UefiArtifactReader implements ArtifactReader { + readonly format = "uefi" as const; + #source: StableRegularFileDescriptor | undefined; + #ownedSource: OwnedFileHandle | undefined; + #pendingSource: Promise | undefined; + readonly #entries = new Map(); + readonly #ownsSource: boolean; + #closed = false; + #closePromise: Promise | undefined; + + constructor( + private readonly path: string, + source?: StableRegularFileDescriptor, + ) { + this.#source = source; + this.#ownsSource = source === undefined; + } + + async *entries( + signal?: AbortSignal, + options?: ArtifactTraversalOptions, + ): AsyncIterable { + const source = await this.#ensureSource(); + if (this.#closed) + throw new ArtifactReaderFailure( + "unavailable", + "UEFI flash image reader is closed", + ); + await this.#verifySource(source); + if (signal?.aborted === true) + throw new ArtifactReaderFailure( + "cancelled", + "UEFI entry scan cancelled", + { + cause: signal.reason, + }, + ); + this.#entries.clear(); + const image = await this.#readImage(source, signal); + const limitations = new Set(); + const omit = (path: string, limitation: string): void => { + options?.onOmission?.({ path, kind: "unsupported" }); + limitations.add(limitation); + }; + const imageTruncated = source.initial.size > image.length; + if (imageTruncated) omit("image-truncated", IMAGE_TRUNCATION_LIMITATION); + const scan = scanFirmwareVolumes( + imageRegion(image, 0, image.length), + UEFI_FIRMWARE_LIMITS.maxVolumes, + { checkpoint: () => assertArtifactReadActive(signal) }, + ); + if (scan.limit !== null) { + omit( + "volume-scan-limit", + scan.limit === "structural-records" + ? `UEFI volume search reached the structural record limit of ${UEFI_FIRMWARE_LIMITS.scanRecords}.` + : "UEFI volume search reached its candidate limit.", + ); + } + for (const { absoluteBase, truncation } of scan.rejected) { + if (truncation === undefined) continue; + omit( + volumePath(absoluteBase), + `Firmware volume at ${hex(absoluteBase)} is truncated: declared ${truncation.declaredLength} bytes, observed ${truncation.observedLength}.`, + ); + } + let filesMapped = 0; + let fileBudgetExhausted = false; + for (const hit of scan.volumes) { + const header = hit.header; + const name = volumePath(header.absoluteBase); + const entry: ArtifactEntry = { + path: name, + kind: "directory", + declaredSize: header.declaredLength, + compressedSize: null, + executable: false, + encrypted: false, + byteOffset: header.absoluteBase, + declaredIntegrity: null, + unpacked: true, + limitations: [ + volumeLimitation(header), + ...(imageTruncated && hit === scan.volumes[0] + ? [IMAGE_TRUNCATION_LIMITATION] + : []), + ], + adapterKey: name, + }; + this.#entries.set(entry.adapterKey, entry); + yield entry; + if (header.fileSystem === "unsupported") { + omit( + name, + "Volumes with unsupported file-system GUIDs were retained without FFS entries.", + ); + continue; + } + for await (const file of this.#volumeFiles( + header, + image, + name, + omit, + signal, + )) { + if (filesMapped >= UEFI_FIRMWARE_LIMITS.maxFiles) { + fileBudgetExhausted = true; + break; + } + this.#entries.set(file.adapterKey, file); + filesMapped += 1; + yield file; + } + if (fileBudgetExhausted) { + omit(name, "UEFI inventory reached its FFS file limit."); + break; + } + } + options?.onCoverage?.({ + status: limitations.size === 0 ? "complete" : "unknown", + limitations: [...limitations], + }); + } + + /** One FFS file occurrence per parseable header; erased tails end the walk. */ + async *#volumeFiles( + header: FirmwareVolumeHeader, + image: Buffer, + volumeName: string, + omit: (path: string, limitation: string) => void, + signal?: AbortSignal, + ): AsyncGenerator { + const region = imageRegion( + image, + header.absoluteBase, + Math.min(header.absoluteBase + header.declaredLength, image.length), + ); + let local = header.firstFileLocal; + while (local < region.end) { + assertArtifactReadActive(signal); + const read = readFfsHeader(region, local, header.erasePolarity); + if (read.kind === "unparsed") { + omit( + `${volumeName}/ffs-suffix-${hex(read.offset)}`, + `Unparsed FFS suffix at ${hex(read.offset)}: ${read.length} bytes.`, + ); + } + if (read.kind !== "file") break; + const fileHeader = read.header; + const name = + fileHeader.nameGuid === null + ? `${volumeName}/ffs-file-${hex(fileHeader.absoluteBase)}.bin` + : `${volumeName}/ffs-file-${fileHeader.nameGuid}.bin`; + const entry: ArtifactEntry = { + path: name, + kind: "file", + declaredSize: fileHeader.observedLength, + compressedSize: null, + executable: false, + encrypted: false, + byteOffset: fileHeader.absoluteBase, + declaredIntegrity: null, + unpacked: true, + limitations: [ + "FFS file sections and nested compression are not expanded by the session inventory reader; inspect_uefi_firmware maps them.", + ...(fileHeader.implausibilities.length > 0 + ? [ + `FFS header implausibility at ${hex(fileHeader.absoluteBase)}: ${fileHeader.implausibilities.join(", ")}.`, + ] + : []), + ], + adapterKey: `uefi-ffs:${hex(fileHeader.absoluteBase)}`, + }; + if (fileHeader.extentIssue !== null) + omit( + name, + `Incomplete FFS extent at ${hex(fileHeader.absoluteBase)}: declared ${fileHeader.declaredLength} bytes, observed ${fileHeader.observedLength} (${fileHeader.extentIssue}).`, + ); + yield entry; + if (fileHeader.extentIssue === "declared-length-truncates-region") break; + const next = nextFfsFileLocal(fileHeader, header.localBase); + if (next <= local) break; + local = next; + } + } + + async open(entry: ArtifactEntry, signal?: AbortSignal): Promise { + if (signal?.aborted === true) + return Promise.reject( + new ArtifactReaderFailure( + "cancelled", + "UEFI flash image read cancelled", + { cause: signal.reason }, + ), + ); + const produced = this.#entries.get(entry.adapterKey); + if (produced === undefined || !sameArtifactEntry(entry, produced)) + throw new ArtifactReaderFailure( + "integrity", + "UEFI flash image entry metadata does not match this reader's inventory", + { integrityCheck: "foreign-entry" }, + ); + const offset = produced.byteOffset; + const size = produced.declaredSize; + if ( + offset === null || + size === null || + !Number.isSafeInteger(offset) || + !Number.isSafeInteger(size) || + offset < 0 || + size <= 0 + ) + throw new ArtifactReaderFailure( + "integrity", + `Invalid UEFI FFS byte range: ${entry.path}`, + { integrityCheck: "entry-metadata" }, + ); + const source = await this.#ensureSource(); + if (this.#closed) + throw new ArtifactReaderFailure( + "unavailable", + "UEFI flash image reader is closed", + ); + await this.#verifySource(source); + if ( + !Number.isSafeInteger(offset + size) || + offset + size > source.initial.size + ) + throw new ArtifactReaderFailure( + "integrity", + `UEFI FFS range is outside the artifact: ${entry.path}`, + { integrityCheck: "entry-metadata" }, + ); + const sourceStream = readArtifactFileChunks(source.handle, { + start: offset, + end: offset + size - 1, + ...(signal === undefined ? {} : { signal }), + }); + const verifySource = () => this.#verifySource(source); + const completionFailure = (): ArtifactReaderFailure | undefined => { + const coverage = sourceStream.readCoverage(); + if (coverage.kind !== "complete") + return new ArtifactReaderFailure( + "integrity", + `UEFI FFS read coverage is incomplete: ${entry.path}`, + { integrityCheck: "declared-size" }, + ); + if (coverage.bytes !== BigInt(size)) + return new ArtifactReaderFailure( + "integrity", + `UEFI FFS size disagrees with the mapped header: ${entry.path}`, + { integrityCheck: "declared-size" }, + ); + if (signal?.aborted) + return new ArtifactReaderFailure( + "cancelled", + "UEFI flash image read cancelled", + { cause: signal.reason }, + ); + return undefined; + }; + const output = Readable.from( + (async function* () { + for await (const raw of sourceStream) { + yield streamChunkToBuffer(raw); + } + const failure = completionFailure(); + if (failure !== undefined) throw failure; + await verifySource(); + assertArtifactReadActive(signal); + })(), + ); + const onSourceError = (cause: unknown): void => { + output.destroy( + cause instanceof ArtifactReaderFailure + ? cause + : new ArtifactReaderFailure( + "integrity", + `Could not read UEFI FFS range: ${entry.path}`, + { cause, integrityCheck: "container-identity" }, + ), + ); + }; + sourceStream.on("error", onSourceError); + sourceStream.once("close", () => + sourceStream.removeListener("error", onSourceError), + ); + output.once("close", () => { + if (!sourceStream.destroyed) sourceStream.destroy(); + }); + return output; + } + + provenance(): readonly ArtifactCommand[] { + // A pure TypeScript parser runs no native commands. + return []; + } + + async close(): Promise { + this.#closed = true; + this.#closePromise ??= this.#closeSource().catch((cause: unknown) => { + this.#closePromise = undefined; + throw cause; + }); + return this.#closePromise; + } + + async #closeSource(): Promise { + await this.#pendingSource?.catch(() => undefined); + if (!this.#ownsSource || this.#ownedSource === undefined) return; + try { + await this.#ownedSource.close(); + this.#ownedSource = undefined; + this.#source = undefined; + } catch (cause: unknown) { + throw ArtifactReaderFailure.withCleanup( + cause, + ArtifactReaderFailure.cleanupObservation(cause, this.path), + ); + } + } + + async #ensureSource(): Promise { + if (this.#closed) + throw new ArtifactReaderFailure( + "unavailable", + "UEFI flash image reader is closed", + ); + if (this.#source !== undefined) return this.#source; + this.#pendingSource ??= this.#acquireSource(); + const source = await this.#pendingSource; + if (this.#closed) + throw new ArtifactReaderFailure( + "unavailable", + "UEFI flash image reader closed during source acquisition", + ); + return source; + } + + async #acquireSource(): Promise { + let source: StableRegularFileDescriptor; + try { + source = await openRegularFile(this.path, { symlinks: "reject" }); + } catch (cause: unknown) { + if (!(cause instanceof RegularFileAdmissionFailure)) throw cause; + this.#ownedSource = cause.owner; + const primary = + cause.cause instanceof NonRegularFileReadError + ? new ArtifactReaderFailure( + "format", + `UEFI flash image source is not a regular file: ${this.path}`, + { cause: cause.cause }, + ) + : cause.cause; + throw ArtifactReaderFailure.withCleanup( + primary, + ArtifactReaderFailure.cleanupObservation(cause.cleanupCause, this.path), + ); + } + this.#ownedSource = new OwnedFileHandle(source.handle); + this.#source = source; + return source; + } + + async #verifySource(source: StableRegularFileDescriptor): Promise { + const [opened, currentPath] = await Promise.all([ + source.handle.stat(), + lstat(this.path), + ]); + if ( + !sameRegularFileState(source.initial, opened) || + !sameRegularFileState(source.initial, currentPath) + ) + throw new ArtifactReaderFailure( + "integrity", + `UEFI flash image source changed during inventory: ${this.path}`, + { integrityCheck: "container-identity" }, + ); + } + + /** Whole-image read bounded by the admission limit; the parsers need bytes. */ + async #readImage( + source: StableRegularFileDescriptor, + signal?: AbortSignal, + ): Promise { + const buffer = Buffer.allocUnsafe( + Math.min(UEFI_FIRMWARE_LIMITS.inputBytes, source.initial.size), + ); + let bytesRead = 0; + while (bytesRead < buffer.length) { + if (signal?.aborted === true) + throw new ArtifactReaderFailure( + "cancelled", + "UEFI flash image read cancelled", + { cause: signal.reason }, + ); + const read = await source.handle.read( + buffer, + bytesRead, + buffer.length - bytesRead, + bytesRead, + ); + if (read.bytesRead === 0) + throw new ArtifactReaderFailure( + "io", + `UEFI flash image truncated during read: ${this.path}`, + ); + bytesRead += read.bytesRead; + } + return buffer; + } +} diff --git a/src/uefi/UefiBytes.ts b/src/uefi/UefiBytes.ts new file mode 100644 index 0000000000..c01a422d18 --- /dev/null +++ b/src/uefi/UefiBytes.ts @@ -0,0 +1,88 @@ +import { Buffer } from "node:buffer"; + +/** + * One bounded read-only window into a flash image or decoded stream. + */ +export interface ScanRegion { + readonly buffer: Buffer; + /** Local start inside `buffer` where the region begins (inclusive). */ + readonly start: number; + /** Local end inside `buffer` (exclusive). */ + readonly end: number; + /** Source-stream offset of `start`; published offsets add the local delta. */ + readonly origin: number; + /** Carrier logical path for decoded bytes. Omitted for the original image. */ + readonly sourceStream?: string; +} + +/** Build a region over one full-image address range; bounds are clamped. */ +export function imageRegion( + buffer: Buffer, + start: number, + end: number, +): ScanRegion { + const clampedStart = Math.max(0, Math.min(start, buffer.length)); + const clampedEnd = Math.max(clampedStart, Math.min(end, buffer.length)); + return { buffer, start: clampedStart, end: clampedEnd, origin: clampedStart }; +} + +/** Map a local position inside the region to its source-stream offset. */ +export function absoluteOffset( + region: ScanRegion, + localOffset: number, +): number { + return region.origin + (localOffset - region.start); +} + +/** Map an source-stream offset back to its local position inside the region. */ +export function localOffsetOf( + region: ScanRegion, + absoluteAddress: number, +): number { + return absoluteAddress - region.origin + region.start; +} + +/** Read bytes of one sub-range as a view; null when outside region bounds. */ +export function sliceRegion( + region: ScanRegion, + absoluteStart: number, + length: number, +): Buffer | null { + const local = absoluteStart - region.origin + region.start; + if ( + absoluteStart < region.origin || + local < region.start || + local + length > region.end + ) { + return null; + } + return region.buffer.subarray(local, local + length); +} + +/** Round up to the next multiple of `alignment`; zero stays zero. */ +export function alignUp(value: number, alignment: number): number { + if (alignment <= 1) { + return Math.max(0, value); + } + return Math.ceil(value / alignment) * alignment; +} + +/** Uniformity over a bounded window; out-of-window bytes read as absent. */ +export function isWindowUniform( + buffer: Buffer, + start: number, + end: number, + byte: number, +): boolean { + const boundedStart = Math.max(0, start); + const boundedEnd = Math.min(end, buffer.length); + if (boundedStart >= boundedEnd) { + return false; + } + for (let index = boundedStart; index < boundedEnd; index += 1) { + if (buffer[index] !== byte) { + return false; + } + } + return true; +} diff --git a/src/uefi/UefiCodeTables.ts b/src/uefi/UefiCodeTables.ts new file mode 100644 index 0000000000..a5c17851f2 --- /dev/null +++ b/src/uefi/UefiCodeTables.ts @@ -0,0 +1,136 @@ +/** File and section type codes with their contract display names. */ + +const FFS_TYPE_CODES = { + raw: 0x01, + freeform: 0x02, + "security-core": 0x03, + "pei-core": 0x04, + "dxe-core": 0x05, + peim: 0x06, + driver: 0x07, + "combined-peim-driver": 0x08, + application: 0x09, + smm: 0x0a, + "firmware-volume-image": 0x0b, + "combined-smm-dxe": 0x0c, + "smm-core": 0x0d, + "mm-standalone": 0x0e, + "mm-core-standalone": 0x0f, + pad: 0xf0, +} as const; + +const SECTION_TYPE_CODES = { + compression: 0x01, + "guid-defined": 0x02, + disposable: 0x03, + pe32: 0x10, + pic: 0x11, + te: 0x12, + "dxe-depex": 0x13, + version: 0x14, + "user-interface": 0x15, + compatibility16: 0x16, + "firmware-volume-image": 0x17, + "freeform-subtype-guid": 0x18, + raw: 0x19, + "pei-depex": 0x1b, + "mm-depex": 0x1c, +} as const; + +function flip(mapping: Record): Record { + const reversed: Record = {}; + for (const [name, code] of Object.entries(mapping)) { + reversed[code] = name; + } + return reversed; +} + +/** File type code to contract name; unlisted codes map to "unknown" at the call site. */ +export const FFS_TYPE_NAME_BY_CODE: Readonly> = + flip(FFS_TYPE_CODES); + +/** Section type code to contract name; unlisted codes map to "unknown" at the call site. */ +export const SECTION_TYPE_NAME_BY_CODE: Readonly> = + flip(SECTION_TYPE_CODES); + +/** GUIDed compression section kinds the engine recognizes up front. */ +export const COMPRESSION_GUID_BY_DISPLAY: Readonly< + Record< + string, + "lzma-custom" | "lzmaf86" | "ami-zlib" | "tiano" | "crc32-guided" + > +> = { + "ee4e5898-3914-4259-9d6e-dc7bd79403cf": "lzma-custom", + "d42ae6bd-1352-4bfb-909a-ca72a6eae889": "lzmaf86", + "ce3233f5-2cd6-4d87-9152-4a238bb6d1c4": "ami-zlib", + "a31280ad-481e-41b6-95e8-127f4c984779": "tiano", + "fc1bcdb0-7d31-49aa-936a-a4600d9dd083": "crc32-guided", +}; + +/** FFS attributes (PI Specification 3.3.1): raw flags, data alignment and checksum bit. */ +export const FFS_ATTRIBUTE_MASKS = { + largeFile: 0x01, + dataAlignment2: 0x02, + fixed: 0x04, + dataAlignment: 0x38, + checksumValid: 0x40, +} as const; + +/** FFS state bits after erase-polarity normalization (PI Specification 3.3.5). */ +export const FFS_STATE_BITS = { + headerConstruction: 0x01, + headerValid: 0x02, + dataValid: 0x04, + markedForUpdate: 0x08, + deleted: 0x10, + headerInvalid: 0x20, +} as const; + +/** FIRMWARE_VOLUME_ATTRIBUTES: bit 0x800 marks bits-on-erased-when-set polarity. */ +export const FV_ATTRIBUTE_ERASE_POLARITY = 0x800; + +/** Layout offsets inside EFI_FIRMWARE_VOLUME_HEADER (PI Specification 3.2.1). */ +export const FV_HEADER_LAYOUT = { + zeroVectorLength: 16, + fileSystemGuidOffset: 16, + fvLengthOffset: 32, + signatureOffset: 40, + attributesOffset: 44, + headerLengthOffset: 48, + checksumOffset: 50, + extHeaderOffsetOffset: 52, + reservedOffset: 54, + revisionOffset: 55, + blockMapOffset: 56, + blockMapEntryLength: 8, + minimumLength: 64, + fileAlignment: 8, +} as const; + +/** Layout offsets inside EFI_FFS_FILE_HEADER (PI Specification 3.2.3). */ +export const FFS_HEADER_LAYOUT = { + nameGuidOffset: 0, + integrityCheckOffset: 16, + typeOffset: 18, + attributesOffset: 19, + sizeOffset: 20, + stateOffset: 23, + length: 24, + extendedSizeOffset: 24, + extendedLength: 32, +} as const; + +/** Common, compression and guided section header geometry (PI Specification 3.2.4). */ +export const SECTION_LAYOUT = { + sizeOffset: 0, + typeOffset: 3, + commonLength: 4, + extendedSizeOffset: 4, + extendedLength: 8, + largeSectionMarker: 0xffffff, + compressionFieldsLength: 5, + compressionTypeFieldOffset: 4, + guidedFieldsLength: 20, + guidDataOffsetFieldOffset: 16, + guidAttributesFieldOffset: 18, +} as const; diff --git a/src/uefi/UefiFailures.ts b/src/uefi/UefiFailures.ts new file mode 100644 index 0000000000..144256b6a5 --- /dev/null +++ b/src/uefi/UefiFailures.ts @@ -0,0 +1,124 @@ +import { capturedProviderOutput } from "../process/capturedProviderOutput.js"; +import type { AnalysisErrorOptions } from "../domain/analysisErrorBase.js"; +import { + AnalysisCancelledError, + AnalysisInputError, + AnalysisTimeoutError, + cancelledBy, + carriedReason, +} from "../domain/analysisErrorCore.js"; +import { ProviderAdapterError } from "../domain/providerAdapterError.js"; +import type { UefiOperation } from "../domain/uefi/uefiFirmwareAnalysis.js"; +import { UEFI_FIRMWARE_LIMITS } from "../domain/uefi/uefiLimits.js"; +import { errorMessage } from "../kernel/errorMessage.js"; +import { classifyProviderOutcome } from "../process/classifyProviderOutcome.js"; +import { DarwinProcessOwnershipInspectionError } from "../process/DarwinProcessRunTokenReader.js"; +import { OwnedCommandFailure } from "../process/OwnedCommand.js"; +import { providerOutcomeOf } from "../process/ProviderOutcome.js"; +import type { ProviderFailureDialect } from "../providers/classifyProviderFailure.js"; +import { + ArtifactReaderFailure, + artifactFileCancellationCause, +} from "../resources/index.js"; +import { UEFI_PROVIDER_IDENTITY } from "./UefiProviderIdentity.js"; + +/** Provider-specific reporting for a bounded decode and its stable artifact reads. */ +export const uefiFailureDialect = ( + operation: UefiOperation, + path: string, +): ProviderFailureDialect => { + const providerId = UEFI_PROVIDER_IDENTITY.id; + const cancellation = ( + reason: unknown, + { cause: _cause, ...details }: AnalysisErrorOptions, + ) => + reason instanceof AnalysisTimeoutError + ? new AnalysisTimeoutError(operation, reason.timeoutMs, { + ...details, + cause: reason, + }) + : cancelledBy( + operation, + carriedReason( + reason instanceof AnalysisCancelledError ? reason.cause : reason, + ), + details, + ); + return { + providerId, + operation, + file: { + path, + description: "UEFI artifact", + fileSize: (cause, details) => + new AnalysisInputError(operation, { ...details, cause }, [ + { path: ["path"], reason: "out_of_range", message: cause.message }, + ]), + }, + recognise(cause, details) { + if ( + cause instanceof ArtifactReaderFailure && + cause.reason === "cancelled" + ) { + return cancellation(artifactFileCancellationCause(cause), { + ...details, + partialObservation: cause.partialObservation, + }); + } + if ( + cause instanceof DarwinProcessOwnershipInspectionError && + cause.cancellation !== undefined + ) { + return cancellation(cause.cancellation.reason, { + ...details, + capturedOutput: cause.capturedOutput, + }); + } + if (!(cause instanceof OwnedCommandFailure)) return undefined; + const outcome = providerOutcomeOf(cause); + const primary = classifyProviderOutcome( + outcome.kind === "cancelled" && + outcome.reason instanceof AnalysisTimeoutError + ? { ...outcome, kind: "timeout" } + : outcome, + { + providerId, + operation, + details: { + ...details, + ...(cause.cleanupFailure === null + ? {} + : { + cleanup: { + reason: cause.cleanupFailure, + resources: cause.resources, + }, + }), + }, + capturedOutput: capturedProviderOutput, + timeout: { ms: UEFI_FIRMWARE_LIMITS.timeoutMs }, + outputLimit: { + limits: { diagnostic_bytes: UEFI_FIRMWARE_LIMITS.diagnosticBytes }, + recovery: { + retryable: false, + remediationAction: + "Use a smaller firmware image or select a narrower extraction scope.", + }, + }, + dialect: (_outcome, _details, unclassified) => unclassified(), + }, + ); + return primary; + }, + unclassified: (cause, details) => + new ProviderAdapterError(providerId, operation, { + ...details, + cause, + diagnostics: { + phase: "unclassified", + path, + reason: errorMessage(cause), + }, + }), + }; +}; diff --git a/src/uefi/UefiFormatProbe.ts b/src/uefi/UefiFormatProbe.ts new file mode 100644 index 0000000000..b7656ba0d7 --- /dev/null +++ b/src/uefi/UefiFormatProbe.ts @@ -0,0 +1,71 @@ +import type { FileHandle } from "node:fs/promises"; +import { readFileHandleRange } from "../filesystem/readFileHandleRange.js"; +import { claimsExecutableHeader } from "../domain/binaryTarget.js"; +import { cancelledBy } from "../domain/analysisErrorCore.js"; +import { imageRegion, type ScanRegion } from "./UefiBytes.js"; +import { scanFirmwareVolumes } from "./FirmwareVolume.js"; +import { UEFI_FIRMWARE_LIMITS } from "../domain/uefi/uefiLimits.js"; + +/** Signature hits evaluate a bounded candidate set so one bogus `_FVH` cannot + * deny a real volume that follows it in the same window. */ +const PROBE_CANDIDATE_BUDGET = 64; +/** PI volume placement; unaligned signature hits stay format-inconclusive. */ +const VOLUME_ALIGNMENT_BYTES = 16; + +/** + * Admit one volume whose header passes the full header plausibility checks + * (checksum, block-map terminator, mapped extent) and declares the FFS2 + * or FFS3 file system. Rejected signature hits stay inconclusive so plain + * bytes containing `_FVH` cannot claim the format. + */ +export function admitUefiFlashImage( + buffer: Buffer, + signatureEnd = buffer.length, +): boolean { + const region: ScanRegion = imageRegion(buffer, 0, buffer.length); + const scan = scanFirmwareVolumes(region, PROBE_CANDIDATE_BUDGET, { + signatureEnd, + }); + return scan.volumes.some( + ({ header }) => + header.checksumValid && + header.absoluteBase % VOLUME_ALIGNMENT_BYTES === 0 && + header.fileSystem !== "unsupported", + ); +} + +/** + * Detect a PI flash image through an aligned `_FVH` plausibility probe over + * the declared admission prefix (1 MiB). The prefix decides most misses + * cheaply; only files that actually carry the signature cost a bounded + * whole-image read. Images whose first volume lies beyond the prefix stay + * unrecognized — an honest admission gap, noted in the probe contract. + */ +export async function probeUefiFlashImage( + handle: FileHandle, + signal?: AbortSignal, +): Promise { + const throwIfCancelled = (): void => { + if (signal?.aborted === true) + throw cancelledBy("resolve_binary_target", signal); + }; + throwIfCancelled(); + const { size } = await handle.stat(); + const prefix = await readFileHandleRange( + handle, + 0, + Math.min(UEFI_FIRMWARE_LIMITS.scanProbeBytes, size), + throwIfCancelled, + ); + throwIfCancelled(); + if (claimsExecutableHeader(prefix, size) || !prefix.includes("_FVH", "ascii")) + return false; + + const readLimit = Math.min(UEFI_FIRMWARE_LIMITS.inputBytes, size); + const observed = + readLimit <= prefix.length + ? prefix + : await readFileHandleRange(handle, 0, readLimit, throwIfCancelled); + throwIfCancelled(); + return admitUefiFlashImage(observed, prefix.length); +} diff --git a/src/uefi/UefiGuid.test.ts b/src/uefi/UefiGuid.test.ts new file mode 100644 index 0000000000..15fb0310e8 --- /dev/null +++ b/src/uefi/UefiGuid.test.ts @@ -0,0 +1,62 @@ +import { Buffer } from "node:buffer"; +import { expect, it } from "vitest"; +import { + FFS2_FILE_SYSTEM_GUID, + formatGuidLittleEndian, + guidEquals, +} from "./UefiGuid.js"; + +const ffs2RawBytes = Buffer.from([ + 0x78, 0xe5, 0x8c, 0x8c, 0x3d, 0x8a, 0x1c, 0x4f, 0x99, 0x35, 0x89, 0x61, 0x85, + 0xc3, 0x2d, 0xd3, +]); + +const lzmaCustomRawBytes = Buffer.from([ + 0x98, 0x58, 0x4e, 0xee, 0x14, 0x39, 0x59, 0x42, 0x9d, 0x6e, 0xdc, 0x7b, 0xd7, + 0x94, 0x03, 0xcf, +]); + +const lzmaf86RawBytes = Buffer.from([ + 0xbd, 0xe6, 0x2a, 0xd4, 0x52, 0x13, 0xfb, 0x4b, 0x90, 0x9a, 0xca, 0x72, 0xa6, + 0xea, 0xe8, 0x89, +]); + +it("formats the FFS2 container GUID from raw little-endian bytes", () => { + const header = Buffer.alloc(48, 0xff); + ffs2RawBytes.copy(header, 16); + expect(formatGuidLittleEndian(header, 16)).toBe( + "8c8ce578-8a3d-4f1c-9935-896185c32dd3", + ); +}); + +it("formats the LZMA custom compression GUID", () => { + expect(formatGuidLittleEndian(lzmaCustomRawBytes, 0)).toBe( + "ee4e5898-3914-4259-9d6e-dc7bd79403cf", + ); +}); + +it("formats the LZMAF86 compression GUID", () => { + expect(formatGuidLittleEndian(lzmaf86RawBytes, 0)).toBe( + "d42ae6bd-1352-4bfb-909a-ca72a6eae889", + ); +}); + +it("returns null for out-of-bounds and truncated reads", () => { + const truncated = ffs2RawBytes.subarray(0, 15); + expect(formatGuidLittleEndian(truncated, 0)).toBeNull(); + expect(formatGuidLittleEndian(Buffer.alloc(0), -1)).toBeNull(); + expect(formatGuidLittleEndian(ffs2RawBytes, 1)).toBeNull(); +}); + +it("accepts a read exactly at the buffer end", () => { + expect(formatGuidLittleEndian(ffs2RawBytes, 0)).toBe(FFS2_FILE_SYSTEM_GUID); +}); + +it("compares GUIDs case-insensitively without accepting mixed values", () => { + expect( + guidEquals(FFS2_FILE_SYSTEM_GUID, "8C8CE578-8A3D-4F1C-9935-896185C32DD3"), + ).toBe(true); + expect( + guidEquals(FFS2_FILE_SYSTEM_GUID, "ee4e5898-3914-4259-9d6e-dc7bd79403cf"), + ).toBe(false); +}); diff --git a/src/uefi/UefiGuid.ts b/src/uefi/UefiGuid.ts new file mode 100644 index 0000000000..507dffa9f4 --- /dev/null +++ b/src/uefi/UefiGuid.ts @@ -0,0 +1,52 @@ +import { BinaryReader } from "../domain/binaryContainer.js"; +import { Buffer } from "node:buffer"; + +/** UEFI GUIDs are 16 raw bytes rendered as 8-4-4-4-12 hex digits. */ +export const GUID_LENGTH = 16; + +/** + * Format a raw GUID with UEFI mixed-endian decoding: the first data word and + * the two following words read little-endian, the remaining eight bytes keep + * their written order. Returns null outside mapped bounds; null is an + * observation, never a guessed identifier. + */ +export function formatGuidLittleEndian( + buffer: Buffer, + offset: number, +): string | null { + if (offset < 0 || offset + GUID_LENGTH > buffer.length) { + return null; + } + const reader = new BinaryReader(buffer, true, "UEFI GUID"); + const data1 = reader.u32(offset); + const data2 = reader.u16(offset + 4); + const data3 = reader.u16(offset + 6); + const tail = buffer.subarray(offset + 8, offset + GUID_LENGTH); + const word = (value: number, digits: number): string => + value.toString(16).padStart(digits, "0"); + const node = Array.from(tail, (byte) => word(byte, 2)).join(""); + return [ + word(data1, 8), + word(data2, 4), + word(data3, 4), + node.slice(0, 4), + node.slice(4), + ].join("-"); +} + +/** Case-insensitive canonical GUID comparison. */ +export function guidEquals(left: string, right: string): boolean { + return left.toLowerCase() === right.toLowerCase(); +} + +/** + * FFS2 container GUID (PI Specification, firmware file system 2). + * Raw bytes: 78 E5 8C 8C 3D 8A 1C 4F 99 35 89 61 85 C3 2D D3. + */ +export const FFS2_FILE_SYSTEM_GUID = "8c8ce578-8a3d-4f1c-9935-896185c32dd3"; + +/** + * FFS3 container GUID (PI Specification, firmware file system 3). + * Raw bytes: 07 12 73 54 41 5C BD 4C B5 E5 CD 26 D8 07 70 B1. + */ +export const FFS3_FILE_SYSTEM_GUID = "54731207-5c41-4cbd-b5e5-cd26d80770b1"; diff --git a/src/uefi/UefiImageScan.test.ts b/src/uefi/UefiImageScan.test.ts new file mode 100644 index 0000000000..f1d7431fd1 --- /dev/null +++ b/src/uefi/UefiImageScan.test.ts @@ -0,0 +1,489 @@ +import { Buffer } from "node:buffer"; +import { expect, it } from "vitest"; + +import { + buildFv, + buildFfsFile, + buildSection, + buildGuidedSection, + buildLzmaGuidedSection, +} from "../../tests/fixtures/uefiImage.js"; +import { AMD_ZLIB_HEADER_LENGTH } from "./FfsSections.js"; +import { scanUefiImage, type UefiLzmaDecoder } from "./UefiImageScan.js"; + +const noDecoder: UefiLzmaDecoder = async () => ({ + ok: false, + reason: "decoder", + message: "test decoder unavailable", +}); + +const decodeNestedFv = + (nestedFv: Buffer): UefiLzmaDecoder => + async ({ payload }) => + payload.equals(Buffer.from([0xde, 0xad, 0xbe, 0xef])) + ? { ok: true, outcome: { bytes: nestedFv, decoderVersion: "test" } } + : { ok: false, reason: "decoder", message: "Unexpected carrier bytes" }; + +const driverFile = (guid: string, payload: Buffer): Buffer => + buildFfsFile({ guid, typeCode: 0x07, payload }); + +it("maps one volume with UI string, PE payload, checksums and pad classification", async () => { + const ui = buildSection(0x15, Buffer.from("BiosModule\0", "utf16le")); + const pe = buildSection(0x10, Buffer.from([0x4d, 0x5a, 0x90, 0x00])); + const fileOne = driverFile( + "21111111-2222-3333-4444-555555555555", + Buffer.concat([ui, pe]), + ); + const fileTwo = buildFfsFile({ + guid: "22111111-2222-3333-4444-555555555555", + typeCode: 0x07, + payload: buildSection(0x19, Buffer.from("integrity")), + alignmentExponent: 7, + fileChecksum: "correct", + }); + const pad = buildFfsFile({ + guid: "00000000-0000-0000-0000-000000000000", + typeCode: 0xf0, + payload: Buffer.alloc(0), + }); + const fv = buildFv({ files: [fileOne, fileTwo, pad] }); + const summary = await scanUefiImage( + fv.buffer, + { maxDepth: 3, maxVolumes: 64, maxFiles: 64 }, + noDecoder, + ); + + expect(summary.volumes).toHaveLength(1); + const volume = summary.volumes[0]; + expect(volume?.offset).toBe(0); + expect(volume?.depth).toBe(0); + expect(volume?.parent_offset).toBeNull(); + expect(volume?.file_system_guid).toBe("8c8ce578-8a3d-4f1c-9935-896185c32dd3"); + expect(volume?.ffs_files).toHaveLength(3); + const [mappedOne, mappedTwo, mappedPad] = volume?.ffs_files ?? []; + expect(mappedOne?.type_name).toBe("driver"); + expect(mappedOne?.ui_string).toBe("BiosModule"); + expect(mappedOne?.checksum).toBe("unchecked"); + expect(mappedOne?.sections).toHaveLength(2); + expect(mappedOne?.sections[0]?.type_name).toBe("user-interface"); + expect(mappedOne?.sections[1]?.type_name).toBe("pe32"); + expect(mappedTwo?.checksum).toBe("valid"); + expect(mappedPad?.type_name).toBe("pad"); + expect(mappedPad?.checksum).toBe("pad-file-unchecked"); + expect(summary.coverage).toBe("complete"); + // Volume block padding (erased) stays classified, never hidden. + const tail = summary.unknownRegions.at(-1); + expect(tail?.classification).toBe("erased-ff"); + expect(tail?.erasure).toBe("0xff"); +}); + +it("recurses into firmware-volume-image sections with parent linkage", async () => { + const nestedInner = buildFfsFile({ + guid: "24111111-2222-3333-4444-555555555555", + typeCode: 0x07, + payload: buildSection(0x19, Buffer.from("inner")), + }); + const nestedFv = buildFv({ files: [nestedInner] }); + const wrapper = driverFile( + "23111111-2222-3333-4444-555555555555", + buildSection(0x17, nestedFv.buffer), + ); + const image = buildFv({ files: [wrapper] }); + const summary = await scanUefiImage( + image.buffer, + { maxDepth: 3, maxVolumes: 2, maxFiles: 64 }, + noDecoder, + ); + + expect(summary.volumes).toHaveLength(2); + expect(summary.coverage).toBe("complete"); + const top = summary.volumes[0]; + const nested = summary.volumes[1]; + expect(nested?.depth).toBe(1); + expect(nested?.parent_offset).toBe(top?.offset ?? -1); + expect(nested?.logical_path.startsWith(`${top?.logical_path}/FFS:`)).toBe( + true, + ); + expect(top?.ffs_files[0]?.sections[0]?.sub_volumes).toEqual([ + nested?.logical_path, + ]); +}); + +it("reinterprets a raw file body that directly carries an embedded firmware volume", async () => { + const holeInner = buildFfsFile({ + guid: "25111111-2222-3333-4444-555555555555", + typeCode: 0x07, + payload: buildSection(0x19, Buffer.from("hole")), + }); + const holeFv = buildFv({ files: [holeInner] }); + // The raw body carries a full FV without a surrounding section header. + const hole = buildFfsFile({ + guid: "27111111-2222-3333-4444-555555555555", + typeCode: 0x01, + payload: holeFv.buffer, + }); + const image = buildFv({ files: [hole] }); + const summary = await scanUefiImage( + image.buffer, + { maxDepth: 3, maxVolumes: 64, maxFiles: 64 }, + noDecoder, + ); + + expect(summary.volumes).toHaveLength(2); + const raw = summary.volumes[0]?.ffs_files[0]; + expect(raw?.type_name).toBe("raw"); + expect(raw?.sections).toHaveLength(0); + const nested = summary.volumes[1]; + expect(nested?.depth).toBe(1); + expect(nested?.parent_offset).toBe(summary.volumes[0]?.offset ?? -1); + expect(nested?.logical_path.includes("/embedded/FV@")).toBe(true); + expect(nested?.ffs_files).toHaveLength(1); +}); + +it("keeps an unframed raw body without a confirmed embedded volume untouched", async () => { + const unframed = buildFfsFile({ + guid: "28111111-2222-3333-4444-555555555555", + typeCode: 0x01, + payload: Buffer.alloc(80, 0x00), + }); + const image = buildFv({ files: [unframed] }); + const summary = await scanUefiImage( + image.buffer, + { maxDepth: 3, maxVolumes: 64, maxFiles: 64 }, + noDecoder, + ); + + expect(summary.volumes).toHaveLength(1); + const raw = summary.volumes[0]?.ffs_files[0]; + expect(raw?.sections).toHaveLength(0); + expect(summary.coverage).toBe("complete"); +}); + +it("decodes LZMA-guided sections through the injected decoder lane", async () => { + const nestedInner = buildFfsFile({ + guid: "26111111-2222-3333-4444-555555555555", + typeCode: 0x07, + payload: buildSection(0x19, Buffer.from("inner")), + }); + const nestedFv = buildFv({ files: [nestedInner] }); + const ui = buildSection(0x15, Buffer.from("CompressedMain\0", "utf16le")); + const decoder = decodeNestedFv(nestedFv.buffer); + const compressedCarrier = Buffer.from([0xde, 0xad, 0xbe, 0xef]); + const wrapper = driverFile( + "25111111-2222-3333-4444-555555555555", + Buffer.concat([ui, buildLzmaGuidedSection(compressedCarrier)]), + ); + const top = buildFv({ files: [wrapper] }); + const summary = await scanUefiImage( + top.buffer, + { maxDepth: 3, maxVolumes: 64, maxFiles: 64 }, + decoder, + ); + + expect(summary.volumes).toHaveLength(2); + const nested = summary.volumes[1]; + expect(nested?.depth).toBe(1); + expect(nested?.parent_offset).toBe(0); + expect(nested?.logical_path).toContain("/lzma/FV@"); + const lzmaSection = summary.volumes[0]?.ffs_files[0]?.sections[1]; + expect(lzmaSection?.compression).toMatchObject({ + kind: "lzma-custom", + data_offset: 24, + }); + expect(lzmaSection?.sub_volumes).toEqual([summary.volumes[1]?.logical_path]); + const carrier = + lzmaSection && + summary.decodedStreams.get(lzmaSection.logical_path)?.carrier; + expect(carrier?.range).toEqual({ + offset: top.headerLength + 24 + ui.length + 24, + length: compressedCarrier.length, + }); + expect(summary.limitations).toHaveLength(0); +}); + +it("decodes AMI-zlib guided sections after peeling the AMD header", async () => { + const nestedInner = buildFfsFile({ + guid: "2b111111-2222-3333-4444-555555555555", + typeCode: 0x07, + payload: buildSection(0x19, Buffer.from("inner")), + }); + const nestedFv = buildFv({ files: [nestedInner] }); + const stream = Buffer.from([0xde, 0xad, 0xbe, 0xef]); + const amdHeader = Buffer.alloc(AMD_ZLIB_HEADER_LENGTH, 0); + amdHeader.writeUInt32LE(stream.length, 0x14); + const decoder = decodeNestedFv(nestedFv.buffer); + const wrapper = driverFile( + "2c111111-2222-3333-4444-555555555555", + buildGuidedSection({ + definitionGuid: "ce3233f5-2cd6-4d87-9152-4a238bb6d1c4", + body: Buffer.concat([amdHeader, stream]), + }), + ); + const top = buildFv({ files: [wrapper] }); + const summary = await scanUefiImage( + top.buffer, + { maxDepth: 3, maxVolumes: 64, maxFiles: 64 }, + decoder, + ); + + expect(summary.volumes).toHaveLength(2); + const nested = summary.volumes[1]; + expect(nested?.depth).toBe(1); + expect(nested?.parent_offset).toBe(0); + expect(nested?.logical_path).toContain("/zlib/FV@"); + const zlibSection = summary.volumes[0]?.ffs_files[0]?.sections[0]; + expect(zlibSection?.compression).toMatchObject({ + kind: "ami-zlib", + data_offset: 24, + }); + expect(zlibSection?.sub_volumes).toEqual([summary.volumes[1]?.logical_path]); + const carrier = + zlibSection && + summary.decodedStreams.get(zlibSection.logical_path)?.carrier; + expect(carrier?.range).toEqual({ + offset: top.headerLength + 24 + 24 + AMD_ZLIB_HEADER_LENGTH, + length: stream.length, + }); + expect(summary.limitations).toHaveLength(0); +}); + +it("keeps walking when the decoder returns null and records the gap", async () => { + const compressedCarrier = Buffer.from([0x1, 0x2, 0x3, 0x4]); + const wrapper = driverFile( + "27111111-2222-3333-4444-555555555555", + buildLzmaGuidedSection(compressedCarrier), + ); + const top = buildFv({ files: [wrapper] }); + const summary = await scanUefiImage( + top.buffer, + { maxDepth: 3, maxVolumes: 64, maxFiles: 64 }, + noDecoder, + ); + expect(summary.volumes).toHaveLength(1); + expect(summary.coverage).toBe("partial"); + expect( + summary.limitations.some((line) => line.includes("lzma decode failed")), + ).toBe(true); +}); + +it("reports a too-small declared length and an overflowing file as integrity records", async () => { + const undersized = buildFfsFile({ + guid: "28111111-2222-3333-4444-555555555555", + typeCode: 0x07, + payload: Buffer.alloc(0), + }); + undersized[20] = 4; + const oversized = buildFfsFile({ + guid: "29111111-2222-3333-4444-555555555555", + typeCode: 0x07, + payload: Buffer.from("more data"), + fileChecksum: "correct", + }); + oversized[20] = 0xff; + oversized[21] = 0xff; + oversized[22] = 0x00; // declared length 0x00ffff exceeds the volume area + const fv = buildFv({ files: [undersized, oversized] }); + const summary = await scanUefiImage( + fv.buffer, + { maxDepth: 3, maxVolumes: 64, maxFiles: 64 }, + noDecoder, + ); + const kinds = summary.integrity.map((record) => record.kind); + expect(kinds.filter((kind) => kind === "size-truncation")).toHaveLength(2); + const files = summary.volumes[0]?.ffs_files; + expect(files).toHaveLength(2); + expect(files?.[1]?.checksum).toBe("unchecked"); + expect( + summary.integrity.filter(({ kind }) => kind === "size-truncation")[1] + ?.range, + ).toEqual({ offset: 96, length: fv.buffer.length - 96 }); +}); + +it("records a volume checksum mismatch without dropping the volume", async () => { + const inner = buildFfsFile({ + guid: "2a111111-2222-3333-4444-555555555555", + typeCode: 0x07, + payload: Buffer.from("z"), + }); + const fv = buildFv({ files: [inner] }); + fv.buffer[55] = 5; // revision rides the corrupted checksum word + const summary = await scanUefiImage( + fv.buffer, + { maxDepth: 3, maxVolumes: 64, maxFiles: 64 }, + noDecoder, + ); + expect(summary.volumes).toHaveLength(1); + expect( + summary.integrity.some((record) => record.kind === "fv-checksum-mismatch"), + ).toBe(true); +}); + +it("maps a plausible PSP directory and candidates an implausible one", async () => { + const plausible = Buffer.alloc(0x20 + 2 * 16, 0); + plausible.write("$PSP", 0, "ascii"); + plausible.writeUInt32LE(2, 8); + plausible.writeUInt32LE(0x2000, 0x10 + 4); + plausible.writeBigUInt64LE(0x4000000000001000n, 0x10 + 8); + plausible.writeBigUInt64LE(0xb123000000000aabn, 0x20 + 8); + // Fletcher-32 over the 20 little-endian words beginning at the count. + plausible.writeUInt32LE(0x9bfc2bd1, 4); + const badChecksum = Buffer.from(plausible); + badChecksum.writeUInt32LE(0, 4); + const bogus = Buffer.alloc(32, 0); + bogus.write("$PL2", 0, "ascii"); + bogus.writeUInt32LE(0x1ff, 8); + const image = Buffer.concat([ + plausible, + badChecksum, + bogus, + Buffer.alloc(0x800, 0xff), + ]); + const summary = await scanUefiImage( + image, + { maxDepth: 3, maxVolumes: 64, maxFiles: 64 }, + noDecoder, + ); + expect(summary.pspTables).toHaveLength(1); + const table = summary.pspTables[0]; + expect(table?.tableMagic).toBe("$PSP"); + expect(table?.totalEntries).toBe(2); + expect(table?.entryStrideBasis).toBe("psp-16"); + expect(table?.entries[0]).toMatchObject({ + declaredLocation: 0x1000, + declaredLocationRaw: "0x4000000000001000", + addressMode: 1, + declaredSize: 0x2000, + locationBasis: "declared-unverified", + }); + expect(table?.entries[1]).toMatchObject({ + declaredLocation: null, + declaredLocationRaw: "0xb123000000000aab", + addressMode: 2, + }); + expect(summary.pspCandidates).toMatchObject([ + { offset: plausible.length, reason: "checksum-mismatch" }, + { + offset: plausible.length + badChecksum.length, + reason: "implausible-entry-count", + }, + ]); +}); + +it("marks the scan partial when the FFS file budget is hit", async () => { + const fileOne = driverFile( + "2b111111-2222-3333-4444-555555555555", + buildSection(0x19, Buffer.from("a")), + ); + const fileTwo = driverFile( + "2c111111-2222-3333-4444-555555555555", + buildSection(0x19, Buffer.from("b")), + ); + const fv = buildFv({ files: [fileOne, fileTwo] }); + const summary = await scanUefiImage( + fv.buffer, + { maxDepth: 3, maxVolumes: 64, maxFiles: 1 }, + noDecoder, + ); + expect(summary.coverage).toBe("partial"); + expect(summary.volumes[0]?.ffs_files).toHaveLength(1); + expect(summary.omissions).toMatchObject([ + { + kind: "size-truncated", + logical_path: "flash/FV@0x0", + detail: expect.stringContaining("FFS file budget"), + }, + ]); +}); + +it("classifies uncovered ranges around volumes and in an image without a volume", async () => { + const fv = buildFv({ files: [] }).buffer; + const prefix = Buffer.from("vendor metadata"); + const middle = Buffer.alloc(16, 0xff); + const suffix = Buffer.from("vendor footer"); + const image = Buffer.concat([prefix, fv, middle, fv, suffix]); + const limits = { maxDepth: 3, maxVolumes: 2, maxFiles: 8 }; + const { unknownRegions } = await scanUefiImage(image, limits, noDecoder); + expect(unknownRegions.map(({ offset, length }) => [offset, length])).toEqual( + expect.arrayContaining([ + [0, prefix.length], + [prefix.length + fv.length, middle.length], + [image.length - suffix.length, suffix.length], + ]), + ); + expect( + (await scanUefiImage(prefix, limits, noDecoder)).unknownRegions, + ).toMatchObject([ + { offset: 0, length: prefix.length, classification: "no-fv-magic" }, + ]); +}); + +it("marks partial when the structural budget ends inside a section chain", async () => { + const frames = Buffer.alloc(400_000); + for (let offset = 0; offset < frames.length; offset += 4) { + frames.writeUInt32LE(0x19000004, offset); + } + const file = driverFile("22111111-2222-3333-4444-555555555555", frames); + const scan = await scanUefiImage( + buildFv({ files: [file] }).buffer, + { maxDepth: 3, maxVolumes: 4, maxFiles: 4 }, + noDecoder, + ); + expect(scan.coverage).toBe("partial"); + expect( + scan.limitations.some((line) => line.includes("Structural record limit")), + ).toBe(true); + expect(scan.volumes[0]?.ffs_files[0]?.sections.length).toBeLessThan(100_000); + expect(scan.omissions).toEqual( + expect.arrayContaining([ + expect.objectContaining({ + kind: "size-truncated", + logical_path: expect.stringContaining("/FFS:"), + detail: expect.stringContaining("section walk"), + }), + ]), + ); +}); + +it("reports a checksum mismatch over the actual file body", async () => { + const data = Buffer.from("checksummed"); + const file = buildFfsFile({ + guid: "29111111-2222-3333-4444-555555555555", + typeCode: 1, + payload: data, + fileChecksum: "wrong", + }); + const fv = buildFv({ files: [file] }); + const scan = await scanUefiImage( + fv.buffer, + { maxDepth: 3, maxVolumes: 2, maxFiles: 2 }, + noDecoder, + ); + expect(scan.integrity).toMatchObject([ + { + kind: "ffs-file-checksum-mismatch", + range: { offset: 96, length: data.length }, + }, + ]); +}); + +it("reports one gap when a confirmed decoded FV exceeds the volume budget", async () => { + const nested = buildFv({ files: [] }); + const decoder = decodeNestedFv(nested.buffer); + const file = driverFile( + "29111111-2222-3333-4444-555555555555", + buildLzmaGuidedSection(Buffer.from([0xde, 0xad, 0xbe, 0xef])), + ); + const fv = buildFv({ files: [file] }); + const scan = await scanUefiImage( + fv.buffer, + { maxDepth: 3, maxVolumes: 1, maxFiles: 2 }, + decoder, + ); + expect(scan.omissions).toMatchObject([ + { + kind: "size-truncated", + range: { offset: 0, length: nested.buffer.length }, + }, + ]); + expect(scan.coverage).toBe("partial"); +}); diff --git a/src/uefi/UefiImageScan.ts b/src/uefi/UefiImageScan.ts new file mode 100644 index 0000000000..a543a70295 --- /dev/null +++ b/src/uefi/UefiImageScan.ts @@ -0,0 +1,971 @@ +import { + scanPspDirectories, + type PspTableRecord, + type PspCandidateRecord, +} from "./UefiPspDirectory.js"; +import { Budget } from "../domain/budget.js"; +import { BinaryReader } from "../domain/binaryContainer.js"; +import { sha256Hex } from "../kernel/sha256Hex.js"; +import { Buffer } from "node:buffer"; +import { UEFI_FIRMWARE_LIMITS } from "../domain/uefi/uefiLimits.js"; +import type { + UefiExtractResult, + UefiFfsFileRecord, + UefiIntegrityRecord, + UefiSectionRecord, + UefiUnknownRegion, + UefiVolumeRecord, +} from "../domain/uefi/uefiFirmwareAnalysis.js"; +import { + FFS_TYPE_NAME_BY_CODE, + FV_HEADER_LAYOUT, + SECTION_TYPE_NAME_BY_CODE, +} from "./UefiCodeTables.js"; +import type { UefiDecodeFailureReason } from "./UefiLzmaProtocol.js"; +import { + checkFfsFileData, + nextFfsFileLocal, + readFfsHeader, +} from "./FfsFile.js"; +import { + AMD_ZLIB_HEADER_LENGTH, + peelAmiZlibPayload, + startsWithSectionFrame, + walkSections, + type UefiDecodeFormat, +} from "./FfsSections.js"; +import { + parseFirmwareVolumeHeader, + scanFirmwareVolumes, + type FirmwareVolumeHeader, + unsupportedVolumeBodyReason, +} from "./FirmwareVolume.js"; +import { + absoluteOffset, + imageRegion, + isWindowUniform, + localOffsetOf, + sliceRegion, + type ScanRegion, +} from "./UefiBytes.js"; + +/** Successful external LZMA decode handed back to the scan. */ +interface UefiLzmaDecodeOutcome { + readonly bytes: Buffer; + readonly decoderVersion: string; +} + +/** One decodable stream submitted to the injected decode lane. */ +interface UefiLzmaDecodeRequest { + readonly payload: Buffer; + readonly format: UefiDecodeFormat; + readonly maxOutputBytes: number; +} + +/** + * The decoder reports recoverable format and output failures as result data. + * The scan retains the carrier and diagnostic for extraction. + */ +export type UefiDecodeResult = + | { readonly ok: true; readonly outcome: UefiLzmaDecodeOutcome } + | { + readonly ok: false; + readonly reason: UefiDecodeFailureReason; + readonly message: string; + }; + +export type UefiLzmaDecoder = ( + request: UefiLzmaDecodeRequest, +) => Promise; + +interface UefiScanLimits { + readonly maxDepth: number; + readonly maxVolumes: number; + readonly maxFiles: number; +} + +/** Payload bytes and the exact window in the stream that supplied them. */ +export interface UefiPayload { + readonly bytes: Buffer; + readonly sourceStream: string | null; + readonly range: { readonly offset: number; readonly length: number }; +} + +interface UefiDecodedStream { + readonly bytes: Buffer; + readonly format: UefiDecodeFormat; + readonly decoderVersion: string; + readonly carrier: UefiPayload; +} + +type ScanOmission = UefiExtractResult["extraction_gaps"][number]; +export interface UefiImageScanSummary { + readonly inputSize: number; + readonly payloads: ReadonlyMap; + readonly decodedStreams: ReadonlyMap; + readonly compressedCarriers: ReadonlyMap; + readonly volumes: readonly UefiVolumeRecord[]; + readonly unknownRegions: readonly UefiUnknownRegion[]; + readonly omissions: readonly ScanOmission[]; + readonly integrity: readonly UefiIntegrityRecord[]; + readonly pspTables: readonly PspTableRecord[]; + readonly pspCandidates: readonly PspCandidateRecord[]; + readonly limitations: readonly string[]; + readonly coverage: "complete" | "partial"; +} + +type VolumeBuilder = { + -readonly [K in keyof UefiVolumeRecord]: UefiVolumeRecord[K]; +}; +type FileBuilder = { + -readonly [K in keyof UefiFfsFileRecord]: UefiFfsFileRecord[K]; +}; +type SectionBuilder = { + -readonly [K in keyof UefiSectionRecord]: UefiSectionRecord[K]; +}; + +const hex = (value: number): string => `0x${value.toString(16)}`; + +/** Table names mirror the contract enum; unlisted codes report "unknown". */ +const ffsTypeNameFor = (code: number): UefiFfsFileRecord["type_name"] => { + const name = FFS_TYPE_NAME_BY_CODE[code] as string | undefined; + return (name ?? "unknown") as UefiFfsFileRecord["type_name"]; +}; + +/** + * Scan one full firmware image: volume discovery, FFS and section mapping, + * explicit recursion into nested volumes and externally decoded LZMA + * payloads, conservative PSP probing, and classification of leftover bytes. + * The decode lane is injected so the scan stays testable without a child + * process; the provider supplies the bounded worker. + */ +export const scanUefiImage = async ( + image: Buffer, + limits: UefiScanLimits, + decodeLzma: UefiLzmaDecoder, + checkpoint: () => void = () => {}, +): Promise => { + const payloads = new Map(); + const decodedStreams = new Map(); + const compressedCarriers = new Map(); + let decodedBytes = 0; + const records = new Budget(UEFI_FIRMWARE_LIMITS.scanRecords); + let structuralLimitReached = false; + const reserve = (count = 1): boolean => { + checkpoint(); + if (structuralLimitReached) return false; + if (records.tryCharge(count)) return true; + structuralLimitReached = true; + limitations.push( + `Structural record limit ${UEFI_FIRMWARE_LIMITS.scanRecords} reached.`, + ); + return false; + }; + const payloadOf = ( + region: ScanRegion, + start: number, + end: number, + ): UefiPayload => ({ + bytes: region.buffer.subarray(start, end), + sourceStream: region.sourceStream ?? null, + range: { offset: absoluteOffset(region, start), length: end - start }, + }); + const volumes: VolumeBuilder[] = []; + const unknownRegions: UefiUnknownRegion[] = []; + const omissions: ScanOmission[] = []; + const integrity: UefiIntegrityRecord[] = []; + const limitations: string[] = []; + let incompleteFraming = false; + let filesDiscovered = 0; + let volumesDiscovered = 0; + + const noteIntegrity = ( + kind: UefiIntegrityRecord["kind"], + logicalPath: string, + offset: number, + length: number, + detail: string, + sourceStream: string | null, + ): void => { + if (!reserve()) return; + integrity.push({ + kind, + logical_path: logicalPath, + source_stream: sourceStream, + range: { offset, length }, + detail, + }); + }; + + const noteLimitations = (lines: readonly string[]): void => { + for (const line of lines) { + if (limitations.length >= 512) break; + limitations.push(line); + } + }; + + const recordOmission = (omission: ScanOmission): void => { + omissions.push(omission); + if (omission.kind !== "pad-file") noteLimitations([omission.detail]); + }; + + const noteOmission = ( + kind: ScanOmission["kind"], + region: ScanRegion, + logicalPath: string, + start: number, + end: number, + detail: string, + ): void => { + if (start >= end) return; + recordOmission({ + kind, + logical_path: logicalPath, + source_stream: region.sourceStream ?? null, + range: { offset: start, length: end - start }, + detail, + }); + }; + + const noteCarrierGap = ( + path: string, + payload: UefiPayload, + kind: ScanOmission["kind"], + detail: string, + ): null => { + if (payload.bytes.length > 0) compressedCarriers.set(path, payload); + recordOmission({ + kind, + logical_path: path, + source_stream: payload.sourceStream, + range: payload.range.length > 0 ? payload.range : null, + detail, + }); + return null; + }; + + const noteUnparsedRange = ( + region: ScanRegion, + absoluteStart: number, + absoluteEnd: number, + logicalPath: string, + known?: { + detail: string; + classification?: UefiUnknownRegion["classification"]; + }, + ): void => { + const length = absoluteEnd - absoluteStart; + if (length <= 0) return; + if (!reserve()) { + noteOmission( + "size-truncated", + region, + logicalPath, + absoluteStart, + absoluteEnd, + `Structural record limit reached before classifying bytes under ${logicalPath}.`, + ); + return; + } + const localStart = Math.max( + region.start, + Math.min(region.end, localOffsetOf(region, absoluteStart)), + ); + const localEnd = Math.max( + localStart, + Math.min(region.end, localStart + length), + ); + let classification: UefiUnknownRegion["classification"] = "no-fv-magic"; + let erasure: UefiUnknownRegion["erasure"] = "none"; + if (isWindowUniform(region.buffer, localStart, localEnd, 0xff)) { + classification = "erased-ff"; + erasure = "0xff"; + } else if (isWindowUniform(region.buffer, localStart, localEnd, 0x00)) { + classification = "erased-00"; + erasure = "0x00"; + } + unknownRegions.push({ + source_stream: region.sourceStream ?? null, + offset: absoluteStart, + length, + sha256: sha256Hex(region.buffer.subarray(localStart, localEnd)), + classification: known?.classification ?? classification, + erasure, + }); + if (known !== undefined || erasure === "none") { + noteOmission( + "unparsed-region", + region, + logicalPath, + absoluteStart, + absoluteEnd, + known?.detail ?? + `Unparsed region under ${logicalPath} at ${hex(absoluteStart)}, ${length} bytes.`, + ); + } + }; + + const scanVolumesInRegion = async ( + region: ScanRegion, + depth: number, + parentOffset: number | null, + parentLogicalPath: string, + mode: "volume-region" | "embedded-probe" = "volume-region", + ): Promise<{ + volumes: VolumeBuilder[]; + status: "mapped" | "absent" | "limited"; + }> => { + const localRecords: VolumeBuilder[] = []; + const regionEnd = absoluteOffset(region, region.end); + if (depth > limits.maxDepth) { + noteOmission( + "depth-limited", + region, + parentLogicalPath, + region.origin, + regionEnd, + `Volume depth limit ${limits.maxDepth} reached under ${parentLogicalPath}.`, + ); + return { volumes: localRecords, status: "limited" }; + } + const discovered = scanFirmwareVolumes( + region, + UEFI_FIRMWARE_LIMITS.scanRecords, + { + reserve, + skipNested: true, + }, + ); + for (const rejected of discovered.rejected) { + noteLimitations([ + `_FVH hit under ${parentLogicalPath} at ${hex(rejected.absoluteBase)} not confirmed: ${rejected.reason}.`, + ]); + if (mode === "volume-region" && rejected.truncation !== undefined) { + incompleteFraming = true; + } + } + + let volumeLimitFrom: number | undefined; + let mappedThrough = region.origin; + for (const { header } of discovered.volumes) { + if (volumesDiscovered >= limits.maxVolumes) { + volumeLimitFrom = header.absoluteBase; + break; + } + volumesDiscovered += 1; + noteUnparsedRange( + region, + mappedThrough, + header.absoluteBase, + parentLogicalPath, + ); + + const logicalPath = `${parentLogicalPath}/FV@${hex(header.absoluteBase)}`; + if (!header.checksumValid) { + noteIntegrity( + "fv-checksum-mismatch", + logicalPath, + header.absoluteBase, + header.headerLength, + "Volume header checksum does not sum to zero over HeaderLength bytes.", + region.sourceStream ?? null, + ); + } + const volumeEnd = Math.min( + header.absoluteBase + header.declaredLength, + absoluteOffset(region, region.end), + ); + const observed = sliceRegion( + region, + header.absoluteBase, + volumeEnd - header.absoluteBase, + ); + const volume: VolumeBuilder = { + source_stream: region.sourceStream ?? null, + parent_logical_path: parentOffset === null ? null : parentLogicalPath, + logical_path: logicalPath, + offset: header.absoluteBase, + length: Math.max(1, volumeEnd - header.absoluteBase), + declared_length: header.declaredLength, + depth, + parent_offset: parentOffset, + sha256: sha256Hex(observed ?? Buffer.alloc(0)), + file_system_guid: header.fileSystemGuid, + signature: "_FVH", + header_length: header.headerLength, + attributes: header.attributes, + revision: header.revision, + ext_header_offset: header.extHeaderOffset, + block_map: header.blockMap.map((entry) => ({ + num_blocks: entry.numBlocks, + length: entry.blockLength, + })), + ffs_files: [], + }; + volumes.push(volume); + if (header.fileSystem === "unsupported") { + noteUnparsedRange( + region, + volume.offset + volume.header_length, + volumeEnd, + logicalPath, + { + detail: unsupportedVolumeBodyReason(header), + classification: "unsupported-file-system", + }, + ); + } else { + await walkFiles(volume, header, depth, region, volumeEnd); + } + mappedThrough = volumeEnd; + localRecords.push(volume); + } + if (volumeLimitFrom !== undefined || discovered.limit !== null) { + const detail = + discovered.limit === "structural-records" + ? `Structural record limit reached during volume scan under ${parentLogicalPath}.` + : discovered.limit === "candidates" + ? `Volume candidate limit reached under ${parentLogicalPath}.` + : `Firmware volume budget ${limits.maxVolumes} reached under ${parentLogicalPath}.`; + noteOmission( + "size-truncated", + region, + parentLogicalPath, + volumeLimitFrom ?? mappedThrough, + regionEnd, + detail, + ); + return { volumes: localRecords, status: "limited" }; + } + if (mode === "volume-region" || localRecords.length > 0) { + noteUnparsedRange(region, mappedThrough, regionEnd, parentLogicalPath); + } + return { + volumes: localRecords, + status: localRecords.length > 0 ? "mapped" : "absent", + }; + }; + + const walkFiles = async ( + volume: VolumeBuilder, + header: FirmwareVolumeHeader, + depth: number, + parentRegion: ScanRegion, + volumeEnd: number, + ): Promise => { + const volumeLocalEnd = localOffsetOf(parentRegion, volumeEnd); + const fileAreaStart = Math.min(header.firstFileLocal, volumeLocalEnd); + const fileArea = subRegion(parentRegion, fileAreaStart, volumeLocalEnd); + let cursor = fileArea.start; + const reserveFile = (): boolean => + filesDiscovered < limits.maxFiles && reserve(); + while (cursor < fileArea.end) { + checkpoint(); + const read = readFfsHeader( + fileArea, + cursor, + header.erasePolarity, + reserveFile, + ); + const at = absoluteOffset(fileArea, cursor); + if (read.kind === "limited") { + noteOmission( + "size-truncated", + fileArea, + volume.logical_path, + at, + volumeEnd, + structuralLimitReached + ? `Structural record limit reached during FFS walk in ${volume.logical_path}.` + : `FFS file budget ${limits.maxFiles} reached inside ${volume.logical_path}.`, + ); + return; + } + if (read.kind === "unparsed") { + noteUnparsedRange( + fileArea, + read.offset, + read.offset + read.length, + volume.logical_path, + { + detail: `Unparsed FFS suffix in ${volume.logical_path} at ${hex(read.offset)}: ${read.length} bytes.`, + }, + ); + return; + } + if (read.kind === "end") break; + const fileHeader = read.header; + filesDiscovered += 1; + for (const implausibility of fileHeader.implausibilities) { + noteLimitations([ + `FFS header implausibility "${implausibility}" at ${hex(fileHeader.absoluteBase)} in ${volume.logical_path}.`, + ]); + } + const logicalPath = `${volume.logical_path}/FFS:${fileHeader.nameGuid ?? "unknown"}@${hex(fileHeader.absoluteBase)}`; + const truncatesArea = + fileHeader.extentIssue === "declared-length-truncates-region"; + if (fileHeader.extentIssue !== null) { + const detail = `FFS declares ${fileHeader.declaredLength} bytes; observed ${fileHeader.observedLength} bytes with a ${fileHeader.headerLength}-byte header (${fileHeader.extentIssue}).`; + noteOmission( + fileHeader.extentIssue === "unusable-header-state" + ? "unparsed-region" + : "size-truncated", + fileArea, + logicalPath, + fileHeader.absoluteBase, + fileHeader.absoluteBase + fileHeader.observedLength, + detail, + ); + if (fileHeader.extentIssue !== "unusable-header-state") + noteIntegrity( + "size-truncation", + logicalPath, + fileHeader.absoluteBase, + fileHeader.observedLength, + detail, + fileArea.sourceStream ?? null, + ); + } else if (fileHeader.typeCode === 0xf0) { + noteOmission( + "pad-file", + fileArea, + logicalPath, + fileHeader.absoluteBase, + fileHeader.absoluteBase + fileHeader.observedLength, + "Pad file extent retained.", + ); + } + if (!fileHeader.headerChecksumValid) { + noteIntegrity( + "ffs-header-checksum-mismatch", + logicalPath, + fileHeader.absoluteBase, + fileHeader.headerLength, + "FFS header checksum does not sum to zero with State and File bytes zeroed.", + fileArea.sourceStream ?? null, + ); + } + const checksum = checkFfsFileData(fileArea, fileHeader); + if (checksum.verdict === "invalid") { + noteIntegrity( + "ffs-file-checksum-mismatch", + logicalPath, + checksum.offset, + checksum.length, + "File data checksum differs from the declared IntegrityCheck.File byte.", + fileArea.sourceStream ?? null, + ); + } + const observedBytes = + sliceRegion( + parentRegion, + fileHeader.absoluteBase, + fileHeader.observedLength, + ) ?? Buffer.alloc(0); + + const sections: SectionBuilder[] = []; + let uiString: string | null = null; + if (fileHeader.typeCode !== 0xf0 && fileHeader.body !== null) { + const { start: bodyStart, end: observedEnd } = fileHeader.body; + const sectioned = + fileHeader.typeCode >= 0x02 && fileHeader.typeCode <= 0x0f; + if (sectioned) { + uiString = await walkSectionChain( + subRegion(fileArea, bodyStart, observedEnd), + logicalPath, + depth, + volume.offset, + sections, + ); + } else { + if (!truncatesArea) + payloads.set( + logicalPath, + payloadOf(fileArea, bodyStart, observedEnd), + ); + if ( + fileHeader.typeCode === 0x01 && + observedEnd - bodyStart >= FV_HEADER_LAYOUT.minimumLength + ) { + await scanVolumesInRegion( + subRegion(fileArea, bodyStart, observedEnd), + depth + 1, + volume.offset, + `${logicalPath}/embedded`, + "embedded-probe", + ); + } + } + } + + volume.ffs_files.push({ + source_stream: fileArea.sourceStream ?? null, + offset: fileHeader.absoluteBase, + header_length: fileHeader.headerLength, + length: fileHeader.observedLength, + declared_length: fileHeader.declaredLength, + guid: fileHeader.nameGuid ?? "ffffffff-ffff-ffff-ffff-ffffffffffff", + type_code: fileHeader.typeCode, + type_name: ffsTypeNameFor(fileHeader.typeCode), + attributes: fileHeader.attributes, + alignment: String(fileHeader.dataAlignment) as FileBuilder["alignment"], + state: fileHeader.rawState, + state_flags: fileHeader.stateFlags as FileBuilder["state_flags"], + checksum: checksum.verdict, + ui_string: uiString, + logical_path: logicalPath, + volume_offset: volume.offset, + sha256: sha256Hex(observedBytes), + sections, + }); + + if (truncatesArea) return; + cursor = nextFfsFileLocal(fileHeader, header.localBase); + } + const lastFile = volume.ffs_files.at(-1); + noteUnparsedRange( + fileArea, + lastFile === undefined + ? fileArea.origin + : lastFile.offset + lastFile.length, + volumeEnd, + volume.logical_path, + ); + }; + + const walkSectionChain = async ( + region: ScanRegion, + parentLogicalPath: string, + depth: number, + volumeOffset: number, + records: SectionBuilder[], + ): Promise => { + const walked = walkSections(region, reserve); + if (walked.remainder !== null) { + const limited = walked.remainder.kind === "limited"; + noteOmission( + limited ? "size-truncated" : "unparsed-region", + region, + parentLogicalPath, + absoluteOffset(region, walked.remainder.start), + absoluteOffset(region, region.end), + limited + ? `Structural record limit reached during section walk under ${parentLogicalPath}.` + : `Section chain under ${parentLogicalPath} ends with incomplete framing.`, + ); + } + for (const padding of walked.nonzeroPadding) { + noteOmission( + "unparsed-region", + region, + parentLogicalPath, + absoluteOffset(region, padding.start), + absoluteOffset(region, padding.end), + `Nonzero alignment bytes in section chain under ${parentLogicalPath}.`, + ); + } + let uiString: string | null = null; + for (const [index, draft] of walked.sections.entries()) { + checkpoint(); + const logicalPath = `${parentLogicalPath}/section[${index}]`; + const payload = + draft.payload === null + ? null + : payloadOf(region, draft.payload.start, draft.payload.end); + const compression = draft.compression; + const record: SectionBuilder = { + logical_path: logicalPath, + parent_logical_path: parentLogicalPath, + source_stream: region.sourceStream ?? null, + offset: draft.absoluteBase, + header_length: draft.headerLength, + length: draft.observedLength, + declared_length: draft.declaredLength, + truncated: draft.truncated, + malformed: draft.malformed, + type_code: draft.typeCode, + type_name: (SECTION_TYPE_NAME_BY_CODE[draft.typeCode] ?? + "unknown") as SectionBuilder["type_name"], + sha256: sha256Hex(payload?.bytes ?? Buffer.alloc(0)), + compression: + compression.kind === "none" + ? compression + : { + kind: compression.kind, + guid: compression.guid, + data_offset: compression.dataOffset, + attributes: compression.attributes, + }, + sub_volumes: [], + }; + records.push(record); + if (draft.truncated || draft.malformed) { + noteOmission( + draft.truncated ? "size-truncated" : "unparsed-region", + region, + logicalPath, + draft.absoluteBase, + draft.absoluteBase + draft.observedLength, + `Section ${logicalPath} framing is ${draft.malformed ? "malformed" : "truncated"}; declared ${draft.declaredLength} bytes, observed ${draft.observedLength}.`, + ); + continue; + } + if (draft.payload === null || payload === null) continue; + const content = draft.content; + if (content.kind === "unsupported") { + noteCarrierGap( + logicalPath, + payload, + content.gap, + `No decoder is available for ${compression.kind} section ${logicalPath}.`, + ); + continue; + } + if (content.kind !== "decode") { + // Stored GUID wrappers describe already-readable child sections. + if (compression.kind === "none") payloads.set(logicalPath, payload); + else if ( + content.kind === "stored-sections" && + content.guidedIntegrityUnchecked + ) + noteLimitations([ + `Guided integrity status for ${logicalPath} was not verified.`, + ]); + if (draft.payload.start === draft.payload.end) continue; + } + const payloadRegion = subRegion( + region, + draft.payload.start, + draft.payload.end, + ); + if (content.kind === "ui") { + uiString ??= decodeUiString(payload.bytes); + } else if (content.kind === "volume") { + const nested = await scanVolumesInRegion( + payloadRegion, + depth + 1, + volumeOffset, + logicalPath, + ); + record.sub_volumes = nested.volumes.map((entry) => entry.logical_path); + } else if (content.kind === "stored-sections") { + if (depth >= limits.maxDepth) { + noteOmission( + "depth-limited", + payloadRegion, + logicalPath, + payload.range.offset, + payload.range.offset + payload.range.length, + `Section depth limit reached under ${logicalPath}.`, + ); + } else { + const childUi = await walkSectionChain( + payloadRegion, + logicalPath, + depth + 1, + volumeOffset, + records, + ); + uiString ??= childUi; + } + } else if (content.kind === "decode") { + const decoded = await resolveDecodedSection( + payload, + logicalPath, + depth, + content.format, + ); + if (decoded === null) continue; + const decodedRegion: ScanRegion = { + buffer: decoded.bytes, + start: 0, + end: decoded.bytes.length, + origin: 0, + sourceStream: logicalPath, + }; + // Select the outer framing before scanning for embedded volume magic. + const leadingSection = startsWithSectionFrame(decodedRegion); + const rootVolume = leadingSection + ? parseFirmwareVolumeHeader( + decodedRegion, + decodedRegion.start, + reserve, + ) + : null; + const sectionsFirst = + leadingSection && + (rootVolume === null || rootVolume.implausibilities.length > 0); + if (!sectionsFirst) { + const nested = await scanVolumesInRegion( + decodedRegion, + depth + 1, + volumeOffset, + `${logicalPath}/${decoded.format}`, + "embedded-probe", + ); + record.sub_volumes = nested.volumes.map( + (entry) => entry.logical_path, + ); + if (nested.status === "absent" && !structuralLimitReached) { + noteUnparsedRange( + decodedRegion, + 0, + decoded.bytes.length, + logicalPath, + { + detail: `Decoded stream at ${logicalPath} has no confirmed volume or section framing; decoded bytes retained.`, + }, + ); + } + } else { + const childUi = await walkSectionChain( + decodedRegion, + logicalPath, + depth + 1, + volumeOffset, + records, + ); + uiString ??= childUi; + } + } + } + return uiString; + }; + + const resolveDecodedSection = async ( + payload: UefiPayload, + logicalPath: string, + depth: number, + format: UefiDecodeFormat, + ): Promise => { + const maxOutputBytes = Math.min( + UEFI_FIRMWARE_LIMITS.lzmaOutputBytes, + UEFI_FIRMWARE_LIMITS.decodedBytes - decodedBytes, + ); + if (depth >= limits.maxDepth) + return noteCarrierGap( + logicalPath, + payload, + "depth-limited", + `Decode depth limit reached under ${logicalPath}.`, + ); + if (maxOutputBytes <= 0) + return noteCarrierGap( + logicalPath, + payload, + "size-truncated", + `Aggregate decoded output limit reached under ${logicalPath}.`, + ); + if (payload.bytes.length === 0) + return noteCarrierGap( + logicalPath, + payload, + "unparsed-region", + `Empty ${format} carrier at ${logicalPath}.`, + ); + let carrier = payload; + if (format === "zlib") { + const peeled = peelAmiZlibPayload(payload.bytes); + if ( + peeled === null || + peeled.declaredCompressedSize !== peeled.stream.length + ) { + return noteCarrierGap( + logicalPath, + payload, + "unparsed-region", + `Invalid AMD zlib header or stream length at ${logicalPath}; carrier retained.`, + ); + } + carrier = { + bytes: peeled.stream, + sourceStream: payload.sourceStream, + range: { + offset: payload.range.offset + AMD_ZLIB_HEADER_LENGTH, + length: peeled.stream.length, + }, + }; + } + const decodedResult = await decodeLzma({ + payload: carrier.bytes, + format, + maxOutputBytes, + }); + checkpoint(); + if (!decodedResult.ok) { + return noteCarrierGap( + logicalPath, + payload, + decodedResult.reason === "output-limit" + ? "size-truncated" + : "unparsed-region", + `${format} decode failed at ${logicalPath}: ${decodedResult.message}`, + ); + } + const outcome = decodedResult.outcome; + if (outcome.bytes.length > maxOutputBytes) { + return noteCarrierGap( + logicalPath, + payload, + "size-truncated", + `Decoded output exceeded its byte limit at ${logicalPath}.`, + ); + } + decodedBytes += outcome.bytes.length; + const decoded = { + bytes: outcome.bytes, + format, + decoderVersion: outcome.decoderVersion, + carrier, + } as const; + decodedStreams.set(logicalPath, decoded); + return decoded; + }; + + const imageRegion0 = imageRegion(image, 0, image.length); + await scanVolumesInRegion(imageRegion0, 0, null, "flash"); + + const { tables: pspTables, candidates: pspCandidates } = scanPspDirectories( + image, + reserve, + ); + + return { + inputSize: image.length, + payloads, + decodedStreams, + compressedCarriers, + volumes, + unknownRegions, + integrity, + pspTables, + pspCandidates, + limitations, + omissions, + coverage: + structuralLimitReached || + incompleteFraming || + omissions.some(({ kind }) => kind !== "pad-file") + ? "partial" + : "complete", + }; +}; + +const subRegion = ( + region: ScanRegion, + start: number, + end: number, +): ScanRegion => ({ + ...region, + start, + end, + origin: absoluteOffset(region, start), +}); + +const decodeUiString = (payload: Buffer): string | null => { + const payloadReader = new BinaryReader(payload, true, "UEFI UI section"); + const limit = Math.min(payload.length - (payload.length % 2), 1024); + let end = 0; + while (end < limit && payloadReader.u16(end) !== 0) end += 2; + return end === 0 ? null : payload.toString("utf16le", 0, end); +}; diff --git a/src/uefi/UefiLzmaProtocol.ts b/src/uefi/UefiLzmaProtocol.ts new file mode 100644 index 0000000000..0ed8e2a625 --- /dev/null +++ b/src/uefi/UefiLzmaProtocol.ts @@ -0,0 +1,37 @@ +import { z } from "zod"; + +import { digestSchema } from "../domain/digests.js"; +import { UEFI_FIRMWARE_LIMITS } from "../domain/uefi/uefiLimits.js"; + +const decodeFailureReasonSchema = z.enum(["format", "decoder", "output-limit"]); +export type UefiDecodeFailureReason = z.infer; + +export const lzmaRequestSchema = z.strictObject({ + format: z.enum(["lzma", "lzmaf86"]), + payload_path: z.string(), + output_path: z.string(), + reply_path: z.string(), + max_output_bytes: z + .number() + .int() + .min(1) + .max(UEFI_FIRMWARE_LIMITS.lzmaOutputBytes), +}); + +export const lzmaReplySchema = z.discriminatedUnion("ok", [ + z.strictObject({ + ok: z.literal(true), + lzma_version: z.string(), + output: z.strictObject({ + sha256: digestSchema, + bytes: z.number().int().min(0), + }), + }), + z.strictObject({ + ok: z.literal(false), + reason: decodeFailureReasonSchema, + message: z.string(), + }), +]); + +export type UefiLzmaReply = z.infer; diff --git a/src/uefi/UefiLzmaWorker.ts b/src/uefi/UefiLzmaWorker.ts new file mode 100644 index 0000000000..a9b3facd9e --- /dev/null +++ b/src/uefi/UefiLzmaWorker.ts @@ -0,0 +1,168 @@ +import { BinaryReader } from "../domain/binaryContainer.js"; +import { sha256Hex } from "../kernel/sha256Hex.js"; +import { Budget } from "../domain/budget.js"; +import { + decodeLimit, + malformedInput, + parseFailureFromCause, + truncatedInput, +} from "../domain/parseFailure.js"; +import { errorMessage } from "../kernel/errorMessage.js"; +import { readFile, writeFile } from "node:fs/promises"; +import { createRequire } from "node:module"; +import { join } from "node:path"; +import { z } from "zod"; +import { undoUefiX86BranchFilter } from "./UefiX86BranchFilter.js"; +import { lzmaRequestSchema, type UefiLzmaReply } from "./UefiLzmaProtocol.js"; +import { UEFI_FIRMWARE_LIMITS } from "../domain/uefi/uefiLimits.js"; + +/** + * Output sink that enforces the byte budget while the decoder writes, instead + * of after the whole stream has expanded in memory. It grows on demand up to + * the limit and throws as soon as the stream would cross it. + */ +class BoundedLzmaOutput { + #buffer: Buffer; + readonly #budget: Budget; + + constructor(readonly limit: number) { + this.#budget = new Budget(limit); + this.#buffer = Buffer.allocUnsafe(Math.min(limit, 0x10000)); + } + + writeByte(byte: number): void { + const position = this.#budget.used; + if (!this.#budget.tryCharge(1)) + throw decodeLimit( + "LZMA", + `Decompressed output exceeds the ${this.limit} byte budget.`, + { name: "output_bytes", maximum: this.limit, required: position + 1 }, + ); + if (position >= this.#buffer.length) { + const next = Buffer.allocUnsafe( + Math.min(this.limit, this.#buffer.length * 2), + ); + this.#buffer.copy(next, 0, 0, position); + this.#buffer = next; + } + this.#buffer[position] = byte; + } + + getBuffer(): Buffer { + return this.#buffer.subarray(0, this.#budget.used); + } +} + +const main = async (): Promise => { + const requestPath = process.argv[2]; + if (requestPath === undefined) { + throw new Error("Owned worker request path missing."); + } + const request = lzmaRequestSchema.parse( + JSON.parse(await readFile(requestPath, "utf8")), + ); + let reply: UefiLzmaReply; + try { + const require2 = createRequire(import.meta.url); + const lzma = require2("lzma-purejs"); + const workerModulePath = require2.resolve("lzma-purejs"); + const upstreamMetadata = JSON.parse( + await readFile(join(workerModulePath, "..", "package.json"), "utf8"), + ); + const decoderVersion = z + .object({ version: z.string() }) + .parse(upstreamMetadata).version; + + const payload = await readFile(request.payload_path); + // .lzma (LZMA-Alone) declares the dictionary before any compressed bytes. + // The upstream decoder allocates its window before it writes to our sink. + if (payload.length < 13) + throw truncatedInput("LZMA-Alone", "Incomplete LZMA stream properties."); + const reader = new BinaryReader(payload, true, "LZMA-Alone"); + const dictionaryBytes = reader.u32(1); + if (dictionaryBytes > UEFI_FIRMWARE_LIMITS.lzmaOutputBytes) { + throw decodeLimit( + "LZMA", + "LZMA dictionary exceeds the worker memory budget.", + { + name: "dictionary_bytes", + maximum: UEFI_FIRMWARE_LIMITS.lzmaOutputBytes, + required: dictionaryBytes, + }, + ); + } + const declaredOutputSize = reader.word(5, 64); + const declaredOutput = + declaredOutputSize === 0xffffffffffffffffn ? null : declaredOutputSize; + if ( + declaredOutput !== null && + declaredOutput > BigInt(request.max_output_bytes) + ) { + throw decodeLimit( + "LZMA", + `Declared LZMA output exceeds ${request.max_output_bytes} bytes.`, + { + name: "output_bytes", + maximum: request.max_output_bytes, + required: declaredOutput, + }, + ); + } + const output = new BoundedLzmaOutput(request.max_output_bytes); + let position = 0; + lzma.decompressFile( + { + readByte() { + if (position === payload.length) + throw truncatedInput( + "LZMA-Alone", + "Compressed stream ends before the decoder can finish.", + ); + return reader.u8(position++); + }, + }, + output, + ); + const decoded = output.getBuffer(); + if (declaredOutput !== null && BigInt(decoded.length) !== declaredOutput) { + throw malformedInput( + "LZMA-Alone", + `LZMA decoded ${decoded.length} bytes; stream declared ${declaredOutput} bytes.`, + ); + } + if (request.format === "lzmaf86") undoUefiX86BranchFilter(decoded); + await writeFile(request.output_path, decoded, { flag: "wx", mode: 0o600 }); + reply = { + ok: true, + lzma_version: decoderVersion, + output: { + sha256: sha256Hex(decoded), + bytes: decoded.length, + }, + }; + } catch (cause: unknown) { + const failure = parseFailureFromCause(cause); + reply = { + ok: false, + reason: + failure === undefined + ? "decoder" + : failure.kind === "limit" + ? "output-limit" + : "format", + message: errorMessage(cause), + }; + } + let encoded = JSON.stringify(reply); + if (Buffer.byteLength(encoded) > UEFI_FIRMWARE_LIMITS.diagnosticBytes) { + const bounded: UefiLzmaReply = { + ok: false, + reason: reply.ok ? "decoder" : reply.reason, + message: "LZMA reply exceeds the diagnostic budget.", + }; + encoded = JSON.stringify(bounded); + } + await writeFile(request.reply_path, encoded, { flag: "wx", mode: 0o600 }); +}; + +await main(); diff --git a/src/uefi/UefiNvram.test.ts b/src/uefi/UefiNvram.test.ts new file mode 100644 index 0000000000..38c68b55e5 --- /dev/null +++ b/src/uefi/UefiNvram.test.ts @@ -0,0 +1,224 @@ +import { Buffer } from "node:buffer"; +import { expect, it } from "vitest"; +import { scanAmiNvramStores } from "./UefiNvram.js"; + +const NVAR_MAGIC = Buffer.from("NVAR", "ascii"); + +const encodeEntry = (name: string, data: Buffer, guidIndex: number): Buffer => { + const nameBytes = Buffer.from(name, "ascii"); + const total = 11 + nameBytes.length + 1 + data.length; + const entry = Buffer.alloc(total, 0); + NVAR_MAGIC.copy(entry, 0); + entry.writeUInt16LE(total, 4); + entry.writeUIntLE(0xffffff, 6, 3); + entry.writeUInt8(0x83, 9); + entry.writeUInt8(guidIndex, 10); + nameBytes.copy(entry, 11); + data.copy(entry, 11 + nameBytes.length + 1); + return entry; +}; + +it("parses one AMI NVRAM entry with name, attributes, GUID index and data range", () => { + const entry = encodeEntry("Setup", Buffer.from([0xde, 0xad]), 3); + const parsed = scanAmiNvramStores(entry, 1, 1).stores[0]?.variables[0]; + expect(parsed).not.toBeNull(); + expect(parsed?.name).toBe("Setup"); + expect(parsed?.attributes).toBe(0x83); + expect(parsed?.guidIndex).toBe(3); + expect(parsed?.dataOffset).toBe(11 + 5 + 1); + expect(parsed?.dataLength).toBe(2); + expect(parsed?.endOffset).toBe(entry.length); +}); + +it("recurses into a StdDefaults container and exposes its nested variables", () => { + const nested = Buffer.concat([ + encodeEntry("Setup", Buffer.from([0x01, 0x01, 0x00, 0x00]), 0), + encodeEntry("PlatformLang", Buffer.from("en-US\0", "ascii"), 1), + Buffer.alloc(4, 0xff), + ]); + const store = encodeEntry("StdDefaults", nested, 0); + const scan = scanAmiNvramStores(store, 16, 2); + expect(scan.coverage).toBe("complete"); + expect(scan.stores).toHaveLength(1); + const found = scan.stores[0]; + if (found === undefined) throw new Error("expected exactly one store"); + expect(found.name).toBe("StdDefaults"); + expect(found.variables.map((v) => [v.name, v.depth])).toEqual([ + ["StdDefaults", 0], + ["Setup", 1], + ["PlatformLang", 1], + ]); + expect(found.variables[0]?.parentOffset).toBeNull(); + expect(found.variables[1]?.parentOffset).toBe(0); +}); + +it("walks a flat sibling chain without treating it as a container", () => { + const flat = Buffer.concat([ + encodeEntry("First", Buffer.from([0x10]), 0), + encodeEntry("Second", Buffer.from([0x20, 0x21]), 1), + Buffer.alloc(8, 0xff), + ]); + const scan = scanAmiNvramStores(flat, 16, 2); + expect(scan.stores).toHaveLength(1); + const found = scan.stores[0]; + if (found === undefined) throw new Error("expected exactly one store"); + expect(found.name).toBe("First"); + expect(found.variables.map((v) => [v.name, v.depth])).toEqual([ + ["First", 0], + ["Second", 0], + ]); + expect(found.trailingPadding).toBe(8); +}); + +it("rejects NVAR byte runs that do not match the record framing", () => { + const image = Buffer.concat([NVAR_MAGIC, Buffer.alloc(20, 0x00)]); + const scan = scanAmiNvramStores(image, 16, 2); + expect(scan.stores).toHaveLength(0); + expect(scan.limitations.join(" ")).toContain("No AMI NVRAM"); +}); + +it("keeps a container's child walk inside the container boundary", () => { + const child = encodeEntry("Child", Buffer.alloc(0), 0); + const outer = encodeEntry("Outer", child, 0); + const sibling = encodeEntry("Sibling", Buffer.alloc(0), 0); + const scan = scanAmiNvramStores(Buffer.concat([outer, sibling]), 16, 2); + expect(scan.stores).toHaveLength(1); + const found = scan.stores[0]; + if (found === undefined) throw new Error("expected exactly one store"); + // Child belongs to Outer; Sibling is a top-level peer, not a second child. + expect(found.variables.map((v) => [v.name, v.depth])).toEqual([ + ["Outer", 0], + ["Child", 1], + ["Sibling", 0], + ]); +}); + +it("reports partial coverage when a nested chain exceeds max_depth", () => { + const leaf = encodeEntry("Leaf", Buffer.alloc(0), 0); + const mid = encodeEntry("Mid", leaf, 0); + const top = encodeEntry("Top", mid, 0); + const scan = scanAmiNvramStores(top, 16, 1); + expect(scan.coverage).toBe("partial"); + expect(scan.limitations.join(" ")).toContain("max_depth 1"); + const found = scan.stores[0]; + if (found === undefined) throw new Error("expected exactly one store"); + expect(found.variables.map((v) => [v.name, v.depth])).toEqual([ + ["Top", 0], + ["Mid", 1], + ]); +}); + +it("returns partial NVAR coverage when a single store exhausts the record limit", () => { + const record = encodeEntry("A", Buffer.alloc(0), 0); + const image = Buffer.alloc(100_001 * record.length); + for (let offset = 0; offset < image.length; offset += record.length) + record.copy(image, offset); + const result = scanAmiNvramStores(image, 1, 1); + expect(result.coverage).toBe("partial"); + expect(result.limitations[0]).toContain("Structural record limit"); + expect(result.stores[0]?.variables.length).toBe(100_000); +}); + +it("preserves a named record's link to a data-only entry without inventing a GUID index", () => { + const named = encodeEntry("Setup", Buffer.from([0x42]), 3); + named.writeUIntLE(named.length, 6, 3); + const dataOnly = Buffer.from([ + 0x4e, 0x56, 0x41, 0x52, 12, 0, 0xff, 0xff, 0xff, 0x88, 0xaa, 0xbb, + ]); + const result = scanAmiNvramStores(Buffer.concat([named, dataOnly]), 16, 2); + expect(result.coverage).toBe("complete"); + expect(result.stores[0]?.variables).toMatchObject([ + { name: "Setup", next: named.length, attributes: 0x83, guidIndex: 3 }, + { + name: null, + next: 0xffffff, + attributes: 0x88, + guidIndex: null, + dataLength: 2, + }, + ]); +}); + +it("separates an inline GUID and UCS-2 name from data and the extended footer", () => { + const name = Buffer.from("Δ\0", "utf16le"); + const entry = Buffer.concat([ + Buffer.from([0x4e, 0x56, 0x41, 0x52, 0, 0, 0xff, 0xff, 0xff, 0x94]), + Buffer.from("78563412bc9af0de1122334455667788", "hex"), + name, + Buffer.from([0x42, 0, 3, 0]), + ]); + entry.writeUInt16LE(entry.length, 4); + const parsed = scanAmiNvramStores(entry, 1, 1).stores[0]?.variables[0]; + expect(parsed).toMatchObject({ + name: "Δ", + guid: "12345678-9abc-def0-1122-334455667788", + guidIndex: null, + dataOffset: 30, + dataLength: 1, + }); +}); + +it.each([false, true])( + "preserves active NVAR siblings across inactive records (nested: %s)", + (nested) => { + const first = encodeEntry("First", Buffer.from([1]), 0); + const inactive = encodeEntry("Inactive", Buffer.from([2]), 0); + inactive.writeUInt8(0x03, 9); + const later = encodeEntry("Later", Buffer.from([3]), 0); + const chain = Buffer.concat([first, inactive, later]); + const result = scanAmiNvramStores( + nested ? encodeEntry("Outer", chain, 0) : chain, + 16, + 2, + ); + expect(result.coverage).toBe("complete"); + expect(result.stores).toHaveLength(1); + expect(result.stores[0]?.variables.map(({ name }) => name)).toEqual( + nested ? ["Outer", "First", "Later"] : ["First", "Later"], + ); + }, +); + +it("reports a truncated successor under an established nested NVAR chain", () => { + const first = encodeEntry("First", Buffer.from([1]), 0); + const later = encodeEntry("Later", Buffer.from([2]), 0); + const chain = Buffer.concat([first, later.subarray(0, 7)]); + const result = scanAmiNvramStores(encodeEntry("Outer", chain, 0), 16, 2); + expect(result.stores[0]?.variables.map(({ name }) => name)).toEqual([ + "Outer", + "First", + ]); + expect(result.coverage).toBe("partial"); + expect(result.limitations.join(" ")).toContain("invalid extent"); +}); + +it("finds the first active child after an inactive prefix without leaving its container", () => { + const inactive = encodeEntry("Inactive", Buffer.alloc(0), 0); + inactive.writeUInt8(0x03, 9); + const active = encodeEntry("Later", Buffer.from([1]), 0); + const outer = encodeEntry( + "StdDefaults", + Buffer.concat([inactive, active]), + 0, + ); + const sibling = encodeEntry("Sibling", Buffer.from([2]), 0); + const data = Buffer.concat([outer, sibling]); + + const scan = scanAmiNvramStores(data, 16, 1); + expect(scan.coverage).toBe("complete"); + expect(scan.stores).toHaveLength(1); + expect( + scan.stores[0]?.variables.map(({ name, depth, parentOffset }) => [ + name, + depth, + parentOffset, + ]), + ).toEqual([ + ["StdDefaults", 0, null], + ["Later", 1, 0], + ["Sibling", 0, null], + ]); + const limited = scanAmiNvramStores(data, 16, 0); + expect(limited.coverage).toBe("partial"); + expect(limited.limitations.join(" ")).toContain("max_depth 0"); +}); diff --git a/src/uefi/UefiNvram.ts b/src/uefi/UefiNvram.ts new file mode 100644 index 0000000000..54c3f4bdbe --- /dev/null +++ b/src/uefi/UefiNvram.ts @@ -0,0 +1,341 @@ +import { BinaryReader } from "../domain/binaryContainer.js"; +import { formatGuidLittleEndian, GUID_LENGTH } from "./UefiGuid.js"; +import { UEFI_FIRMWARE_LIMITS } from "../domain/uefi/uefiLimits.js"; +/** + * AMI NVRAM variable-store cartography for UEFI flash images. + * + * Vendor AMI images carry factory defaults (and other setup state) in a + * proprietary variable store whose entries are chained by the ASCII magic + * "NVAR". This module finds those chains inside a raw image and reports their + * structure as observations; it never interprets the variable data and never + * executes anything. + * + * The fixed prefix contains magic, size, a 24-bit Next displacement and an + * 8-bit attribute field. Body framing follows the attributes. See the + * AMI NVAR format definition in UEFITool (common/ksy/ami_nvar.ksy). + * + * The factory-default store is itself one such entry (name "StdDefaults") whose + * data holds a nested NVAR chain of the individual setup variables. The scan + * therefore recurses into entries whose data starts with another valid entry, + * so the result is a flat list with `depth` and `parent_offset` describing the + * nesting instead of hiding the children behind an opaque data range. + */ + +/** "NVAR" stored as a little-endian uint32. */ +const NVAR_MAGIC = 0x5241564e; +const NVAR_HEADER_BYTES = 10; +const NVAR_MIN_ENTRY_BYTES = NVAR_HEADER_BYTES + 1; +const NVAR_ATTRIBUTES = { + valid: 0x80, + extendedHeader: 0x10, + dataOnly: 0x08, + localGuid: 0x04, + asciiName: 0x02, +} as const; +/** ASCII search needle for locating candidate chains. */ +const NVAR_BYTES = Buffer.from("NVAR", "ascii"); + +const isPrintableAscii = (byte: number): boolean => + byte >= 0x20 && byte <= 0x7e; + +/** One parsed entry, before nesting metadata is attached. */ +interface ParsedNvramEntry { + readonly offset: number; + readonly name: string | null; + readonly next: number; + readonly attributes: number; + readonly guidIndex: number | null; + readonly guid: string | null; + readonly dataOffset: number; + readonly dataLength: number; + /** Byte just past this entry; the next sibling entry starts here. */ + readonly endOffset: number; +} + +/** One parsed AMI NVRAM variable entry with its nesting position. */ +export interface AmiNvramVariable extends ParsedNvramEntry { + /** 0 for a top-level entry, 1 for a variable inside a container, and so on. */ + readonly depth: number; + /** Offset of the enclosing container entry, or null at the top level. */ + readonly parentOffset: number | null; +} + +/** One top-level AMI NVRAM chain and its flattened nested variables. */ +export interface AmiNvramStore { + /** Offset of the first top-level entry. */ + readonly offset: number; + /** Name of the first top-level entry (for example "StdDefaults"). */ + readonly name: string | null; + /** Flattened entries across all depths, ordered by offset. */ + readonly variables: readonly AmiNvramVariable[]; + /** Count of trailing 0xFF padding bytes after the top-level chain, if any. */ + readonly trailingPadding: number | null; +} + +/** Outcome of scanning an image for AMI NVRAM stores. */ +export interface AmiNvramScan { + readonly stores: readonly AmiNvramStore[]; + readonly coverage: "complete" | "partial"; + readonly limitations: readonly string[]; +} + +/** Locate a nonempty, terminated name within the framed record body. */ +const readNvarName = ( + reader: BinaryReader, + start: number, + end: number, + ascii: boolean, +): { name: string; dataOffset: number } | null => { + const width = ascii ? 1 : 2; + for (let cursor = start; cursor + width <= end; cursor += width) { + const unit = ascii ? reader.u8(cursor) : reader.u16(cursor); + if (unit === 0) { + if (cursor === start) return null; + return { + name: reader.bytes.toString(ascii ? "ascii" : "utf16le", start, cursor), + dataOffset: cursor + width, + }; + } + if ( + ascii + ? !isPrintableAscii(unit) + : unit < 0x20 || (unit >= 0xd800 && unit <= 0xdfff) + ) + return null; + } + return null; +}; + +type FramedNvarRecord = + | { kind: "inactive" | "malformed"; endOffset: number } + | { kind: "active"; entry: ParsedNvramEntry }; + +type NvarRecord = + | { kind: "end" } + | { kind: "invalid-frame" } + | FramedNvarRecord; + +function readNvarRecord( + reader: BinaryReader, + offset: number, + endOffset: number, +): NvarRecord { + if ( + offset < 0 || + offset + NVAR_BYTES.length > endOffset || + reader.u32(offset) !== NVAR_MAGIC + ) + return { kind: "end" }; + if (offset + NVAR_HEADER_BYTES > endOffset) return { kind: "invalid-frame" }; + const totalSize = reader.u16(offset + 4); + const entryEnd = offset + totalSize; + if (totalSize < NVAR_HEADER_BYTES || entryEnd > endOffset) + return { kind: "invalid-frame" }; + + const attributes = reader.u8(offset + 9); + if ((attributes & NVAR_ATTRIBUTES.valid) === 0) + return { kind: "inactive", endOffset: entryEnd }; + const entry = parseActiveRecord(reader, offset, entryEnd, attributes); + return entry === null + ? { kind: "malformed", endOffset: entryEnd } + : { kind: "active", entry }; +} + +function parseActiveRecord( + reader: BinaryReader, + offset: number, + entryEnd: number, + attributes: number, +): ParsedNvramEntry | null { + if (entryEnd - offset < NVAR_MIN_ENTRY_BYTES) return null; + const next = reader.u16(offset + 6) | (reader.u8(offset + 8) << 16); + const bodyStart = offset + NVAR_HEADER_BYTES; + let dataEnd = entryEnd; + if ((attributes & NVAR_ATTRIBUTES.extendedHeader) !== 0) { + if (entryEnd - bodyStart < 3) return null; + const extensionSize = reader.u16(entryEnd - 2); + if (extensionSize < 3 || extensionSize > entryEnd - bodyStart) return null; + dataEnd -= extensionSize; + } + + let dataOffset = bodyStart; + let name: string | null = null; + let guidIndex: number | null = null; + let guid: string | null = null; + if ((attributes & NVAR_ATTRIBUTES.dataOnly) === 0) { + const inlineGuid = (attributes & NVAR_ATTRIBUTES.localGuid) !== 0; + const nameStart = bodyStart + (inlineGuid ? GUID_LENGTH : 1); + const parsedName = readNvarName( + reader, + nameStart, + dataEnd, + (attributes & NVAR_ATTRIBUTES.asciiName) !== 0, + ); + if (parsedName === null) return null; + ({ name, dataOffset } = parsedName); + if (inlineGuid) guid = formatGuidLittleEndian(reader.bytes, bodyStart); + else guidIndex = reader.u8(bodyStart); + } + + return { + offset, + name, + next, + attributes, + guidIndex, + guid, + dataOffset, + dataLength: dataEnd - dataOffset, + endOffset: entryEnd, + }; +} + +/** Walk a confirmed chain without using record bodies to advance its cursor. */ +function collectChain( + reader: BinaryReader, + first: { offset: number; record: FramedNvarRecord }, + endOffset: number, + depth: number, + parentOffset: number | null, + maxDepth: number, + out: AmiNvramVariable[], + reserve: () => boolean, + noteOmission: (detail: string) => void, +): number { + let cursor = first.offset; + let record: NvarRecord = first.record; + while (record.kind !== "end") { + if (!reserve()) break; + if (record.kind === "invalid-frame") { + noteOmission( + `NVAR record at 0x${cursor.toString(16)} has an incomplete or invalid extent.`, + ); + break; + } + if (record.kind !== "active") { + if (record.kind === "malformed") + noteOmission( + `NVAR record at 0x${cursor.toString(16)} has malformed variable data.`, + ); + cursor = record.endOffset; + record = readNvarRecord(reader, cursor, endOffset); + continue; + } + + const { entry } = record; + out.push({ ...entry, depth, parentOffset }); + const dataEnd = entry.dataOffset + entry.dataLength; + const nested = readNvarRecord(reader, entry.dataOffset, dataEnd); + // Framing can establish a nested chain even if its first body is unusable. + if (nested.kind !== "end" && nested.kind !== "invalid-frame") { + if (depth < maxDepth) { + collectChain( + reader, + { offset: entry.dataOffset, record: nested }, + dataEnd, + depth + 1, + entry.offset, + maxDepth, + out, + reserve, + noteOmission, + ); + } else { + noteOmission( + `Nested NVAR chain below max_depth ${maxDepth} under variable at 0x${entry.offset.toString(16)}.`, + ); + } + } + cursor = entry.endOffset; + record = readNvarRecord(reader, cursor, endOffset); + } + return cursor; +} + +/** Scan a raw image for chained AMI NVRAM variable stores. */ +export const scanAmiNvramStores = ( + image: Buffer, + maxStores: number, + maxDepth: number, + checkpoint: () => void = () => {}, +): AmiNvramScan => { + const stores: AmiNvramStore[] = []; + const limitations: string[] = []; + const reader = new BinaryReader(image, true, "AMI NVAR"); + let partial = false; + const noteOmission = (detail: string): void => { + partial = true; + if (limitations.length < 512) limitations.push(detail); + }; + let remaining: number = UEFI_FIRMWARE_LIMITS.scanRecords; + let recordLimited = false; + const reserve = (): boolean => { + checkpoint(); + if (remaining === 0) { + recordLimited = true; + return false; + } + remaining -= 1; + return true; + }; + let searchFrom = 0; + while (searchFrom + NVAR_MIN_ENTRY_BYTES <= image.length) { + checkpoint(); + const firstOffset = image.indexOf(NVAR_BYTES, searchFrom); + if (firstOffset < 0) break; + const first = readNvarRecord(reader, firstOffset, image.length); + if (first.kind !== "active") { + searchFrom = firstOffset + 1; + continue; + } + if (stores.length >= maxStores) { + limitations.push( + `Stopped after ${maxStores} AMI NVRAM stores; additional stores exist.`, + ); + return { stores, coverage: "partial", limitations }; + } + const variables: AmiNvramVariable[] = []; + const lastEnd = collectChain( + reader, + { offset: firstOffset, record: first }, + image.length, + 0, + null, + maxDepth, + variables, + reserve, + noteOmission, + ); + let padding = 0; + while ( + lastEnd + padding < image.length && + image[lastEnd + padding] === 0xff + ) { + if (padding % 65536 === 0) checkpoint(); + padding += 1; + } + if (variables.length > 0) + stores.push({ + offset: firstOffset, + name: first.entry.name, + variables, + trailingPadding: padding > 0 ? padding : null, + }); + searchFrom = Math.max(firstOffset + 1, lastEnd); + if (recordLimited) { + limitations.push( + `Structural record limit ${UEFI_FIRMWARE_LIMITS.scanRecords} reached in the NVAR chain at 0x${firstOffset.toString(16)}.`, + ); + return { stores, coverage: "partial", limitations }; + } + } + if (stores.length === 0) + limitations.push( + "No AMI NVRAM variable stores (NVAR chains) were found in the image.", + ); + return { + stores, + coverage: partial ? "partial" : "complete", + limitations, + }; +}; diff --git a/src/uefi/UefiProviderIdentity.ts b/src/uefi/UefiProviderIdentity.ts new file mode 100644 index 0000000000..634e7e5efc --- /dev/null +++ b/src/uefi/UefiProviderIdentity.ts @@ -0,0 +1,5 @@ +export const UEFI_PROVIDER_IDENTITY = { + id: "rea-uefi", + name: "REA UEFI firmware parser", + version: "1.0.0", +} as const; diff --git a/src/uefi/UefiPspDirectory.ts b/src/uefi/UefiPspDirectory.ts new file mode 100644 index 0000000000..712e81a981 --- /dev/null +++ b/src/uefi/UefiPspDirectory.ts @@ -0,0 +1,117 @@ +import { Buffer } from "node:buffer"; +import { BinaryReader } from "../domain/binaryContainer.js"; + +const PSP_MAGICS = ["$PSP", "$PL2"] as const; + +interface PspEntryRecord { + readonly type: number; + readonly declaredLocation: number | null; + readonly declaredLocationRaw: string; + readonly addressMode: number; + readonly declaredSize: number; + readonly imageOffset: number | null; + readonly sha256: string | null; + readonly locationBasis: "declared-unverified"; +} + +export interface PspTableRecord { + readonly offset: number; + readonly length: number; + readonly tableMagic: "$PSP" | "$PL2"; + readonly totalEntries: number; + readonly entries: readonly PspEntryRecord[]; + readonly entryStrideBasis: "psp-16"; +} + +export interface PspCandidateRecord { + readonly offset: number; + readonly magic: string; + readonly reason: string; +} + +/** The PSP checksum covers the count, additional info and directory entries. */ +function directoryChecksum( + reader: BinaryReader, + start: number, + end: number, +): number { + let low = 0xffff; + let high = 0xffff; + for (let offset = start; offset < end; offset += 2) { + low += reader.u16(offset); + low = (low & 0xffff) + (low >>> 16); + high += low; + high = (high & 0xffff) + (high >>> 16); + } + return ((high << 16) | low) >>> 0; +} + +export const scanPspDirectories = ( + image: Buffer, + reserve: (count?: number) => boolean, +): { tables: PspTableRecord[]; candidates: PspCandidateRecord[] } => { + const tables: PspTableRecord[] = []; + const candidates: PspCandidateRecord[] = []; + const reader = new BinaryReader(image, true, "AMD PSP directory"); + const headerLength = 16; + const entryLength = 16; + for (const magic of PSP_MAGICS) { + let searchFrom = 0; + while (searchFrom < image.length) { + const hit = image.indexOf(magic, searchFrom, "ascii"); + if (hit < 0 || !reserve()) break; + searchFrom = hit + magic.length; + const totalEntries = + hit + headerLength <= image.length ? reader.u32(hit + 8) : 0; + const tableLength = headerLength + totalEntries * entryLength; + if ( + totalEntries === 0 || + totalEntries > 255 || + hit + tableLength > image.length + ) { + candidates.push({ + offset: hit, + magic, + reason: "implausible-entry-count", + }); + continue; + } + if (!reserve(totalEntries)) return { tables, candidates }; + if ( + reader.u32(hit + 4) !== + directoryChecksum(reader, hit + 8, hit + tableLength) + ) { + candidates.push({ offset: hit, magic, reason: "checksum-mismatch" }); + continue; + } + const entries: PspEntryRecord[] = []; + for (let index = 0; index < totalEntries; index += 1) { + const start = hit + headerLength + index * entryLength; + const raw = reader.word(start + 8, 64); + const location = raw & ((1n << 62n) - 1n); + entries.push({ + type: reader.u8(start), + declaredLocation: + location <= BigInt(Number.MAX_SAFE_INTEGER) + ? Number(location) + : null, + declaredLocationRaw: `0x${raw.toString(16).padStart(16, "0")}`, + addressMode: Number(raw >> 62n), + declaredSize: reader.u32(start + 4), + imageOffset: null, + sha256: null, + locationBasis: "declared-unverified", + }); + } + tables.push({ + offset: hit, + length: tableLength, + tableMagic: magic, + totalEntries, + entries, + entryStrideBasis: "psp-16", + }); + } + } + return { tables, candidates }; +}; diff --git a/src/uefi/UefiPublication.ts b/src/uefi/UefiPublication.ts new file mode 100644 index 0000000000..974b062927 --- /dev/null +++ b/src/uefi/UefiPublication.ts @@ -0,0 +1,122 @@ +import { sha256Hex } from "../kernel/sha256Hex.js"; +import { join } from "node:path"; +import { Readable } from "node:stream"; +import type { AnalysisError } from "../domain/analysisErrorBase.js"; +import { + type ArtifactResourceScope, + AnalysisCleanupLease, + AnalysisCleanupLeaseGroup, + SafeOutputTree, + SafeOutputTreeCreationFailure, +} from "../resources/index.js"; +import { analysisErrorWithCleanupDependencies } from "../domain/analysisErrorCleanup.js"; +import { ProviderCleanupError } from "../domain/providerCleanupError.js"; +import type { + UefiExtractResult, + UefiOperation, +} from "../domain/uefi/uefiFirmwareAnalysis.js"; +import { uefiFailureDialect } from "./UefiFailures.js"; +import { classifyProviderFailure } from "../providers/classifyProviderFailure.js"; + +import { UEFI_PROVIDER_IDENTITY } from "./UefiProviderIdentity.js"; + +type UefiPublishedFile = UefiExtractResult["files"][number]; + +/** One staged payload with provenance from the scanner that supplied it. */ +export interface UefiPublicationEntry { + readonly relativePath: string; + readonly bytes: Buffer; + readonly facts: Omit< + UefiPublishedFile, + "path" | "size" | "sha256" | "relative_path" + >; +} + +interface UefiPublicationOutcome { + readonly result: UefiExtractResult; + readonly failure?: AnalysisError; +} + +/** + * Publish extraction payloads through the SafeOutputTree contract: absent + * output directory, exclusive creation, digest-verified writes, commit or + * rollback. No executable bits are ever set by the tree. + */ +export const publishUefiFiles = async (context: { + readonly outputDirectory: string; + readonly operation: UefiOperation; + readonly entries: readonly UefiPublicationEntry[]; + readonly signal: AbortSignal; + readonly checkpoint: () => void; + readonly resources: ArtifactResourceScope; + /** Validate the result with actual write receipts before committing the tree. */ + readonly buildResult: ( + outputRoot: string, + files: UefiPublishedFile[], + ) => UefiExtractResult; +}): Promise => { + let tree: SafeOutputTree | undefined; + let result: UefiExtractResult | undefined; + const files: UefiPublishedFile[] = []; + try { + context.checkpoint(); + tree = await SafeOutputTree.create(context.outputDirectory); + for (const entry of context.entries) { + context.checkpoint(); + const sha256 = sha256Hex(entry.bytes); + const written = await tree.write( + entry.relativePath, + Readable.from([entry.bytes]), + { sha256, bytes: entry.bytes.length }, + context.signal, + ); + files.push({ + ...entry.facts, + relative_path: written.relativePath, + path: join(tree.outputRoot, written.relativePath), + size: written.bytesWritten, + sha256: written.sha256, + }); + } + result = context.buildResult(tree.outputRoot, files); + context.checkpoint(); + await tree.commit(context.signal); + return { result }; + } catch (cause: unknown) { + if (cause instanceof SafeOutputTreeCreationFailure) tree = cause.tree; + const primary = classifyProviderFailure( + cause, + uefiFailureDialect(context.operation, context.outputDirectory), + ); + if (tree === undefined) throw primary; + + const ownedTree = tree; + const lease = new AnalysisCleanupLease(async () => { + await ownedTree.rollback(); + }, [ownedTree.outputRoot]); + if (primary.cleanupIncomplete) lease.bindCleanupError(primary); + const released = await context.resources.release({ + kind: "lease", + resource: ownedTree.outputRoot, + lease, + }); + if (released.kind === "released") { + if (tree.published && result !== undefined) return { result }; + throw primary; + } + const cleanup = new ProviderCleanupError( + UEFI_PROVIDER_IDENTITY.id, + [tree.outputRoot], + { reason: String(released.cause) }, + { cause: released.cause, operation: context.operation }, + ); + new AnalysisCleanupLeaseGroup(cleanup, [released.lease]); + const failure = analysisErrorWithCleanupDependencies( + primary, + cleanup, + context.operation, + ); + if (tree.published && result !== undefined) return { result, failure }; + throw failure; + } +}; diff --git a/src/uefi/UefiX86BranchFilter.ts b/src/uefi/UefiX86BranchFilter.ts new file mode 100644 index 0000000000..d839904db3 --- /dev/null +++ b/src/uefi/UefiX86BranchFilter.ts @@ -0,0 +1,55 @@ +import { BinaryReader } from "../domain/binaryContainer.js"; +/** + * Decode the x86 BCJ transform over a complete stream at instruction pointer + * zero, as used by EDK II's LZMAF86 handler. The transform is size-preserving. + * + * Adapted from Igor Pavlov's public-domain Bra86.c (2017-04-03), pinned at + * https://github.com/tianocore/edk2/blob/556dcfb466e9f05affeaff881d738807f8156d3c/MdeModulePkg/Library/LzmaCustomDecompressLib/Sdk/C/Bra86.c + */ +export function undoUefiX86BranchFilter(bytes: Buffer): void { + const reader = new BinaryReader(bytes, true, "x86 BCJ stream"); + const lastOpcode = bytes.length - 5; + let position = 0; + // Records nearby nonconverted opcode bytes that may overlap an operand. + let priorOpcodeMask = 0; + while (position <= lastOpcode) { + const searchStart = position; + while (position <= lastOpcode && (reader.u8(position) & 0xfe) !== 0xe8) { + position += 1; + } + if (position > lastOpcode) break; + + const distance = position - searchStart; + priorOpcodeMask = distance > 2 ? 0 : priorOpcodeMask >>> distance; + if ( + (priorOpcodeMask !== 0 && + (priorOpcodeMask > 4 || + priorOpcodeMask === 3 || + isSignByte(reader.u8(position + (priorOpcodeMask >>> 1) + 1)))) || + !isSignByte(reader.u8(position + 4)) + ) { + priorOpcodeMask = (priorOpcodeMask >>> 1) | 4; + position += 1; + continue; + } + + const nextInstruction = position + 5; + let displacement = reader.u32(position + 1) - nextInstruction; + if (priorOpcodeMask !== 0) { + const shift = (priorOpcodeMask & 6) << 2; + if (isSignByte((displacement >>> shift) & 0xff)) { + displacement = + (displacement ^ ((0x100 << shift) - 1)) - nextInstruction; + } + priorOpcodeMask = 0; + } + const signExtension = -((displacement >>> 24) & 1) << 24; + bytes.writeUInt32LE( + ((displacement & 0xffffff) | signExtension) >>> 0, + position + 1, + ); + position = nextInstruction; + } +} + +const isSignByte = (byte: number): boolean => byte === 0 || byte === 0xff; diff --git a/tests/acceptance/uefiFirmware.test.ts b/tests/acceptance/uefiFirmware.test.ts new file mode 100644 index 0000000000..62681c7223 --- /dev/null +++ b/tests/acceptance/uefiFirmware.test.ts @@ -0,0 +1,484 @@ +import { createHash } from "node:crypto"; +import { execFile } from "node:child_process"; +import { readFile, writeFile } from "node:fs/promises"; +import { basename, join } from "node:path"; +import { fileURLToPath } from "node:url"; +import { promisify } from "node:util"; +import { expect, it } from "vitest"; + +import { parseBinaryTarget } from "../../src/application/BinaryTargetResolver.js"; +import { pe } from "../../src/domain/binaryTarget.fixture.js"; +import { minimalElfImage } from "../fixtures/nativeHeaders.js"; +import { artifactInventoryResultSchema } from "../../src/domain/artifactGraph.js"; +import { artifactInspectionResultSchema } from "../../src/domain/artifactInspection.js"; +import { uefiResultSchemas } from "../../src/domain/uefi/uefiFirmwareAnalysis.js"; +import { parseEvidence } from "../../src/domain/evidence.js"; +import { + buildFfsFile, + buildFv, + buildImage, + buildSection, +} from "../../tests/fixtures/uefiImage.js"; +import { connectLocalToolsMcp } from "../fixtures/localToolsMcp.js"; +import { parseMcpToolError } from "../fixtures/mcpToolError.js"; +import { createTestTempDirectory } from "../fixtures/temporaryDirectory.js"; + +const execute = promisify(execFile); +const cli = fileURLToPath(new URL("../../scripts/rea.mjs", import.meta.url)); + +const sha256 = (bytes: Buffer): string => + createHash("sha256").update(bytes).digest("hex"); + +const DRIVER_GUID = "9e21fd93-9c72-4c15-8c4b-e77f9db8d4d2"; +const PAD_GUID = "fff12b8d-d7da-47f8-b4cf-1a0a2a1c1b1c"; +const PAYLOAD = Buffer.from( + "4d5a90000300000004000000ffff00020000000012345678hello-bios", + "hex", +); + +/** + * One B550-shaped flash image: an erased lead-in with no volume at offset 0, + * the platform volume at 0x1000 carrying two FFS files (one payload, one pad + * file), and a second volume holding a third file. + */ +const PE_SECTION = buildSection(0x10, PAYLOAD); + +const buildFlashImage = (): Buffer => { + const payloadFile = buildFfsFile({ + guid: DRIVER_GUID, + typeCode: 0x07, + payload: PE_SECTION, + }); + const padFile = buildFfsFile({ + guid: PAD_GUID, + typeCode: 0xf0, + payload: Buffer.alloc(0), + }); + const trailingFile = buildFfsFile({ + guid: "0a8f1d2b-1111-2222-3333-445566778899", + typeCode: 0x15, + payload: Buffer.from("second volume module", "ascii"), + }); + const body = buildImage({ + volumes: [ + buildFv({ files: [payloadFile, padFile] }).buffer, + buildFv({ files: [trailingFile] }).buffer, + ], + }); + // An erased lead-in keeps the first volume away from offset 0. + return Buffer.concat([Buffer.alloc(0x1000, 0xff), body]); +}; + +const extractFlashFileViaCli = async ( + root: string, + imageName: string, + offset: number, +) => { + const cliExtraction = await execute( + process.execPath, + [ + cli, + "extract-uefi-firmware", + imageName, + "cli-extracted", + "--file-offset", + String(offset), + "--source-stream", + "flash", + "--json", + ], + { cwd: root }, + ); + return parseEvidence(JSON.parse(cliExtraction.stdout)); +}; + +it("maps a flash image end to end through CLI inspection and MCP session inventory", async () => { + const root = await createTestTempDirectory("rea-uefi-session-acceptance-"); + const image = buildFlashImage(); + const imagePath = join(root, "B550AORUSELITEV212.FIb"); + await writeFile(imagePath, image); + + const cliResult = await execute(process.execPath, [ + cli, + "inspect-uefi-firmware", + imagePath, + "--json", + ]); + expect(cliResult.stderr, cliResult.stderr).toBe(""); + const cliEvidence = parseEvidence(JSON.parse(cliResult.stdout)); + const inspected = uefiResultSchemas.inspect_uefi_firmware.parse( + cliEvidence.normalized_result, + ); + expect(inspected.input_size).toBe(image.length); + expect(inspected.flash_image.sha256).toBe(sha256(image)); + expect(inspected.flash_image.entry_basis).toBe("scanned"); + // 0x1000 lead volume, then the trailing volume right after the first block. + expect(inspected.firmware_volumes.map((volume) => volume.offset)).toEqual([ + 0x1000, 0x2000, + ]); + expect(inspected.unknown_regions.length).toBeGreaterThan(0); + + const { call } = await connectLocalToolsMcp(); + const opened = await call("open_binary", { path: imagePath }); + expect(opened.isError, JSON.stringify(opened.content)).not.toBe(true); + + const inspectedSession = await call("inspect_artifact", {}); + expect(inspectedSession.isError, JSON.stringify(inspectedSession)).not.toBe( + true, + ); + const sessionEvidence = parseEvidence(inspectedSession.structuredContent); + const sessionInspection = artifactInspectionResultSchema.parse( + sessionEvidence.normalized_result, + ); + const sessionInventoryEvidence = sessionInspection.substeps[0]?.evidence; + if (sessionInventoryEvidence === undefined) + throw new Error("MCP inspection did not retain inventory Evidence"); + const sessionInventory = artifactInventoryResultSchema.parse( + sessionInventoryEvidence.normalized_result, + ); + expect(sessionInventory.coverage).toMatchObject({ + scope: "container-entries", + status: "complete", + }); + const rootOccurrence = sessionInventory.occurrences.find( + (occurrence) => occurrence.parent_occurrence_id === null, + ); + expect(rootOccurrence).toMatchObject({ + logical_path: ".", + artifact_format: "uefi", + artifact_kind: "resource", + }); + expect( + sessionInventory.occurrences.map((occurrence) => occurrence.logical_path), + ).toEqual( + expect.arrayContaining([ + "firmware-volume-0x1000", + `firmware-volume-0x1000/ffs-file-${DRIVER_GUID}.bin`, + `firmware-volume-0x1000/ffs-file-${PAD_GUID}.bin`, + "firmware-volume-0x2000", + "firmware-volume-0x2000/ffs-file-0a8f1d2b-1111-2222-3333-445566778899.bin", + ]), + ); + const payloadFileOffset = 0x1000 + 72; + const driverOccurrence = sessionInventory.occurrences.find( + (occurrence) => + occurrence.logical_path === + `firmware-volume-0x1000/ffs-file-${DRIVER_GUID}.bin`, + ); + if (driverOccurrence === undefined) + throw new Error("FFS occurrence is missing from the inventory"); + if (driverOccurrence.source_location === null) + throw new Error("FFS occurrence lost its byte range"); + expect(driverOccurrence).toMatchObject({ + hash_status: "verified", + source_location: { + offset: payloadFileOffset, + length: 24 + PE_SECTION.length, + }, + }); + const sourceLocation = driverOccurrence.source_location; + const driverNode = sessionInventory.nodes.find( + (node) => + node.sha256 === + sha256( + image.subarray( + sourceLocation.offset, + sourceLocation.offset + sourceLocation.length, + ), + ), + ); + expect(driverNode).toBeDefined(); + + const extractedSession = await call("extract_uefi_firmware", { + path: imagePath, + output_directory: join(root, "extracted"), + target: { kind: "ffs-file", offset: sourceLocation.offset }, + }); + expect(extractedSession.isError, JSON.stringify(extractedSession)).not.toBe( + true, + ); + const extractEvidence = parseEvidence(extractedSession.structuredContent); + const extractResult = uefiResultSchemas.extract_uefi_firmware.parse( + extractEvidence.normalized_result, + ); + expect(extractResult.selection).toMatchObject({ + offset: sourceLocation.offset, + length: 24 + PE_SECTION.length, + target_kind: "ffs-file", + }); + expect(extractResult.files).toHaveLength(1); + const publishedFile = extractResult.files[0]; + if (publishedFile === undefined) throw new Error("extraction lost its file"); + // The extractor publishes decoded payload with its own original byte range; + // published bytes must equal exactly that image range. + const publishedRange = publishedFile.original_file_range; + if (publishedRange === null) + throw new Error("flash payload lost its source range"); + expect(publishedFile.sha256).toBe( + sha256( + image.subarray( + publishedRange.offset, + publishedRange.offset + publishedRange.length, + ), + ), + ); + const published = await readFile(publishedFile.path); + expect(createHash("sha256").update(published).digest("hex")).toBe( + publishedFile.sha256, + ); + + const cliExtractionEvidence = await extractFlashFileViaCli( + root, + basename(imagePath), + sourceLocation.offset, + ); + expect(cliExtractionEvidence).toMatchObject({ + caller_input_path: basename(imagePath), + caller_input_paths: { output_directory: "cli-extracted" }, + }); + const cliExtracted = uefiResultSchemas.extract_uefi_firmware.parse( + cliExtractionEvidence.normalized_result, + ); + expect(cliExtracted.selection).toEqual(extractResult.selection); + expect(cliExtracted.files.map((file) => file.sha256)).toEqual([ + publishedFile.sha256, + ]); +}); + +it("never admits prose carrying a `_FVH` string as the flash image format", async () => { + const root = await createTestTempDirectory("rea-uefi-probe-negative-"); + const path = join(root, "text-with-signature.txt"); + // A plain text file carrying `_FVH` must not claim the flash image format; + // unrecognized files stay outside artifact admission entirely. + await writeFile( + path, + Buffer.concat([ + Buffer.from('"_FVH" appears inside prose', "ascii"), + Buffer.alloc(0x1000, 0x20), + ]), + ); + let output = ""; + try { + const cliResult = await execute(process.execPath, [ + cli, + "inspect-artifact", + path, + "--json", + ]); + output = cliResult.stdout + cliResult.stderr; + } catch (error) { + const failure = error as { stdout?: string; stderr?: string }; + output = `${failure.stdout ?? ""}${failure.stderr ?? ""}`; + } + expect(output, output).not.toContain('"uefi"'); +}); + +it.each([ + { format: "elf", native: minimalElfImage() }, + { format: "pe", native: pe(0x8664) }, +])( + "preserves leading $format admission with an appended firmware volume", + async ({ format, native }) => { + const root = await createTestTempDirectory("rea-uefi-native-admission-"); + const path = join(root, "native.bin"); + const aligned = Buffer.alloc(0x1000); + native.copy(aligned); + await writeFile( + path, + Buffer.concat([aligned, buildFv({ files: [] }).buffer]), + ); + expect(await parseBinaryTarget(path)).toMatchObject({ + ok: true, + value: { format, kind: "executable" }, + }); + const command = await execute(process.execPath, [ + cli, + "inspect-artifact", + path, + "--json", + ]); + const result = artifactInspectionResultSchema.parse( + parseEvidence(JSON.parse(command.stdout)).normalized_result, + ); + const inventory = artifactInventoryResultSchema.parse( + result.substeps[0]?.evidence?.normalized_result, + ); + expect(inventory.manifest.root_format).toBe(format); + }, +); + +it("keeps deep-provider analysis unavailable for the admitted uefi target", async () => { + const root = await createTestTempDirectory("rea-uefi-deep-rejection-"); + const imagePath = join(root, "image.FIb"); + await writeFile(imagePath, buildFlashImage()); + const { call } = await connectLocalToolsMcp(); + const opened = await call("open_binary", { path: imagePath }); + expect(opened.isError, JSON.stringify(opened.content)).not.toBe(true); + const deep = await call("analyze_function", { procedure: "main" }); + expect(deep.isError).toBe(true); + const rejection = parseMcpToolError(deep); + // Session-level rejection is typed, with per-provider reasons retained. + expect(rejection.error).toMatchObject({ + code: "capability_unavailable", + category: "unsupported_provider", + details: { + operation: "analyze_function", + selection_reason: "target_unsupported", + rejections: expect.arrayContaining([ + expect.objectContaining({ + code: expect.any(String), + reason: expect.any(String), + }), + ]), + }, + }); +}); + +it("retains an opaque volume and reports only the unparsed ranges in the selected extraction scope", async () => { + const root = await createTestTempDirectory("rea-uefi-opaque-volume-"); + const path = join(root, "mixed.fd"); + const nvDataGuid = "fff12b8d-7696-4c8b-a985-2747075b4f50"; + const valid = buildFv({ + fileSystemGuid: "54731207-5c41-4cbd-b5e5-cd26d80770b1", + files: [ + buildFfsFile({ guid: DRIVER_GUID, typeCode: 0x07, payload: PE_SECTION }), + ], + }); + const opaque = buildFv({ + fileSystemGuid: nvDataGuid, + // These bytes could be walked as FFS if the volume GUID were ignored. + files: [ + buildFfsFile({ guid: DRIVER_GUID, typeCode: 0x07, payload: PE_SECTION }), + ], + }); + const opaqueOffset = valid.buffer.length; + const suffix = Buffer.from("vendor footer"); + const suffixOffset = opaqueOffset + opaque.buffer.length; + await writeFile(path, Buffer.concat([valid.buffer, opaque.buffer, suffix])); + + const { call } = await connectLocalToolsMcp(); + const { normalized_result: inspection } = parseEvidence( + (await call("inspect_uefi_firmware", { path })).structuredContent, + ); + const inspected = uefiResultSchemas.inspect_uefi_firmware.parse(inspection); + expect(inspected.coverage).toBe("partial"); + expect(inspected.firmware_volumes).toMatchObject([ + { offset: 0, ffs_files: [{ guid: DRIVER_GUID }] }, + { offset: opaqueOffset, file_system_guid: nvDataGuid, ffs_files: [] }, + ]); + expect(inspected.unknown_regions).toEqual( + expect.arrayContaining([ + expect.objectContaining({ + classification: "unsupported-file-system", + sha256: sha256(opaque.buffer.subarray(opaque.headerLength)), + offset: opaqueOffset + opaque.headerLength, + length: opaque.buffer.length - opaque.headerLength, + }), + ]), + ); + + const opened = await call("open_binary", { path }); + expect(opened.isError, JSON.stringify(opened.content)).not.toBe(true); + const inventoryEvidence = parseEvidence( + (await call("inspect_artifact", {})).structuredContent, + ); + const inventory = artifactInventoryResultSchema.parse( + artifactInspectionResultSchema.parse(inventoryEvidence.normalized_result) + .substeps[0]?.evidence?.normalized_result, + ); + const opaquePath = `firmware-volume-0x${opaqueOffset.toString(16)}`; + expect( + inventory.occurrences + .filter(({ logical_path }) => logical_path.startsWith(opaquePath)) + .map(({ logical_path }) => logical_path), + ).toEqual([opaquePath]); + expect(inventory.coverage.status).toBe("unknown"); + + const extract = async ( + name: string, + target?: { kind: "volume"; offset: number }, + ) => + uefiResultSchemas.extract_uefi_firmware.parse( + parseEvidence( + ( + await call("extract_uefi_firmware", { + path, + output_directory: join(root, name), + ...(target === undefined ? {} : { target }), + }) + ).structuredContent, + ).normalized_result, + ); + const whole = await extract("whole"); + expect(whole.files.map(({ sha256 }) => sha256)).toEqual([sha256(PAYLOAD)]); + expect(whole.coverage).toBe("partial"); + expect(whole.extraction_gaps).toMatchObject([ + { + kind: "unparsed-region", + logical_path: `flash/FV@0x${opaqueOffset.toString(16)}`, + source_stream: null, + range: { + offset: opaqueOffset + opaque.headerLength, + length: opaque.buffer.length - opaque.headerLength, + }, + }, + { + kind: "unparsed-region", + logical_path: "flash", + source_stream: null, + range: { offset: suffixOffset, length: suffix.length }, + }, + ]); + + const selected = await extract("volume", { kind: "volume", offset: 0 }); + expect(selected.coverage).toBe("complete"); + expect(selected.extraction_gaps).toEqual([]); + const selectedOpaque = await extract("opaque", { + kind: "volume", + offset: opaqueOffset, + }); + expect(selectedOpaque.coverage).toBe("partial"); + expect(selectedOpaque.files).toEqual([]); + expect(selectedOpaque.extraction_gaps).toEqual([whole.extraction_gaps[0]]); +}); + +it("publishes distinct AMI NVAR link, attributes, GUID index and data digest", async () => { + const root = await createTestTempDirectory("rea-nvar-record-"); + const path = join(root, "variables.fd"); + // Two contiguous NVAR records: Setup links forward to a nameless data entry. + await writeFile( + path, + Buffer.from( + "4e56415212001200008303536574757000424e5641520c00ffffff88aabb", + "hex", + ), + ); + const { call } = await connectLocalToolsMcp(); + const response = await call("inspect_uefi_nvram", { path }); + const result = uefiResultSchemas.inspect_uefi_nvram.parse( + parseEvidence(response.structuredContent).normalized_result, + ); + expect(result.coverage).toBe("complete"); + expect(result.stores[0]?.variables).toMatchObject([ + { + name: "Setup", + offset: 0, + next: 18, + attributes: 0x83, + guid_index: 3, + data_offset: 17, + data_length: 1, + data_sha256: sha256(Buffer.from([0x42])), + }, + { + name: null, + offset: 18, + next: 0xffffff, + attributes: 0x88, + guid_index: null, + data_offset: 28, + data_length: 2, + data_sha256: sha256(Buffer.from([0xaa, 0xbb])), + }, + ]); +}); diff --git a/tests/boundary/uefi/lzmaWorker.test.ts b/tests/boundary/uefi/lzmaWorker.test.ts new file mode 100644 index 0000000000..edfcf2f7b6 --- /dev/null +++ b/tests/boundary/uefi/lzmaWorker.test.ts @@ -0,0 +1,136 @@ +import { execFile } from "node:child_process"; +import { createHash } from "node:crypto"; +import { readFile, writeFile } from "node:fs/promises"; +import { createRequire } from "node:module"; +import { join } from "node:path"; +import { fileURLToPath } from "node:url"; +import { promisify } from "node:util"; +import { expect, it } from "vitest"; +import { createTestTempDirectory } from "../../fixtures/temporaryDirectory.js"; + +/** The pinned pure-JS decoder, used in tests to build real streams. */ +const lzmaPurescript = createRequire(import.meta.url)( + "lzma-purejs", +) as unknown as { + compressFile: (buffer: Buffer) => Uint8Array; + decompressFile: (buffer: Buffer) => Uint8Array; +}; + +interface UefiLzmaWorkerReply { + readonly ok: unknown; + readonly reason?: unknown; + readonly message?: unknown; + readonly lzma_version?: unknown; + readonly output?: { readonly sha256: unknown; readonly bytes: unknown }; +} + +const runLzmaWorker = async ( + directory: string, + payload: Buffer, + maxOutputBytes: number, +): Promise => { + const payloadPath = join(directory, "payload.lzma"); + const outputPath = join(directory, "output.bin"); + const replyPath = join(directory, "reply.json"); + const requestPath = join(directory, "request.json"); + await writeFile(payloadPath, payload); + await writeFile( + requestPath, + JSON.stringify({ + format: "lzma", + payload_path: payloadPath, + output_path: outputPath, + reply_path: replyPath, + max_output_bytes: maxOutputBytes, + }), + ); + await promisify(execFile)( + process.execPath, + [ + "--max-old-space-size=256", + "--disable-wasm-trap-handler", + fileURLToPath( + new URL("../../../dist/uefi/UefiLzmaWorker.js", import.meta.url), + ), + requestPath, + ], + { timeout: 30_000, maxBuffer: 1024 * 1024 }, + ); + return JSON.parse(await readFile(replyPath, "utf8")) as UefiLzmaWorkerReply; +}; + +/** Real compiled worker and pinned decoder; no provider-admission claim. */ +it("decompresses a real lzma-purejs stream through the actual worker", async () => { + const directory = await createTestTempDirectory("rea-uefi-lzma-"); + const plain = Buffer.from( + "B550 AORUS Elite V2 firmware module payload. ".repeat(40), + ); + const reply = await runLzmaWorker( + directory, + Buffer.from(lzmaPurescript.compressFile(plain)), + 1024 * 1024, + ); + expect(reply.ok, JSON.stringify(reply)).toBe(true); + expect(reply.lzma_version).toBe("0.9.3"); + expect(reply.output?.bytes).toBe(plain.length); + expect(reply.output?.sha256).toBe( + createHash("sha256").update(plain).digest("hex"), + ); + expect((await readFile(join(directory, "output.bin"))).equals(plain)).toBe( + true, + ); +}); + +it("reports a typed failure for an undecodable stream", async () => { + const directory = await createTestTempDirectory("rea-uefi-lzma-"); + // Valid property byte, corrupt LZMA stream behind it. + const reply = await runLzmaWorker( + directory, + Buffer.from([0x5d, 0x00, 0x00, 0x80, 0x00, 0x11, 0x22, 0x33, 0x44]), + 1024 * 1024, + ); + expect(reply.ok).toBe(false); + expect(reply.message, JSON.stringify(reply)).not.toBe(""); + expect(["format", "decoder"]).toContain(reply.reason); +}); + +it("honors the caller's output budget as an output-limit failure", async () => { + const directory = await createTestTempDirectory("rea-uefi-lzma-"); + const plain = Buffer.from( + "decompressed payload beyond the tight budget".repeat(5), + ); + const reply = await runLzmaWorker( + directory, + Buffer.from(lzmaPurescript.compressFile(plain)), + 16, + ); + expect(reply.ok).toBe(false); + expect(reply.reason).toBe("output-limit"); + await expect(readFile(join(directory, "output.bin"))).rejects.toThrow(); +}); + +it("checks the declared dictionary before the decoder allocates its window", async () => { + const directory = await createTestTempDirectory("rea-uefi-lzma-"); + const stream = Buffer.from( + lzmaPurescript.compressFile(Buffer.from("small firmware payload")), + ); + stream.writeUInt32LE(128 * 1024 * 1024, 1); + const reply = await runLzmaWorker(directory, stream, 1024); + expect(reply).toMatchObject({ + ok: false, + reason: "output-limit", + message: expect.stringContaining("dictionary"), + }); +}); + +it("rejects an incomplete coded body even when its declared output size is plausible", async () => { + const directory = await createTestTempDirectory("rea-uefi-lzma-eof-"); + const input = Buffer.from( + lzmaPurescript.compressFile( + Buffer.from("Ordinary test data for the LZMA worker's read boundary."), + ), + ); + const reply = await runLzmaWorker(directory, input.subarray(0, -1), 1024); + expect(reply).toMatchObject({ ok: false, reason: "format" }); + await expect(readFile(join(directory, "output.bin"))).rejects.toThrow(); +}); diff --git a/tests/conformance/providerCapabilityCases.ts b/tests/conformance/providerCapabilityCases.ts index f578f07ff4..11f2496144 100644 --- a/tests/conformance/providerCapabilityCases.ts +++ b/tests/conformance/providerCapabilityCases.ts @@ -82,6 +82,7 @@ export const PROVIDER_CAPABILITY_CONFORMANCE: Readonly< erlangBeam: { cases: ["tests/acceptance/erlangBeamCli.test.ts"] }, evmInterface: { cases: ["tests/boundary/mcp/evmInterfaceMcp.test.ts"] }, firmwareAnalysis: { cases: ["tests/boundary/mcp/firmwareMcp.test.ts"] }, + uefiAnalysis: { cases: ["tests/acceptance/uefiFirmware.test.ts"] }, flutter: { cases: ["tests/boundary/cli/flutterCli.test.ts"] }, fridaInstrumentation: { cases: ["tests/boundary/cli/fridaCli.test.ts"] }, gdbSessions: { cases: ["tests/boundary/cli/gdbStartupCleanupCli.test.ts"] }, diff --git a/tests/fixtures/uefiImage.ts b/tests/fixtures/uefiImage.ts new file mode 100644 index 0000000000..90b9775b5f --- /dev/null +++ b/tests/fixtures/uefiImage.ts @@ -0,0 +1,289 @@ +import { Buffer } from "node:buffer"; + +import { formatGuidLittleEndian } from "../../src/uefi/UefiGuid.js"; + +/** LZMA custom GUIDed-section definition GUID (display form). */ +export const GUID_LZMA_CUSTOM_DISPLAY = "ee4e5898-3914-4259-9d6e-dc7bd79403cf"; + +/** GUID display string to the 16 raw little-endian bytes images carry. */ +export function guidBytes(display: string): Buffer { + const parts = display.split("-"); + const bytes = Buffer.alloc(16, 0); + bytes.writeUInt32LE(Number.parseInt(parts[0] ?? "0", 16), 0); + bytes.writeUInt16LE(Number.parseInt(parts[1] ?? "0", 16), 4); + bytes.writeUInt16LE(Number.parseInt(parts[2] ?? "0", 16), 6); + Buffer.from(parts.slice(3).join(""), "hex").copy(bytes, 8); + return bytes; +} + +const payloadSum = (buffer: Buffer): number => { + let total = 0; + for (const byte of buffer) { + total = (total + byte) & 0xff; + } + return total; +}; + +export interface FfsFileSpec { + guid: string; + typeCode: number; + /** File data; pad files normally have an empty payload. */ + payload: Buffer; + alignmentExponent?: number; + /** File-integrity mode; "correct"/"wrong" set the 0x40 attribute bit. */ + fileChecksum?: "none" | "correct" | "wrong"; + erasePolarity?: boolean; + /** Deliberately corrupt the header checksum byte. */ + breakHeaderChecksum?: boolean; +} + +const NORMALIZED_COMPLETE_STATE = 0x07; + +/** Build one 24-byte FFS file with correct header checksum and state bits. */ +export function buildFfsFile(spec: FfsFileSpec): Buffer { + const erasePolarity = spec.erasePolarity ?? true; + const header = Buffer.alloc(24, 0); + guidBytes(spec.guid).copy(header, 0); + const size = 24 + spec.payload.length; + if (size > 0xffffff) { + throw new Error("test FFS files must stay below the extended-size marker"); + } + header[20] = size & 0xff; + header[21] = (size >> 8) & 0xff; + header[22] = (size >> 16) & 0xff; + header[18] = spec.typeCode; + const fileChecksumWanted = + spec.fileChecksum === "correct" || spec.fileChecksum === "wrong"; + header[19] = + ((spec.alignmentExponent ?? 0) << 3) | (fileChecksumWanted ? 0x40 : 0); + header[23] = erasePolarity + ? ~NORMALIZED_COMPLETE_STATE & 0x3f + : NORMALIZED_COMPLETE_STATE; + let sum = 0; + for (let offset = 0; offset < 24; offset += 1) { + const skip = offset === 23 || offset === 17 || offset === 16; + sum = (sum + (skip ? 0 : (header[offset] ?? 0))) & 0xff; + } + header[16] = (0x100 - sum) & 0xff; + if (spec.fileChecksum === "correct") { + header[17] = (0x100 - payloadSum(spec.payload)) & 0xff; + } else if (spec.fileChecksum === "wrong") { + header[17] = (0x100 - payloadSum(spec.payload) + 1) & 0xff; + } + if (spec.breakHeaderChecksum === true) { + header[16] = ((header[16] ?? 0) + 1) & 0xff; + } + return Buffer.concat([header, spec.payload]); +} + +export interface FvSpec { + files: readonly Buffer[]; + blockSize?: number; + blockMapEntries?: number; + erase?: 0xff | 0x00; + fileSystemGuid?: string; + extendedHeader?: "standalone" | "pad-file"; +} + +export interface BuiltFv { + buffer: Buffer; + absoluteBase: number; + declaredLength: number; + headerLength: number; + files: readonly Buffer[]; +} + +const aligned = (value: number, alignment: number): number => + Math.ceil(value / alignment) * alignment; + +/** FV header: 56 fixed bytes + one block pair + the {0,0} terminator. */ +const FV_HEADER_TEST_LENGTH = 72; + +/** + * Build a complete firmware volume: terminated block map (FFS2, 16-bit-word + * checksum), 8-aligned files, erase padding to the block boundary. + */ +export function buildFv(spec: FvSpec, absoluteBase = 0): BuiltFv { + const blockSize = spec.blockSize ?? 0x1000; + const erase = spec.erase ?? (0xff as const); + const blockMapEntries = spec.blockMapEntries ?? 1; + const headerLength = FV_HEADER_TEST_LENGTH + 8 * (blockMapEntries - 1); + const fileSystemGuid = + spec.fileSystemGuid ?? "8c8ce578-8a3d-4f1c-9935-896185c32dd3"; + const extension = spec.extendedHeader === undefined ? null : Buffer.alloc(28); + if (extension !== null) { + guidBytes("12345678-1234-4321-aaaa-bbbbbbbbbbbb").copy(extension); + extension.writeUInt32LE(extension.length, 16); + extension.writeUInt16LE(8, 20); + extension.writeUInt16LE(3, 22); // EFI_FV_EXT_TYPE_USED_SIZE + extension.writeUInt32LE(blockSize, 24); + } + const extendedPrefix = + extension === null + ? [] + : [ + spec.extendedHeader === "pad-file" + ? buildFfsFile({ + guid: "ffffffff-ffff-ffff-ffff-ffffffffffff", + typeCode: 0xf0, + payload: extension, + erasePolarity: erase === 0xff, + }) + : extension, + ]; + const fileArea = Buffer.concat( + [...extendedPrefix, ...spec.files].map((file) => { + const padTo = aligned(file.length, 8); + return Buffer.concat([file, Buffer.alloc(padTo - file.length, erase)]); + }), + ); + const declaredLength = Math.max( + blockSize, + aligned(headerLength + fileArea.length, blockSize), + ); + const header = Buffer.alloc(headerLength, 0); + guidBytes(fileSystemGuid).copy(header, 16); + header.writeBigUInt64LE(BigInt(declaredLength), 32); + header.write("_FVH", 40, "ascii"); + header.writeUInt32LE(erase === 0xff ? 0x800 : 0, 44); + header.writeUInt16LE(headerLength, 48); + if (extension !== null) + header.writeUInt16LE( + headerLength + (spec.extendedHeader === "pad-file" ? 24 : 0), + 52, + ); + header[54] = 0; + header[55] = 2; // EFI_FIRMWARE_VOLUME_HEADER.Revision + const mappedBlocks = Math.max(1, Math.ceil(declaredLength / blockSize)); + if (blockMapEntries === 1) { + header.writeUInt32LE(mappedBlocks, 56); + header.writeUInt32LE(blockSize, 60); + } else { + // Distinct contiguous blocks whose total covers the declared volume. + for (let entry = 0; entry < blockMapEntries; entry += 1) { + header.writeUInt32LE(1, 56 + 8 * entry); + header.writeUInt32LE( + entry === 0 ? declaredLength - blockMapEntries + 1 : 1, + 60 + 8 * entry, + ); + } + } + // The following block-map terminator pair stays zero. + let wordSum = 0; + for (let offset = 0; offset < headerLength; offset += 2) { + if (offset === 50) { + continue; + } + wordSum = (wordSum + header.readUInt16LE(offset)) & 0xffff; + } + header.writeUInt16LE((0x10000 - wordSum) & 0xffff, 50); + const buffer = Buffer.concat([ + header, + fileArea, + Buffer.alloc(declaredLength - headerLength - fileArea.length, erase), + ]); + return { + buffer, + absoluteBase, + declaredLength, + headerLength, + files: spec.files, + }; +} + +/** Plain (non-guided) section: 4-byte header + body, 4-byte aligned in a chain. */ +export function buildSection(typeCode: number, body: Buffer): Buffer { + const size = 4 + body.length; + const section = Buffer.concat([ + Buffer.from([ + size & 0xff, + (size >> 8) & 0xff, + (size >> 16) & 0xff, + typeCode, + ]), + body, + Buffer.alloc(aligned(size, 4) - size, 0), + ]); + return section; +} + +export interface GuidedSectionSpec { + definitionGuid: string; + body: Buffer; + dataOffset?: number; + attributes?: number; +} + +/** GUIDed section: 24-byte header (definition GUID, DataOffset, Attributes) + payload. */ +export function buildGuidedSection(spec: GuidedSectionSpec): Buffer { + const dataOffset = spec.dataOffset ?? 24; + const size = dataOffset + spec.body.length; + const section = Buffer.alloc(size, 0); + section[0] = size & 0xff; + section[1] = (size >> 8) & 0xff; + section[2] = (size >> 16) & 0xff; + section[3] = 0x02; + guidBytes(spec.definitionGuid).copy(section, 4); + section.writeUInt16LE(dataOffset, 20); + section.writeUInt16LE(spec.attributes ?? 0, 22); + spec.body.copy(section, dataOffset); + return section.subarray(0, aligned(size, 4)); +} + +/** LZMA-custom guided section body: the raw `.lzma` stream bytes. */ +export function buildLzmaGuidedSection(compressed: Buffer): Buffer { + return buildGuidedSection({ + definitionGuid: GUID_LZMA_CUSTOM_DISPLAY, + body: compressed, + }); +} + +/** Classic compression section: UncompressedLength u32 + CompressionType u8. */ +export function buildCompressionSection( + compressed: Buffer, + compressionType: number, + uncompressedLength: number, +): Buffer { + const body = Buffer.alloc(5, 0); + body.writeUInt32LE(uncompressedLength, 0); + body[4] = compressionType; + return buildSection(0x01, Buffer.concat([body, compressed])); +} + +export interface ImageSpec { + volumes: readonly Buffer[]; + /** Optional filler after concatenation, in bytes. */ + tailPad?: number; + erase?: 0xff | 0x00; + alignment?: number; +} + +/** Concatenate volumes with erase padding between them into one image. */ +export function buildImage(spec: ImageSpec): Buffer { + const align = spec.alignment ?? 0x1000; + const erase = spec.erase ?? (0xff as const); + const chunks: Buffer[] = []; + let cursor = 0; + for (const volume of spec.volumes) { + const pad = aligned(cursor, align) - cursor; + if (pad > 0) { + chunks.push(Buffer.alloc(pad, erase)); + cursor += pad; + } + chunks.push(volume); + cursor += volume.length; + } + if ((spec.tailPad ?? 0) > 0) { + chunks.push(Buffer.alloc(spec.tailPad ?? 0, erase)); + cursor += spec.tailPad ?? 0; + } + return Buffer.concat(chunks); +} + +/** Round-trip sanity: a built FV header must parse its checksum as valid. */ +export function assertBuiltFvHeaderIntegrity(fv: BuiltFv): void { + const guid = formatGuidLittleEndian(fv.buffer, 16); + if (guid == null || guid !== "8c8ce578-8a3d-4f1c-9935-896185c32dd3") { + throw new Error("fixture FV header GUID mismatch"); + } +} diff --git a/tests/support/providerLifecycleCoverage.ts b/tests/support/providerLifecycleCoverage.ts index f91f2ba452..b9281ff876 100644 --- a/tests/support/providerLifecycleCoverage.ts +++ b/tests/support/providerLifecycleCoverage.ts @@ -134,6 +134,7 @@ const historicalCapture = ( }, }); +const UEFI_PROVIDER = "src/uefi/UefiAnalysisProvider.test.ts"; const FIRMWARE_INTEGRATION = "tests/boundary/firmware/firmwareIntegration.test.ts"; const REVERSE_LAUNCH_ERRORS = @@ -2029,6 +2030,42 @@ export const PROVIDER_LIFECYCLE_COVERAGE: Readonly< ), }, }, + "rea-uefi": { + ownership: "process", + stages: { + launch: covered( + test( + UEFI_PROVIDER, + "decodes an LZMA-custom section through the owned worker and derives it", + ), + ), + handshake: ONE_SHOT, + operation: covered( + test( + "tests/acceptance/uefiFirmware.test.ts", + "maps a flash image end to end through CLI inspection and MCP session inventory", + ), + ), + cancel: covered( + test( + UEFI_PROVIDER, + "waits for committed output finalization during late cancellation and retries retained cleanup", + ), + ), + cleanup: covered( + test( + UEFI_PROVIDER, + "retains the worker root across a failed descriptor retry and releases its child before root removal", + ), + ), + retry: covered( + test( + UEFI_PROVIDER, + "retains the worker root across a failed descriptor retry and releases its child before root removal", + ), + ), + }, + }, unblob: { ownership: "process", stages: {