How to Interpret VMAware's percentage() Output and What It Represents

VMAware's VM::percentage() returns a std::uint8_t value between 0 and 100 that represents the confidence level of virtual machine detection, aggregating evidence from all enabled techniques where 0% indicates no virtualization detected and 100% indicates the raw score exceeded the configured threshold.

The percentage() function in the VMAware library (kernelwernel/vmaware) provides a granular confidence metric for VM detection. Unlike the binary detect() method, this function returns a continuous scale from 0 to 100, reflecting the cumulative weight of triggered detection techniques. Understanding how this score is calculated—and what each percentile range signifies—is essential for correctly interpreting virtualization evidence in your environment.

What VMAware's percentage() Output Represents

VM::percentage() serves as the primary confidence metric of the VMAware library. According to the source code in src/vmaware.hpp, the function returns a std::uint8_t value between 0 and 100 that quantifies how likely the current environment is a virtual machine based on the aggregate results of all enabled detection techniques.

This output differs fundamentally from the binary VM::detect() method. While detect() provides a yes/no answer based on whether the score meets a threshold, percentage() exposes the underlying confidence level, allowing applications to implement custom logic for uncertain results.

How the Percentage Is Calculated

The calculation pipeline involves four distinct stages implemented in src/vmaware.hpp (around lines 12150-1220).

First, the system collects technique flags into a std::bitset via core::arg_handler, using either the default technique set or user-supplied combinations. Second, core::run_all(flags, SHORTCUT) executes every enabled technique, returning a raw score (points) typically ranging from 0 to approximately 300.

Third, the function determines the threshold value. Normal mode uses threshold_score (approximately 150), while the presence of the VM::HIGH_THRESHOLD flag raises this to high_threshold_score (approximately 300).

Finally, the raw points map to the percentage output through the following logic:

• points ≥ threshold: Returns 100% (definite VM indication)
• 100 ≤ points < threshold: Returns 99% (very strong indication)
• points < 100: Returns min(points, 99) (0-99% proportional to evidence)

Notably, the library deliberately avoids returning 100% for a raw score of exactly 100 to prevent false-positive "perfect" scores, requiring the score to exceed the higher threshold before reporting certainty.

Interpreting the Confidence Score

The returned percentage falls into four distinct diagnostic categories:

0% indicates that no detection technique identified virtualization artifacts. The environment is almost certainly not virtualized.

1-98% represents partial evidence where the library remains uncertain. While the number reflects accumulated detection weight, the documentation explicitly warns against using these intermediate values as binary decisions.

99% indicates very strong evidence (raw score ≥100 but < threshold). Despite the high number, this remains a probabilistic assessment rather than a guarantee.

100% signifies that the confidence exceeds the configured threshold (default ~150, or ~300 with HIGH_THRESHOLD). This represents the strongest possible indication of virtualization, though the documentation still recommends pairing this with additional security measures.

According to docs/documentation.md, you should not base security decisions solely on this percentage. The function is designed primarily as a diagnostic and visibility tool, with VM::detect() providing the definitive binary verdict.

Effect of HIGH_THRESHOLD Flag

When you invoke VM::percentage(VM::HIGH_THRESHOLD), the library switches to a stricter detection regime. This flag raises the internal threshold_score to high_threshold_score (approximately 300), requiring significantly more concurrent detection triggers before reporting 100% confidence.

Use this mode when false positives must be minimized, accepting that genuine VMs with subtle fingerprints might return lower percentages or require additional verification.

Practical Code Examples

Basic Usage with Default Techniques

The following example demonstrates standard invocation without flags, yielding a 0-100 confidence score:

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

int main() {
    std::uint8_t percent = VM::percentage();   // Returns 0-100
    std::cout << "VM likelihood: " << static_cast<int>(percent) << "%\n";

    if (percent == 100) {
        std::cout << "High confidence: Virtual machine detected\n";
    } else if (percent == 0) {
        std::cout << "High confidence: Bare metal detected\n";
    } else {
        std::cout << "Ambiguous result - consider VM::detect() for binary answer\n";
    }
}

Selective Technique Evaluation

You can restrict the percentage calculation to specific detection vectors:

// Only evaluate CPU brand and hypervisor string techniques
std::uint8_t percent = VM::percentage(VM::CPU_BRAND, VM::HYPERVISOR_STR);
std::cout << "Selective technique confidence: " << static_cast<int>(percent) << "%\n";

High-Threshold Mode

For environments requiring reduced false-positive rates:

std::uint8_t percent = VM::percentage(VM::HIGH_THRESHOLD);
std::cout << "Strict mode confidence: " << static_cast<int>(percent) << "%\n";

CLI Integration

The command-line interface exposes this functionality via the --percent (or -p) flag, implemented in src/cli.cpp (lines 338-1062):

$ ./vmaware-cli -p
VM likeliness: 87%

Summary

• VM::percentage() returns a std::uint8_t from 0-100 representing VM detection confidence in the VMAware library.
• The calculation aggregates raw scores (0-300) from enabled techniques, mapping them against thresholds (~150 normal, ~300 strict).
• 0% indicates no virtualization, 100% exceeds the threshold, and intermediate values represent partial evidence.
• The HIGH_THRESHOLD flag increases the threshold to ~300, reducing false positives at the cost of detection sensitivity.
• Never use percentage values alone for security decisions; rely on VM::detect() for binary determinations.

Frequently Asked Questions

What is the range of values returned by VM::percentage()?

The function returns a std::uint8_t between 0 and 100, inclusive. This represents a percentage scale where 0 indicates no virtualization detected and 100 indicates the raw detection score exceeded the configured threshold (approximately 150 in normal mode or 300 in high-threshold mode).

Why does VMAware never return 100% for a raw score of exactly 100?

The implementation deliberately maps raw scores of exactly 100 to 99% to avoid the implication of a "perfect" or infallible detection. Only scores that meet or exceed the higher threshold values (150 or 300) trigger a 100% return, ensuring that the highest confidence level requires substantial concurrent evidence from multiple detection techniques.

Should I use percentage() or detect() for security decisions?

According to the official documentation in docs/documentation.md, you should use VM::detect() for security decisions and binary determinations. The percentage() function is primarily a diagnostic tool for visibility into detection confidence. While 100% indicates strong evidence, the library authors explicitly warn against using percentage values as the sole basis for security enforcement.

Where is the percentage calculation implemented in the source code?

The core logic resides in src/vmaware.hpp around lines 12150-1220 (depending on version). This implementation includes the core::arg_handler for flag processing, core::run_all() for technique execution, and the mapping logic that converts raw detection points (0-300) into the final 0-100 percentage output. The CLI wrapper exposing this functionality is located in src/cli.cpp, and performance benchmarks are available in auxiliary/benchmark.cpp.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}