https://github.com/zhuagenborn/windows-x86-debugger
🐞 A simple Windows x86 debugging framework written in C++20 that supports software breakpoints and hardware breakpoints. It can be used to create custom debuggers.（使用C++20开发的简易Windows x86调试框架，支持软件断点和硬件断点，可以用于创建自定义调试器。）
https://github.com/zhuagenborn/windows-x86-debugger
cpp20 debugger framework windows
Last synced: 8 months ago
JSON representation
🐞 A simple Windows x86 debugging framework written in C++20 that supports software breakpoints and hardware breakpoints. It can be used to create custom debuggers.（使用C++20开发的简易Windows x86调试框架，支持软件断点和硬件断点，可以用于创建自定义调试器。）
- Host: GitHub
- URL: https://github.com/zhuagenborn/windows-x86-debugger
- Owner: Zhuagenborn
- License: mit
- Created: 2021-11-15T01:28:53.000Z (over 4 years ago)
- Default Branch: main
- Last Pushed: 2025-03-30T04:02:40.000Z (12 months ago)
- Last Synced: 2025-06-06T13:06:23.973Z (10 months ago)
- Topics: cpp20, debugger, framework, windows
- Language: C++
- Homepage:
- Size: 93.8 KB
- Stars: 11
- Watchers: 4
- Forks: 3
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
- Citation: CITATION.cff
Awesome Lists containing this project
README
# *Windows* x86 Debugger
[](https://cmake.org)
[](https://visualstudio.microsoft.com/)
[](https://www.microsoft.com/en-ie/windows)
## Introduction
A simple ***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*](https://github.com/x64dbg/GleeBug).
## Getting Started
### Prerequisites
- Install [*Visual Studio 2022*](https://visualstudio.microsoft.com).
- Install [*CMake*](https://cmake.org).
- Set the `PATH` environment variables.
### Building
Set the location to the project folder and run:
```bash
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`.
```c++
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*](https://www.doxygen.nl) specification.
### Class Diagram
```mermaid
classDiagram
namespace register {
class RegisterIndex {
<>
EAX
EBX
ECX
EDX
}
class Register {
Set(int)
Reset()
Get() int
}
class Flag {
<>
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 {
<>
DR0
DR1
DR2
DR3
}
class HardwareBreakpointType {
<>
Execute
Write
ReadWrite
}
class HardwareBreakpointSize {
<>
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.