memn0ps / illusion-rs

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

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

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.

Currently, the following features are not supported but are planned for future releases:

• Integration of a Windows kernel driver with a UEFI runtime driver hypervisor for flexible deployment.
• Implementation of Intel Processor Trace (Intel PT).
• AMD-V (SVM) with Nested Page Tables (NPT) support.
• Support for running as the primary hypervisor on top of Microsoft Hyper-V (Type-1) with Virtualization-Based Security (VBS).

However, neither basic nor advanced techniques to evade hypervisor detection will be implemented in the public version of this hypervisor.

Description

What is a Hypervisor?

A hypervisor, also known as a virtual machine monitor (VMM) or virtualizer, is software, firmware, or hardware that creates and runs virtual machines. The physical machine on which a hypervisor runs one or more virtual machines is called a host machine, and each virtual machine is called a guest machine. The hypervisor provides a virtual operating platform for guest operating systems and manages their execution.

What Can Hypervisors Be Used For?

1. Fuzzing
2. Reverse engineering / debugging obfuscated software
3. Malware research (Blue-Pill / Red Pill)
4. Anti-cheat (AC) / Anti-virus (AV) / Endpoint detection and response (EDR)
5. Server consolidation / Security isolation

Types of Hypervisors

Type	Description	Examples
Type 1	Runs directly on hardware, with all OSes as guests (VMX non-root)	VMware ESXi, Microsoft Hyper-V, ProxMox
Type 2	Runs on a host OS, which in turn runs guest OSes (VMX root)	VMware Workstation, Oracle VirtualBox, KVM
Full-fledged	Offers complete virtual machines	VMware, Hyper-V, ProxMox, KVM
Pass-through	Only virtualizes existing CPUs and MMU	BitVisor, SimpleVisor, Illusion, Matrix

UEFI-Based vs Kernel Module-Based Pass-Through Hypervisors

Type	Advantages	Disadvantages	Examples
UEFI-Based	Greater ability to take control of the system, more stealthiness, cross-platform by design, easier to understand VT	Limited ability to interact directly with the operating system, requires system reboot for installation	BitVisor, Bareflank, CheatEngine, FalkVisor (boot-loader), Illusion
Kernel Module-Based	More seamless interaction with the guest, easier to develop and debug, no reboot required for installation, trivial to support sleep/hibernation	Limited ability to take control of the system, more detectable from the guest, constrained by OS enforced security policies, platform-specific	AV software, iKGT, BluePill, SimpleVisor, CheatEngine, Matrix

This diagram illustrates the mechanism of translating x64 virtual addresses to physical addresses and the Extended Page Tables (EPT) used in hardware-assisted virtualization. In x64 systems, the translation involves four tables: PML4, PDPT, PDT, and PT, each using 9 bits to point to the next table, finally mapping to the physical RAM address.

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

Extended Page Tables (EPT), used in technologies like Intel VT-x and AMD-v's (SVM) Nested Page Tables (NPT), provide a Second Layer of Address Translation (SLAT). EPT maps guest physical addresses to host physical addresses, reducing VM exits and improving performance. While traditional paging translates virtual to physical addresses, EPT adds another layer, translating guest physical addresses to host physical addresses. This dual-layer approach in EPT involves two sets of page tables: one managed by the guest OS and the other by the hypervisor. The guest OS page tables translate virtual addresses to guest physical addresses, while the EPT tables map these guest physical addresses to the actual host physical addresses, enabling efficient virtualization with minimal overhead.

The diagram below illustrates the structure and flow of the Windows UEFI Blue Pill Type-1 Hypervisor written in Rust, demonstrating the use of Extended Page Table (EPT) hooks.

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

Features

PatchGuard Compatible Features

• ✅ Hidden System Call (Syscall) Hooks Via System Service Descriptor Table (SSDT).
• ✅ Hidden Kernel Inline Hooks.
• ✅ Hidden Model Specific Registers (MSR) Hooks.
• ❌ Hidden Interrupt Descriptor Table (IDT) Hooks.
• ❌ Hidden Hardware Debug Register Breakpoints.

Processor-Specific Features

• ✅ Extended Page Tables (EPT).
• ✅ Memory Type Range Registers (MTRRs).
• ❌ Intel Processor Trace (PT).

Microsoft Hyper-V Compatible Features

• ❌ Support for running as a nested hypervisor under Microsoft Hyper-V (Type-2) with Virtualization Based Security (VBS) Enabled.
• ❌ Support for running as the primary hypervisor on top of Microsoft Hyper-V (Type-1) with Virtualization Based Security (VBS) Enabled.

VM Exit Handling

• ✅ VM Exit Handling: ExceptionOrNmi (#GP, #PF, #BP, #UD) (0), InitSignal (3), StartupIpi (4), Cpuid (10), Getsec (11), Hlt (12), Invd (13), Vmcall (18), Vmclear (19), Vmlaunch (20), Vmptrld (21), Vmptrst (22), Vmresume (24), Vmxon (27), Vmxoff (26), Rdmsr (31), Wrmsr (32), MonitorTrapFlag (37), Rdtsc (49), EptViolation (48), EptMisconfiguration (50), Invept (53), Invvpid (55), Xsetbv (55).

Hypervisor Detection

• ❌ Neither basic nor advanced techniques to evade hypervisor detection will be implemented in the public version of this hypervisor.

Supported Hardware

• ✅ Intel processors with VT-x and Extended Page Tables (EPT) support.
• ❌ AMD processors with AMD-V (SVM) and Nested Page Tables (NPT) support.

Supported Platforms

• ✅ Windows 10 - Windows 11, x64 only.

Installation

• Install Rust from here.
• Install cargo-make: cargo install cargo-make.

Building the Project

• Debug: cargo make build-debug.
• Release: cargo make build-release.

Usage

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

• Secure Boot is Disabled: No vulnerabilities needed (supported by this project).
• Virtualization-Based Security (VBS) is Disabled: Ensures compatibility.
• Exploiting Known UEFI Flaws: Using outdated or unsupported firmware, including the Bring Your Own Vulnerable Binary (BYOVB) technique, to bypass Secure Boot.
• Exploiting Unspecified UEFI Flaws: Using zero-day vulnerabilities to disable Secure Boot.

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

1. Setup for VMware Workstation

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

2. 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:
     • 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.
   • 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).

3. 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

Figure 3: VMware Workstation Boot Options

4. 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.

Figure 4: VMware Workstation UEFI Shell

5. 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.

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.

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

   • EDK2 EFI Shell
   • 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.

• Daax (@daaximus): For his outstanding free series on hypervisor development, which is one of the best resources available and has greatly influenced my work with its thorough research and clear explanations. His support and answers to my questions were invaluable in getting me started with hypervisor development:

  • 7 Days to Virtualization.
  • MMU Virtualization via Intel EPT.

• Satoshi Tanda (@tandasat): Satoshi Tanda's guidance, projects, and structured training programs have been incredibly helpful. His detailed explanations and contributions on GitHub have significantly enhanced my understanding, making him a great mentor throughout my journey:

  • Hypervisor Development for Security Researchers.
  • Hypervisor 101 in Rust.
  • Additional Projects: Hello-VT-rp, DdiMon, HyperPlatform, MiniVisorPkg.

• Jess (@jessiep_): For his invaluable support and collaboration in several areas of this project, providing essential insights and expertise, and for his quick responses to my questions.

• Drew (@drew): For his help, guidance, and quick responses to my questions in various aspects of hypervisor development.

• Sina Karvandi (@Intel80x86): For his detailed free Hypervisor From Scratch series:

  • Tutorial Series.
  • GitHub Repository.

• Matthias (@not-matthias): For his impactful work on the amd_hypervisor project, which greatly inspired and influenced this research.

• Nick Peterson (@everdox) and Aidan Khoury (@ajkhoury): For their insightful explorations into hypervisor introspection and syscall hooking:

  • Patchguard: Hypervisor Based Introspection [P1].
  • Patchguard: Hypervisor Based Introspection [P2].
  • Syscall Hooking Via Extended Feature Enable Register (EFER).

Community and Technical Resources

• Secret Club: Insights into anti-cheat systems and hypervisor detection, which also inspired this project:

  • System emulation detection by @Daax, @iPower, @ajkhoury, @drew.
  • BattlEye hypervisor detection by @vmcall, @Daax.

• Other Essential Resources:

  • Intel's Software Developer's Manual.
  • Maurice Heumann's (@momo5502) Detecting Hypervisor-Assisted Hooking.
  • Guided Hacking's x64 Virtual Address Translation on YouTube.
  • UnKnoWnCheaTs forum post by @namazso.
  • RVM1.5, Barbervisor, rustyvisor, orange_slice, mythril, uhyve, maystorm.
  • AMD-V Hypervisor Development by Back Engineering, bluepill by @_xeroxz.
  • hvpp by @wbenny.
  • HyperHide by @Air14.
  • How AetherVisor works under the hood by M3ll0wN1ght.
  • Rust library to use x86 (amd64) specific functionality and registers (x86 crate for Rust).
  • DarthTon's HyperBone (based on the legendary Alex Ionescu's version) on UnknownCheats.
  • Joanna Rutkowska: Pioneering the Blue Pill Hypervisor Concept, one of the earliest proofs of concept.

Helpers and Collaborators

Special thanks to:

• Daax.
• Satoshi Tanda (@tandasat).
• Drew (@drew).
• iPower (@iPower).
• Namazso (@namazso).
• Jess (@jessiep_).
• Matthias @not-matthias.
• @felix-rs / @joshuа.
• Ryan McCrystal / @rmccrystal.
• Jim Colerick (@vmprotect).
• Xitan (@xitan).

License

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

illusion-rs's Issues

Add CPUID Password-Protected Backdoor for Hypervisor Communication

Implement a CPUID password-protected backdoor to communicate with the hypervisor from user-mode and perform certain tasks. This feature could include:

• Telling the hypervisor to perform hooks or unhooks.
• Other tasks as required.

This enhancement will allow secure communication with the hypervisor for specialized tasks.

Integrate Windows (Kernel Driver) with UEFI (Runtime Driver) Hypervisor for Flexible Deployment

Integrate Windows (Kernel Driver) with the UEFI (Runtime Driver) hypervisor to allow users the option to build the software as either a kernel driver or a UEFI runtime driver, providing flexibility in deployment options.

Support JMP, INT3, VMCALL, and CPUID Hooks Based on User Preference

The Windows hypervisor matrix-rs hook mechanism in the library relies on INT3, which causes VM exits and potential performance issues. To offer users flexibility, the hypervisor needs to support JMP, INT3, VMCALL, and CPUID hooks, allowing them to choose the preferred method based on their requirements. Additionally, supporting relative JMP hooks is essential for improved efficiency. Careful consideration should be given to selecting the appropriate library for hooking implementation.

Note: INT3, VMCALL, CPUID hooks will cause a vmexit.

Careful consideration should be given to allocating and executing the trampoline, which would be allocated in the host address space unless specified otherwise. This would disallow the guest to execute the allocated trampoline on the host PA space unless the guest itself allocates memory, but that would expose the trampoline. Alternative ways should be explored e.g Manipulation of EPT…

Implement Hardware-Assisted Breakpoints

Add support for hardware-assisted breakpoints using CPU debug registers to enhance debugging capabilities in the hypervisor.

AMD-V (SVM) Support

Plan to explore AMD support with Nested Page Tables (NPT) in the future, aiming for implementation within one year.

Develop Functionality Without Reliance on x86 Crate

Avoid using the x86 crate overall and develop the necessary functionality from scratch. This approach will facilitate learning and reduce dependence on external libraries, potentially increasing accuracy. However, it may require more effort. This task is optional and not urgent.

Serial Logs Freeze Post-Windows Boot

Issue: Serial logs stop updating after Windows OS boots, although the hypervisor continues to run.

Expected Behavior: Serial logs should continue to output after Windows OS boots.

Actual Behavior: Logs freeze upon Windows boot.

Steps to Reproduce:

1. Boot Windows OS in the hypervisor environment.
2. Observe the serial logs.

Additional Info: Hypervisor remains operational; issue only affects log visibility.

Implement Hidden Interrupt Descriptor Table (IDT) Hooks

Add support for hidden Interrupt Descriptor Table (IDT) hooks to enhance the hypervisor's capability to intercept and manage interrupt and exception handling more efficiently.

Option for Hypervisor Graceful Shutdown Over Panic

Errors in the hypervisor are typically handled using a custom error type, HypervisorError, through Result or Option. Despite this, errors default to causing a panic in the vmm.rs file, particularly during critical issues that necessitate halting the hypervisor. This panic approach, while highlighting problems quickly, isn't always ideal, especially when a graceful shutdown would be preferable. It can hinder debugging and disrupt processes unnecessarily, although there are cases where shutting down the hypervisor isn't desired, and panicking is the preferred option. I personally prefer handling all errors with a custom error type, returning Result<(), HypervisorError>, and funneling them to a single location in the main function (vmm.rs). If an error cannot be handled and I no longer want the hypervisor running or off, I opt for panicking the Windows guest OS (BSOD).

To improve the hypervisor's adaptability and robustness, a mechanism for a graceful shutdown and CPU devirtualization could be a better option. This would involve executing VMXOFF to cleanly exit VMX operation, restoring any altered states during VMXON, and orderly devirtualizing CPUs.

Implement Support for Running as the Primary Hypervisor on Top of Microsoft Hyper-V (Type-1) with VBS

Implement support for nested virtualization, enabling the hypervisor to run on top of Hyper-V while ensuring compatibility and performance.

Implementing a Custom Allocator for Improved Memory Management in Hypervisor

The current memory allocator and tracking system have limitations that need to be addressed. The hypervisor should aim to record all memory allocations directly within GlobalAlloc and utilize fixed-size heap allocators to improve efficiency and reliability.

Implement Support for Running as a Nested Hypervisor Under Microsoft Hyper-V (Type-2) with VBS

Issue: Support for running as a nested hypervisor under Microsoft Hyper-V with Virtualization Based Security (VBS).

Environment: UEFI Rust hypervisor, with partial support for Hyper-V nested virtualization.

Current Status:

• Implemented: Out of Range MSRs and Hyper-V Interface CPUID Leaves.
• Pending:
  1. Implementation of Hyper-V Hypercalls (VMCALLs).
  2. Transition to Advanced Configuration and Power Interface (ACPI) from the older Multiprocessor Specification (MP Protocol).

Required Implementation:

1. Hyper-V Hypercalls (VMCALLs) - Essential for managing interactions between the hypervisor and the nested virtual machine (VM). This includes recognizing and correctly handling VMCALLs from both the hypervisor and nested VMs to maintain system stability and functionality.
2. Advanced Configuration and Power Interface (ACPI) - Transition from MP Protocol to ACPI is necessary to meet Hyper-V's configuration and power management standards.

Current Behavior: Without proper VMCALL handling and ACPI support, the hypervisor cannot correctly interact with Hyper-V, leading to potential failures or incorrect operations under Hyper-V nested virtualization.

Expected Behavior:

• The hypervisor should intercept and manage VMCALLs effectively, ensuring smooth operation and compatibility within a Hyper-V environment.
• Transition to ACPI support to enhance compatibility with Hyper-V's power management and configuration requirements.

Steps to Reproduce:

1. Set up the hypervisor with Hyper-V.
2. Observe operational issues related to unhandled VMCALLs and potential issues due to MP Protocol usage instead of ACPI.

Additional Information:
Implementing these functionalities is crucial for ensuring that the hypervisor can run efficiently under Hyper-V, handling all necessary hypercalls and configuration protocols as expected by the Hyper-V Hypervisor Top-Level Functional Specification (TLFS). Transitioning to ACPI will address compatibility issues with Hyper-V's advanced power management features.

Implement Intel Processor Trace (Intel PT)

Add support for Intel Processor Trace (Intel PT) to enhance tracing and debugging capabilities in the hypervisor.

Ensure EPT Hooks Work on the Same Page

Ensure that EPT hooks function correctly when targeting the same page. When splitting 2MB pages into 4KB pages using the same pre-allocated Page Table (PT), it can cause an issue. Or when multiple hooks require a shadow page, it's essential that they share a single shadow page rather than each having its distinct shadow page. This requirement is crucial for the hooks to operate correctly and could potentially cause issues with the current setup if not handled properly.

We need a better way to manage and keep track of hooks, utilizing guest_page_pa to consistently track associated shadow pages and PTs. Investigate and refine our approach to guarantee the stability and effectiveness of EPT hooks, particularly after integrating a communication method to perform hooks/unhooks from user-mode, as noted in issue #20.

Restore Multi-Core Support and Stabilize Main Branch

The hypervisor previously supported multiple cores, but recent changes have disrupted this functionality. The goal is to restore effective multi-core support and ensure the main branch is stable for production use. This includes identifying and fixing any bugs introduced during these changes, and ensuring the overall stability and reliability of the hypervisor.