Desktop - Debugger - Detector (Pro)

Debuggers let an attacker pause your game, inspect memory, change values, and step through your code. There are two flavours: user-mode debuggers attached to your process (e.g. Visual Studio, dnSpy, x64dbg, OllyDbg, JetBrains debugger) and kernel-mode debuggers attached to the system (e.g. WinDbg in /KD mode, Syser, SoftICE). Use the 'DebuggerDetector' to detect both and react accordingly.

Detector

The 'DebuggerDetector' does not require any monitor. On demand, it queries multiple debugger sources and aggregates the results:

  1. Managed debugger: Reads 'System.Diagnostics.Debugger.IsAttached' to detect a managed debugger like the Unity Editor debugger or the Visual Studio managed debugger.

  2. User-mode debugger: Asks the platform-specific 'IPlatformProbe.IsUserModeDebuggerPresent'. On Windows this combines 'kernel32!IsDebuggerPresent', 'kernel32!CheckRemoteDebuggerPresent', and 'ntdll!NtQueryInformationProcess' against 'ProcessDebugPort', 'ProcessDebugObjectHandle', and 'ProcessDebugFlags'. On macOS it inspects the 'P_TRACED' flag returned by 'sysctl' with 'KERN_PROC_PID'. On Linux it parses 'TracerPid' from '/proc/self/status'.

  3. Kernel-mode debugger: Asks the platform-specific 'IPlatformProbe.IsKernelModeDebuggerPresent'. On Windows this calls 'ntdll!NtQuerySystemInformation' with 'SystemKernelDebuggerInformation' and reports a kernel debugger that is enabled and present. On macOS and Linux, kernel-mode debugger detection is currently a no-op and reserved for a future native plugin probe.

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.

Detector Status

When a debugger is found, the detector notifies its observers with a 'DesktopCheatingDetectionStatus' which implements 'IDesktopCheatingDetectionStatus'. The status contains the following properties:

  1. PossibilityOfFalsePositive: A value indicating the possibility of a false positive when assessing threats for the implementing subject, from 0.0 to 1.0.
  2. ThreatRating: The threat rating associated with the detected cheating, indicating the assessed level of a potential threat.
  3. DesktopCheatingType: The type of cheating detected on the desktop platform.
  4. Evidence: A short, human-readable string describing what triggered the detection (e.g. 'IsDebuggerPresent', 'ProcessDebugPort=0x...', 'KernelDebuggerEnabled').

The 'DesktopCheatingType' property can take the following values for this detector:

  • DEBUGGER_USER_MODE: A user-mode debugger is currently attached to the process.
  • DEBUGGER_KERNEL_MODE: A kernel-mode debugger is currently active on the system.
  • DEBUGGER_REMOTE: A remote debugger is currently attached or a debug port has been assigned to the process.

Supported Platforms

The detector is available on Windows, macOS, and Linux Standalone players.

  • User-mode debugger detection is implemented on all three platforms.
  • Kernel-mode debugger detection is currently implemented on Windows only; on macOS and Linux the kernel-mode probe returns false and 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 - this is important because the Unity Editor itself counts as a managed debugger.

How To Use

The usage is straightforward: attach a 'DebuggerDetector' 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 'DebuggerDetector' MonoBehavior from the 'GUPS.AntiCheat.Detector.Desktop' namespace to your 'AntiCheat-Monitor' GameObject, or better, to a child GameObject.

Settings

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

  • 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.
  • Scan 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 queries the managed and native debugger sources and notifies observers if a debugger 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 debugger 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 - keep this off in production-like testing or you will permanently report a debugger.
  • Detect User-Mode Debugger: 'Desktop_DetectUserModeDebugger'. Master switch for the user-mode probe. On by default.
  • Detect Kernel-Mode Debugger: 'Desktop_DetectKernelModeDebugger'. Master switch for the kernel-mode probe. On by default; effective only on Windows for now.
  • Report Managed Debugger Only: 'Desktop_Debugger_ReportManagedOnly'. When true, the detector only reports if 'Debugger.IsAttached' is true and ignores the native probes. Useful when shipping a Development Build to your QA team.

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<DebuggerDetector>();

// 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.