{"id":13840147,"url":"https://github.com/Bareflank/MicroV","last_synced_at":"2025-07-11T07:33:08.773Z","repository":{"id":38096956,"uuid":"254735585","full_name":"Bareflank/MicroV","owner":"Bareflank","description":"A micro hypervisor for running micro VMs","archived":false,"fork":false,"pushed_at":"2024-08-22T15:34:20.000Z","size":443064,"stargazers_count":255,"open_issues_count":12,"forks_count":48,"subscribers_count":22,"default_branch":"master","last_synced_at":"2024-11-20T23:01:06.517Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Bareflank.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.md","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":"SUPPORT.md","governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-04-10T21:01:31.000Z","updated_at":"2024-11-20T05:47:03.000Z","dependencies_parsed_at":"2024-11-13T22:13:27.987Z","dependency_job_id":null,"html_url":"https://github.com/Bareflank/MicroV","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Bareflank%2FMicroV","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Bareflank%2FMicroV/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Bareflank%2FMicroV/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Bareflank%2FMicroV/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Bareflank","download_url":"https://codeload.github.com/Bareflank/MicroV/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":225705272,"owners_count":17511256,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-08-04T17:00:42.688Z","updated_at":"2024-11-21T09:31:10.281Z","avatar_url":"https://github.com/Bareflank.png","language":"C++","funding_links":[],"categories":["Research Projects","C++","C++ (225)"],"sub_categories":["AMD"],"readme":"\u003cimg src=\"https://github.com/Bareflank/MicroV/raw/master/.github/images/microv_logo.png\" alt=\"microv-logo\"/\u003e\n\n## Description\n\n**warning**: MicroV is currently a work in progress. If you need support now,\nplease see the [Mono](https://github.com/Bareflank/MicroV/tree/mono) branch until MicroV is more complete which is expected to be some time Q1 of 2022.\n\nThe MicroV Hypervisor is an open source, micro-hypervisor led by [Assured\nInformation Security, Inc.](https://www.ainfosec.com/), designed specifically\nto run micro VMs (i.e., tiny virtual machines that require little or no\nemulation).\n\n\u003cimg src=\"https://github.com/Bareflank/MicroV/raw/master/.github/images/high_level.png\" alt=\"highlevel\"/\u003e\n\n## Advantages:\nUnlike existing hypervisors, MicroV's design has some unique advantages including:\n\u003cimg src=\"https://github.com/Bareflank/MicroV/raw/master/.github/images/cross_platform.png\" alt=\"cross-platform\" align=\"right\" height=\"300\" /\u003e\n- **Cross-Platform Support:** In open source, examples of hypervisors that are\n  capable of supporting guest virtual machines include Xen, KVM, and\n  VirtualBox. The first two only support Linux and BSD and VirtualBox\n  expands this support to Windows and macOS, while sacrificing security. MicroV\n  aims to support as many operating systems as possible including Windows,\n  Linux, UEFI and others while maintaining performance and security. This is\n  accomplished by compiling the hypervisor as a self-contained binary,\n  independent of the root operating system. All of the applications provided\n  by MicroV are written in raw C++ to maximize cross-platform\n  support, and any code that is platform specific, including drivers, is\n  broken into the platform specific logic (which is minimal) and common logic\n  that can be used across all platforms.\n\n- **Disaggregation and Deprivilege:** None of the above mentioned hypervisors\n  have a true focus on a reduced Trusted Computing Base (TCB). Xen comes the\n  closest and has made amazing progress in this direction, but a fully\n  disaggregated and deprivileged hypervisor has yet to be fully realized or\n  supported. MicroV's design starts with a microkernel architecture inside\n  the hypervisor, running most of it's internal logic at lower privilege\n  levels. On Intel, when virtualization is enabled, the CPU is divided into\n  the host and the guest. The hypervisor runs in the host, while the operating\n  system runs in the guest. *Both* the host and the guest have a Ring 0 and\n  Ring 3 privilege level. Monolithic hypervisors like Xen and KVM run most,\n  if not all of the hypervisor in Ring 0 of the host. Typically we call this\n  Ring -1. This picture is far more complicated when you include System\n  Management Mode (SMM) which adds two more Ring 0s, so lets pretend they do\n  not exist for now. The thing is, this is not the only way to construct a\n  hypervisor. Like the operating system in each guest, the hypervisor can use\n  both Ring 0 and Ring 3 in the host, keeping the Ring 0 component as small as\n  possible, while running most of the logic in Ring 3. In some ways, this is\n  how KVM works. The kernel part of the hypervisor in KVM is the entire Linux\n  kernel while VM management and emulation is handled in Ring 3 by QEMU\n  (usually). The obvious problem with this design, besides the lack of\n  cross-platform support is the size of the TCB is huge. MicroV's design\n  leverages the Bareflank microkernel which is a small kernel capable of\n  executing hypervisor extensions in Ring 3 of the host. By itself,\n  Bareflank's microkernel is not capable of executing virtual machines,\n  but instead relies on an extension to provide the meat and potatoes. MicroV,\n  at its most basic level is a Bareflank extension that runs in Ring 3, that\n  provides guest virtual machine support.\n\n- **Performance:** Another important focus of the project is on performance.\n  Existing hypervisors make heavy use of emulation where virtualization could\n  be used instead, Furthermore, Xen and KVM only support Linux and BSD and\n  therefore are not capable of leveraging some of the performance benefits of\n  macOS, Android and even Windows such as scheduling and power management,\n  which becomes evident when attempting to use these hypervisors on laptops and\n  mobile devices. Other approaches to microkernel hypervisors attempt to\n  provide their own device drivers, schedulers and power management algorithms.\n  This limits their ability to widely support hardware, and guarantees a\n  compromised user experience. The operating system that was built for a\n  device should be the operating system that manages the device.\n\n- **Virtual Device Support:** Hypervisors like KVM manage all physical devices\n  in Ring 0 of the host (the most privileged code on the system) using the\n  Linux kernel. This is one way in which Xen is more deprivileged than KVM.\n  Unlike KVM which runs device drivers in Ring 0 of the host, Xen runs device\n  drivers in Ring 0 of the guest (specifically in Dom 0). MicroV aims to\n  take a similar approach to Xen, keeping the code in the host as small as\n  possible, and instead, delegating the guest operating system to manage the\n  physical devices it is given. All virtual device backend drivers run in Ring\n  0 or Ring 3 of the root VM, which is the main virtual machine on the\n  system.\n\n  \u003cimg src=\"https://github.com/Bareflank/MicroV/raw/master/.github/images/scheduler.png\" alt=\"cross-platform\" align=\"right\" height=\"300\" /\u003e\n- **Scheduling:** Although closely related to performance, MicroV leverages a\n  hybrid design, incorporating the design goals of Xen to provide disaggregation\n  and deprivilege while leveraging the scheduling benefits of hypervisor designs\n  like KVM and VirtualBox. Specifically MicroV doesn't include its own scheduler\n  , relying on the root VM's operating system to schedule each VM along with the\n  rest of the critical tasks it must perform. Not only does this reduce the\n  overall complexity and size of MicroV, but it allows MicroV to leverage the\n  advanced schedulers already present in modern operating systems. Since MicroV\n  is designed with cross-platform in mind, this also means that support for\n  custom schedulers is possible, including RTOS schedulers.\n\n- **AUTOSAR Compliance:** Although Xen, KVM and VirtualBox provide various\n  levels of testing, continuous integration and continuous deployment, MicroV\n  aims to take this a step further, providing the highest levels of testing\n  possible to support standards such as ISO 26262. In addition, MicroV was\n  re-engineered from the ground up using the AUTOSAR coding guidelines (MicroV\n  is our third iteration of this hypervisor project). This will not only\n  improve reliability and security, but also enable the use of MicroV in\n  critical system environments were high levels of testing are required such\n  as automotive, medical, space and government.\n\n- **Early Boot and Late Launch Support:** Xen, KVM and VirtualBox support\n  early boot (i.e., the hypervisor starts first during boot) or late launch\n  (i.e., the operating system starts first, and then the hypervisor starts).\n  None of these hypervisors support both.\n\n  \u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://github.com/Bareflank/MicroV/raw/master/.github/images/boot_order.png\" alt=\"highlevel\" height=\"300\"/\u003e\n  \u003c/p\u003e\n\n  Early boot is critical in supporting a fully deprivileged host while late\n  launch is easier to set up, configure and use. Late launch is also a lot\n  easier on developers, preventing the need to reboot each time a line of code\n  changes in the hypervisor itself. MicroV aims to support both early boot and\n  late launch from inception, giving both users and developers as many options\n  as possible.\n\n- **Licensing:** Most of the hypervisors available today in open source\n  leverage the GPL license making it difficult to incorporate their\n  technologies in closed source commercial products. MicroV is licensed\n  under MIT. Feel free to use it however you wish. All we ask is that if you\n  find and fix something wrong with the open source code, that you work with\n  us to upstream the fix. We also love pull requests, RFCs, bug reports and\n  feature requests.\n\n## Disadvantages:\nNo design is without its disadvantages:\n- **VM DoS Attacks**:\n  Since the main operating system is responsible for scheduling micro VMs for\n  execution, it is possible that an attack in this operating system could\n  prevent the micro VMs from executing (i.e., DoS attack). For most\n  applications, this type of attack is a non-issue as isolation is more\n  important than resilience against DoS attacks. With that said, there is no\n  reason why a micro VM could not be in charge of scheduling VMs with its own\n  scheduling and power management software (just like it would be possible to\n  run all of the tool stack software in a dedicated micro VM as well). Like\n  Xen, MicroV is designed to ensure these facilities are not dependent on the\n  main operating system. The upstream project simply defaults to this type of\n  configuration as its the larger, more prevalent use case. And keep in mind\n  that there is always a tradeoff. Although the upstream approach is vulnerable\n  to DoS attacks, implementing your own scheduler and power management software\n  is no easy task, and should be limited to specific use cases (unless\n  performance and battery life is not important).\n\n## **Quick start**\nTBD\n\n## Interested In Working For AIS?\nCheck out our [Can You Hack It?®](https://www.canyouhackit.com) 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.\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://www.ainfosec.com/\"\u003e\n    \u003cimg src=\"https://github.com/Bareflank/MicroV/raw/master/.github/images/ais.png\" alt=\"cross-platform\" height=\"100\" /\u003e\n  \u003c/a\u003e\n\u003c/p\u003e\n\n## Demo\nTBD\n\n## **Build Requirements**\nCurrently, 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.\n\n### **Windows**\nTo 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:\n```\nbcdedit.exe /set testsigning ON\n\u003creboot\u003e\n```\n\nNext, install the following:\n- [Visual Studio](https://visualstudio.microsoft.com/thank-you-downloading-visual-studio/?sku=Community\u0026rel=16) (Enable \"Desktop development with C++\")\n- [WDK](https://docs.microsoft.com/en-us/windows-hardware/drivers/download-the-wdk)\n- [LLVM 10+](https://github.com/llvm/llvm-project/releases)\n- [CMake 3.13+](https://cmake.org/download/)\n- [Ninja](https://github.com/ninja-build/ninja/releases)\n- [Git](https://git-scm.com/downloads)\n\nVisual 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\nin 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.\n\nTo 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:\n- MSBuild\n- devcon\n- certmgr\n\nFor example, in your .bashrc, you might add the following (depending on where Visual Studio put these files):\n```bash\nexport 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\"\n```\n\nFinally, run the following from Bash:\n```bash\ngit clone https://github.com/bareflank/microv\nmkdir microv/build \u0026\u0026 cd microv/build\ncmake ..\nninja info\nninja\n```\n\n### **Ubuntu Linux**\nTo compile the BSL on Ubuntu (20.04 or higher) you must first install the following dependencies:\n```bash\nsudo apt-get install -y clang cmake lld\n```\n\nTo compile the BSL, use the following:\n```bash\ngit clone https://github.com/bareflank/microv\nmkdir microv/build \u0026\u0026 cd microv/build\ncmake ..\nmake info\nmake\n```\n\n### **UEFI**\nTBD\n\n## Usage Instructions\nMicroV 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:\n\nFirst, 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:\n```\nmake loader_quick\nmake -j\u003cnum cores\u003e\nmake start\n```\n\nYou can run the following to verify that your OS is not in the root VM:\n```\nmake dump\n```\n\nAnd you should see something like:\n```\n ___                __ _           _\n| _ ) __ _ _ _ ___ / _| |__ _ _ _ | |__\n| _ \\/ _` | '_/ -_)  _| / _` | ' \\| / /\n|___/\\__,_|_| \\___|_| |_\\__,_|_||_|_\\_\\\n\nPlease give us a star on: https://github.com/Bareflank/hypervisor\n==================================================================\n\nDEBUG [0000:0000:0000:0000:0000:US]: root OS had been demoted to vm 0x0000 on pp 0x0000\nDEBUG [0000:0000:0001:0001:0001:US]: root OS had been demoted to vm 0x0000 on pp 0x0001\nDEBUG [0000:0000:0002:0002:0002:US]: root OS had been demoted to vm 0x0000 on pp 0x0002\nDEBUG [0000:0000:0003:0003:0003:US]: root OS had been demoted to vm 0x0000 on pp 0x0003\nDEBUG [0000:0000:0004:0004:0004:US]: root OS had been demoted to vm 0x0000 on pp 0x0004\n```\n\nTo be able to run KVM APIs, you must load the shim driver, which acts like KVM. To do this, run:\n```\nmake shim_quick\n```\n\nYou 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`.\n\nIf `make start` fails, it means that Bareflank's loader is not running, which is why we can `make loader_quick`.\n\nFrom here, you can run whatever integration test you want. For example:\n```\nmake kvm_create_vm\nmake kvm_create_vcpu\n```\n\nYou 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`.\n\nYou 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:\n```\nmake mv_handle_op_open_handle\nmake mv_handle_op_close_handle\n```\n\nYou 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.\n\n## **Resources**\n[![Join the chat](https://img.shields.io/badge/chat-on%20Slack-brightgreen.svg)](https://bareflank.herokuapp.com/)\n\nMicroV provides a ton of useful resources to learn how to use the library including:\n-   **Documentation**: \u003chttps://bareflank.github.io/microv/\u003e\n-   **Unit Tests**: \u003chttps://github.com/Bareflank/microv/tree/master/test\u003e\n\nIf you have any questions, bugs, or feature requests, please feel free to ask on any of the following:\n-   **Slack**: \u003chttps://bareflank.herokuapp.com/\u003e\n-   **Issue Tracker**: \u003chttps://github.com/Bareflank/microv/issues\u003e\n\nIf you would like to help:\n-   **Pull Requests**: \u003chttps://github.com/Bareflank/microv/pulls\u003e\n-   **Contributing Guidelines**: \u003chttps://github.com/Bareflank/microv/blob/master/contributing.md\u003e\n\n## **Testing**\n[![Build Status](https://img.shields.io/endpoint.svg?url=https%3A%2F%2Factions-badge.atrox.dev%2Fbareflank%2Fmicrov%2Fbadge\u0026style=flat)](https://actions-badge.atrox.dev/bareflank/microv/goto)\n[![codecov](https://codecov.io/gh/Bareflank/microv/branch/master/graph/badge.svg)](https://codecov.io/gh/Bareflank/microv)\n\nMicroV leverages the following tools to ensure the highest possible code quality. Each pull request undergoes the following rigorous testing and review:\n-   **Static Analysis:** [Clang Tidy](https://github.com/Bareflank/llvm-project)\n-   **Dynamic Analysis:** Google's ASAN and UBSAN\n-   **Code Coverage:** Code Coverage with CodeCov\n-   **Coding Standards**: [AUTOSAR C++14](https://www.autosar.org/fileadmin/user_upload/standards/adaptive/17-03/AUTOSAR_RS_CPP14Guidelines.pdf) and [C++ Core Guidelines](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md)\n-   **Style**: Clang Format\n-   **Documentation**: Doxygen\n\n## Serial Instructions\nOn Windows, serial output might not work, and on some systems (e.g. Intel NUC),\nthe default Windows serial device may prevent Bareflank from starting at all.\nIf this is the case, disable the default serial device using the following:\n```\nreg add \"HKEY_LOCAL_MACHINE\\System\\CurrentControlSet\\Services\\Serial\" /f /v \"start\" /t REG_DWORD /d \"4\"\n```\n\n## License\n\nThe Bareflank Hypervisor is licensed under the MIT License.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FBareflank%2FMicroV","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FBareflank%2FMicroV","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FBareflank%2FMicroV/lists"}