NotRequiem/VMAware: C++ Virtual Machine Detection

What VMAware Detects and Who Uses It

VMAware addresses the need to identify an execution environment that may be a virtual machine rather than bare metal. The README describes detection for around 70 VM brands, including VMware, VirtualBox, QEMU, and Hyper-V, plus semi-VM technologies such as hypervisors, emulators, containers, and sandboxes. Its intended users include security researchers, VM engineers, anticheat developers, malware analysts studying VM concealment, and proprietary software developers interested in reducing reverse-engineering opportunities. The library can also support application behavior changes when a program needs different behavior in virtualized environments.

This is a detection and classification library, not a security boundary by itself. A result such as VirtualBox or Hypervisor type 2 comes from the project’s detection methods and scoring system. The README’s example includes a certainty percentage. That makes the API suitable for a policy decision, such as recording an environment or selecting a reduced feature set, but the application still has to decide what its own threshold means. The project names sandbox and container detection among its supported targets, although the README excerpt does not enumerate the exact technique-to-technology mapping. The distinction matters because a detection result can be useful for instrumentation or compatibility policy without proving that an environment is hostile.

Scored Detection Architecture

The central mechanism is an accumulation of results from low-level and high-level anti-VM techniques. According to the README’s question-and-answer section, each technique contributes a score based on criteria intended to identify stealthy virtual machines while minimizing false positives. Scores range from 0 to 100, and the scores for techniques that detect a virtual machine are added to an accumulated total. A threshold determines whether the environment is classified as virtualized. The project therefore uses multiple observations rather than one vendor-specific file, registry key, or process check.

The public API separates detection from classification. `VM::detect()` returns whether the environment is considered virtualized. `VM::brand()` returns a VM name, while `VM::type()` returns a type such as Hypervisor type 2. `VM::percentage()` returns the certainty score shown as an integer in the README example. This structure lets callers combine the boolean result with brand, type, and score information. It also distinguishes a named virtualization product from an unidentified hypervisor, which can be useful when an application records diagnostic context or applies a product-specific policy.

VMAware describes itself as memoized. Past results are cached and retrieved when the library runs again for performance benefits. The README does not specify the exact cache invalidation policy, so callers should not assume that changing the environment or settings always forces a new evaluation. The project’s full documentation should be consulted for the settings and technique-selection behavior before relying on a particular combination in production.

Header-Only C++ Integration

The simplest integration path is a single-header installation. The README says to download `vmaware.hpp` from the latest release section and place it in the project. It explicitly states that no CMake or shared-object linkage is required. This is useful for small native applications, command-line tools, and experiments where adding a package or runtime library would complicate deployment. VMAware supports C++11 and newer and has no external dependencies according to the project description.

The header also provides fine-grained control over which techniques execute. That matters when a deployment has known virtualization characteristics, when different environments need different detection policies, or when a security review needs to record the exact checks used. The README excerpt does not provide the complete settings API, so a production integration should consult `docs/documentation.md` rather than assume that every technique is enabled by default or that the same set is available on every operating system.

The listed architecture support is broad. The README names alpha, amd64, arm64, arm64ec, armel, armhf, hppa, i386, m68k, mips, mipsel, mips64, mips64el, powerpc, ppc64, ppc64el, riscv64, s390x, sh4, sparc64, and x32. Broad target coverage does not by itself prove that every detection technique works identically on every target. Platform-specific implementation and build testing remain relevant integration checks.

Installing the Header and Running the First Check

For a minimal C++ application, download `vmaware.hpp` from the latest VMAware release and put it beside the source file or in an include directory. The README’s example can then be compiled with a C++11-compatible compiler. The first call should be treated as an environment observation. The program below reports the boolean decision, brand, type, and certainty score rather than printing only one vendor name.

#include "vmaware.hpp"
#include <iostream>

int main() {
    if (VM::detect()) {
        std::cout << "Virtual machine detected!" << "\n";
    } else {
        std::cout << "Running on bare metal" << "\n";
    }

    std::cout << "VM name: " << VM::brand() << "\n";
    std::cout << "VM type: " << VM::type() << "\n";
    std::cout << "VM certainty: " << (int)VM::percentage() << "%" << "\n";
}

The README shows a possible VirtualBox result with `Hypervisor (type 2)` and `100%`, but that is an example output, not a promise for every machine. A reader should check the include path and compare the reported environment with the host or virtual machine where the program is running. The README does not provide a universal compile command in the excerpt, so no compiler-specific flag should be invented.

Building the Full Project and CLI

The full project provides globally accessible headers and a CLI. On Linux, the README gives the following build sequence. The package-manager command is presented as a template because the exact distribution package manager varies.

git clone https://github.com/NotRequiem/VMAware
cd VMAware
mkdir build
cd build
cmake ..
sudo make install

The documented Linux build also shows a distribution update command before the build directory is created. The macOS path omits the package-manager update step. These commands install or build the project as documented, but the excerpt does not describe the resulting CLI binary name, installation prefix, or command-line options.

For Windows, the README gives this CMake configuration command.

cmake -S . -B build/ -G "Visual Studio 16 2019"

This is a build command, not a runtime command. The CLI is described as cross-platform, but the excerpt does not give a portable invocation example or enumerate its flags, so an invented invocation would not be reliable. The optional debug setting is documented as `-DCMAKE_BUILD_TYPE=Debug`, which can be appended to CMake arguments.

CMake Download Integration

The repository also documents a CMake snippet that downloads the release header. This is useful when a consuming project wants a reproducible include file without manually copying `vmaware.hpp`. The destination path is intentionally a placeholder in the README, so it must be changed to a real project directory. The snippet checks whether the destination exists before downloading.

set(DIRECTORY "/path/to/your/directory/")
set(DESTINATION "${DIRECTORY}vmaware.hpp")

if (NOT EXISTS ${DESTINATION})
    message(STATUS "Downloading VMAware")
    set(URL "https://github.com/NotRequiem/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 are located in `auxiliary/vmaware_download.cmake`. The snippet does not show how the downloaded header is added to include paths or how a consumer target links against it, so an application must connect the download step to its own CMake target. Because the URL points to `releases/latest/download/vmaware.hpp`, a build process that requires pinned versions should review that behavior before using it unchanged.

Limitations and Appropriate Use

The main limitation is the nature of heuristic detection. VMAware says its scoring system is designed to reduce false positives and detect stealthy VMs, but the README does not provide a formal false-positive rate, a complete platform matrix for individual techniques, or a guarantee that every evasion method is covered. A VM can alter artifacts, and any detection library can become outdated when virtualization platforms or analysis environments change. Memoization also means repeated calls may return cached results, which is useful for performance but makes cache policy relevant when an application expects fresh observations.

The library is not a complete anti-tampering system. It can report a detected environment, but the README does not say that it blocks execution, protects secrets, signs results, or prevents an attacker from patching the application. Those are separate application and system-security concerns.

A practical use is to classify an environment for telemetry, compatibility behavior, anticheat policy, malware analysis, or a controlled virtualization experiment. An inappropriate use is to rely on `VM::detect()` alone as definitive proof that a machine is physical or safe. The API should be combined with the application’s own policy and reviewed against the intended platforms. The CLI can also help compare how the library classifies a virtual machine, but the README does not document rollback or a formal regression workflow.

Ports, License, and Maintenance Signals

The project lists an official Ruby port in the repository, plus JavaScript and Rust ports hosted separately. The README describes the Ruby port as officially supported by the VMAware developers, notes that Windows is not supported there, and says the JavaScript port supports 64-bit only. The README also describes the Rust repository as a binding with the same API. It separately warns that unofficial ports are not tested compared with the official ones and says to use them at own risk. The existence of a port therefore does not remove the need to verify platform support and API parity.

VMAware is released under the MIT license. The README characterizes the license as allowing unrestricted use and distribution, and the repository includes a `LICENSE` file. This article does not interpret license obligations beyond that project statement. Users still need to inspect the license text and account for dependencies or separately distributed ports in their own distribution review.

The repository is not archived. Its last push was on 2026-10-07, and the listed release history includes v2.8.2 on 2026-09-14, v2.8.1 on 2026-08-09, and v2.8.0 on 2026-07-06. Those dates indicate recent repository activity, but the README does not promise a release cadence, long-term support window, or compatibility guarantee for older versions. Upgrading from one release to another should be checked against the project documentation and the application’s chosen techniques.

Choosing VMAware or a Conventional Platform Check

A conventional platform check might ask one operating-system API whether a process is associated with a hypervisor, or it might inspect one vendor artifact. That approach is simpler, but it has a narrow signal and can be easier to classify as one specific check. VMAware takes a different approach: it aggregates many anti-VM techniques, assigns scores, caches results, and exposes brand, type, and certainty information. Its trade-off is greater behavioral complexity and the need to understand which techniques are enabled.

VMAware is the more relevant choice when a C++ application needs configurable cross-platform classification and wants to inspect multiple signals through one interface. A single-purpose application that needs only one documented operating-system status value may not need that machinery. The README does not provide performance measurements, so it is not possible to claim which approach is faster or lighter in a particular deployment. The deciding evidence should come from the platform APIs the application must support, the detection policy it needs, and the project’s documented build and configuration behavior. For a CLI experiment, the release binaries may be preferable to manually copying a header. For library integration, the header-only form removes linkage complexity but requires careful control of configuration and release versioning.

Editorial conclusion

Adopt VMAware when a C++ application needs configurable VM and hypervisor detection without linking a separate library. Do not treat its score as proof of a physical machine, because the README describes heuristic scoring and does not guarantee zero false positives. Check the selected detection techniques, platform build path, expected brand and type results, and the application policy for low-confidence environments first. The last push was on 2026-10-07, and the listed releases include v2.8.2 from 2026-09-14.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. NotRequiem/VMAware on GitHub
4. README
5. Releases