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

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.

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.
• ✅ Kernel Inline Hooks: PatchGuard-compatible breakpoint (int3) hooks.
• ✅ 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.

• Daax Rynd (@daaximus), Aidan Khoury (@ajkhoury), Nick Peterson (@everdox): For their comprehensive series on hypervisor development:

  • 7 Days to Virtualization
  • MMU Virtualization via Intel EPT
  • Patchguard: Hypervisor Based Introspection [P1]
  • Patchguard: Hypervisor Based Introspection [P2]
  • Syscall Hooking Via Extended Feature Enable Register (EFER)

• Sina Karvandi (@Intel80x86): For the extensive Hypervisor From Scratch series:

  • Tutorial Series
  • GitHub Repository

• Satoshi Tanda(@tandasat): His work has significantly influenced this project:

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

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

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 Rynd
• Satoshi Tanda
• Drew (@drew)
• Matthias @not-matthias
• @felix-rs / @joshuа
• Jess (@jessiep_)
• Ryan McCrystal / @rmccrystal
• Jim Colerick (@vmprotect)

License

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