Hypervisor

Description

The Bareflank Hypervisor is an open source hypervisor Software Development Toolkit (SDK) for Rust and C++, led by Assured Information Security, Inc. (AIS), that provides the tools needed to rapidly prototype and create your own hypervisor on 64bit versions of Intel and AMD (ARMv8 CPUs, RISC-V and PowerPC also planned). The Bareflank SDK is intended for instructional/research purposes as it only provides enough virtualization support to start/stop a hypervisor. Bareflank can also be used as the foundation to create your own, fully functional hypervisor as it uses the MIT license, includes 100% unit test coverage and compliance for AUTOSAR. If you are looking for a complete hypervisor (and not an SDK), please see MicroV. If you are looking for a minimal SDK for education or to perform research, this is the project for you. If you are simply looking for a reference hypervisor, please see SimpleVisor.

Bareflank uses a layered, modular approach, that lets you pick just how much complexity you need in your project when creating your own custom hypervisor:

• BSL: provides a header-only, AUTOSAR compliant implementation of a subset of the C++ Standard Library, used to implement Bareflank's C++ components ensuring Bareflank and projects built using Bareflank can support critical systems applications.
• LLVM: provides our custom implementation of the LLVM Clang-Tidy static analysis tool to ensure compliance with AUTOSAR.
• PAL: provides auto-generated intrinsics APIs for Intel, AMD and ARM on any combination of OS and language.
• hypervisor: provides the base SDK including the loader, the Bareflank microkernel and support applications. Although this repo is labeled "hypervisor", this repo only provides the base scaffolding for creating your own hypervisor. If you are in education or performing research and do not want to deal with the complexity of a fully functional hypervisor, this repo would be your starting point. By itself, the code in this repo only implements enough virtualization to start/stop a hypervisor.
• MicroV: This is the project led by Assured Information Security, Inc. (AIS) the provides a fully functional hypervisor that uses the Bareflank SDK as it's foundation. If you are looking for an actual hypervisor and not an SDK, this is the project you are looking for.

Quick start

Get the latest version of the Bareflank Hypervisor SDK from GitHub:

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

Enjoy:

make driver_quick
make start
make dump
make stop

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/hypervisor/raw/master/.github/images/ais.png" alt="ais" height="100" /> </a> </p>

Demo

Check out the latest demo for how to compile and use the Bareflank Hypervisor on Ubuntu 20.04:

Additional Videos

Check out our YouTube Channel for more great content as well as the following videos at CppCon below:

Important Tips

Before attempting to use Bareflank, please review the following tips as they can make a huge difference in your initial experience:

• Make sure you are running on a system with a serial port. Which serial port Bareflank uses can be configured by setting HYPERVISOR_SERIAL_PORT on x86 or HYPERVISOR_SERIAL_PORTH and HYPERVISOR_SERIAL_PORTL on ARMv8. Cables like these work great. Bareflank uses the following settings (115200 baud rate, 8 data bits, no parity bits, one stop bit).
• Using PCI serial addon cards will not work with UEFI. These cards need to be initialized by the OS, logic that Bareflank does not currently contain. If you are using Bareflank directly from Windows/Linux, these cards will work fine, but from UEFI, you need a serial port provided on the motherboard.
• The serial output might contain a lot of ANSI color codes if you are using a terminal that doesn't support ANSI color. To remove these, configure CMake with -DENABLE_COLOR=OFF.
• Windows Subsystem For Linux v2 is not supported. When this is turned on, Windows runs under HyperV, which currently does not support nested virtualization. Furthermore, if you have ever enabled the WSL2, you must turn HyperV off using bcdedit /set hypervisorlaunchtype off as HyperV will continue to run even if you are no longer using the WSL2.
• When running under Windows, driver issues can be seen by using DbgView. This tool must be run with Admin rights, and you need to turn on kernel output. Once this is working, you will see error messages coming from the Windows driver if needed.
• Nested virtualization (i.e., attempting to run Bareflank inside a VM) is not officially supported, but does work if you know what you are doing. Specifically, a headless version of Linux 20.04 or higher in VMWare works with the proper configuration. VirtualBox does not work due to a lack of supported features and KVM may or may not work (your milage may vary). In general, you should be using real hardware.
• If you need to compile Bareflank on older versions of Linux, it is possible, but you will need to update the build tools manually including LLVM 10+ and CMake 3.13+.

Build Requirements

Currently, the Bareflank hypervisor only supports the Clang/LLVM 10+ compiler. This, however, ensures that the hypervisor 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 (Enable "Desktop development with C++")
• WDK
• LLVM 10+
• CMake 3.13+
• Ninja
• Git

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:

• MSBuild
• devcon
• certmgr

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/hypervisor
mkdir hypervisor/build && cd hypervisor/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/hypervisor
mkdir hypervisor/build && cd hypervisor/build
cmake ..
make info
make

UEFI

To compile for UEFI, simply follow t