VMAware Documentation

VMAware is designed for security researchers, VM engineers, white-hat hackers, and developers needing robust VM detection mechanisms.

Key Use Cases:

• Malware Analysis: Helping analysts test the stealth capabilities of virtual machines.
• Software Protection: Assisting proprietary software developers in protecting applications from reverse engineering.
• Benchmarking: Serving as an effective tool to evaluate VM cloaking/stealth detection capabilities.
• Behavioral Adjustment: Allowing applications to adjust their behavior based on the detected environment (useful for debugging, testing, or enforcing license restrictions against unauthorized VM use).

VMAware calculates a final score for each VM detection technique to represent the confidence level that a positive result indicates a virtual environment.

The final score is derived by summing scores from two primary categories, which are then subject to a penalty based on false positive likelihood:

1. Reliability (Max 50%): Measures consistency across tests and the detection rate (probability of detecting a VM vs non-VM).
2. Specificity to VMs (Max 50%): Measures how specific the technique is to VM environments and its sensitivity to different VM platforms/configurations.

Calculation Flow: Final Score = (Reliability Score + Specificity Score) - False Positive Penalty

Note: The final score has a minimum floor of 5.

VMAware uses a scoring system to detect virtual machines. It employs a list of low-level and high-level anti-VM techniques, each assigned a score between 0 and 100 based on objective criteria designed to minimize false positives.

As the library runs, every technique that successfully detects a VM adds its score to an accumulative total. A predefined threshold of this total score determines whether the environment is classified as running in a VM.

VMAware utilizes a comprehensive anti-VM detection checklist that combines both low-level and high-level techniques. It employs a weighted scoring mechanism to identify virtual machine environments:

1. Weight Assignment: Each detection technique is assigned a weight between 0 and 100 based on objective criteria designed to minimize false positives and focus on highly stealthy VM detection.
2. Accumulation: As techniques successfully detect VM indicators, their assigned weights are accumulated.
3. Threshold: If the total accumulated score exceeds a pre-set threshold, the environment is classified as a Virtual Machine.

VMAware provides a flag system that allows users to control exactly which detection techniques are executed. This gives you complete control over the detection process, allowing you to choose specific methods based on your requirements for certainty, platform support, or administrative privileges.

Each flag represents a specific technique (e.g., checking CPUID, MAC addresses, or specific system files) and is associated with a platform (Linux, Windows, or macOS) and a certainty level.

The vmaware command-line interface is composed of several internal modules that handle specific tasks:

• cli/main.cpp: The entry point for the CLI and handles argument parsing.
• cli/output.hpp: Manages output formatting, including general display and JSON output.
• cli/strings.hpp: Provides ANSI color strings, argument enums, and global counters.
• cli/types.hpp: Contains shared primitive type aliases used across the CLI.
• cli/sha256.hpp: Provides the SHA-256 implementation used by the CLI.
• cli/windows_tui.hpp: Contains Windows-specific terminal UI code used when the --rich option is enabled.

VMAware is a cross-platform C++ framework used to detect virtual machines, hypervisors, emulators, containers, and sandboxes. It provides high-level functions to check for VM presence, identify the specific brand, determine the VM type, and assess the certainty of the detection. The library is header-only, has no external dependencies, and uses memoization to cache results for performance.

#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";
}

If a detection technique is prone to false positives in non-VM environments, a penalty is applied to the sum of its Reliability and Specificity scores. The penalty is determined by the risk level:

Important: For the High risk level, if the calculated score after the 80% reduction is less than 5, the final score is set to 5.