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.
• ✅ 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.

• Daax Rynd (@daaximus): For his outstanding 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:

  • 7 Days to Virtualization
  • MMU Virtualization via Intel EPT

• Satoshi Tanda (@tandasat): Satoshi Tanda's guidance, projects, and training sessions have been incredibly helpful. His detailed explanations and contributions on GitHub, along with his structured training programs, 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.

• Sina Karvandi (@Intel80x86): For his detailed 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): For insightful explorations into hypervisor introspection:

  • Patchguard: Hypervisor Based Introspection [P1]

• Aidan Khoury (@ajkhoury): For insightful explorations into hypervisor introspection:

  • 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 Rynd
• Satoshi Tanda (@tandasat)
• Drew (@drew)
• iPower (@iPower)
• Namazso (@namazso)
• 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.