/hypervisor-rs

Rusty Hypervisor - Windows Blue Pill Type-2 Hypervisor in Rust (Codename: Matrix)

Primary LanguageRustMIT LicenseMIT

Windows Kernel Blue Pill Type-2 Hypervisor in Rust (Codename: Matrix)

Build Status License Issues Forks Stars

A lightweight, memory-safe, and blazingly fast Rust-based type-2 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.

Features

  • ✅ Extended Page Tables (EPT): Support for Memory Type Range Registers (MTRR).
  • ✅ VM Exit Handling: Handling of ExceptionOrNmi (#GP, #PF, #BP, #UD), Cpuid, Getsec, Vmcall, Vmclear, Vmlaunch, Vmptrld, Vmptrst, Vmresume, Vmxon, Vmxoff Rdmsr, Wrmsr, Invd, Rdtsc, EptViolation, EptMisconfiguration, Invept, Invvpid, Xsetbv.
  • ✅ Hidden Kernel Inline Hooks: PatchGuard-compatible breakpoint (int3) hooks.
  • ✅ Hidden System Call (Syscall) Hooks: PatchGuard-compatible hooks for System Service Descriptor Table (SSDT) function entries.

Planned Enhancements

  • ❌ Isolation and Security: Development of custom implementations for Global Descriptor Table (GDT), Interrupt Descriptor Table (IDT), and Page Tables to enhance security. Aiming to reduce dependency on the host's ntoskrnl.exe CR3. Credits to @namazso.

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

  1. Install Rust from here.
  2. Switch to Rust Nightly: rustup toolchain install nightly and rustup default nightly.
  3. Install LLVM: winget install LLVM.LLVM.
  4. Install Tools: cargo install cargo-make cargo-expand cargo-edit cargo-workspaces.
  5. Install WDK/SDK/EWDK: Steps here.

Building the Project

  • Development: cargo make --profile development.
  • Production: cargo make --profile release.

Debugging

Enabling Debug Modes

  • Test Mode: Activate test signing with bcdedit.exe /set testsigning on.
  • Windows Debugging: Follow the steps in this Microsoft guide.
bcdedit.exe /bootdebug {bootmgr} on
bcdedit.exe /bootdebug on
bcdedit.exe /debug on

Network Debugging with Windbg

Setup: bcdedit.exe /dbgsettings net hostip:w.x.y.z port:n.

Debug Print Filter

  1. Open regedit.exe.
  2. Go to HKLM\SYSTEM\CurrentControlSet\Control\Session Manager.
  3. Create Debug Print Filter with DEFAULT DWORD = 8.

VMware Serial Port Debugging

  1. Add Serial Port in VMware: 'Use output file'.
  2. Configure in Windows VM: $serialPort = New-Object System.IO.Ports.SerialPort COM2,9600,None,8,One; $serialPort.Open().

Service Management

Use Service Controller (sc.exe) to create and manage the hypervisor service:

sc.exe create matrix type= kernel binPath= C:\Windows\System32\drivers\matrix.sys
sc.exe query matrix
sc.exe start matrix

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.