PhoenixBoot (also known as PhoenixGuard) is a production-ready firmware defense system designed to protect against bootkits, rootkits, and supply chain attacks. It provides hardware-level firmware recovery, secure boot enforcement, and a complete UEFI boot chain with cryptographic verification.

• Linux system with UEFI firmware
• Python 3.8+ with venv
• Build tools: gcc, make, git
• QEMU for testing (optional)
• efibootmgr, mokutil for boot management
• EDK2 for building UEFI applications from source

# Clone the repository
git clone https://github.com/P4X-ng/PhoenixBoot.git
cd PhoenixBoot

# Set up Python environment (if not already done)
python3 -m venv ~/.venv
source ~/.venv/bin/activate
pip install -r requirements.txt  # if requirements.txt exists

# Run the task runner
./pf.py <task-name>

A battle-tested UEFI bootloader with strict security requirements:

• Secure Boot enforcement - Requires Secure Boot to be enabled
• Runtime attestation - Verifies binary hash against sidecar file
• Network-based boot - Can download boot configuration over HTTPS
• Memory-safe - Built with EDK2 for maximum reliability

Status: ✅ Fully implemented and tested

Automated Secure Boot key enrollment utility:

• Enrolls PK, KEK, and db keys from ESP
• Supports authenticated variables
• Prepares system for custom Secure Boot configuration

Status: ✅ Fully implemented

Tools for managing UEFI boot entries:

• os-boot-clean: Clean stale UEFI boot entries
• os-mok-enroll: Enroll MOK keys for module signing
• os-mok-list-keys: List available MOK certificates
• uuefi-install: Install UUEFI.efi to system ESP
• uuefi-apply: Set BootNext for one-time UUEFI boot
• uuefi-report: Display system security status

Status: ✅ Scripts implemented, tested on real hardware

Comprehensive QEMU-based testing:

• test-qemu: Main QEMU boot test with OVMF firmware
• test-qemu-secure-positive: Secure Boot enabled tests
• test-qemu-secure-strict: Strict security verification
• test-qemu-secure-negative-attest: Negative attestation testing

Status: ✅ Fully implemented with JUnit report generation

Bootable EFI System Partition image creation:

• Creates FAT32 ESP images
• Includes all necessary EFI binaries
• Supports ISO integration
• Validates boot structure

Status: ✅ Implemented

Kernel module signing for Secure Boot:

• Sign individual modules or directories
• MOK certificate management
• Integration with system module loading

Status: ✅ Fully functional

A simplified UEFI application for system diagnostics:

• Display firmware information
• Show memory map
• Report security status
• Boot configuration viewer

Status: 🚧 Source code complete, needs building

• ✅ Source files created: staging/src/UUEFI.c, UUEFI.inf
• ✅ Build script ready: staging/tools/build-uuefi.sh
• ⚠️ Requires EDK2 toolchain to build
• ⚠️ Currently staging/boot/UUEFI.efi is a copy of NuclearBootEdk2.efi (causes immediate exit)

Known Issue: The current UUEFI.efi binary crashes immediately on boot because it's actually NuclearBootEdk2.efi which enforces strict security checks. To fix:

# Build UUEFI from source (requires EDK2)
cd staging/src
chmod +x ../tools/build-uuefi.sh
../tools/build-uuefi.sh

# The build will create UUEFI.efi in staging/boot/

• SPI flash extraction and verification
• Bootkit protection bypass
• Firmware baseline comparison
• Automated remediation workflows

Status: 📝 Research phase, scripts exist in scripts/

• VM snapshot-based recovery
• Dom0 firmware audits
• GPU passthrough for clean boot environments

Status: 📝 Documentation and proof-of-concept in resources/xen/

• Remote attestation API
• Centralized firmware database
• Cooperative defense network

Status: 📝 API sketches in ideas/cloud_integration/

The project uses a custom task runner called pf.py that reads task definitions from .pf files. This is not the same as a Justfile (which is being deprecated in another issue).

• build.pf - Build tasks
• test.pf - Testing tasks
• os.pf - OS-level operations
• validate.pf - Validation and verification
• secure.pf - Security operations
• iso.pf - ISO creation
• usb.pf - USB preparation

# Build production artifacts
./pf.py build-build

# Package ESP image
./pf.py build-package-esp

# Run QEMU tests
./pf.py test-qemu

# Test UUEFI (currently fails - see Known Issues)
./pf.py test-qemu-uuefi

# Install UUEFI to system ESP
./pf.py uuefi-install

# Set one-time boot to UUEFI
./pf.py os-boot-once

# Display system security report
./pf.py uuefi-report

# Validate keys and ESP
./pf.py validate-all

# Enroll MOK keys
./pf.py os-mok-enroll

# Sign kernel modules
PATH=/path/to/module ./pf.py os-kmod-sign

Many operations can also be run directly via bash scripts in the scripts/ directory:

# UUEFI operations
bash scripts/uuefi-install.sh
bash scripts/uuefi-apply.sh
bash scripts/uuefi-report.sh
bash scripts/host-uuefi-once.sh

# Boot management
bash scripts/os-boot-clean.sh
bash scripts/enroll-mok.sh <cert.crt> <cert.der> [dry_run]
bash scripts/mok-list-keys.sh

# Testing
bash scripts/qemu-test.sh
bash scripts/qemu-test-uuefi.sh

PhoenixBoot/
├── 🎯 staging/          # Production-ready code (source for all builds)
│   ├── src/            # UEFI application source (NuclearBootEdk2, KeyEnrollEdk2, UUEFI)
│   ├── boot/           # Compiled EFI binaries (checked in as prebuilt)
│   └── tools/          # Build scripts for EDK2 compilation
├── 🔧 scripts/         # Operational scripts for installation and testing
├── 📦 out/             # Build artifacts and test results
│   ├── staging/       # Compiled production binaries
│   ├── esp/           # ESP images and packaging
│   └── qemu/          # QEMU test logs and reports
├── 🔐 keys/            # Secure Boot keys (PK, KEK, db, MOK)
├── 📋 docs/            # Comprehensive documentation
├── 🧪 tests/           # Test suites
├── 🎭 examples_and_samples/  # Demonstration content
├── 💡 ideas/           # Future features and research
└── ⚙️ *.pf            # Task definitions for pf.py runner

PhoenixBoot includes comprehensive QEMU tests that boot real UEFI firmware (OVMF):

# Run main boot test
./pf.py test-qemu

# Run with Secure Boot enabled
./pf.py test-qemu-secure-positive

# Test UUEFI (needs proper binary)
./pf.py test-qemu-uuefi

Test results are saved in:

• Serial logs: out/qemu/serial*.log
• JUnit reports: out/qemu/report*.xml

To rebuild UEFI applications from source, you need the EDK2 toolchain:

# Build NuclearBoot
cd staging/src
chmod +x ../tools/build-nuclear-boot-edk2.sh
../tools/build-nuclear-boot-edk2.sh

# Build UUEFI (fixes the crash issue)
cd staging/src
chmod +x ../tools/build-uuefi.sh
../tools/build-uuefi.sh

# Build KeyEnroll
# (automatically built with NuclearBoot script)

Alternatively, force a source rebuild during packaging:

PG_FORCE_BUILD=1 ./pf.py build-build

The system supports custom Secure Boot key hierarchies:

1. PK (Platform Key) - Root of trust
2. KEK (Key Exchange Key) - Intermediate authority
3. db (Signature Database) - Allowed signatures
4. MOK (Machine Owner Key) - Module signing

Keys are stored in the keys/ directory and can be enrolled using KeyEnrollEdk2.efi.

Kernel modules must be signed to load with Secure Boot enabled:

# Sign a single module
PATH=/lib/modules/.../module.ko ./pf.py os-kmod-sign

# Sign all modules in a directory
PATH=/lib/modules/$(uname -r) FORCE=1 ./pf.py os-kmod-sign

Comprehensive documentation is available in the docs/ directory:

• docs/README.md - Detailed technical documentation
• docs/SECURE_BOOT.md - Secure Boot implementation guide
• docs/BOOT_SEQUENCE_AND_ATTACK_SURFACES.md - Boot security analysis
• docs/FIRMWARE_RECOVERY.md - Firmware recovery procedures
• docs/HARDWARE_ACCESS_DEEP_DIVE.md - Hardware-level access documentation

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

This project is licensed under the Apache License 2.0. See LICENSE file for details.

For issues, questions, or support:

• GitHub Issues: https://github.com/P4X-ng/PhoenixBoot/issues
• Documentation: docs/ directory
• Examples: examples_and_samples/ directory

Issue: Attempting to boot UUEFI just stops and returns immediately.

Cause: The current staging/boot/UUEFI.efi is identical to NuclearBootEdk2.efi (same MD5 hash). When it boots, it enforces strict Secure Boot and attestation requirements, causing immediate failure.

Status: ✅ Fixed in source code

• New UUEFI.c implementation created that displays diagnostics without strict security
• Build script ready at staging/tools/build-uuefi.sh
• Requires EDK2 build environment to compile

Workaround: Build UUEFI from source or use NuclearBoot with proper attestation files.

As the project currently stands, two of the things stand out here as very practical for everyday use and setup of a computer. First is, you can generate secure boot certs very easily (check the pf tasks, there's one to create a new set of keys and put them in EFI, from there you can easily enroll them). For me I use this everyday to spin up new machines with a write-only USB (hardware protected). Barring that I do recommend an actual CD burner that connects via USB, they're super cheap and the medium is immutable once burned, so burn it, check the image hash, and you know you're good to go. If you use PhoenixBoot's image burner you just point it at an ISO, it'll generate all necessary artifacts for secureboot, and you can enroll on first boot. It should also enroll the CD through a shimx64.efi or BOOTX64.efi. Though that's not strictly necessary (I skip that, because secure boot can be touchy with ISOs depending on the drivers you load at boot), but after initial install of the OS boot up to BIOS, enroll those custom keys, takes about 2 minutes, and you're well on your way. In other words, right now it's great as a convenience tool for new boots, or for changing keys on secure boot.

So SecureBoot is nice but it's also kind of a pain in the ass. Specifically kernel modules have to be signed, and there's a few fairly key ones that I use in ubuntu that come with no signature (lookin' at you apfs.ko). SecureBoot has a signing tool, it'll use you MOK.crt to sign it for your OS, and pop you into a screen to enter a password. Then reboot, at reboot the MOK manager should show up. Enter that password and you've got a PhoenixBoot signed kernel mod.

Another useful feature right now is, if you don't have an immutable medium available, or even if you just don't feel like getting up and using a USB stick, it creates a new partition with an image burned into it in the ESP. That means you can boot from your boot partition as if there were a USB stick in there. Basically it's a fake little cd, a little trickery there. This can be used for two things (and they're two separate operations on PB) - first is new install of an OS, though again I do recommend an immutable medium, but it's also used as a recovery environment. Currently I'd use the KVM recovery env. KVM/QEMU are there in a minimal recovery environment that has flashrom and a handful of other tools to manage, analyze, and mess with your boot. If you're new to messing with boot stuff (I was when I started this project), a good first start is to totally wipe your BIOS and reinstall it. You can use flashrom from this recovery environment to do that. All of the permissions are set for it, so it shouldn't fail.

The other modes and other stuff - they need a good amount of testing before they're ready for prime time. By all means feel free to test around and see some of the other utility scripts and workflows we implement - i've been pretty careful not to have anything that might hurt your computer. At worst you'll mess up your boot, which can be flashed again. That said every warning out there tells me there's a possibility of bricking your computer with these things. I've never experienced that, but it sounds like less than fun, so still be careful!

• Nuclear Boot implementation
• Key enrollment automation
• QEMU testing framework
• ESP packaging
• Module signing integration
• UUEFI source code
• Build UUEFI binary (requires EDK2)
• Hardware firmware recovery automation
• Xen hypervisor integration
• Cloud attestation API
• P4X OS integration
• Universal hardware compatibility

Made with 🔥 for a more secure boot process