2026-04-19 — Initial Release v1.0.0.1

UEFIExtract is a Windows x64 utility for parsing and extracting UEFI firmware images. It builds a full tree of Firmware Volumes, FFS files, and sections — with transparent decompression of Tiano and LZMA-compressed sections. Supports IFR/HII package extraction, BIOS setting offset search (biosfind), Intel FIT parsing, and live BIOS flash read via FPTW64 (readbios). Runs in both GUI and CLI mode from the same binary.

UEFIExtract — UEFI Firmware Parser and Extractor

📚 Table of Contents

• Overview
• Architecture
• CLI Reference
• GUI Reference
• Firmware Parsing
• Compression Support
• Vendor Wrapper Detection
• IFR Extraction
• PE/TE Analyzer
• BIOS Setting Finder
• Search Engine
• Intel FIT Parser
• Live BIOS Read (readbios)
• Dump Modes
• Report Generator
• Surgical Patching
• Build System
• Source Code Structure
• Error Codes
• Troubleshooting

Overview

UEFIExtract parses UEFI firmware images into a structured tree of nodes and provides multiple extraction and analysis operations on that tree.

What UEFIExtract Does NOT Do

• ❌ No re-compression — PatchNode() replaces body bytes in-place at original size; compressing and rebuilding a section is not supported
• ❌ No live flash read on AMD — readbios requires Intel PCH + MEI; parsing a .rom file from any platform (Intel, AMD, ARM) works normally via FfsParser
• ❌ No Linux / macOS — Windows x64 only (Win32, SetupAPI, DWM)
• ❌ No automatic NVRAM writing — biosfind only locates offsets; writing is left to external tools (e.g. setup_var, UnderVolter)

Architecture

CLI Reference

The binary uses WinMain as its entry point. When launched with arguments it calls AttachConsole(ATTACH_PARENT_PROCESS) or AllocConsole() as needed, then routes through RunCli(). Version string is 2.0.0.

UEFIExtract {-h|--help|-v|--version}
UEFIExtract <image>
UEFIExtract <image> all
UEFIExtract <image> dump
UEFIExtract <image> report
UEFIExtract <image> guids
UEFIExtract <image> ifrscan [-o <dir>]
UEFIExtract <image> biosfind <query> [-o <txt>]
UEFIExtract <image> <GUID> [-o <outfile>] [-m <mode>] [-t <type>]
UEFIExtract readbios [-o <output.rom>]

Targeted GUID Extraction Flags

Multiple GUIDs can be listed on one command line; each reads its own -o/-m/-t after it.

Console Attach Strategy

The binary is compiled as a GUI subsystem application (WinMain). When invoked from a shell with arguments, it calls AttachConsole(ATTACH_PARENT_PROCESS). If that fails (e.g. an elevated process that lost its parent), it falls back to AllocConsole(). Stdout, stderr, and stdin are reopened to CONOUT$ / CONIN$ accordingly.

After CLI work completes, if the console was attached (not allocated), the function InjectEnterToConsole() writes a synthetic VK_RETURN key-down + key-up pair into the console input buffer via WriteConsoleInputW. This causes the parent shell (CMD, PowerShell) to redraw its prompt — without it, the cursor blinks indefinitely because the shell already printed the prompt before the GUI-subsystem process returned. If the console was allocated (new window), FreeConsole() is called instead so the window closes cleanly.

0 on success. Non-zero ErrorCode value on failure (see Error Codes).

GUI Reference

Launched when no arguments are passed (or with --gui / -g). Built on ModernWindow — a Win32 window class with DWM Mica styling. Defaults to dark mode; toggleable at runtime via Dark Mode button.

Controls

Context Menu (right-click on tree node)

IFR Visual Hinting and Text Cache

Nodes that contain detectable IFR packages are indicated in the tree using a lazy-evaluated cache (m_ifrCache). Detection uses IsIfrCandidate() which scans the first 2 MB of a node's data for EFI/UEFI IFR protocol markers. The cache is keyed by TreeNode* and is cleared on each image reload in PopulateTree().

A separate m_ifrTextCache stores the full ExtractIFR() text output per node. On the first access (e.g. via Extract IFR or a biosfind search), the text is parsed once and stored. All subsequent accesses for the same node return the cached string immediately — avoiding repeated IFR decode passes during interactive search.

Splitters

Two draggable splitters: vertical (m_splitX, default 300 px) separating the tree from the right panes; horizontal (m_splitY, default 220 px) separating details from hex. Minimum pane width/height: 80 px / 40 px.

Firmware Parsing

FirmwareImage

FirmwareImage::FromFile() reads the entire file into a ByteBuffer, runs vendor detection, and strips the wrapper if found (see Vendor Wrapper Detection). The buffer is then handed to FfsParser::Parse(). Decompressed section data is stored in m_ownedBuffers; TreeNode objects hold non-owning ByteView spans into these buffers.

FfsParser

Scans the image for Firmware Volume headers (_FVH signature 0x4856465F). For each valid volume, enumerates FFS files and recurses into sections. Decompression is triggered inline when a Compression or GUID-Defined section is encountered.

Node Tree

Each node carries:

Volume Subtypes

File Subtypes

Section Subtypes

Compression Support

Both decompressors are called from FfsParser and the result is stored as an owned ByteBuffer in FirmwareImage::m_ownedBuffers. The node's uncompressedData() view points into that buffer.

The LZMA implementation bundles the LZMA SDK C files (LzmaDec.c, Bra.h, 7zTypes.h) directly in the source tree under src/Compression/SDK/C/.

Vendor Wrapper Detection

VendorLoader.hpp detects known firmware packaging formats before the FFS parser runs:

If unwrapping succeeds, only the inner payload is parsed; FirmwareImage::wrapperInfo() holds the wrapper name string.

IFR Extraction

Internal Forms Representation (IFR) is the binary encoding of UEFI HII setup forms stored inside firmware.

Protocol Detection

IFRBridge::DetectProtocol() distinguishes two variants:

IsIfrCandidate() limits scanning to the first 2 MB of any node's data as a fast pre-filter before committing to full extraction.

ifrscan Output Format

[N] IFR <Protocol>  <NodeType> / <SectionSubtype>  @ 0x<offset>  size=0x<size>  data=<body|uncompressed>  <displayName>

With -o <dir>, each match is saved as <displayName>.ifr.txt. A ifrscan_summary.txt index is always written to the output directory.

PE/TE Analyzer

PeAnalyzer runs automatically in the GUI details pane (UpdateDetailsPane) whenever a PE32 or TE section node is selected. It parses the image header and displays:

TE (Terse Executable) is a stripped PE format used by PEI and some DXE modules to minimise image size. The analyzer handles both formats via separate AnalyzePe() and AnalyzeTe() functions. This is independent of IFR detection — it activates on section type alone.

BIOS Setting Finder

biosfind automates the lookup of BIOS setup variable offsets from IFR text. This is the equivalent of manually grepping IFR dumps for CFG Lock, overclocking settings, or any other NVRAM variable.

Query Parsing

The query string is split on ,, ;, \n, and \r. Each phrase is independently normalized (lowercased, non-alphanumeric replaced with spaces) and tokenized. Generic tokens (lock, setting, option, feature, mode, state, enable, disable, support, control) carry a scoring penalty.

Scoring Algorithm

Minimum score threshold for a candidate to be included: 260.

Candidate Extraction

Candidates are extracted from IFR text using two regular expressions:

(Setting|Checkbox|Numeric|Password):\s+(.+?),\s+Variable:\s+0x([0-9A-Fa-f]+)
Numeric:\s+(.+?)\s+\([^)]*\),\s+Variable:\s+0x([0-9A-Fa-f]+)

Variable: 0x0 entries are always discarded. Deduplication key: kind:offset:name.

Output Format

#Rank  Score  setup_var_3 0x<offset> 0x00   <matchedPhrase>    <name> [<nodeName> | <protocol>]

Up to 24 candidates are printed; additional results are indicated by a count message. The command format shown (setup_var_3) is a heuristic for AMI/Dell-style BIOSes.

Search Engine

SearchEngine supports four pattern kinds, all auto-detected from the query string:

Plain text queries (AutoDetectAll) generate both an ASCII and a Unicode pattern and search with both simultaneously.

Matching Details

• Exact hex without wildcards — uses std::boyer_moore_horspool_searcher for fast bulk scan.
• Wildcards (??) — linear scan with per-byte mask check.
• Case-insensitive ASCII — std::tolower per byte against lowercased pattern bytes.
• Case-insensitive Unicode — 2-byte wide-char units folded via std::towlower.

Search Scope

Each node is searched across three data views:

1. body() — raw payload
2. header() — only when searchHeaders = true
3. uncompressedData() — if non-empty (decompressed content)

Node metadata (name(), text()) is also checked for text and Unicode patterns; metadata matches report matchOffset = 0.

Intel FIT Parser

FitParser.hpp locates and decodes the Intel Firmware Interface Table present in SPI flash images.

FIT Pointer Location

The FIT pointer is a 64-bit physical address stored at image_base + image_size - 0x40. The image is assumed to map to the physical range [0x100000000 - image_size, 0x100000000).

FIT Entry Types

BootGuard Status

FIT output is appended to the GUI details pane when an image is loaded.

Live BIOS Read

readbios reads the BIOS SPI flash region from a running Intel platform using Intel's Flash Programming Tool (FPTW64).

Prerequisites

Execution Flow

1. DetectPch() — scans PCI devices, returns PchInfo with fptwName (e.g. FPTW64_CSME_v12r38.exe) and meVersion string.
2. RunFptw() — extracts the matching FPTW64 executable from the bundled in-memory 7z archive, runs it, monitors stdout for percentage lines (progress callback 0–100).
3. On success, the dumped ROM is saved (default: bios_dump.rom next to the EXE, or -o <path>).
4. The ROM is then parsed by FfsParser and a report + dump are generated automatically.

CLI Progress Display

The prefix Reading BIOS: is printed once. A 7-character dynamic suffix (NNN% <spinner>) is updated at 100 ms intervals by backspacing over the previous value. The spinner characters are -\|/.

Common Failure Causes

• Not running as Administrator
• MEI driver not installed or disabled in BIOS
• Flash descriptor has BIOS region read protection enabled (common on locked OEM systems)

Dump Modes

FirmwareDumper supports six extraction modes controlled by DumpOptions::mode:

File Naming

FileNamingStrategy generates names from the node's text, name, or GUID string. Illegal filesystem characters are stripped. Collisions are resolved by appending a counter suffix. Extended names are enabled by default.

Filters

DumpOptions::guidFilter — if non-empty, only nodes whose GUID string matches are dumped.
DumpOptions::sectionTypeFilter — if not 0xFF, only sections whose raw type byte matches are dumped.

Report Generator

ReportGenerator produces two output formats from the parsed tree:

Both are generated by the default <image> command and by <image> all. Each can be requested independently with the report or guids sub-commands.

Surgical Patching

FirmwareImage::PatchNode() replaces a node's body bytes in the original buffer.

Constraints

• newBody.size() must be ≤ node.body().size(). Expansion is not supported.
• Bytes from newBody.size() to node.body().size() are filled with 0xFF (erased flash state).

Checksum Update

When the FFS file header has FFS_ATTRIB_CHECKSUM (bit 0x40) set in the Attributes byte (offset 19 of the 24-byte FFS header), the IntegrityCheck.File byte (offset 17) is recomputed:

IC1 = (uint8_t)(0 - sum_of_all_body_bytes)

This maintains the invariant sum(body) + IC1 = 0 mod 256. The IntegrityCheck.Header byte (offset 16) is computed over the header with IC1 = 0 and is therefore unaffected by body changes.

The GUI exposes this via the Replace Body context menu item.

Build System

Building

.\build.ps1

Requires Visual Studio 2026 with the C++ Desktop workload and vswhere.exe present in %ProgramFiles(x86)%\Microsoft Visual Studio\Installer\.

Dependencies

All dependencies are bundled in the source tree; no package manager or external download is required at build time.

Source Code Structure

src/
├── main.cpp                     Entry point: mode dispatch, console attach/inject-Enter
├── CliRunner.cpp / .hpp         CLI command parsing and dispatch
├── Analysis/
│   ├── BiosSettingFinder.hpp    biosfind: query parser, scorer, candidate extractor
│   ├── FitParser.hpp            Intel FIT parser (header-only)
│   ├── PeAnalyzer.cpp / .hpp    PE/TE image analysis helpers
│   └── SearchEngine.hpp         Multi-pattern search engine (header-only)
├── Common/
│   ├── ErrorHandling.hpp        ErrorCode enum, Result<T> = std::expected<T, ErrorCode>
│   ├── GuidUtils.hpp            GUID ↔ string conversion
│   ├── StringUtils.cpp / .hpp   UTF-8 / wide string conversion
│   ├── Types.hpp                ByteBuffer, ByteView, Guid, String type aliases
│   └── WinApiUtils.cpp / .hpp   File I/O, directory creation, full path resolution
├── Compression/
│   ├── EfiTianoDecompress.c / .h   EFI standard (Tiano) decompressor
│   ├── LzmaDecompress.c / .h       LZMA wrapper
│   ├── UefiDecompressor.cpp / .hpp High-level decompress API
│   └── SDK/C/                      LZMA SDK (7-Zip) C sources
├── Dumper/
│   ├── FileNamingStrategy.cpp / .hpp  Node → filename generation with collision avoidance
│   └── FirmwareDumper.cpp / .hpp      Tree walk → file extraction
├── Firmware/
│   ├── FfsParser.cpp / .hpp     FV + FFS + Section recursive parser
│   ├── FirmwareImage.cpp / .hpp Image load, buffer ownership, PatchNode()
│   ├── NodeType.cpp / .hpp      NodeType / VolumeSubtype / FileSubtype / SectionSubtype enums
│   ├── TreeNode.hpp             Node data model (type, GUID, views, children)
│   └── VendorLoader.hpp         Vendor wrapper detection and stripping (header-only)
├── IFR/
│   ├── EFI.cpp / .h             EFI IFR protocol decoder
│   ├── IFRBridge.cpp / .hpp     Protocol detection, ExtractIFR() entry point
│   ├── UEFI.cpp / .h            UEFI IFR protocol decoder
│   └── util.h                   IFR utility types
├── Report/
│   └── ReportGenerator.cpp / .hpp  Text report and GUID CSV generation
├── UI/
│   ├── MainWindow.cpp / .hpp    Application main window: controls, tree, hex, search, IFR
│   └── ModernWindow.cpp / .hpp  Win32 base window with DWM/Mica styling
└── Utils/
    ├── FptwRunner.cpp / .hpp    FPTW64 extraction from 7z archive + execution + progress
    └── PchDetect.cpp / .hpp     Intel PCH detection via SetupAPI

Error Codes

RunCli() and most internal operations return or propagate these codes as process exit values:

Troubleshooting

"No UEFI firmware volumes found"

Symptom: CLI prints the error and exits with ParseError.

Solutions:

1. Verify the file is a raw UEFI SPI dump, not a compressed update package. Try the vendor's own extraction tool first if the file has an .exe or .cab extension.
2. If it is an EXE-based update, UEFIExtract's vendor unwrapper scans 512-byte-aligned offsets for _FVH or Intel FD magic. A non-standard update format may not be detected — in that case extract the raw ROM manually with 7-Zip or binwalk.
3. Confirm the file is not truncated: a typical full BIOS dump is 4–32 MB.

IFR Scan Returns No Matches

Symptom: ifrscan reports No IFR matches found.

Solutions:

1. Some BIOS images store HII resources only in compressed sections. Verify the image parsed correctly and that the report shows Compression or GUID Defined sections — these are decompressed automatically and should contain IFR.
2. Very old BIOSes (pre-UEFI) may use vendor-specific form encoding not covered by EFI or UEFI IFR protocols.

biosfind Returns No Candidates

Symptom: Command exits with No BIOS setting candidates found.

Solutions:

1. Run ifrscan first to confirm IFR is present at all.
2. The minimum score threshold is 260. Try a shorter or more specific query — single distinctive words outperform phrases containing generic tokens (lock, enable, mode).
3. If multiple phrases are needed, separate them with commas: UEFIExtract image.rom biosfind "CFG Lock, overclocking lock".

readbios Fails: PCH Not Detected

Symptom: Error: Intel PCH not detected via SetupAPI.

Solutions:

1. Run only on Intel platforms. AMD systems are not supported.
2. Confirm Intel MEI/ME driver is installed (visible in Device Manager as "Intel Management Engine Interface").
3. Some virtualized environments do not expose the PCH PCI device — run on physical hardware.

readbios Fails: FPTW64 Error

Symptom: Error: FPTW64 failed to dump BIOS.

Solutions:

1. Run UEFIExtract.exe as Administrator. FPTW64 requires direct hardware access.
2. Confirm data archive is present next to the EXE. If missing, download from https://kvc.pl/data.
3. Some platforms have the BIOS region locked in the flash descriptor. In that case FPTW64 exits with a region access error — the lock can sometimes be lifted by enabling an OEM unlock option in BIOS settings, or by using an unlocked descriptor (advanced, hardware risk).

GUID Targeted Extraction: 0 Items Dumped

Symptom: [+] Target {GUID} dumped 0 items to: ...

Solutions:

1. Verify the GUID string format: XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX. Curly braces are accepted but not required.
2. Run guids sub-command first to obtain the exact GUID strings present in the image: UEFIExtract image.rom guids.
3. Check -t <type> filter — if set, only matching section types within the file are extracted. Omit -t to extract everything.

Patched Image Fails to Boot

Symptom: After Replace Body, the firmware does not boot.

Considerations:

1. Only the body bytes and the FFS IntegrityCheck.File field are updated. Secure Boot signatures and other integrity measurements (BootGuard BP hash) are not recomputed — a modified image will fail measured boot on BootGuard-protected platforms.
2. The replacement body must fit within the original body size. Larger bodies are not supported.
3. Decompressed section contents cannot be re-compressed — patching works only on uncompressed sections.

License

Apache License 2.0

Full text available in project repository (LICENSE file).

Disclaimer

WARNING: This tool accesses raw firmware data and can interact with system hardware (FPTW64 flash read). It is provided for research, analysis, and educational purposes. Incorrect use — especially with readbios on locked or production systems — may result in system instability. Use at your own risk.

All trademarks, logos, and brand names are the property of their respective owners. Intel, Management Engine, and related marks are trademarks of Intel Corporation.

Last updated: 2026-04-19