Desktop - Virtual Environment - Detector (Pro)

A frequent cheating pattern on desktop is running your game inside a virtual machine (e.g. VMware, VirtualBox, Hyper-V, QEMU/KVM, Parallels) to ease memory inspection, snapshot and rewind game state, or run automation farms. Use the 'VirtualEnvironmentDetector' to detect a virtualized host and react accordingly.

Detector

The 'VirtualEnvironmentDetector' does not require any monitor. On demand, it performs three independent scans:

  1. MAC address OUI scan: Iterates 'NetworkInterface.GetAllNetworkInterfaces()' and checks the OUI prefix (the first three bytes of each adapter's MAC address) against the configured list of vendor OUIs (e.g. '08:00:27' VirtualBox, '00:0C:29' / '00:50:56' VMware, '00:15:5D' Hyper-V, '52:54:00' QEMU/KVM, '00:1C:42' Parallels).

  2. BIOS / DMI string scan: Asks the platform-specific 'IPlatformProbe.IsRunningInVirtualMachine'. On Windows this reads HKLM 'HARDWARE\DESCRIPTION\System\BIOS' (vendor, version, system manufacturer, system product) and probes well-known guest service registry keys (e.g. VBoxService, vmtools) using direct 'advapi32.dll' P/Invokes. On macOS it queries 'sysctlbyname' for 'hw.model' and related identifiers. On Linux it reads '/sys/class/dmi/id/sys_vendor', 'product_name', 'bios_vendor', and 'board_vendor'.

  3. Hypervisor bit: Asks the platform-specific 'IPlatformProbe.IsHypervisorBitSet'. On Linux this checks for the 'hypervisor' flag in '/proc/cpuinfo'. On Windows and macOS this is currently a no-op and reserved for a future native plugin probe that reads CPUID directly.

Observed Subject

The detector does not observe any monitor. It runs an on-demand scan when 'ManualScan()' is invoked or, if enabled, automatically during 'Start' and on a configurable interval.

Status

When a virtual environment is found, the detector notifies its observers with a DesktopCheatingDetectionStatus, which implements IDesktopCheatingDetectionStatus (and therefore IDetectorStatus):

public struct DesktopCheatingDetectionStatus : IDesktopCheatingDetectionStatus
{
    // Probability that the detection is a false positive, in the range [0.0, 1.0].
    public float PossibilityOfFalsePositive { get; }

    // The threat rating reported with this detection.
    public uint ThreatRating { get; }

    // The type of cheating detected on the desktop platform.
    public EDesktopCheatingType DesktopCheatingType { get; }

    // A short, human-readable string describing what triggered the detection.
    public string Evidence { get; }
}
  • Evidence: For example the matching OUI, BIOS value, or service key.

For this detector, DesktopCheatingType can be:

public enum EDesktopCheatingType : byte
{
    VIRTUAL_MACHINE_BIOS = 30,           // BIOS / DMI strings indicate a VM vendor.
    VIRTUAL_MACHINE_MAC = 31,            // A MAC address belongs to a known VM vendor OUI.
    VIRTUAL_MACHINE_HYPERVISOR_BIT = 32, // The CPUID hypervisor bit is set (future native probe).
    VIRTUAL_MACHINE_PROCESS = 33         // A VM guest-additions process is running.
}

Threat rating and false positives

  • PossibilityOfFalsePositive: default 0.15 (range 0-1). Set high, because many legitimate users run inside Hyper-V / WSL2 / cloud-streamed Windows.
  • ThreatRating: default 200 (recommended 200; raise if your game must not run in a VM).

Configuration

  • Is Active (isActive, bool, default true) - whether the detector is active and watching.
  • Possibility Of False Positive (possibilityOfFalsePositive, float, default 0.15, range 0-1).
  • Threat Rating (threatRating, uint, default 200).
  • On Cheating Detection Event (OnCheatingDetectionEvent) - a UnityEvent raised on every detection.
  • Check Only On Game Start (CheckOnlyOnGameStart, bool, default true) - run the VM check only once on start; disable to also run a periodic recheck. The result of a VM check rarely changes during a session.
  • Recheck Interval For Possible Cheating (RecheckIntervalForPossibleCheating, float, default 120, range 1-600) - interval in seconds between checks.

The MAC OUIs and BIOS keywords to scan for are configured in the global project settings (see 'Configure Desktop Settings' below).

Supported Platforms

The detector is available on Windows, macOS, and Linux Standalone players. The MAC OUI scan is fully cross-platform. The BIOS/DMI scan uses platform-specific probes. The hypervisor-bit probe is currently effective on Linux; Windows and macOS coverage is reserved for a future native plugin.

Requirements

There are no native requirements; the detector uses managed APIs and platform P/Invokes provided by the package. In the Unity Editor and in Development Builds, the detector only runs when 'Desktop_Enable_Development' is enabled in the global AntiCheat settings.

False Positives

VM detection is the most false-positive-prone of the desktop detectors: many legitimate users (developers, QA, cloud-streaming providers, security-conscious players, corporate laptops with Hyper-V enabled) run inside virtual environments. We recommend pairing this detector with a soft reaction (e.g. flag the session, reduce trust score, disable leaderboards) rather than immediately exiting the game. The 'PossibilityOfFalsePositive' value reflects this, and the configurable threat rating lets you tune severity.

How To Use

The usage is straightforward: attach a 'VirtualEnvironmentDetector' to a child GameObject of the 'AntiCheat-Monitor', configure the global Desktop settings, and define a reaction to detected cheating.

Requirements

There are none. No additional monitor is required.

Add Detector Component

Manual

Add the 'VirtualEnvironmentDetector' MonoBehavior from the 'GUPS.AntiCheat.Detector.Desktop' namespace to your 'AntiCheat-Monitor' GameObject, or better, to a child GameObject.

Add the 'VirtualEnvironmentDetector' as a Component.

Settings

After attaching the 'VirtualEnvironmentDetector' MonoBehavior to a GameObject, you will see the following in the inspector:

The settings of the 'VirtualEnvironmentDetector' Component (shown together with the 'DebuggerDetector').

  • General Settings: Define here whether the detector should be active.
  • Threat Rating Settings: Define here the severity of the detected cheating.
  • Observable Settings: Add here callbacks invoked when cheating is detected.
  • Virtual Environment Settings: Set whether the scan runs once on Start and/or repeats on a configurable interval.

Runtime

On Start (and on the configured interval), the detector runs the OUI, BIOS/DMI, and hypervisor-bit checks and notifies observers if a virtual environment is found. You can also trigger 'ManualScan()' yourself.

Configure Desktop Settings

Open 'Edit -> Project Settings -> GuardingPearSoftware -> AntiCheat' and switch to the 'Desktop' tab.

In the AntiCheat Project Settings, configure the Desktop virtual environment detection.

Use the following entries to control this detector:

  • Enable in Development: 'Desktop_Enable_Development'. Set to true to allow detection inside the Unity Editor and Development Builds. Off by default.
  • Detect Virtual Machine: 'Desktop_DetectVirtualMachine'. Master switch for this detector. On by default.
  • Virtual Machine MAC OUIs: 'Desktop_VirtualMachine_MacOuis'. List of case-insensitive MAC address OUIs (first three bytes), with or without separators (e.g. '080027', '08-00-27', '08:00:27'). Used to identify VM-vendor network adapters.
  • Virtual Machine BIOS Keywords: 'Desktop_VirtualMachine_BiosKeywords'. List of case-insensitive substrings to look for in BIOS / DMI strings (e.g. 'VirtualBox', 'VMware', 'Hyper-V', 'QEMU', 'Xen', 'Parallels').

When any of these lists is empty, the detector falls back to a built-in default list of well-known virtualization vendors.

Consume the detection in code

Besides the inspector event, you can subscribe your own observer. Every detector derives from ADetector and exposes Subscribe(IObserver<IDetectorStatus>), which returns an IDisposable you can dispose to unsubscribe. Cast the status to DesktopCheatingDetectionStatus to read the desktop-specific fields:

using System;
using GUPS.AntiCheat;
using GUPS.AntiCheat.Core.Detector;
using GUPS.AntiCheat.Detector.Desktop;
using UnityEngine;

public class VirtualEnvironmentDetectionLogger : MonoBehaviour, IObserver<IDetectorStatus>
{
    private void Start()
    {
        var detector = AntiCheatMonitor.Instance.GetDetector<VirtualEnvironmentDetector>();
        detector.Subscribe(this);
    }

    public void OnNext(IDetectorStatus status)
    {
        if (status is DesktopCheatingDetectionStatus desktopStatus)
        {
            Debug.LogWarning($"Virtual environment detected: {desktopStatus.DesktopCheatingType} " +
                             $"(threat={desktopStatus.ThreatRating}, evidence={desktopStatus.Evidence}).");
        }
    }

    public void OnError(Exception error) { }
    public void OnCompleted() { }
}

React On Cheating

When the detector is set up, you surely want to react to detected cheating.

Punisher

In general, any cheat detected is forwarded to the 'AntiCheat-Monitor', which calculates an overall threat level. Based on the threat level, you can apply punishments by using Punisher components added to a child GameObject of the 'AntiCheat-Monitor'. There are some built-in punishers that you can find here as prefabs:

The location of the built-in Punisher prefabs.

Inspector

You can set a callback in the Unity Inspector view of the detector. This callback is invoked as soon as the specific cheating is detected.

Code

If you would like to write a custom listener for the detector, you can attach an observer:

// Get the detector.
var detector = AntiCheatMonitor.Instance
      .GetDetector<VirtualEnvironmentDetector>();

// Subscribe as observer and get notified on inconsistency.
detector.Subscribe(myObserver);

The detector also has an inherited property 'PossibleCheatingDetected' which is set to true once cheating has been detected.