VMAware
Advanced VM detection library and tool
Install / Use
/learn @kernelwernel/VMAwareREADME
The library is:
- Very easy to use
- Cross-platform (Windows + MacOS + Linux)
- Features around 90 unique VM detection techniques [list]
- Features the most cutting-edge techniques
- Able to detect around 70 VM brands including VMware, VirtualBox, QEMU, Hyper-V, and much more [list]
- Able to beat VM hardeners
- Compatible with x86 and ARM, with backwards compatibility for 32-bit systems
- Very flexible, with total fine-grained control over which techniques get executed
- Able to detect various VM and semi-VM technologies like hypervisors, emulators, containers, sandboxes, and so on
- Available with C++11 and above
- Header-only
- Free of any external dependencies
- Memoized, meaning past results are cached and retrieved if ran again for performance benefits
- Fully MIT-licensed, allowing unrestricted use and distribution
[!NOTE] We are looking for translators willing to translate this README into your native language. If you'd like to contribute, feel free to give us a PR!
Example 🧪
#include "vmaware.hpp"
#include <iostream>
int main() {
if (VM::detect()) {
std::cout << "Virtual machine detected!" << "\n";
} else {
std::cout << "Running on baremetal" << "\n";
}
std::cout << "VM name: " << VM::brand() << "\n";
std::cout << "VM type: " << VM::type() << "\n";
std::cout << "VM certainty: " << (int)VM::percentage() << "%" << "\n";
std::cout << "VM hardening: " << (VM::is_hardened() ? "likely" : "not found") << "\n";
}
possible output:
Virtual machine detected!
VM name: VirtualBox
VM type: Hypervisor (type 2)
VM certainty: 100%
VM hardening: not found
Structure ⚙️
<p align="center"> <img src="assets/vmaware.png" align="center" title="VMAware"> <br> </p> <br>CLI tool 🔧
This project also provides a handy CLI tool utilising the full potential of what the library can do. It also has cross-platform support.
Below is an example of a basic QEMU system with no hardening modifications on Linux.
<img src="assets/demo.png" title="cli"> <!-- Try it out on [Compiler Explorer](https://godbolt.org/z/4sKa1sqrW)!--> <br>Installation 📥
To install the library, download the vmaware.hpp file in the latest release section to your project. The binaries are also located there. No CMake or shared object linkages are necessary, it's literally that simple.
However, if you want the full project (globally accessible headers with <vmaware.hpp> and the CLI tool), follow these commands:
git clone https://github.com/kernelwernel/VMAware
cd VMAware
FOR LINUX:
sudo dnf/apt/yum update -y # change this to whatever your distro is
mkdir build
cd build
cmake ..
sudo make install
FOR MACOS:
mkdir build
cd build
cmake ..
sudo make install
FOR WINDOWS:
cmake -S . -B build/ -G "Visual Studio 16 2019"
Optionally, you can create a debug build by appending -DCMAKE_BUILD_TYPE=Debug to the cmake arguments.
CMake installation
# edit this
set(DIRECTORY "/path/to/your/directory/")
set(DESTINATION "${DIRECTORY}vmaware.hpp")
if (NOT EXISTS ${DESTINATION})
message(STATUS "Downloading VMAware")
set(URL "https://github.com/kernelwernel/VMAware/releases/latest/download/vmaware.hpp")
file(DOWNLOAD ${URL} ${DESTINATION} SHOW_PROGRESS)
else()
message(STATUS "VMAware already downloaded, skipping")
endif()
The module file and function version is located here
<br>Documentation and code overview 📒
You can view the full docs here. All the details such as functions, techniques, settings, and examples are provided. Trust me, it's not too intimidating ;)
If you want to learn about the architecture and design of the library, head over to https://deepwiki.com/kernelwernel/VMAware
<br>Q&A ❓
<details> <summary>How does it work?</summary> <br></details> <details> <summary>Who is this library for and what are the use cases?</summary> <br>It utilises a comprehensive list of low-level and high-level anti-VM techniques that gets accounted in a scoring system. The scores (0-100) for each technique are given based on an objective criteria focused on detecting the most stealthy VMs by minimizing false positives as much as possible, and every technique that has detected a VM will have their score added to a single accumulative point, where a threshold point number will decide whether it's actually running in a VM.
</details> <details> <summary>Why another VM detection project?</summary> <br>It's designed for security researchers, VM engineers, anticheat developers, and pretty much anybody who needs a practical and rock-solid VM detection mechanism in their project. The library is useful for malware analysts testing the concealment of their VMs and for proprietary software developers aiming to protect their applications from reverse engineering. It's an effective tool to benchmark how well a VM can hide itself from detection.
Additionally, software could adjust the behaviour of their program based on the detected environment. It could be useful for debugging and testing purposes, while system administrators could manage configurations differently. Finally, some applications might want to legally restrict usage in VMs as a license clause to prevent unauthorized distribution or testing.
There are also projects that utilise our tool such as Hypervisor-Phantom, which is an advanced malware analysis project that we helped strengthen their hypervisor environment and undetectability.
</details> <!-- <details> <summary>How does it compare to paid VM detection libraries?</summary> <br> > There are several paid software solutions available for protecting software licenses from reverse engineering or cracking, such as <a href="https://docs.sentinel.thalesgroup.com/home.htm">Thales' Sentinel RMS</a> and <a href="https://vmpsoft.com/">VMProtect</a>. These tools include VM detection as part of their feature set, though their primary focus is not necessarily VM detection unlike this project. </details> --> <details> <summary>Wouldn't it make it inferior for having the project open source?</summary> <br>There's already loads of projects that have the same goal such as <a href="https://github.com/CheckPointSW/InviZzzible">InviZzzible</a>, <a href="https://github.com/a0rtega/pafish">pafish</a> and <a href="https://github.com/LordNoteworthy/al-khaser">Al-Khaser</a>. But the difference between the aforementioned projects is that they don't provide a programmable interface to interact with the detection mechanisms, on top of having little to no support for non-Windows systems. Additionally, the VM detections in all those projects are often not sophisticated enough to be practically applied to real-world scenarios while not providing enough VM detection techniques. An additional hurdle is that they are all GPL projects, so using them for proprietary projects (which would be the main audience for such a functionality), is out of the question.
Pafish and InviZzzible have been abandoned for years. Although Al-Khaser does receive occasional updates and has a wide scope of detections that VMAware doesn't provide (anti-debugging, anti-injection, and so on), it still falls short due to the previously mentioned problems above.
While those projects have been useful to VMAware to some extent, we wanted to make them far better. Our goal was to make the detection techniques to be accessible programmatically in a cross-platform and flexible way for everybody to get something useful out of it rather than providing just a CLI tool. It also contains a larger quantity of techniques, so it's basically just a VM detection framework on steroids that focuses on practical and realistic usability for any scenario.
The only downside to VMAware is that it's fully open source, which makes the job of bypassers easier compared to having it closed source. However, We'd argue that's a worthy tradeoff by having as many VM detection techniques in an open and interactive manner rather than trying to obfuscate. Having it open source means we can have valuable community feedback to strengthen the library more effectively and accurately through discussions, collaborations, and competition against anti-anti-vm projects and malware analysis tools which try to hide it's a VM.
All of this combined has further advanced the
Related Skills
ai-cmo
Collection of my Agent Skills and books.
orbit-planning
O.R.B.I.T. - strategic project planning before you build. Objective, Requirements, Blueprint, Implementation Roadmap, Track.
next
A beautifully designed, floating Pomodoro timer that respects your workspace.
product-manager-skills
34PM skill for Claude Code, Codex, Cursor, and Windsurf: diagnose SaaS metrics, critique PRDs, plan roadmaps, run discovery, and coach PM career transitions.
