A practical, ground-up guide to understanding, building, running, and security-testing UEFI firmware using TianoCore's EDK II — the open-source reference implementation of UEFI.
It's written for two audiences at once:
- Novices who have never opened a firmware codebase and want a mental model plus a working build/run/debug loop.
- Security engineers who already know memory-safety and vuln research and want to map those skills onto the boot process: where the attack surface is, how to reach it, and how to test it (static analysis, dynamic debugging, fuzzing, sanitizers, coverage).
If you read this top to bottom you'll go from "what even is UEFI" to "I have a modified firmware image running under a debugger with a fuzzer hitting a DXE service and CodeQL flagging the bug."
UEFI (Unified Extensible Firmware Interface) is the specification for the software that runs before your operating system — from the first instruction the CPU executes out of reset, up through handing control to the OS loader. It replaced legacy BIOS. It defines a rich C ABI of services, protocols, and data structures that firmware exposes to drivers and to the OS.
Two specs matter:
- UEFI spec — the interfaces visible to OS loaders and 3rd-party drivers (Boot Services, Runtime Services, protocols, the boot manager, variables).
- PI (Platform Initialization) spec — the internal architecture of the firmware itself (the SEC/PEI/DXE phases, PEIMs, DXE drivers, HOBs, PPIs).
EDK II is the open-source codebase (maintained by TianoCore) that implements those specs. It's what real vendor firmware is built on top of, and it's what you'll read, build, and break here. Related repos you'll meet:
| Repo | Role |
|---|---|
tianocore/edk2 |
Core, mostly platform-independent code (the DXE Core, MdePkg, OvmfPkg, ShellPkg, …). |
edk2-platforms |
Board/silicon-specific code (e.g. BoardX58Ich10). |
edk2-non-osi |
Vendor binaries/blobs that can't ship under the OSI license. |
Intel FSP |
Firmware Support Package — closed-source silicon init consumed by the open code. |
Why security people care: firmware runs before — and more privileged than — the OS and hypervisor. A bug in DXE or (worse) in SMM (ring −2) can undermine Secure Boot, persist across OS reinstalls, and is invisible to most host defenses. 204 bootloader/firmware CVEs were reported in 2024 alone.
Execution moves through phases, each with less-privileged, more-featureful code than the last. Untrusted input enters at different points in different phases — knowing which phase you're in tells you what's initialized, what the attack surface is, and what debug tooling is available.
Power on
│
SEC Security phase. First code out of reset (often ROM). Sets up a
│ temporary stack (cache-as-RAM), finds and verifies the PEI core.
│
PEI Pre-EFI Initialization. Runs in a memory-constrained world; brings up
│ main DRAM. Made of PEIMs communicating via PPIs. Produces HOBs
│ (Hand-Off Blocks) describing the platform for the next phase.
│
DXE Driver Execution Environment. The big one. Full C environment, memory
│ available. The DXE Core dispatches DXE drivers that publish PROTOCOLS
│ onto the Boot Services table. Most of EDK II lives here.
│
BDS Boot Device Selection. Applies boot policy: which device/OS to load,
│ Secure Boot verification, the boot menu, console setup.
│
TSL Transient System Load. The OS loader (e.g. GRUB, Windows Boot Manager)
│ runs as a UEFI application, still able to call Boot Services.
│
RT Runtime. ExitBootServices() has been called; the OS is up. Only
│ Runtime Services (a small subset, e.g. variable + time) remain callable.
│
SMM System Management Mode — runs ORTHOGONALLY to all of the above, at
ring −2, entered via SMIs. Persists into OS runtime. The crown-jewel
attack surface: an SMI handler that trusts an OS-supplied pointer is a
classic privilege-escalation primitive.
Key globals you'll see everywhere, established during DXE:
gST— the System Table (root of everything).gBS— Boot Services (memory alloc, protocol handling, events, image load). Valid only beforeExitBootServices().gRT— Runtime Services (variables, time, reset) — survive into the OS.
EDK II looks huge and alien at first. It isn't — it's extremely regular once you learn its five file types and the package/module structure. Read the dedicated guide for a worked example:
The 60-second version:
- Packages are the top-level unit (
MdePkg,MdeModulePkg,OvmfPkg,UefiCpuPkg,SecurityPkg,ShellPkg, …). A package groups related modules and declarations. - Modules are individual drivers/apps/libraries inside a package.
- Five file extensions carry all the build metadata:
| File | Answers the question |
|---|---|
.dec |
What does this package declare? — GUIDs, protocols, PCDs, library classes it exposes. |
.dsc |
What do I build, and with which library instances? — the build recipe. |
.inf |
What is this one module? — its sources, dependencies, entry point, module type. |
.fdf |
How is the final flash image laid out? — firmware volumes, sections, the reset vector. |
.c/.h |
The actual code. |
Reading trick: start from a module's .inf, read [Sources] for the files,
[LibraryClasses]/[Protocols]/[Pcd] for its dependencies, and
[Defines] ENTRY_POINT for where execution starts. To find who implements a
protocol, grep the code for its GUID.
Follow these in order. Each links to a focused guide.
- Build it → Compiling on Linux
Get the toolchain, run
edksetup, and produce your first firmware image (OVMF, which is runnable in QEMU). - Run it → Testing Platforms overview, then QEMU + OVMF or Simics. Boot your build to the UEFI Shell and run an application.
- Debug it → Source-level debugging with GDB Break on firmware code, load symbols at the right address, single-step DXE.
- Analyze it statically → CodeQL on EDK II Build a database, run the C/C++ security queries, write a custom query for a firmware-specific bug pattern.
- Test its security → Security Testing overview Threat model, attack surface, then hands-on fuzzing: BreakingBoot · BBClient · Code coverage.
If you're here to find bugs, these are the high-value targets and the tools that reach them. Details in Security Testing.
| Attack surface | Why it's juicy | Reach it with |
|---|---|---|
| SMM / SMI handlers | ring −2, persists into OS; CommBuffer TOCTOU & pointer callouts | CodeQL patterns, Simics, chipsec |
| DXE services & protocols | parse attacker-influenced data (FV, images, network) | FuzzUEr / BBClient fuzzing, uefi_asan |
| UEFI variable services | untrusted, persistent, feed Secure Boot | fuzzing + static analysis |
| PE/COFF image loader | loads third-party & OS binaries | CodeQL, fuzzing |
| Firmware volume parsing | attacker-supplied capsules / update images | FuzzUEr (ProcessFirmwareVolume) |
| Network stack (PXE/HTTP boot) | remote, pre-OS | fuzzing, CodeQL |
Companion tooling built in this org:
- FuzzUEr — fuzzing UEFI interfaces on EDK II (found 20 zero-days).
- firness — automated harness generation for UEFI interfaces.
- uefi_asan — AddressSanitizer adapted to the freestanding UEFI environment.
learning-edk2/
├── README.md ← you are here (start + mental model)
├── Codebase/
│ └── Reading-the-Codebase.md how EDK II is structured & how to navigate it
├── Compiling/
│ └── Linux-Compiling.md toolchain, edksetup, building OVMF
├── Executing/
│ ├── README.md QEMU vs Simics
│ ├── QEMU-Emulation.md QEMU+OVMF and the EmulatorPkg host
│ ├── Simics-Simulation.md custom firmware in Simics
│ └── GDB-Debugging.md source-level debugging under QEMU
├── CodeQL/
│ └── CodeQL.md static analysis: DB creation, queries, custom
└── Testing/
├── Security-Testing.md threat model + attack surface + method
├── BreakingBoot.md the BreakingBoot fuzzing shell app
├── BBClient.md the BBClient service fuzzer
└── CodeCoverage.md coverage with the Simics UEFI tracker
- UEFI & PI specifications — the source of truth.
- EDK II documentation — build spec, module writer's guide, DSC/INF/DEC/FDF references.
- Beyond BIOS (Zimmer, Rothman, Marmorstein) — the canonical PI/DXE book.
- OVMF README — the virtual firmware you'll run in QEMU.
- chipsec — platform security assessment framework.