VMAware is a cross-platform C++ library for virtual machine detection, implemented as a single header file (vmaware.hpp) providing a static class interface (VM::) with approximately 90 detection techniques across Windows, Linux, and macOS. The library identifies over 70 VM brands through a scoring-based detection model and supports x86, x86_64, ARM32, and ARM64 architectures with C++11 compatibility.
Key Characteristics:
This page provides a high-level architectural overview of the library's structure, component interactions, and detection methodology.
Sources: README.md14-38 src/vmaware.hpp1-217 src/vmaware.hpp535-654
VMAware's architecture consists of a static class VM defined in struct VM src/vmaware.hpp535 with deleted constructors src/vmaware.hpp702-704 exposing five primary public functions and four internal module structs. All state is managed through static member variables within the module structs.
Title: VM Class Public Interface
Sources: src/vmaware.hpp535-704 src/vmaware.hpp547-654 docs/documentation.md26-96
The library internally organizes code into four module structs (cpu, memo, util, core) contained within the VM struct as private nested types. These modules are not instantiated; they provide static member functions and data.
Title: VM Internal Module Organization
Sources: src/vmaware.hpp535-704 src/vmaware.hpp718-3039 src/vmaware.hpp3041-3223 src/vmaware.hpp3223-11338 src/vmaware.hpp11338-11716
| Calling Module | Called Module | Example Interaction | Code Location |
|---|---|---|---|
| Public API → core | VM::detect() → core::run_all() | Detection orchestration | src/vmaware.hpp11716-12736 |
| core → techniques | core::run_all() → technique functions | Execute each enabled technique | src/vmaware.hpp11338-11716 |
| techniques → cpu | VMID() → cpu::vmid_template() | CPUID brand string extraction | src/vmaware.hpp4283-4300 |
| techniques → util | REGISTRY() → util::read_reg_key() | Windows registry queries | src/vmaware.hpp3223-11338 |
| cpu → memo | cpu::get_brand() → memo::cpu_brand | Cache CPU brand string | src/vmaware.hpp857-891 |
| core → memo | core::run_all() → memo::cache_table | Retrieve/store technique results | src/vmaware.hpp11338-11716 |
Sources: src/vmaware.hpp718-12736
VMAware implements a scoring-based accumulation model where each of the ~90 techniques contributes a score (5-150 points) if VM indicators are detected. The cumulative score is compared against a threshold (default: 150 points) defined in threshold_score src/vmaware.hpp662 to determine VM presence.
Title: VM::detect() Execution Pipeline
Sources: src/vmaware.hpp11716-12736 src/vmaware.hpp11338-11716 src/vmaware.hpp3041-3223 src/vmaware.hpp144-217
The library defines detection techniques in a compile-time TECHNIQUE table stored in core module. Each entry is a technique_struct containing:
Example techniques from the table:
VMID → 100 points → VM::VMID() function src/vmaware.hpp4283-4300HYPERVISOR_BIT → 100 points → VM::HYPERVISOR_BIT() function src/vmaware.hpp4375-4400CPU_BRAND → 95 points → VM::CPU_BRAND() function src/vmaware.hpp4301-4374TIMER → 150 points → VM::TIMER() function src/vmaware.hpp4587-4716The technique enum VM::enum_flags src/vmaware.hpp547-654 provides compile-time identifiers for all techniques, with values:
0 to HIGH_THRESHOLD-1HIGH_THRESHOLD to MULTIPLEDEFAULT, ALL, NULL_ARGSources: src/vmaware.hpp547-654 src/vmaware.hpp11338-11716 src/vmaware.hpp656-673
The BRAND scoreboard is a static std::unordered_map<const char*, brand_score_t> src/vmaware.hpp692-695 maintained by the core module. When a technique detects a VM and identifies a brand, it calls core::add(brand_name) which increments the brand's score.
Title: Brand Detection Workflow
Brand constants are defined in the brands namespace src/vmaware.hpp452-521 examples:
brands::VBOX = "VirtualBox"brands::VMWARE = "VMware"brands::QEMU = "QEMU"brands::HYPERV = "Microsoft Hyper-V"brands::KVM = "KVM"Special merging rules in core::merge_brands():
HYPERV + AZURE detected → Result: brands::AZURE_HYPERVQEMU + KVM detected → Result: brands::QEMU_KVMKVM + KVM_HYPERV detected → Result: brands::QEMU_KVM_HYPERVSources: src/vmaware.hpp452-521 src/vmaware.hpp11338-11716 src/vmaware.hpp173-210
| Constant | Value | Location | Description |
|---|---|---|---|
base_technique_count | 90+ | src/vmaware.hpp660 | Number of detection techniques |
maximum_points | 5510 | src/vmaware.hpp661 | Theoretical maximum if all techniques detect |
threshold_score | 150 | src/vmaware.hpp662 | Default detection threshold |
high_threshold_score | 300 | src/vmaware.hpp663 | Threshold when VM::HIGH_THRESHOLD flag set |
SHORTCUT | true | src/vmaware.hpp664 | Early exit if threshold met during execution |
Sources: src/vmaware.hpp656-664
The VMAware project consists of three primary components: the core library (vmaware.hpp), a CLI wrapper (cli.cpp), and development tooling. The library is designed for header-only inclusion, while the CLI provides immediate usability without compilation.
Title: Component Dependency Graph
Sources: src/vmaware.hpp1-12736 src/cli.cpp docs/documentation.md1-724 README.md23-38
The library has zero external dependencies beyond the C++ standard library and OS-specific headers:
<windows.h>, <intrin.h>, <winternl.h>, <setupapi.h>, <winevt.h> src/vmaware.hpp380-394<cpuid.h>, <sys/sysinfo.h>, <dirent.h>, <pthread.h>, <sys/syscall.h> src/vmaware.hpp395-419<sys/sysctl.h>, <cpuid.h>, <sys/types.h> src/vmaware.hpp420-433| Path | Lines | Purpose | Page Reference |
|---|---|---|---|
src/vmaware.hpp | ~12,000 | Core detection library | Core Library Architecture |
src/vmaware_MIT.hpp | ~8,000 | MIT-only variant (no GPL techniques) | Dual Licensing Strategy |
src/cli.cpp | ~1,000 | Command-line interface | Command-Line Interface |
docs/documentation.md | ~724 | API reference, auto-generated | Documentation Maintenance |
auxiliary/updater.py | N/A | Syncs documentation with code | Documentation Maintenance |
auxiliary/add_technique.py | N/A | Automates technique addition | Adding New Detection Techniques |
CMakeLists.txt | N/A | Build system configuration | Build System Configuration |
Sources: src/vmaware.hpp1-12736 src/cli.cpp docs/documentation.md1-724 README.md84-147
The library exposes all functionality through static member functions in the VM struct src/vmaware.hpp535 with deleted constructors and copy/move operations src/vmaware.hpp702-704 This eliminates instantiation and enforces stateless usage from the caller's perspective.
All internal state (technique cache, brand scoreboard, CPU data) is stored in static members within the nested module structs (cpu, memo, util, core). This design:
#include with immediate usageSources: src/vmaware.hpp535-704 src/vmaware.hpp702-704 README.md34
Platform-specific code is conditionally compiled using macros defined at src/vmaware.hpp229-336 The library defines:
| Macro | Meaning | Set When |
|---|---|---|
WINDOWS | Compiling for Windows | _WIN32 or _WIN64 defined |
LINUX | Compiling for Linux | __linux__ defined |
APPLE | Compiling for macOS | __APPLE__ or __MACH__ defined |
x86 | x86 architecture (32 or 64-bit) | __i386__ or __x86_64__ |
ARM | ARM architecture (32 or 64-bit) | __arm__ or __aarch64__ |
MSVC | Microsoft Visual C++ compiler | _MSC_VER defined |
GCC | GNU Compiler Collection | __GNUC__ defined (non-clang) |
CLANG | Clang compiler | __clang__ defined |
Techniques use these macros for platform-specific implementations:
The library maintains C++11 compatibility src/vmaware.hpp277-279 while conditionally enabling C++17/C++20/C++23 features when available via the VMA_CPP macro src/vmaware.hpp261-275
Sources: src/vmaware.hpp229-336 src/vmaware.hpp255-279 README.md30
The memo module implements four caching mechanisms to avoid redundant computation:
Title: Memoization Cache Organization
Each cache provides fetch() and store() static member functions:
memo::cache_table::fetch(u8 technique_enum, bool& result) → bool src/vmaware.hpp3041-3223memo::cpu_brand::is_cached() → bool, memo::cpu_brand::fetch() → const char* src/vmaware.hpp857-891memo::leaf_cache::fetch(u32 leaf, bool& result) → bool src/vmaware.hpp803-807memo::brand::is_cached() → bool, memo::brand::fetch() → std::string src/vmaware.hpp3041-3223The memoization strategy provides significant performance improvements for repeated API calls, especially VM::detect() followed by VM::brand(), as technique results are reused.
Sources: src/vmaware.hpp3041-3223 src/vmaware.hpp803-835 src/vmaware.hpp857-891 README.md36
VMAware supports three primary integration methods catering to different use cases:
Download vmaware.hpp, include it directly:
Compilation: g++ main.cpp -o detector -lm -lstdc++
Sources: README.md96
Clone repository, build library and CLI tool globally:
Enables #include <vmaware.hpp> system-wide and installs vmaware CLI binary.
Sources: README.md98-127
Automated download during project configuration:
Sources: README.md131-147
This overview establishes the foundational understanding of VMAware's architecture. Subsequent wiki pages delve into specific subsystems:
Sources: README.md152-154
Refresh this wiki