admin/MiniVisorPkg
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Fix markdown style errors

Browse Source
This commit is contained in:
Satoshi Tanda
2020-02-25 16:48:01 -08:00
parent cb07599011
commit 3245a658a7
2 changed files with 33 additions and 58 deletions
Download Patch File Download Diff File Expand all files Collapse all files

60
Docs/Building_and_Debugging.md
View File

@@ -3,15 +3,13 @@ Building and Debugging
This document provides step-by-step instructions to build and debug MiniVisor for both UEFI and Windows driver configurations.
Common Build Prerequisites
---------------------------
To build MiniVisor, the followings are required.
- [Visual Studio Community 2019](https://www.visualstudio.com/downloads/)
- [Windows Software Development Kit (SDK) for Windows 10 ](https://developer.microsoft.com/en-us/windows/downloads/windows-10-sdk) 10.0.18362 or later
- [Windows Driver Kit (WDK) for Windows 10](https://developer.microsoft.com/en-us/windows/hardware/windows-driver-kit) 10.0.18362 or later
* [Visual Studio Community 2019](https://www.visualstudio.com/downloads/)
* [Windows Software Development Kit (SDK) for Windows 10](https://developer.microsoft.*om/en-us/windows/downloads/windows-10-sdk) 10.0.18362 or later
* [Windows Driver Kit (WDK) for Windows 10](https://developer.microsoft.com/en-us/windows/hardware/windows-driver-kit) 10.0.18362 or later
Terms
------
@@ -20,7 +18,6 @@ In this document, the "host" system refers to the system that builds MiniVisor a
The "target" system refers to the system that loads MiniVisor". This can be a separate bare-metal machine or a virtual machine running inside the host system.
UEFI: Building the Driver
--------------------------
@@ -89,16 +86,15 @@ The below instructions are all to be done on the host system.
(You should see multiple entries under C:\edk2\Build\)
```
UEFI: Preparing the Target System
----------------------------------
The target system must be a UEFI-based x64 system without Secure Boot and be able to boot one of the supported operating systems.
In the case of virtual machines, only VMware Workstation is supported. For the other possible configurations, see the below sections. With VMware Workstation, make sure that
- `Virtualize Intel VT-x/EPT or AMD-V/RVI` is checked,
- in the `Advanced` section, `UEFI` is selected, and
- `Enable secure boot` is unchecked.
* `Virtualize Intel VT-x/EPT or AMD-V/RVI` is checked,
* in the `Advanced` section, `UEFI` is selected, and
* `Enable secure boot` is unchecked.
![Building_and_Testing_VMwareWS_VTx.png](Resources/Building_and_Testing_VMwareWS_VTx.png)
@@ -107,7 +103,6 @@ In the case of virtual machines, only VMware Workstation is supported. For the o
In the case of bare-metal, some UEFI-based systems enable the "legacy BIOS" mode to boot the operating system. This mode is essentially equivalent to using old fashioned BIOS and not supported by this project. Changing the mode is possible in the UEFI settings but will render the existing operating system unbootable. Here is the example with Dell UEFI settings configured to boot the system with the UEFI mode.
![Building_and_Testing_BootMode.jpg](Resources/Building_and_Testing_BootMode.jpg)
UEFI: Loading the Driver
-------------------------
@@ -155,7 +150,7 @@ In this instruction, we will boot the target system into the UEFI shell, load Mi
5. Select the filesystem
1. Run `map` command to list the available filesystems. Identify one that has `USB` in the path. We assume that is `fs1:` in this instruction.
- If not found, USB might not be recognized. Make sure it is accessible from the target system and run `map -r` to refresh the list.
* If not found, USB might not be recognized. Make sure it is accessible from the target system and run `map -r` to refresh the list.
2. Run `fs1:` to move to the filesystem.
3. Run `ls` command and make sure `MiniVisorDxe.efi` exists.
@@ -177,7 +172,6 @@ In this instruction, we will boot the target system into the UEFI shell, load Mi
Unloading the driver after operating system boot is unsupported.
UEFI: Building the Project on Visual Studio
--------------------------------------------
@@ -189,7 +183,6 @@ __Once the project is built with EDK2__, you may build it on Visual Studio with
Visual Studio will produce output as `C:\edk2\MiniVisorPkg\Builds\x64\UEFI\MiniVisorDxe.efi`. This binary is always compiled for debugging without optimization.
UEFI: Build Customization
--------------------------
@@ -209,7 +202,6 @@ UEFI: Build Customization
For more details of logging with serial output, see the below section.
UEFI & Windows: Testing Existence of MiniVisor
-----------------------------------------------
@@ -217,8 +209,8 @@ One can verify that MiniVisor has virtualized all processors by executing the ac
This program can be compiled into both for Windows and Linux.
- For Windows, open `MiniVisorPkg\Tests\CheckHvVendor\CheckHvVendor.sln` with Visual Studio and compile it with `x64` + `Release` configuration.
- For Linux, compile `MiniVisorPkg\Tests\CheckHvVendor\CheckHvVendor\CheckHvVendor.cpp` with `g++`.
* For Windows, open `MiniVisorPkg\Tests\CheckHvVendor\CheckHvVendor.sln` with Visual Studio and compile it with `x64` + `Release` configuration.
* For Linux, compile `MiniVisorPkg\Tests\CheckHvVendor\CheckHvVendor\CheckHvVendor.cpp` with `g++`.
Once compiled, deploy the executable onto the target system and run from the terminal. The output should contain `MiniVisor` if MiniVisor is successfully installed.
@@ -234,7 +226,6 @@ Executing CPUID(0x40000000) on CPU 3
Result: MiniVisor
```
UEFI: Configuring VMware Virtual Machine for Debugging
-------------------------------------------------------
@@ -275,7 +266,6 @@ It is recommended to configure all of them for debugging the UEFI driver.
Here is an example output, showing that triple fault occurred.
![Building_and_Testing_VMwareWS_FullLogging_Sample.jpg](Resources/Building_and_Testing_VMwareWS_FullLogging_Sample.jpg)
UEFI: Viewing Serial Output From the Virtual Machine
-----------------------------------------------------
@@ -300,7 +290,6 @@ To do so,
This also displays unhandled exception information that occurred during UEFI boot-time if possible. This is extremely useful since a debugger (mentioned below) is unable to catch and diagnose them.
![Building_and_Testing_PuTTY_Exception_with_VMware.png](Resources/Building_and_Testing_PuTTY_Exception_with_VMware.png)
UEFI: Debugging the Driver with a Debugger
-------------------------------------------
@@ -324,43 +313,40 @@ Debugging the UEFI driver is not easy due to the fact that source-level debuggin
See "Debugging a standalone module loaded in a UEFI shell" section of the accompanying manual if interested.
UEFI: Testing with Other Virtualization Platform
-------------------------------------------------
VMware Workstation is the only supported virtualization platform. However, one can choose to try on the other system with some limitations. This section describes limitations on the other vitalization platforms for the purpose of developing and testing a UEFI driver hypervisor.
- KVM + QEMU on Linux
* KVM + QEMU on Linux
This is the most viable alternative, and even in some cases more useful than VMware Workstation.
Pros:
- No software cost.
- Possible to inspect the system even on an unhandled exception. This is not possible with VMware Workstation as it terminates immediately.
- Functional with a single processor configuration.
* No software cost.
* Possible to inspect the system even on an unhandled exception. This is not possible with VMware Workstation as it terminates immediately.
* Functional with a single processor configuration.
Cons:
- Unable to test multi-processor configurations. Boot hangs once VMXON is executed on an application processor.
- A Linux host is required.
* Unable to test multi-processor configurations. Boot hangs once VMXON is executed on an application processor.
* A Linux host is required.
- Hyper-V
* Hyper-V
Hardly usable due to lack of multi-processor protocol support and underneath Hyper-V forwarding VM-exit despite those are not enabled.
- VirtualBox
* VirtualBox
Not usable due to lack of nested EPT support and buggy nesting implementation.
- QEMU on Windows
* QEMU on Windows
Not usable due to lack of nested virtualization support.
- Bochs
* Bochs
Not usable due to lack of UEFI support.
UEFI: Testing with Single-board Computers
------------------------------------------
@@ -368,13 +354,11 @@ Testing against physical devices is MUST. While testing on VMware can uncover ma
The authors recommend purchasing an AMD64 single-board computer with a serial port and test against it. One of such devices is [MinnowBoard Turbot](https://store.netgate.com/Turbot4.aspx). We do not go into details of how to set it up for debugging as it is device-specific.
UEFI: Testing with Regular Devices
-----------------------------------
Testing against regular laptops and desktops is another way to find bugs. This does not require purchasing and configuring a single board computer, but diagnosing issues tends to be significantly harder due to not being able to use serial logging.
UEFI: Debugging Tricks
-----------------------
@@ -382,16 +366,14 @@ UEFI: Debugging Tricks
2. If you use IDA Pro for debugging, run `Builds\Platform\EFI\locate_image_base.py` and follow the instructions displayed after attaching to the target.
3. Start with a single processor. With a bare-metal, where its processor count cannot be reduced, just skip entering the non-root mode on application processors.
Windows: Building the Driver
-----------------------------
Building the Windows driver can be fully done on Visual Studio with the following stesp:
Building the Windows driver can be fully done on Visual Studio with the following steps:
1. Open `MiniVisorPkg\Builds\MiniVisor.sln` with Visual Studio.
2. Select `Debug` or `Release` build configuration.
3. Run `Build Solution`.
Windows: Preparing the Target System
-------------------------------------
@@ -412,7 +394,6 @@ Finally, run the following command to create the service to load the driver on t
> sc.exe create MiniVisor type= kernel binPath= C:\Users\user\Desktop\MiniVisor.sys
```
Windows: Loading the Driver
----------------------------
@@ -426,7 +407,6 @@ Similarly, the below command will unload the driver.
> sc.exe stop MiniVisor
```
Windows: Debugging the Driver with a Debugger
----------------------------------------------

31
README.md
View File

@@ -7,19 +7,17 @@ This is a research hypervisor written as a UEFI and Windows driver for the educa
This MiniVisor, as a UEFI driver, provides the ability to inspect system activities even before the operating system boots, while as a Windows driver, allows developers to debug it with familiar tools like WinDbg.
Showcase
---------
* Loading the hypervisor from the UEFI shell.
![Readme_Showcase1.jpg](Docs/Resources/Readme_Showcase1.jpg)
![Readme_Showcase1.jpg](Docs/Resources/Readme_Showcase1.jpg)
* Logging boot activities and interacting with the guest.
![Readme_Showcase2.jpg](Docs/Resources/Readme_Showcase2.jpg)
![Readme_Showcase2.jpg](Docs/Resources/Readme_Showcase2.jpg)
* Booting Ubuntu on a bare-metal.
![Readme_Showcase3.jpg](Docs/Resources/Readme_Showcase3.jpg)
![Readme_Showcase3.jpg](Docs/Resources/Readme_Showcase3.jpg)
Motivation
-----------
@@ -30,27 +28,25 @@ There are numerous open source hypervisors with small and easy-to-study implemen
Given the universality of UEFI systems on the AMD64 ecosystem and the unique ability to monitor, attack and protect the system throughout operating system startup on bare-metal systems, the authors believe that having the understanding and being able to develop this type of hypervisors are valuable for research.
System Requirements
--------------------
Common Requirements:
- Intel VT-x and EPT supported processors
* Intel VT-x and EPT supported processors
Requirements for the UEFI driver:
- UEFI-based system
- 64bit Windows 10, IoT Core, or Ubuntu to boot
* UEFI-based system
* 64bit Windows 10, IoT Core, or Ubuntu to boot
Requirements for the Windows driver:
- 64bit Windows 7 and 10
* 64bit Windows 7 and 10
See [Building and Debugging](Docs/Building_and_Debugging.md) for testing.
Advantages and Use Cases
-------------------------
While this project does not implement any immediately useful features, UEFI-based hypervisors have multiple advantages over Windows driver-based ones and can implement unique features.
While this project does not implement or designed for any immediately useful features, UEFI-based hypervisors have multiple advantages over Windows driver-based ones and can implement unique features.
* No need of disabling Hyper-V (Virtualization Based Security) to run the custom hypervisor
* No need of enabling the test-signing mode
@@ -59,13 +55,12 @@ While this project does not implement any immediately useful features, UEFI-base
* Detecting bootkit and early system modification
* Implementing operating system agnostic solutions
Acknowledgments
----------------
The authors thank for creators and maintainers of the following projects:
- [Bareflank](https://github.com/Bareflank/hypervisor) and [STM](https://github.com/jyao1/STM) -- for publishing UEFI-base hypervisors with the relatively small codebase.
- [zpp_hypervisor](https://github.com/eyalz800/zpp_hypervisor) -- for making me realize that writing UEFI-based hypervisors is viable.
- [EfiGuard](https://github.com/Mattiwatti/EfiGuard) -- for clean codebase and rich documentation for UEFI development newbies.
- [hvpp](https://github.com/wbenny/hvpp) -- for few techniques required for the UEFI environment.
- [ia32-doc](https://github.com/wbenny/ia32-doc) -- for saving me from defining thousands of constants and structures by hand.
* [Bareflank](https://github.com/Bareflank/hypervisor) and [STM](https://github.comjyao1/STM) -- for publishing UEFI-base hypervisors with the relatively small codebase.
* [zpp_hypervisor](https://github.com/eyalz800/zpp_hypervisor) -- for making me realize that writing UEFI-based hypervisors is viable.
* [EfiGuard](https://github.com/Mattiwatti/EfiGuard) -- for clean codebase and rich documentation for UEFI development newbies.
* [hvpp](https://github.com/wbenny/hvpp) -- for few techniques required for the UEFI environment.
* [ia32-doc](https://github.com/wbenny/ia32-doc) -- for saving me from defining thousands of constants and structures by hand.