Contents

• VM::detect()
• VM::percentage()
• VM::brand()
• VM::check()
• VM::add_custom()
• VM::type()
• VM::conclusion()
• VM::detected_count()
• VM::is_hardened()
• (Advanced) VM::flag_to_string()
• (Advanced) VM::detected_enums()
• vmaware struct
• Notes and overall things to avoid
• Flag table
• Brand table
• Setting flags
• Variables
• CLI documentation

VM::detect()

This is basically the main function you're looking for, which returns a bool. If no parameter is provided, all the recommended checks will be performed. But you can optionally set which techniques are used.

#include "vmaware.hpp"

int main() {
    /**
     * The basic way to detect a VM where the default checks will 
     * be performed. This is the recommended usage of the lib.
     */ 
    bool is_vm = VM::detect();


    /**
     * This does the exact same as above, but as an explicit alternative.
     */ 
    bool is_vm2 = VM::detect(VM::DEFAULT);


    /**
     * All checks are performed including techniques that are
     * disabled by default for a viariety of reasons. If you 
     * want all techniques for the sake of completeness, then 
     * you can use this flag but remember that there may be potential 
     * performance bottlenecks and an increase in false positives.
     */ 
    bool is_vm3 = VM::detect(VM::ALL);


    /**
     * This will raise the detection threshold above the default level.
     * Use this if you want to be extremely sure if it's a VM, but this 
     * increases the chance of a false negative. Use VM::percentage() 
     * for a more precise result if you want.
     */ 
    bool is_vm4 = VM::detect(VM::HIGH_THRESHOLD);


    /**
     * Essentially means only the CPU brand, MAC, and hypervisor bit techniques 
     * should be performed. Note that the less technique flags you provide, the more 
     * likely the result will not be accurate. If you just want to check for 
     * a single technique, use VM::check() instead. Also, read the flag table
     * at the end of this doc file for a full list of technique flags.
     */
    bool is_vm5 = VM::detect(VM::CPU_BRAND, VM::MAC, VM::HYPERVISOR_BIT);


    /**
     * If you want to disable any technique for whatever reason, use VM::DISABLE(...).
     * This code snippet essentially means "perform all the default flags, but only 
     * disable the VM::RDTSC technique". 
     */ 
    bool is_vm6 = VM::detect(VM::DISABLE(VM::RDTSC));


    /**
     * Same as above, but you can disable multiple techniques at the same time.
     */ 
    bool is_vm7 = VM::detect(VM::DISABLE(VM::VMID, VM::RDTSC, VM::HYPERVISOR_BIT));


    /**
     * This is just an example to show that you can use a combination of 
     * different flags and non-technique flags with the above examples. 
     */ 
    bool is_vm8 = VM::detect(VM::DEFAULT, VM::HIGH_THRESHOLD, VM::DISABLE(VM::RDTSC, VM::VMID));
}

VM::percentage()

This will return a std::uint8_t between 0 and 100. It'll return the certainty of whether it has detected a VM based on all the techniques available as a percentage.

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

int main() {
    // uint8_t and unsigned char works too
    const std::uint8_t percent = VM::percentage();

    if (percent == 100) {
        std::cout << "Definitely a VM!\n";
    } else if (percent == 0) {
        std::cout << "Definitely NOT a VM\n";
    } else {
        std::cout << "Unsure if it's a VM\n";
    }

    // converted to int for console character encoding reasons
    std::cout << "percentage: " << static_cast<int>(percent) << "%\n"; 

    return 0;
}

VM::brand()

This will essentially return the VM brand as a std::string. All the brands and brand alias variables are listed here

If none were detected, it will return Unknown. It should be noted that this could be a common scenario even if you're running inside a VM due to technical difficulties with accomplishing this. This is especially true for VMware sub-versions (ESX, GSX, Fusion, etc...). It's not recommended to rely on this function for critical operations as if your whole program depends on it.

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

int main() {
    const std::string result = VM::brand();

    if (result == "KVM") {
        // do KVM specific stuff
    } else if (result == "VirtualBox") {
        // you get the idea
    } else if (result == brands::VMWARE) {
        // having manual string comparisons like the two
        // previous ones can lead to typos which will 
        // make the whole check completely redundant.
        // So the lib provides hardcoded string variables 
        // as aliases to avoid these kinds of situations. 
        // They are located in the aforementioned brand table
    }

    return 0;
}

On rare occasions, there might be cases where there's multiple brands that have been detected, which might cause a conflicting output with an inaccurate result. To prevent this, you can use the VM::MULTIPLE flag that returns a message rather than a VM brand string. For example, if it found 2 conflicting brands, it will return VMware or VirtualBox. For 3 conflicts, it's VMware or VirtualBox or QEMU and so on.

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

int main() {
    // format: "vmbrand1 or vmbrand2 [or vmbrandx...]"
    const std::string result = VM::brand(VM::MULTIPLE);

    // example output: "VMware or Bochs"
    std::cout << result << "\n";

    // Keep in mind that there's no limit to how many conflicts there can be.
    // And if there's no conflict, it'll revert back to giving the brand string
    // normally as if the VM::MULTIPLE wasn't there

    return 0;
}

VM::check()

This takes a single technique argument and returns a bool. It essentially returns a technique's effective output. Nothing more, nothing less.

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

int main() {
    if (VM::check(VM::VMID)) {
        std::cout << "VMID technique detected a VM!\n";
    }

    if (VM::check(VM::HYPERVISOR_BIT)) {
        std::cout << "Hypervisor bit is set, most definitely a VM!\n";
    }

    return 0;
}

VM::add_custom()

This function allows you to add your own custom VM detection techniques to the scoring system. The first parameter is the percentage score (0 to 100) of how likely it's a VM if your custom code returns true, and the second parameter should either be a lambda, a function pointer, or a std::function<bool()>

// Example 1 with function pointers

bool new_technique() {
    // add your VM detection code here
    return true; 
}

VM::add_custom(50, new_technique);

// Example 2 with lambdas

VM::add_custom(50, []() -> bool { 
    // add your VM detection code here
    return true; 
});

auto new_technique = []() -> bool { 
    // add your VM detection code here
    return true;
}

VM::add_custom(50, new_technique);

// Example 3 with std::function

std::function<bool()> new_technique = []() -> bool {
    // add your VM detection code here
    return true;
};

VM::add_custom(50, new_technique);

VM::type()

This will return the VM type (or architecture) as a std::string based on the brand found. The possible return values are listed here in the type column.

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

int main() {
    // example output: VirtualBox is a Hypervisor (type 2) VM
    std::cout << VM::brand() << " is a " << VM::type() << " VM\n";
    return 0;
}

VM::conclusion()

This will return the "conclusion" message of what the overall result is as a std::string. By default, there are 2 possible outputs:

• Running on baremetal
• Running inside a [brand] VM

The [brand] part might contain a brand or may as well be empty, depending on whether a brand has been found. Additionally, you can extend this by adding the VM::DYNAMIC flag which will now allow much more variadic potential outputs:

• Running on baremetal
• Very unlikely a [brand] VM
• Unlikely a [brand] VM
• Potentially a [brand] VM
• Might be a [brand] VM
• Likely a [brand] VM
• Very likely a [brand] VM
• Running inside a [brand] VM

VM::detected_count()

This will fetch the number of techniques that have been detected as a std::uint8_t.

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

int main() {
    const std::uint8_t count = VM::detected_count();

    // output: 7 techniques were detected
    std::cout << count << " techniques were detected" << "\n"; 

    // note that if it's baremetal, it should be 0.
    // if it's a VM, it should have at least 4 to  
    // maybe around 15 max. The most I've seen was 
    // around 18 but that only occurs very rarely.

    return 0;
}

VM::is_hardened()

This will detect whether the environment has any hardening indications as a bool.

Internally, this function works by analysing which combination of techniques are expected to be detected together. If a certain combination rule is mismatched, it indicates some kind of tampering of the system which assumes some sort of VM hardening.

Similiary to VM::brand(), do not rely on this function for critical operations. This is meant to be a heuristic assumption rather than a concrete guarantee.

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

int main() {
    if (VM::is_hardened()) {
        std::cout << "Potential hardening detected" << "\n";
    } else {
        std::cout << "Unsure if hardened" << "\n";
    }

    return 0;
}

(Advanced) VM::flag_to_string()

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

int main() {
    const std::string name = VM::flag_to_string(VM::VMID);

    // output: VM::VMID 
    std::cout << "VM::" << name << "\n"; 

    return 0;
}

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

int main() {
    // this will loop through all the enums in the technique_vector variable,
    // and then checks each of them and outputs the enum that was detected
    for (const auto technique_enum : VM::technique_vector) {
        if (VM::check(technique_enum)) {
            const std::string name = VM::flag_to_string(technique_enum);
            std::cout << "VM::" << name << " was detected\n";
        }
    }

    return 0;
}

(Advanced) VM::detected_enums()

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

int main() {
    std::vector<VM::enum_flags> flag_list = VM::detected_enums();

    for (const auto flag : flag_list) {
        std::cout << "VM::" << VM::flag_to_string(flag) << " was detected" << "\n"; 
    }

    return 0;
}

vmaware struct

If you prefer having an object to store all the relevant information about the program's environment instead of calling static member functions, you can use the VM::vmaware struct:

struct vmaware {
    std::string brand;
    std::string type;
    std::string conclusion;
    bool is_vm;
    bool is_hardened;
    std::uint8_t percentage;
    std::uint8_t detected_count;
    std::uint8_t technique_count;
    std::vector<enum_flags> detected_techniques;
    std::vector<std::string> detected_technique_strings;
    std::vector<enum_flags> disabled_techniques;
}; 

example:

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

int main() {
    VM::vmaware vm;

    std::cout << "Is this a VM? = " << vm.is_vm << "\n";
    std::cout << "How many techniques detected a VM? = " << vm.detected_count << "%\n";
    std::cout << "What's the VM's type? = " << vm.type << "%\n";
    std::cout << "What's the overview in a human-readable message?" << vm.conclusion << "\n";
}

Notes and overall things to avoid

❌ 1. Do NOT rely on the percentage to determine whether you're in a VM. The lib is not designed for this way, and you're potentially increasing false positives. Use VM::detect() instead for that job.

❌ 2. Do NOT depend your whole program on whether a specific brand was found. VM::brand() will not guarantee it'll give you the result you're looking for even if the environment is in fact that specific VM brand.

// wrapper.hpp
#include <string>

namespace wrapper {
    bool is_this_a_vm();
    std::string vm_brand_name();
}

// wrapper.cpp
#include "vmaware.hpp"
#include "wrapper.hpp"

bool wrapper::is_this_a_vm() {
    return VM::detect();
}

std::string wrapper::vm_brand_name() {
    return VM::brand();
}

// something.cpp
#include "wrapper.hpp"

void something() {
    if (wrapper::is_this_a_vm()) {
        std::cout << wrapper::vm_brand_name() << "\n";
    }
}

Flag table

VMAware provides a convenient way to not only check for VMs, but also have the flexibility and freedom for the end-user to choose what techniques are used with complete control over what gets executed or not. This is handled with a flag system.

Brand table

This is the table of all the brands the lib supports.

Setting flags

Variables

CLI documentation