Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.
Awesome Lists | Featured Topics | Projects
https://github.com/memN0ps/matrix-rs

Rusty Hypervisor - Windows Kernel Blue Pill Type-2 Hypervisor in Rust (Codename: Matrix)
https://github.com/memN0ps/matrix-rs
blue-pill hypervisor intel kernel ring-1 rootkit rust virtualization vt-x windows
Last synced: about 1 month ago
JSON representation
Rusty Hypervisor - Windows Kernel Blue Pill Type-2 Hypervisor in Rust (Codename: Matrix)
Host: GitHub
URL: https://github.com/memN0ps/matrix-rs
Owner: memN0ps
License: mit
Archived: true
Created: 2022-12-09T09:10:51.000Z (about 2 years ago)
Default Branch: main
Last Pushed: 2024-07-07T06:02:10.000Z (5 months ago)
Last Synced: 2024-08-02T16:30:46.611Z (4 months ago)
Topics: blue-pill, hypervisor, intel, kernel, ring-1, rootkit, rust, virtualization, vt-x, windows
Language: Rust
Homepage: https://memn0ps.github.io/hypervisor-development-in-rust-part-1/
Size: 2.58 MB
Stars: 254
Watchers: 9
Forks: 28
Open Issues: 0
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project

awesome-offensive-rust - Matrix-rs - Rusty Hypervisor - Windows Blue Pill Type-2 Hypervisor in Rust (Codename: Matrix) (Projects)
README

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

![License](https://img.shields.io/github/license/memN0ps/hypervisor-rs)

![Issues](https://img.shields.io/github/issues/memN0ps/hypervisor-rs)

![Forks](https://img.shields.io/github/forks/memN0ps/hypervisor-rs)

![Stars](https://img.shields.io/github/stars/memN0ps/hypervisor-rs)

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](https://github.com/memN0ps/illusion-rs) (Windows UEFI Blue Pill Type-1 Hypervisor in Rust) is more stable, supports more features, and is overall better designed. The [**Matrix** hypervisor](https://github.com/memN0ps/matrix-rs) (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

- :white_check_mark: **Extended Page Tables (EPT)**: Support for Memory Type Range Registers (MTRR).

- :white_check_mark: **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`.

- :white_check_mark: **Hidden Kernel Inline Hooks**: PatchGuard-compatible breakpoint (`int3`) hooks.

- :white_check_mark: **Hidden System Call (Syscall) Hooks**: PatchGuard-compatible hooks for System Service Descriptor Table (SSDT) function entries.

- :white_check_mark: **Isolation and Security**: Custom implementations of the Global Descriptor Table (GDT), Interrupt Descriptor Table (IDT), and Page Tables to improve the security and isolation of the hypervisor. [Credits to @namazso](https://www.unknowncheats.me/forum/2779560-post4.html) for raising awareness.

## Supported Hardware

- :white_check_mark: Intel processors with VT-x and Extended Page Tables (EPT) support.

- :x: AMD processors with AMD-V (SVM) and Nested Page Tables (NPT) support.

## Supported Platforms

- :white_check_mark: Windows 10 - Windows 11, x64 only.

## Installation

1. Install Rust from [here](https://www.rust-lang.org/tools/install).

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](https://docs.microsoft.com/en-us/windows-hardware/drivers/download-the-wdk).

6. Set the `WDKContentRoot` environment variable to point to your WDK installation path, If it hasn't been set automatically during the WDK installation:

```powershell

[System.Environment]::SetEnvironmentVariable("WDKContentRoot", "C:\Program Files (x86)\Windows Kits\10", [System.EnvironmentVariableTarget]::User)

```

## 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](https://learn.microsoft.com/en-us/windows-hardware/drivers/devtest/bcdedit--bootdebug).

```powershell

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:

```powershell

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

sc.exe query matrix

sc.exe start matrix

```

## Usage

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 the VMware serial port for debugging.

![VMware Serial Port Settings](./images/vmware_serial.png)

**Figure 1: VMware Serial Port Settings**

   Ensure that `"Virtualize Intel VT-x/EPT or AMD-V/RVI"` is enabled and `"Virtualize IOMMU (IO memory management unit)"` is enabled.

![VMware Processors Settings](./images/vmware_processors.png)

**Figure 2: VMware Processors Settings**

3. **Copy the Driver**

   Copy the `matrix.sys` driver to the `C:\Windows\System32\drivers` directory.

4. **VMware Serial Port Debugging**

   Execute the PowerShell script in the Serial Port Debugging section to open the serial port.

5. **Load the Hypervisor**

   Use the `load.ps1` PowerShell script shown in the Service Management section to create and start the hypervisor service.

![Load Hypervisor](./images/hypervisor_load.png)

**Figure 3: Load Hypervisor**

### PoC

![Hypervisor PoC Setup](./images/hypervisor_poc_setup.png)

**Figure 4: Logs and Windbg PoC Setup**

![Hypervisor PoC Execute](./images/hypervisor_poc_execute.png)

**Figure 5: Logs and Windbg PoC Execute**

## 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)](https://github.com/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](https://revers.engineering/7-days-to-virtualization-a-series-on-hypervisor-development/).

  - [MMU Virtualization via Intel EPT](https://revers.engineering/mmu-virtualization-via-intel-ept-index/).

- **[Satoshi Tanda (@tandasat)](https://github.com/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](https://tandasat.github.io/Hypervisor_Development_for_Security_Researchers.html).

  - [Hypervisor 101 in Rust](https://github.com/tandasat/Hypervisor-101-in-Rust).

  - Additional Projects: [Hello-VT-rp](https://github.com/tandasat/Hello-VT-rp), [DdiMon](https://github.com/tandasat/DdiMon), [HyperPlatform](https://github.com/tandasat/HyperPlatform), [MiniVisorPkg](https://github.com/tandasat/MiniVisorPkg).

- **[Jess (@jessiep_)](https://github.com/Intege-rs)**: 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)](https://github.com/drew-gpf)**: For his help, guidance, and quick responses to my questions in various aspects of hypervisor development.

- **[Sina Karvandi (@Intel80x86)](https://github.com/SinaKarvandi)**: For his detailed free Hypervisor From Scratch series:

  - [Tutorial Series](https://rayanfam.com/tutorials/).

  - [GitHub Repository](https://github.com/SinaKarvandi/Hypervisor-From-Scratch/).

- **[Matthias (@not-matthias)](https://github.com/not-matthias)**: For his impactful work on the [amd_hypervisor](https://github.com/not-matthias/amd_hypervisor) project, which greatly inspired and influenced this research.

- **[Nick Peterson (@everdox)](https://github.com/everdox)** and **[Aidan Khoury (@ajkhoury)](https://github.com/ajkhoury)**: For their insightful explorations into hypervisor introspection and syscall hooking:

  - [Patchguard: Hypervisor Based Introspection [P1]](https://revers.engineering/patchguard-detection-of-hypervisor-based-instrospection-p1/).

  - [Patchguard: Hypervisor Based Introspection [P2]](https://revers.engineering/patchguard-detection-of-hypervisor-based-instrospection-p2/).

  - [Syscall Hooking Via Extended Feature Enable Register (EFER)](https://revers.engineering/syscall-hooking-via-extended-feature-enable-register-efer/).

#### Community and Technical Resources

- **[Secret Club](https://github.com/thesecretclub)**: Insights into anti-cheat systems and hypervisor detection, which also inspired this project:

  - [System emulation detection](https://secret.club/2020/04/13/how-anti-cheats-detect-system-emulation.html) by [@Daax](https://github.com/daaximus), [@iPower](https://github.com/iPower), [@ajkhoury](https://github.com/ajkhoury), [@drew](https://github.com/drew-gpf).

  - [BattlEye hypervisor detection](https://secret.club/2020/01/12/battleye-hypervisor-detection.html) by [@vmcall](https://github.com/vmcall), [@Daax](https://github.com/daaximus).

- **Other Essential Resources**:

  - [Intel's Software Developer's Manual](https://www.intel.com/).

  - [Maurice Heumann's (@momo5502)](https://github.com/momo5502/) [Detecting Hypervisor-Assisted Hooking](https://momo5502.com/posts/2022-05-02-detecting-hypervisor-assisted-hooking/).

  - [Guided Hacking's](https://guidedhacking.com/) [x64 Virtual Address Translation](https://www.youtube.com/watch?v=W3o5jYHMh8s) on YouTube.

  - [UnKnoWnCheaTs](https://unknowncheats.me/) [forum post](https://www.unknowncheats.me/forum/2779560-post4.html) by [@namazso](https://github.com/namazso).

  - [RVM1.5](https://github.com/rcore-os/RVM1.5), [Barbervisor](https://github.com/Cisco-Talos/Barbervisor), [rustyvisor](https://github.com/iankronquist/rustyvisor), [orange_slice](https://github.com/gamozolabs/orange_slice), [mythril](https://github.com/mythril-hypervisor/mythril), [uhyve](https://github.com/hermit-os/uhyve), [maystorm](https://github.com/neri/maystorm).

  - [AMD-V Hypervisor Development by Back Engineering](https://blog.back.engineering/04/08/2022), [bluepill by @_xeroxz](https://git.back.engineering/_xeroxz/bluepill).

  - [hvpp by @wbenny](https://github.com/wbenny/hvpp).

  - [HyperHide by @Air14](https://github.com/Air14/HyperHide).

  - [How AetherVisor works under the hood by M3ll0wN1ght](https://mellownight.github.io/AetherVisor).

  - [Rust library to use x86 (amd64) specific functionality and registers (x86 crate for Rust)](https://github.com/gz/rust-x86).

  - [DarthTon's HyperBone](https://github.com/DarthTon/HyperBone) (based on the legendary [Alex Ionescu's](https://github.com/ionescu007/SimpleVisor) version) on [UnknownCheats](https://www.unknowncheats.me/forum/c-and-c-/173560-hyperbone-windows-hypervisor.html).

  - [Joanna Rutkowska: Pioneering the Blue Pill Hypervisor Concept, one of the earliest proofs of concept](https://blog.invisiblethings.org/2006/06/22/introducing-blue-pill.html).

#### Helpers and Collaborators

Special thanks to:

- [Daax](https://revers.engineering/).

- [Satoshi Tanda (@tandasat)](https://github.com/tandasat).

- [Drew (@drew)](https://github.com/drew-gpf).

- [iPower (@iPower)](https://github.com/iPower).

- [Namazso (@namazso)](https://github.com/namazso).

- [Jess (@jessiep_)](https://github.com/Intege-rs).

- [Matthias @not-matthias](https://github.com/not-matthias/).

- [@felix-rs / @joshuа](https://github.com/felix-rs).

- [Ryan McCrystal / @rmccrystal](https://github.com/rmccrystal).

- [Jim Colerick (@vmprotect)](https://github.com/thug-shaker).

## License

This project is licensed under the MIT License. For more information, see the [MIT License details](./LICENSE).