NtWaitForDebugEvent

Prototype

NTSTATUS NtWaitForDebugEvent(
  HANDLE                      DebugObjectHandle,
  BOOLEAN                     Alertable,
  PLARGE_INTEGER              Timeout,
  PDBGUI_WAIT_STATE_CHANGE    StateChange
);

Arguments

Syscall IDs by Windows version

Syscall stub

4C 8B D1            mov r10, rcx
B8 E4 01 00 00      mov eax, 0x1E4     ; Win11 24H2 SSN
F6 04 25 08 03 FE 7F 01   test byte ptr [0x7FFE0308], 1
75 03               jne short +3
0F 05               syscall
C3                  ret
CD 2E               int 2Eh
C3                  ret

Undocumented notes

The kernel-side primitive sitting under `WaitForDebugEventEx`. A debugger attaches by creating (or opening) a debug object with `NtCreateDebugObject` and binding it to a target process via `NtDebugActiveProcess`, then loops on `NtWaitForDebugEvent` to receive the canonical state changes: `DbgCreateProcessStateChange`, `DbgCreateThreadStateChange`, `DbgLoadDllStateChange`, `DbgExceptionStateChange` (the big one — breakpoint, single-step, access violation), `DbgExitThreadStateChange`, `DbgExitProcessStateChange`, `DbgUnloadDllStateChange`. Each event must be acknowledged with `NtDebugContinue`. The `DBGUI_WAIT_STATE_CHANGE` union carries event-specific data — a CONTEXT for exceptions, image base/name for module loads, exit codes, etc.

Common malware usage

Two distinct offensive shapes. (1) **Self-debug anti-attach**: the process creates a debug object, attaches it to itself (or to a child it spawns), and loops on `NtWaitForDebugEvent` from a dedicated worker thread. Because Windows allows only one debugger per process, an external `windbg`/`x64dbg` can no longer attach — its `DebugActiveProcess` fails with `STATUS_PORT_ALREADY_SET`. Packers like Themida and a handful of crypters ship variants of this. (2) **Headless debugger** for instrumenting a child without spawning a visible UI — useful for malware that needs to step through unpacked code or react to specific exceptions in another binary. Inverse-side, anti-anti-debug tools (TitanHide, ScyllaHide) use the same primitives to keep the debug loop alive while filtering events visible to the analyst.

Detection opportunities

`NtCreateDebugObject` followed shortly by `NtDebugActiveProcess(self_or_child)` and a thread parked in `NtWaitForDebugEvent` is the canonical fingerprint. ETW Microsoft-Windows-Kernel-Process emits process-debug-port-set events. The `EPROCESS.DebugPort` field becoming non-NULL on a non-developer-tool process is very high-signal — kernel callbacks via `PsSetCreateProcessNotifyRoutineEx2` and the EDR's protected-process protections catch this. From user mode, `NtQueryInformationProcess` with `ProcessDebugPort`/`ProcessDebugObjectHandle` reveals the attachment, which is exactly why packers freeze that path with hook detours.

Direct syscall examples

// Run in a dedicated thread spawned at startup. After this returns,
// no external debugger can attach until the debug object handle is closed.
DWORD WINAPI SelfDebugLoop(LPVOID arg) {
    HANDLE hDbg = NULL;
    OBJECT_ATTRIBUTES oa = { sizeof(oa) };
    NTSTATUS st = NtCreateDebugObject(&hDbg, DEBUG_ALL_ACCESS, &oa, 0);
    if (!NT_SUCCESS(st)) return st;

    // Attach to ourselves — blocks future DebugActiveProcess() from any other tool.
    st = NtDebugActiveProcess(NtCurrentProcess(), hDbg);
    if (!NT_SUCCESS(st)) return st;

    DBGUI_WAIT_STATE_CHANGE sc;
    for (;;) {
        st = NtWaitForDebugEvent(hDbg, FALSE, NULL, &sc);
        if (!NT_SUCCESS(st)) break;

        // Pass everything through so the debuggee keeps running.
        NtDebugContinue(hDbg, &sc.AppClientId, DBG_CONTINUE);
    }
    return 0;
}

; NtWaitForDebugEvent direct syscall (Win11 24H2 SSN 0x1E4)
NtWaitForDebugEvent PROC
    mov  r10, rcx
    mov  eax, 1E4h
    syscall
    ret
NtWaitForDebugEvent ENDP

// Cargo: windows-sys = "0.59"
use windows_sys::Win32::Foundation::HANDLE;
use windows_sys::Win32::System::LibraryLoader::*;

type WaitFn = unsafe extern "system" fn(HANDLE, u8, *const i64, *mut [u8; 0xD8]) -> i32;
type ContFn = unsafe extern "system" fn(HANDLE, *const [usize; 2], i32) -> i32;

unsafe fn drain(dbg: HANDLE) {
    let nt = GetModuleHandleA(b"ntdll.dll\0".as_ptr());
    let wait: WaitFn = std::mem::transmute(
        GetProcAddress(nt, b"NtWaitForDebugEvent\0".as_ptr()).unwrap());
    let cont: ContFn = std::mem::transmute(
        GetProcAddress(nt, b"NtDebugContinue\0".as_ptr()).unwrap());
    let mut sc = [0u8; 0xD8];
    loop {
        if wait(dbg, 0, std::ptr::null(), &mut sc) < 0 { break; }
        let cid_ptr = sc.as_ptr().add(8) as *const [usize; 2]; // AppClientId
        // 0x00010002 = DBG_CONTINUE
        cont(dbg, cid_ptr, 0x00010002);
    }
}

MITRE ATT&CK mappings

• T1622Debugger Evasionmitre ↗
• T1106Native APImitre ↗