Skip to main content
Be Bitwise

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:

c
#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

text
┌──────────────────────────────┬──────────────────────────────┐
│ 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 │
└──────────────────────────────┴──────────────────────────────┘
Debug Event Flow

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

c
// Attach to an already-running process
BOOL success = DebugActiveProcess(targetPid);
if (success) {
// Now receiving debug events
// ...
// Detach without killing the target
DebugActiveProcessStop(targetPid);
}

Reading and Writing Target Memory

c
// Read memory from the target process
BYTE 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 opcode
BYTE 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):

text
Before breakpoint: After setting breakpoint:
0x401000: 55 push rbp 0x401000: CC ← INT 3
0x401001: 48 89 E5 mov rbp, rsp 0x401001: 48 89 E5
0x401004: 48 83 EC 10 sub rsp, 0x10 0x401004: 48 83 EC 10

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

One hit of a software breakpoint at 0x401000
c
// Setting a software breakpoint
void 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 hit
void 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:

c
// Set a hardware breakpoint on DR0
CONTEXT ctx;
ctx.ContextFlags = CONTEXT_DEBUG_REGISTERS;
GetThreadContext(hThread, &ctx);
ctx.Dr0 = (DWORD64)targetAddress; // Address to break on
ctx.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: write
ctx.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)
Key Concept
Hardware Debug Registers

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:

c
// Enable single-stepping
CONTEXT ctx;
ctx.ContextFlags = CONTEXT_CONTROL;
GetThreadContext(hThread, &ctx);
ctx.EFlags |= 0x100; // Set Trap Flag
SetThreadContext(hThread, &ctx);
// Resume the thread
ContinueDebugEvent(pid, tid, DBG_CONTINUE);
// Next event will be EXCEPTION_SINGLE_STEP
// The target has executed exactly one instruction

How Debuggers Work: The Complete Picture

text
┌──────────────────────────────────────┐
│ 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.