lightweight, extendable hypervisor written in C++ with support for Windows and Linux
C++ CMake C Assembly Other
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.

README.md

Bareflank


GitHub Version Build Status Build Status Coverage Status Codacy Status CII Best Practices Join the chat at https://gitter.im/Bareflank-hypervisor/Lobby

Description

The Bareflank Hypervisor is an open source, hypervisor Software Development Toolkit (SDK), led by Assured Information Security, Inc. (AIS), that provides a set of APIs needed to rapidly prototype and create new hypervisors. To ease development, Bareflank is written in C/C++, and includes support for C++ exceptions, JSON, the GSL and the C++ Standard Template Library (STL).

The Bareflank Hypervisor uses a layered, modular approach.

  • hypervisor: provides a minimal, hypervisor implementation, the build system, and architecture specific intrinsics.
  • extended_apis: adds hardware virtualization extension APIs to the hypervisor.
  • hyperkernel: adds guest support APIs to the hypervisor.
  • pv_interface: adds a hypercall API/ABI and PV interface to the hypervisor.

To support Bareflank's design approach, the hypervisor is licensed under the GNU Lesser General Public License v2.1 (LGPL), specifically enabling users of the project to both contribute back to the project, but also create proprietary extensions of the VMM if so desired.

In addition, the project comes complete with a set of unit tests to validate that the provided SDK works as expected. These tests are checked for completeness using Codecov. Furthermore, Travis CI has been setup to test source code formatting via Astyle, and static / dynamic analysis via Clang Tidy, Codacy, and Google's Sanitizers. Finally, we adhere to the CII Best Practices, the High Integrity C++ Guidelines and the C++ Core Guidelines including support for the Guideline Support Library.

Currently we have support for the following 64bit host operating systems on Intel Sandy Bridge and above hardware:

  • Arch Linux
  • Ubuntu 17.10+
  • Windows 10
  • Windows 7
  • UEFI (64bit)

In the future, we would also like to support:

  • macOS
  • BSD
  • ARM64 (currently under development)

Motivation

Most people think that hypervisors are meant to virtualize servers and provide a means to run Windows on a Mac, but there is a whole field of research where hypervisors are used, and in some cases even without guest virtual machines. Since a hypervisor is capable of controlling the host OS running underneath it (so called "ring -1"), hypervisors have been used for introspection, reverse engineering, anti-virus, containerization, diversity, and even architectural research like the MoRE hypervisor. All of these use cases start the same way, by spending months standing up the hypervisor itself before you can start working on your actual project. Existing open source hypervisors are burdened with legacy support and unnecessary complexity that make them painful to work with when conducting hypervisor research.

Links

Bareflank Hypervisor Website
Bareflank Hypervisor API Documentation

Demo

Checkout the latest demo for how to compile, use and extend the Bareflank Hypervisor

Bareflank Demonstration Video

Additional Videos

CppCon 2017 CppCon 2016

Dependencies

Although Bareflank can be made to run on most systems, the following are the supported platforms and their dependencies:

Arch Linux:

sudo pacman -S linux-headers nasm cmake base-devel clang

Ubuntu 17.10 (or Higher):

sudo apt-get install git build-essential linux-headers-$(uname -r) nasm clang cmake libelf-dev

Windows (Cygwin):

To install Cygwin, simply install using all default settings, and then copy setup-x86_64.exe to C:\cygwin64\bin. From there, open a Cygwin terminal and run the following:

setup-x86_64.exe -q -P git,make,gcc-core,gcc-g++,nasm,clang,clang++,cmake,python,gettext,bash-completion
git config --global core.autocrlf false

After installing the the above packages and disabling auto CRLF (which breaks bash scripts) you must enable test signing mode. This can be done from a command prompt with admin privileges:

bcdedit.exe /set testsigning ON
<reboot>

UEFI:

TBD

Compilation Instructions

To compile with default settings for your host environment, run the following commands:

git clone https://github.com/bareflank/hypervisor.git
mkdir build; cd build
cmake ../hypervisor
make -j<# cores + 1>

For more detailed build instructions, see the detailed build instructions. For instructions on building and creating Bareflank extensions, see the extension build instructions

Usage Instructions

To use the hypervisor, run the following commands:

make driver_quick
make quick

to get status information, use the following:

make status
make dump

to reverse this:

make unload
make driver_unload

to clean up:

make distclean

Serial Instructions

On Windows, serial output might not work, and on systems (e.g. Intel NUC), 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"

Cygwin SSH Instructions

You might find it useful to setup SSH if you are using Cygwin. The instructions for setting up SSH on Cygwin are as follows:

setup-x86_64.exe -q -P getent,cygrunsrv,openssl,openssh

ssh-host-config -y
<password>
<password>

net start sshd
netsh advfirewall firewall add rule name='SSH Port' dir=in action=allow protocol=TCP localport=22

Additional Layers

*** WARNING ***
The master branch is our development branch and should be considered unstable. It is possible these additional projects might not compile with master. If you need a stable branch that works with these repos, please use a tagged release.

Since the main, hypervisor repo only provides the a minimal implementation, we have created other repositories that extend Bareflank to provide additional capabilities that you might find useful.

Extended APIs:
https://github.com/Bareflank/extended_apis

Hyperkernel:
https://github.com/Bareflank/hyperkernel

PV Interface:
https://github.com/Bareflank/pv_interface

Example Extensions

*** WARNING ***
The master branch is our development branch and should be considered unstable. It is possible these additional projects might not compile with master. If you need a stable branch that works with these repos, please use a tagged release.

To provide examples of how you might extend Bareflank to provide your own custom functionality, we have provided a couple of examples:

Enable VPID:
https://github.com/Bareflank/hypervisor_example_vpid

CPUID Count:
https://github.com/Bareflank/hypervisor_example_cpuidcount

MSR Bitmap:
https://github.com/Bareflank/hypervisor_example_msr_bitmap

Extended APIs EPT Hook:
https://github.com/Bareflank/extended_apis_example_hook

License

The Bareflank Hypervisor is licensed under the GNU Lesser General Public License v2.1 (LGPL). The Windows and EFI drivers are licensed under the MIT License. The Linux driver is licensed under the General Public License v2.0 (GPL) License.

Related

If you’re interested in Bareflank, you might also be interested in the following hypervisor projects:

MoRE:
https://github.com/ainfosec/MoRE

SimpleVisor:
https://github.com/ionescu007/SimpleVisor

HyperPlatform:
https://github.com/tandasat/HyperPlatform