Home

Awesome

<img src="https://github.com/Bareflank/MicroV/raw/master/.github/images/microv_logo.png" alt="microv-logo"/>

Description

warning: MicroV is currently a work in progress. If you need support now, please see the Mono branch until MicroV is more complete which is expected to be some time Q1 of 2022.

The MicroV Hypervisor is an open source, micro-hypervisor led by Assured Information Security, Inc., designed specifically to run micro VMs (i.e., tiny virtual machines that require little or no emulation).

<img src="https://github.com/Bareflank/MicroV/raw/master/.github/images/high_level.png" alt="highlevel"/>

Advantages:

Unlike existing hypervisors, MicroV's design has some unique advantages including: <img src="https://github.com/Bareflank/MicroV/raw/master/.github/images/cross_platform.png" alt="cross-platform" align="right" height="300" />

Disadvantages:

No design is without its disadvantages:

Quick start

TBD

Interested In Working For AIS?

Check out our Can You Hack It?® challenge and test your skills! Submit your score to show us what you’ve got. We have offices across the country and offer competitive pay and outstanding benefits. Join a team that is not only committed to the future of cyberspace, but to our employee’s success as well.

<p align="center"> <a href="https://www.ainfosec.com/"> <img src="https://github.com/Bareflank/MicroV/raw/master/.github/images/ais.png" alt="cross-platform" height="100" /> </a> </p>

Demo

TBD

Build Requirements

Currently, MicroV only supports the Clang/LLVM 10+ compiler. This, however, ensures that MicroV can be natively compiled on Windows including support for cross-compiling. Support for other C++20 compilers can be added if needed, just let us know if that is something you need.

Windows

To compile the BSL on Windows, you must first disable UEFI SecureBoot and enable test signing mode. Note that this might require you to reinstall Windows (you have been warned). This can be done from a command prompt with admin privileges:

bcdedit.exe /set testsigning ON
<reboot>

Next, install the following:

Visual Studio is needed as it contains Windows specific libraries that are needed during compilation. Instead of using the Clang/LLVM project that natively ships with Visual Studio, we use the standard Clang/LLVM binaries provided by the LLVM project which ensures we get all of the tools including LLD, Clang Tidy and Clang Format. Also note that you must put Ninja somewhere in your path (we usually drop into CMake's bin folder). Finally, make sure you follow all of the instructions when installing the WDK. These instructions change frequently, and each step must be installed correctly and in the order provided by the instructions. Skipping a step, or installing a package in the wrong order will result in a WDK installation that doesn't work.

To compile the BSL, we are going to use Bash. There are many ways to start Bash including opening a CMD prompt and typing "bash". Once running bash, make sure you add the following to your PATH:

For example, in your .bashrc, you might add the following (depending on where Visual Studio put these files):

export PATH="/c/Program Files (x86)/Microsoft Visual Studio/2019/Community/MSBuild/Current/Bin:/c/Program Files (x86)/Windows Kits/10/Tools/x64:/c/Program Files (x86)/Windows Kits/10/bin/10.0.19041.0/x64:$PATH"

Finally, run the following from Bash:

git clone https://github.com/bareflank/microv
mkdir microv/build && cd microv/build
cmake ..
ninja info
ninja

Ubuntu Linux

To compile the BSL on Ubuntu (20.04 or higher) you must first install the following dependencies:

sudo apt-get install -y clang cmake lld

To compile the BSL, use the following:

git clone https://github.com/bareflank/microv
mkdir microv/build && cd microv/build
cmake ..
make info
make

UEFI

TBD

Usage Instructions

MicroV is designed to use existing KVM userspace software to execute guest virtual machines from the root VM. To execute our integration tests that leverage the KVM API, do the following:

First, you need to place your current OS into a VM called the root VM. This is done by hoisting your current OS into a VM (often times called a VMX rootkit, but in our case, this is defensive, not offensive). To do this run the following:

make loader_quick
make -j<num cores>
make start

You can run the following to verify that your OS is not in the root VM:

make dump

And you should see something like:

 ___                __ _           _
| _ ) __ _ _ _ ___ / _| |__ _ _ _ | |__
| _ \/ _` | '_/ -_)  _| / _` | ' \| / /
|___/\__,_|_| \___|_| |_\__,_|_||_|_\_\

Please give us a star on: https://github.com/Bareflank/hypervisor
==================================================================

DEBUG [0000:0000:0000:0000:0000:US]: root OS had been demoted to vm 0x0000 on pp 0x0000
DEBUG [0000:0000:0001:0001:0001:US]: root OS had been demoted to vm 0x0000 on pp 0x0001
DEBUG [0000:0000:0002:0002:0002:US]: root OS had been demoted to vm 0x0000 on pp 0x0002
DEBUG [0000:0000:0003:0003:0003:US]: root OS had been demoted to vm 0x0000 on pp 0x0003
DEBUG [0000:0000:0004:0004:0004:US]: root OS had been demoted to vm 0x0000 on pp 0x0004

To be able to run KVM APIs, you must load the shim driver, which acts like KVM. To do this, run:

make shim_quick

You can only run the shim driver AFTER MicroV has started. Otherwise you will get a failure. If you look at dmesg, you will see that the shim driver will have complained that MicroV's is not running, which likely means that you need to rerun make start.

If make start fails, it means that Bareflank's loader is not running, which is why we can make loader_quick.

From here, you can run whatever integration test you want. For example:

make kvm_create_vm
make kvm_create_vcpu

You can see the results of the integration test by either looking at the resulting console output, or looking at what MicroV's debug buffer contains by using make dump.

You can also run MicroV's integration tests as well. These are tests designed to talk directly to MicroV instead of using the KVM APIs. For example:

make mv_handle_op_open_handle
make mv_handle_op_close_handle

You do not need the shim driver to run these integration tests, and yes, you can use the MicroV ABIs to write your own VMM without the need for the KVM shim, or any of the KVM APIs if you would like. This removes the need for the additional kernel calls and overhead of the shim driver, but requires that you write your own VMM software as things like QEMU and rust-vmm will not work without modifications to talk directly to MicroV instead of to MicroV via the KVM APIs.

Resources

Join the chat

MicroV provides a ton of useful resources to learn how to use the library including:

If you have any questions, bugs, or feature requests, please feel free to ask on any of the following:

If you would like to help:

Testing

Build Status codecov

MicroV leverages the following tools to ensure the highest possible code quality. Each pull request undergoes the following rigorous testing and review:

Serial Instructions

On Windows, serial output might not work, and on some systems (e.g. Intel NUC), the default Windows serial device may prevent Bareflank from starting at all. If this is the case, disable the default serial device using the following:

reg add "HKEY_LOCAL_MACHINE\System\CurrentControlSet\Services\Serial" /f /v "start" /t REG_DWORD /d "4"

License

The Bareflank Hypervisor is licensed under the MIT License.