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

> Understand VMAware percentage() output. Learn how this uint8 value represents VM detection confidence from 0 to 100 based on enabled techniques.

- Repository: [Louis/vmaware](https://github.com/kernelwernel/vmaware)
- Tags: how-to-guide
- Published: 2026-03-05

---

**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`](https://github.com/kernelwernel/vmaware/blob/main/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`](https://github.com/kernelwernel/vmaware/blob/main/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`](https://github.com/kernelwernel/vmaware/blob/main/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:

```cpp
#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:

```cpp
// 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:

```cpp
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`](https://github.com/kernelwernel/vmaware/blob/main/src/cli.cpp) (lines 338-1062):

```bash
$ ./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`](https://github.com/kernelwernel/vmaware/blob/main/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`](https://github.com/kernelwernel/vmaware/blob/main/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`](https://github.com/kernelwernel/vmaware/blob/main/src/cli.cpp), and performance benchmarks are available in [`auxiliary/benchmark.cpp`](https://github.com/kernelwernel/vmaware/blob/main/auxiliary/benchmark.cpp).