VMAware is a cross-platform C++ library for virtual machine detection. This document provides a high-level introduction to the project's architecture, capabilities, and design philosophy. It covers the core components, detection methodology, and integration patterns.
For detailed API documentation, see Public API Reference. For installation instructions, see Installation. For a complete list of detection techniques, see Detection Techniques.
Sources: README.md1-38 docs/documentation.md1-22
VMAware (VM + Aware) is a header-only C++ framework that provides programmatic access to approximately 90 distinct virtual machine detection techniques. The library employs a scoring-based detection engine that aggregates evidence from multiple techniques to determine with high confidence whether the host environment is virtualized.
The project consists of two primary user-facing components:
| Component | File | Purpose |
|---|---|---|
| Core Library | vmaware.hpp | Header-only library providing programmatic VM detection API |
| CLI Tool | cli.cpp | Command-line utility demonstrating full library capabilities |
The library is designed for security researchers, malware analysts, anti-cheat developers, and software protection engineers who need reliable VM detection in production environments.
Sources: README.md14-38 docs/documentation.md1-98
Diagram: VMAware System Architecture - Component Relationships
This diagram illustrates the layered architecture where user code interacts with the public API layer, which delegates to the core detection engine that orchestrates technique execution through internal modules. The memoization system (VM::memo) caches results across all modules for performance optimization.
Sources: README.md75-82 docs/documentation.md1-500
VMAware is implemented as a single header file (src/vmaware.hpp) containing all functionality. This design eliminates external dependencies and simplifies integration—users only need to download one file and include it in their project.
The library requires C++11 or higher and links against standard system libraries (-lstdc++ and -lm on Unix-like systems). No external dependencies like Boost or third-party libraries are required.
Sources: README.md34-37 README.md96-97 README.md254-257
The entire API is contained within the VM namespace:
Brand string constants are provided in the brands namespace for type-safe comparisons:
Sources: docs/documentation.md142-158 docs/documentation.md604-680
| Function | Return Type | Purpose |
|---|---|---|
VM::detect() | bool | Binary detection: is this a VM? |
VM::percentage() | std::uint8_t | Confidence score (0-100%) |
VM::brand() | std::string | Identified VM vendor (e.g., "VirtualBox") |
VM::type() | std::string | VM architecture (e.g., "Hypervisor (type 2)") |
VM::check() | bool | Test single technique |
VM::is_hardened() | bool | Detect VM hardening attempts |
VM::add_custom() | void | Register custom detection function |
VM::conclusion() | std::string | Human-readable summary message |
VM::detected_count() | std::uint8_t | Number of techniques that detected VM |
All functions accept optional flag parameters for fine-grained control over which techniques execute.
Sources: docs/documentation.md26-340
VMAware employs a cumulative scoring system rather than relying on any single technique. Each detection technique is assigned a weight (0-150% of certainty) based on its reliability and false positive rate.
Diagram: Detection Engine Workflow
The default threshold is 150 points. If techniques accumulate at least this score, VM::detect() returns true. Users can raise the threshold to 300 with the VM::HIGH_THRESHOLD flag to reduce false positives at the cost of potential false negatives.
Example Score Calculation:
VM::HYPERVISOR_BIT detected → +100 pointsVM::VMID detected → +100 pointsVM::CPU_BRAND detected → +95 pointsSources: README.md163-165 docs/documentation.md28-96 docs/documentation.md507-598
Detection techniques are organized by platform support:
| Category | Count | Examples | Platform Identifier |
|---|---|---|---|
| Cross-Platform | 9 | VM::VMID, VM::HYPERVISOR_BIT, VM::CPU_BRAND, VM::TIMER | 🐧🪟🍏 |
| Windows-Only | 32 | VM::DRIVERS, VM::GPU_CAPABILITIES, VM::MUTEX | 🪟 |
| Linux-Only | 30 | VM::DMIDECODE, VM::DMESG, VM::SYSTEMD | 🐧 |
| macOS-Only | 6 | VM::MAC_IOKIT, VM::MAC_SIP, VM::HWMODEL | 🍏 |
Techniques automatically skip execution if the current platform doesn't support them. For example, VM::DRIVERS (Windows registry enumeration) will not run on Linux systems.
Sources: docs/documentation.md501-598
When techniques detect VM artifacts, they report which VM brand(s) they've identified. The VM::core module maintains a brand scoreboard that aggregates this evidence:
Diagram: Brand Scoreboard Aggregation
The brand with the most supporting evidence is returned by VM::brand(). If multiple brands have equal evidence, the VM::MULTIPLE flag can be used to return a message like "VMware or VirtualBox" instead of selecting arbitrarily.
Sources: docs/documentation.md132-189 docs/documentation.md604-680
Diagram: Platform and VM Type Support
The library supports x86 and ARM architectures with backwards compatibility for 32-bit systems (legacy Windows techniques like VM::VPC_INVALID and VM::VMWARE_STR require 32-bit mode).
Sources: README.md25-33 docs/documentation.md604-680
The simplest integration method requires only downloading vmaware.hpp and including it:
Compilation requires standard C++ libraries:
clang++ -std=c++11 main.cpp -lstdc++ -lmcl.exe main.cpp (MSVC)Sources: README.md95-127 docs/documentation.md455-498
For global accessibility and the CLI tool:
This installs:
/usr/include/vmaware.hpp/usr/bin/vmawareSources: README.md98-119
For CMake projects, a downloadable module is available at auxiliary/vmaware_download.cmake that automatically fetches the header:
Sources: README.md130-147
Researchers use VMAware to validate the stealth of their analysis environments. The library helps identify which VM artifacts are detectable and guides hardening efforts to improve concealment from malware samples.
Example: Testing if a hardened VirtualBox installation successfully evades detection after applying anti-detection patches.
Game developers and proprietary software vendors integrate VMAware to restrict execution in virtualized environments, preventing reverse engineering, debugging, and unauthorized distribution.
Example: Rejecting game client execution if VM::detect() returns true to prevent cheating tools from analyzing game logic in isolated VMs.
Software licenses often prohibit VM usage for specific deployment scenarios. VMAware enables programmatic enforcement of these terms.
Example: Enterprise software that checks VM::brand() and refuses activation on unauthorized VM platforms while allowing sanctioned cloud deployments.
System administrators use the CLI tool (cli.cpp) to verify VM detection signatures and validate environment configurations without writing code.
Example: Running vmaware --verbose to audit which techniques successfully detect a newly deployed KVM hypervisor.
Sources: README.md169-177 README.md84-90 docs/documentation.md704-726
VMAware prioritizes:
VM::memo memoization system to avoid redundant expensive operationsThe scoring system is calibrated based on empirical data from production deployments, not theoretical assumptions. Techniques are continuously validated against evolving VM hardening methods.
Sources: README.md36-37 README.md204-211 README.md225-239
The command-line interface (src/cli.cpp) provides immediate access to all library capabilities:
The CLI includes additional detection techniques not present in the library (e.g., ANY.RUN sandbox detection) and performs SHA256 self-integrity verification on Windows platforms.
Sources: README.md84-93 docs/documentation.md704-728
Diagram: Documentation Navigation from Overview
This overview provides the conceptual foundation. For implementation details, consult the referenced sections in the table of contents.
Sources: Table of Contents JSON
Refresh this wiki