Windows Debugging APIs
Windows Internals for Low-Level Programming · Windows Programming track
10 min read
In this module
Building Debuggers with the Windows Debug API
The Windows debugging API lets one process control another: set breakpoints, single-step, read and write memory, intercept exceptions. Understanding it demystifies how WinDbg, x64dbg, and Visual Studio work under the hood, and it's the foundation for building security tools, profilers, and custom analysis frameworks.
The Debug Loop
A debugger attaches to a target process and enters a loop that receives debug events:
#include <windows.h>#include <stdio.h>
int main(int argc, char *argv[]) { // Start a process under the debugger STARTUPINFO si = { .cb = sizeof(si) }; PROCESS_INFORMATION pi;
CreateProcess(NULL, argv[1], NULL, NULL, FALSE, DEBUG_PROCESS, // We are the debugger NULL, NULL, &si, &pi);
// Debug event loop DEBUG_EVENT dbgEvent; BOOL running = TRUE;
while (running) { // Wait for a debug event from the target WaitForDebugEvent(&dbgEvent, INFINITE);
DWORD continueStatus = DBG_CONTINUE;
switch (dbgEvent.dwDebugEventCode) { case CREATE_PROCESS_DEBUG_EVENT: printf("Process created: PID %lu\n", dbgEvent.dwProcessId); printf(" Base: %p\n", dbgEvent.u.CreateProcessInfo.lpBaseOfImage); printf(" Entry: %p\n", dbgEvent.u.CreateProcessInfo.lpStartAddress); break;
case CREATE_THREAD_DEBUG_EVENT: printf("Thread created: TID %lu\n", dbgEvent.dwThreadId); break;
case LOAD_DLL_DEBUG_EVENT: printf("DLL loaded at %p\n", dbgEvent.u.LoadDll.lpBaseOfDll); break;
case EXCEPTION_DEBUG_EVENT: { EXCEPTION_RECORD *rec = &dbgEvent.u.Exception.ExceptionRecord; printf("Exception: 0x%08X at %p", rec->ExceptionCode, rec->ExceptionAddress);
if (rec->ExceptionCode == EXCEPTION_BREAKPOINT) { printf(" (breakpoint)\n"); } else if (rec->ExceptionCode == EXCEPTION_SINGLE_STEP) { printf(" (single step)\n"); } else { printf(" (first chance=%d)\n", dbgEvent.u.Exception.dwFirstChance); continueStatus = DBG_EXCEPTION_NOT_HANDLED; } break; }
case EXIT_PROCESS_DEBUG_EVENT: printf("Process exited: code %lu\n", dbgEvent.u.ExitProcess.dwExitCode); running = FALSE; break; }
// Resume the target ContinueDebugEvent(dbgEvent.dwProcessId, dbgEvent.dwThreadId, continueStatus); }
CloseHandle(pi.hProcess); CloseHandle(pi.hThread); return 0;}Debug Event Types
┌──────────────────────────────┬──────────────────────────────┐│ Event │ When │├──────────────────────────────┼──────────────────────────────┤│ CREATE_PROCESS_DEBUG_EVENT │ Target process starts ││ CREATE_THREAD_DEBUG_EVENT │ New thread in target ││ LOAD_DLL_DEBUG_EVENT │ DLL loaded in target ││ UNLOAD_DLL_DEBUG_EVENT │ DLL unloaded from target ││ OUTPUT_DEBUG_STRING_EVENT │ OutputDebugString called ││ EXCEPTION_DEBUG_EVENT │ Exception in target ││ EXIT_THREAD_DEBUG_EVENT │ Thread exits ││ EXIT_PROCESS_DEBUG_EVENT │ Process exits ││ RIP_EVENT │ System debugging error │└──────────────────────────────┴──────────────────────────────┘When a debug event occurs, the target thread is suspended. The debugger receives the event through WaitForDebugEvent, processes it, and then calls ContinueDebugEvent to resume the thread. The continueStatus parameter can be DBG_CONTINUE (exception handled, resume normally) or DBG_EXCEPTION_NOT_HANDLED (let the target's own exception handlers try). While waiting, the debugger can read/write memory, get/set registers, and inspect the target.
Attaching to Running Processes
// Attach to an already-running processBOOL success = DebugActiveProcess(targetPid);if (success) { // Now receiving debug events // ...
// Detach without killing the target DebugActiveProcessStop(targetPid);}Reading and Writing Target Memory
// Read memory from the target processBYTE buffer[1024];SIZE_T bytesRead;ReadProcessMemory(hProcess, (LPCVOID)targetAddress, buffer, sizeof(buffer), &bytesRead);
// Write memory (e.g., to set a software breakpoint)BYTE int3 = 0xCC; // INT 3 opcodeBYTE original;ReadProcessMemory(hProcess, breakpointAddr, &original, 1, NULL);WriteProcessMemory(hProcess, breakpointAddr, &int3, 1, NULL);FlushInstructionCache(hProcess, breakpointAddr, 1);Software Breakpoints
Software breakpoints replace an instruction byte with INT 3 (0xCC):
Before breakpoint: After setting breakpoint:0x401000: 55 push rbp 0x401000: CC ← INT 30x401001: 48 89 E5 mov rbp, rsp 0x401001: 48 89 E50x401004: 48 83 EC 10 sub rsp, 0x10 0x401004: 48 83 EC 10The hard part is getting past the breakpoint without losing it. Follow the round trip below: the debugger has to put the real byte back, rewind the instruction pointer, run exactly one instruction, and then plant the 0xCC again before letting the target run freely.
// Setting a software breakpointvoid SetBreakpoint(HANDLE hProcess, LPVOID addr, BYTE *savedByte) { ReadProcessMemory(hProcess, addr, savedByte, 1, NULL); BYTE int3 = 0xCC; WriteProcessMemory(hProcess, addr, &int3, 1, NULL); FlushInstructionCache(hProcess, addr, 1);}
// Handling a breakpoint hitvoid HandleBreakpoint(HANDLE hProcess, HANDLE hThread, LPVOID addr, BYTE savedByte) { // Restore original byte WriteProcessMemory(hProcess, addr, &savedByte, 1, NULL);
// Back up the instruction pointer (it advanced past the INT 3) CONTEXT ctx; ctx.ContextFlags = CONTEXT_CONTROL; GetThreadContext(hThread, &ctx); ctx.Rip--; // x64: back up one byte ctx.EFlags |= 0x100; // Set Trap Flag for single-step SetThreadContext(hThread, &ctx);
// After single-step, re-insert the breakpoint}Hardware Breakpoints
x86/x64 processors have four debug registers (DR0-DR3) that can hold breakpoint addresses, and DR7 that controls them:
// Set a hardware breakpoint on DR0CONTEXT ctx;ctx.ContextFlags = CONTEXT_DEBUG_REGISTERS;GetThreadContext(hThread, &ctx);
ctx.Dr0 = (DWORD64)targetAddress; // Address to break onctx.Dr7 |= 0x01; // Enable DR0 (local)// DR7 bits for DR0:// Bits 16-17: condition (00=execute, 01=write, 11=read/write)// Bits 18-19: length (00=1 byte, 01=2 bytes, 11=4 bytes)
// Set for write watchpoint, 4 bytes:ctx.Dr7 |= (0x01 << 16); // Condition: writectx.Dr7 |= (0x03 << 18); // Length: 4 bytes
SetThreadContext(hThread, &ctx);Hardware breakpoints have advantages over software breakpoints:
- Do not modify code (work on read-only memory, ROM)
- Can break on data access (read/write watchpoints), not just execution
- Cannot be easily detected by reading memory
- Limited to 4 simultaneous breakpoints (DR0-DR3)
x86/x64 CPUs provide debug registers DR0-DR3 for breakpoint addresses and DR7 for control. Each register can be configured for execution breakpoints (break when code at that address executes), write watchpoints (break when data at that address is written), or read/write watchpoints. DR6 is the status register that indicates which breakpoint was triggered. These are per-thread resources managed through the thread context.
Single-Stepping
The Trap Flag (TF) in the EFLAGS register causes the CPU to raise EXCEPTION_SINGLE_STEP after executing each instruction:
// Enable single-steppingCONTEXT ctx;ctx.ContextFlags = CONTEXT_CONTROL;GetThreadContext(hThread, &ctx);ctx.EFlags |= 0x100; // Set Trap FlagSetThreadContext(hThread, &ctx);
// Resume the threadContinueDebugEvent(pid, tid, DBG_CONTINUE);
// Next event will be EXCEPTION_SINGLE_STEP// The target has executed exactly one instructionHow Debuggers Work: The Complete Picture
┌──────────────────────────────────────┐│ Debugger Process ││ ││ Debug Loop: ││ 1. WaitForDebugEvent() ││ 2. Process event: ││ - BREAKPOINT → show state ││ - SINGLE_STEP → update display ││ - DLL_LOAD → update symbols ││ - EXCEPTION → display error ││ 3. User commands: ││ - "step" → set TF, continue ││ - "break 0x401000" → set BP ││ - "read rax" → GetThreadContext ││ - "dump 0x7ff..." → ReadProcess ││ 4. ContinueDebugEvent() ││ ││ Symbol Engine (dbghelp.dll): ││ - Load PDB files ││ - Map addresses to source lines ││ - Resolve function names │└──────────────────────────────────────┘ │ │ Debug Events / Memory Access │ (through kernel) ▼┌──────────────────────────────────────┐│ Target Process ││ Suspended when debug event occurs ││ Memory readable/writable by debugger││ Registers get/set via Context │└──────────────────────────────────────┘The Windows debugging API is the plumbing behind every Windows debugger, crash dump analyser, and a good chunk of the security tooling ecosystem. Understanding it lets you build custom analysis tools, understand anti-debugging techniques from the inside out, and appreciate the mechanisms that make serious security research on Windows possible.