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
- Install Rust from here.
- Switch to Rust Nightly:
rustup toolchain install nightly
andrustup default nightly
. - Install LLVM:
winget install LLVM.LLVM
. - Install Tools:
cargo install cargo-make cargo-expand cargo-edit cargo-workspaces
. - 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
- Open
regedit.exe
. - Go to
HKLM\SYSTEM\CurrentControlSet\Control\Session Manager
. - Create
Debug Print Filter
withDEFAULT
DWORD =8
.
VMware Serial Port Debugging
- Add Serial Port in VMware: 'Use output file'.
- 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:
-
Sina Karvandi (@Intel80x86): For the extensive Hypervisor From Scratch series:
-
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:
-
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.