search

memN0ps / illusion-rs

Rusty Hypervisor - Windows UEFI Blue Pill Type-1 Hypervisor in Rust (Codename: Illusion)
MIT License
239 stars 29 forks source link
blue-pill bootkit hypervisor intel ring-1 rootkit rust uefi virtualization vt-x windows

readme

Windows UEFI Blue Pill Type-1 Hypervisor in Rust (Codename: Illusion)

Build Status License Issues Forks Stars

A lightweight, memory-safe, and blazingly fast Rust-based type-1 research hypervisor with hooks for Intel VT-x, focused on studying the core concepts of virtualization.

Note: The Illusion hypervisor (Windows UEFI Blue Pill Type-1 Hypervisor in Rust) is more stable, supports more features, and is overall better designed. The Matrix hypervisor (Windows Kernel Blue Pill Type-2 Hypervisor in Rust) is an older, experimental version and is not intended for production use. Both projects serve as templates to help people get started with hypervisor development in Rust.

Description

Paging: Translating x64 Virtual Addresses to Physical Addresses

This diagram illustrates the mechanism of translating x64 virtual addresses to physical addresses in traditional paging systems. In x64 architecture, this translation involves four levels of page tables: PML4, PDPT, PDT, and PT (Page Map Level 4, Page Directory Pointer Table, Page Directory Table, and Page Table). Each level uses 9 bits of the virtual address to index into the next level, ultimately pointing to a specific physical address in RAM. This process is managed by the operating system and the Memory Management Unit (MMU), which translates virtual addresses used by software into physical addresses used by hardware.

x64 Virtual Address Translation
Figure 1: x64 Virtual Address Translation (Full Credits: Guided Hacking)

Extended Page Tables (EPT): Second Level Address Translation (SLAT)

Extended Page Tables (EPT) are a feature of hardware-assisted virtualization technologies such as Intel VT-x and AMD-V's Nested Page Tables (NPT). EPT implements Second Level Address Translation (SLAT), specifically designed for virtualized environments. While traditional paging translates virtual addresses to physical addresses within the guest OS, EPT adds an additional layer by translating guest physical addresses (used by the guest OS) to host physical addresses (used by the hypervisor). This second layer of translation is managed by the hypervisor, allowing guest operating systems to manage their own page tables independently. SLAT improves performance by minimizing the need for VM exits during memory operations, which reduces overhead and enhances virtualization efficiency.

The diagram below demonstrates how to implement hidden EPT hooks in the Windows UEFI Blue Pill Type-1 Hypervisor (Codename: Illusion) written in Rust.

EPT Hooks
Figure 2: Extended Page Tables (EPT) Hooks (Illusion)

Features

PatchGuard Compatible Features

Processor-Specific Features

Microsoft Hyper-V Compatible Features

VM Exit Handling

Hypervisor Detection

Isolation and Security

Supported Hardware

Supported Platforms

Installation

Building the Project

Running the Project

Debugging

Enabling Debug Modes

bcdedit.exe /bootdebug {bootmgr} on
bcdedit.exe /bootdebug on
bcdedit.exe /debug on

Network Debugging with Windbg

Usage

A UEFI blue-pill hypervisor operates under the following conditions:

Configuration Note

When setting up this UEFI hypervisor, it's important to configure the file depending on the number of logical processors/cores/threads based on your system. Please edit the relevant code in global_const.rs.

The global heap allocator is shared among all processors/cores/threads and is a pre-allocated pool of memory. The stack size is allocated per processor/core/thread. This design makes it easier to keep track of memory allocations, especially for tasks like setting up hooks that require pre-allocated buffers. By adjusting the settings in this file, you ensure that enough memory is allocated to accommodate all processors while maintaining optimal performance and resource management.

Usage 1: Running a UEFI Blue-Pill Hypervisor through the UEFI Shell on VMware Workstation (Supported)

  1. Create a Virtual USB Drive for Booting

    Run the following PowerShell script as an administrator to create a new partition on the USB drive and format it as FAT32. This script shrinks the existing partition by 512 MB and creates a new partition with the label "Hypervisor" on the USB drive. Make sure to modify the drive letters according to your environment. Alternatively, you can use a physical USB drive.

    # Define the size to shrink in MB
$sizeToShrinkMB = 512

# Define the drive letter of the existing partition to shrink
$existingDriveLetter = "C"

# Define the drive letter and label for the new partition
$newDriveLetter = "D"
$newFileSystemLabel = "Hypervisor"

# Shrink the existing partition
$volume = Get-Volume -DriveLetter $existingDriveLetter
$partition = $volume | Get-Partition
Resize-Partition -DriveLetter $partition.DriveLetter -Size ($partition.Size - ($sizeToShrinkMB * 1MB))

# Create a new partition in the unallocated space
$disk = Get-Disk -Number $partition.DiskNumber
$newPartition = New-Partition -DiskNumber $disk.Number -UseMaximumSize -DriveLetter $newDriveLetter

# Format the new partition
Format-Volume -DriveLetter $newDriveLetter -FileSystem FAT32 -NewFileSystemLabel $newFileSystemLabel

Write-Output "Partition created and formatted successfully."

  2. Setup for VMware Workstation

    • Build the Project: Follow the build instructions provided in the previous sections to compile the project.

  3. Set Up VMware Workstation

    Configure VMware Workstation to boot into the firmware setup on the next boot and to use the physical USB drive as the boot device:

    • Add a Hard Disk:
      • Physical USB: Go to VM -> Settings -> Hardware -> Add -> Hard Disk -> Next -> SCSI or NVMe (Recommended) -> Next -> Use a physical disk (for advanced users) -> Next -> Device: PhysicalDrive1 and Usage: Use entire disk -> Next -> Finish.
      • Virtual USB: Go to VM -> Settings -> Hardware -> Add -> Hard Disk -> Next -> SCSI or NVMe (Recommended) -> Next -> Use a physical disk (for advanced users) -> Next -> Device: PhysicalDrive0 and Usage: Use individual partitions -> Select Partition -> Next -> Finish.
    • Add a Serial Port:
      • Go to VM -> Settings -> Add -> Serial Port -> Finish.
      • Select Use output file: C:\Users\memN0ps\Documents\GitHub\illusion-rs\logs.txt to direct the Serial Port output from COM1 to the logs.txt file. (You can choose any location, but the preference is within the project directory).
    • Boot Options:
      • If you're not using the automated PowerShell script, start the VM by clicking Power On to Firmware.
      • Select Internal Shell (Unsupported option) or EFI VMware Virtual SCSI Hard Drive (1.0).

  4. Run the PowerShell Script

    Execute the following PowerShell script to automate the setup process. Make sure to modify the paths according to your environment.

    ### Change paths according to your environment ###

# Set build type to either 'debug' or 'release'
$buildType = "debug" # Use this line for a debug build
# $buildType = "release" # Uncomment this line and comment the above for a release build

# Define the file path to copy all EFI files based on the build type
$efiFilePaths = ".\target\x86_64-unknown-uefi\$buildType\*.efi"

# Define the destination path on the USB drive D:\
$usbFilePath = "D:\"

# Define the path to the VMX file
$vmxPath = "C:\Users\memN0ps\Documents\Virtual Machines\Class_Windows\Class_Windows.vmx"

# Define the path to the vmrun.exe file
$vmrunPath = "C:\Program Files (x86)\VMware\VMware Workstation\vmrun.exe"

# Define the path to the log file
$logFilePath = ".\logs.txt"

# Copy all EFI applications to the D:\ drive
Copy-Item -Path $efiFilePaths -Destination $usbFilePath

# Print the contents of the D:\ drive to verify the copy operation
Get-ChildItem -Path D:\ -Recurse

# Append configuration to the VMX file for booting into firmware setup on next boot
Add-Content -Path $vmxPath -Value "bios.forceSetupOnce = `"TRUE`""

# Check if the log file exists and delete it if it does
if (Test-Path $logFilePath) {
   Remove-Item $logFilePath -Force
   Write-Host "Log file $logFilePath deleted."
}

# Start the VMware VM and open the GUI. Attempt to boot to firmware (if supported).
& "$vmrunPath" -T ws start "$vmxPath" gui

# Wait for the log file to be created (e.g., by another process) before proceeding to tail it
while (-not (Test-Path $logFilePath)) {
   Start-Sleep -Seconds 1
   Write-Host "Waiting for log file to be created..."
}

# Tail the log file to display live updates from the start
Write-Host "Monitoring log file from the start for updates..."
Get-Content -Path $logFilePath -Wait

VMware Workstation Boot Options Figure 3: VMware Workstation Boot Options

  1. Navigate to the USB Drive and Start the Hypervisor

    In the UEFI Shell, navigate to the USB drive and run the loader (loader.efi). The hypervisor will start, followed by the Windows Boot Manager (bootmgfw.efi) to boot into Windows.

VMware Workstation UEFI Shell Figure 4: VMware Workstation UEFI Shell

  1. Interact with the Hypervisor

    After Windows boots, use client.exe to interact with the hypervisor and perform various operations, including checking the hypervisor's presence or setting hidden EPT hooks.

Hypervisor Client Figure 5: Hypervisor Client

PoC

Verify the execution of the EPT hooking proof of concept (PoC) by checking the hypervisor's logs (serial port logger through COM ports) and Windbg. A PoC screenshot is provided below.

Logs and Windbg PoC Figure 6: Logs and Windbg PoC

Usage 2: Running a UEFI Blue-Pill Hypervisor through the UEFI Shell on Baremetal (Supported)

The following outlines a supported method to execute a UEFI blue-pill hypervisor using the UEFI Shell. By leveraging either the EDK2 EFI shell or the UEFI-Shell, users can set up a USB drive to boot into a UEFI shell environment. From there, the hypervisor can be loaded and executed directly.

  1. Build the Project

    Follow the build instructions provided in the previous sections to compile the project.

  2. Download EDK2 EFI Shell or UEFI-Shell

  3. Prepare the USB Drive

    a. Extract the downloaded EFI shell and rename the file Shell.efi (found in the UefiShell/X64 folder) to bootx64.efi.

    b. Format the USB drive to FAT32.

    c. Create the following folder structure on the USB drive:

    USB:.
│   loader.efi
│   illusion.efi
│
└───EFI
   └───Boot
          bootx64.efi

Usage 3: Infecting the Windows Boot Manager (bootmgfw.efi) on Disk (Unsupported)

UEFI blue-pill hypervisors can target the Windows Boot Manager (bootmgfw.efi) found in the EFI partition at \EFI\Microsoft\Boot\bootmgfw.efi (also at C:\Windows\Boot\EFI\bootmgfw.efi). The process involves:

  1. Convert the hypervisor into position-independent code (PIC) or shellcode.
  2. Locate bootmgfw.efi in the EFI partition.
  3. Add a new .efi section to bootmgfw.efi.
  4. Inject the hypervisor shellcode into the new .efi section.
  5. Modify the entry point to point to the shellcode.
  6. Reboot the system.

More information: Bootkitting Windows Sandbox

Acknowledgments, References, and Motivation

Big thanks to the amazing people and resources that have shaped this project. A special shout-out to everyone listed below. While I didn't use all these resources in my work, they've been goldmines of information, super helpful for anyone diving into hypervisor development, including me.

Community and Technical Resources

Helpers and Collaborators

Special thanks to:

License

This project is licensed under the MIT License. For more information, see the MIT License details.