Windows x86 Debugger

Introduction

A tiny Windows x86 debugging framework written in C++20 that supports software breakpoints and hardware breakpoints. It can be used to create custom debuggers. Some design patterns came from GleeBug.

Getting Started

Prerequisites

• Install Visual Studio 2022.
• Install CMake.
• Set the PATH environment variables.

Building

Set the location to the project folder and run:

mkdir -p build
cd build
cmake .. -G "Visual Studio 17 2022" -A Win32
cmake --build .

Usage

Users can create derived classes inheriting from Debugger class and override or implement provided event callbacks.

• Debugger does not provide any implementation for event callbacks whose names start with cb.
• Debugger provides the basic implementation for event callbacks whose names start with On.

class MyDebugger : public Debugger {
private:
    void cbCreateProcess(const CREATE_PROCESS_DEBUG_INFO& details,
                         const Process& process) override {
        std::cout << std::format("The process {} has been created.",
                                 process.Id())
                  << std::endl;
    }

    void cbExitProcess(const EXIT_PROCESS_DEBUG_INFO& details,
                       const Process& process) override {
        std::cout << std::format("The process {} has exited.",
                                 process.Id())
                  << std::endl;
    }
};

Documents

Code comments follow Doxygen specification.

Class Diagram

classDiagram

namespace register {

    class RegisterIndex {
        <<enumeration>>
        EAX
        EBX
        ECX
        EDX
    }

    class Register {
        Set(int)
        Reset()
        Get() int
    }

    class Flag {
        <<enumeration>>
        CF
        AF
        PF
        ZF
    }

    class FlagRegister {
        SetCF()
        ResetCF()
        CF() bool
    }

    class DebugStatusRegister {
        SetB0()
        ResetB0()
        B0() bool
    }

    class DebugControlRegister {
        SetL0()
        ResetL0()
        L0() bool
        SetRW0(val)
        RW0() int
    }

    class Registers {
        Register EAX
        FlagRegister EFLAGS
        DebugStatusRegister DR6
        DebugControlRegister DR7
    }
}

Register --> RegisterIndex
Register <|-- FlagRegister
FlagRegister ..> Flag
Register <|-- DebugStatusRegister
Register <|-- DebugControlRegister
Registers o-- Register

namespace breakpoint {

    class Breakpoint {
        int address
    }

    class HardwareBreakpointSlot {
        <<enumeration>>
        DR0
        DR1
        DR2
        DR3
    }

    class HardwareBreakpointType {
        <<enumeration>>
        Execute
        Write
        ReadWrite
    }

    class HardwareBreakpointSize {
        <<enumeration>>
        Byte
        Word
        Dword
    }

    class HardwareBreakpoint {
        HardwareBreakpointSlot slot
        HardwareBreakpointType access
        HardwareBreakpointSize size
    }

    class SoftwareBreakpoint {
        byte origin
    }
}

Breakpoint <|-- HardwareBreakpoint
HardwareBreakpoint --> HardwareBreakpointSlot
HardwareBreakpoint --> HardwareBreakpointType
HardwareBreakpoint --> HardwareBreakpointSize
Breakpoint <|-- SoftwareBreakpoint

class Thread {
    Suspend()
    Resume()
    StepInto()
    SetHardwareBreakpoint(addr, slot, type, size)
    DeleteHardwareBreakpoint(slot)
}

Thread *-- HardwareBreakpoint
Thread --> Registers

class Process {
    Suspend()
    Resume()
    FindThread(id) Thread
    NewThread(thread)
    RemoveThread(thread)
    SetSoftwareBreakpoint(addr, callback)
    DeleteSoftwareBreakpoint(addr)
    FindSoftwareBreakpoint(addr) SoftwareBreakpoint
    SetHardwareBreakpoint(addr, slot, type, size, callback)
    DeleteHardwareBreakpoint(addr)
    FindHardwareBreakpoint(addr) HardwareBreakpoint
    WriteMemory(addr, data)
    ReadMemory(addr, size) vector~byte~
}

Process *-- Thread
Process *-- SoftwareBreakpoint

class Debugger {
    Create(file, cmd)
    Attach(proc)
    Start()
    Detach()
    Stop()
}

Debugger o-- Process

License

Distributed under the MIT License. See LICENSE for more information.