SoftICE-like Kernel Debugger For Home windows 11

Introduction

BugChecker is a SoftICE-like kernel and person debugger for Home windows 11 (and Home windows XP as effectively: it helps Home windows variations from XP to 11, each x86 and x64). BugChecker would not require a second machine to be related to the system being debugged, like within the case of WinDbg and KD. This model of BugChecker (in contrast to the authentic model developed 20 years in the past) leverages the inner and undocumented KD API in NTOSKRNL. KD API permits WinDbg/KD to do calls like learn/write digital reminiscence, learn/write registers, place a breakpoint at an deal with and many others.

In contrast, the unique BugChecker, like SoftICE as effectively, used to “take over” the system, by hooking a number of kernel APIs (each exported and personal), taking management of the APIC, sending IPIs and many others. This strategy will increase complexity exponentially (and lowers system stability), because the implementation have to be suitable with all of the supported variations and sub-version of Home windows (on the perform signature stage) in addition to all of the attainable supported {hardware} configurations. Furthermore, 20 years later, PatchGuard makes this resolution not possible.

In contrast, this model of BugChecker, by intercepting calls to KdSendPacket and KdReceivePacket within the kernel, presents itself to the machine being debugged as a second system operating an exterior kernel debugger, however, in actuality, all the things occurs on the identical machine. Usually that is achieved by changing KDCOM.DLL (which is the module that implements serial cable communication for the KD API in Home windows) and by beginning the system in kernel debugging mode. This strategy (impressed by VirtualKD) lowers complexity and will increase stability and compatibility (and portability, for instance, to ARM – and modularity, because the decrease stage debugger capabilities are carried out behind KdXxxPacket and could possibly be changed with a customized implementation). Furthermore, the presence of a kernel debugger at boot time (though “faux”) makes Home windows disable PatchGuard.

In the meanwhile, BugChecker requires a PS/2 keyboard for enter and a linear framebuffer to jot down its output.

• Assist for Home windows XP as much as Home windows 11, x86 and x64, and SMP kernels. Assist for WOW64 processes on x64.
• Integration of QuickJSPP, which is a port of QuickJS to MSVC++. Earlier than calling QuickJS, BugChecker saves the FPU state (on x86) and switches to an expanded stack of 128KB.
• Instructions settle for JS expressions. For instance, “U rip+rax*4” and “U MyJsFn(rax+2)” are legitimate instructions. Customized features could be outlined within the Script Window. CPU registers are declared as world scope variables mechanically by BugChecker.
• Assist for PDB image recordsdata. PDB recordsdata could be specified manually or Image Loader can obtain them from a logo server.
• JavaScript code can name the next asynchronous features: WriteReg, ReadMem, WriteMem.
• Breakpoints can have a JS situation: if situation evaluates to 0, no “breakin” occurs. This permits to set “Logpoints” and breakpoints that may change the circulation of execution.
• Log window reveals the messages despatched to the kernel debugger (for instance DbgPrint messages).
• JavaScript window with syntax highlighting.
• The tab key permits, given few digits, to cycle via all of the hex numbers on the display screen or, given few characters, to cycle via all of the symbols containing these characters.
• EASTL and C++20 coroutines make creating new instructions a breeze. Be at liberty to ship your pull requests!

Movies (Youtube)

Demonstration of BugChecker on Home windows 11 22H2, inside VirtualBox 7.0.4. A JavaScript breakpoint situation is written that modifications the circulation of execution in an person mode thread.

BugChecker operating in a really constrained atmosphere: a Raspberry Pi 4 (4GB RAM), through QEMU on Home windows XP (512MB RAM). A breakpoint is used to log all of the SYSENTER calls from person mode to the kernel. The service index is saved in a JavaScript array.

Be sure that Safe Boot is disabled when putting in and utilizing BugChecker. Usually you’ll be able to re-enable it later. In case you are utilizing VMware or VirtualBox, Safe Boot could be disabled within the digital machine settings.

Think about additionally enabling legacy boot menu, if utilizing Home windows 8, 10 or 11, by utilizing the command: bcdedit /set “{present}” bootmenupolicy legacy. It permits a smoother expertise throughout boot, by permitting to pick the BugChecker boot choice after which to disable Driver Signature Enforcement on the similar time.

Directions

Step one is to begin Image Loader:

If essential, disable the show drivers, by clicking on the “Disable Show Drvs” button. The identical factor could be achieved in Home windows Gadget Supervisor. After the show drivers have been disabled, they continue to be disabled even after a system reboot. They are often re-enabled at any time later when not utilizing BugChecker.

The purpose right here is that BugChecker wants a linear framebuffer with a format of 32 bits-per-pixel, to attract its interface. When disabling the show drivers, Home windows dismisses {hardware} acceleration for drawing its UI and falls again to VGA compatibility mode. If operating on naked steel or VMware, you need to disable show drivers. If operating on VirtualBox, you need to disable show drivers or set the vm_screen setting in BugChecker.dat, as described beneath. If operating on QEMU, you need not disable show drivers however be sure that to specify the “-vga std” show gadget.

Be aware that VGA compatibility mode may restrict the utmost display screen decision. VMware is proscribed to a most decision of 1152×864. QEMU with the “-vga std” show gadget would not endure from this limitation.

Curiously if BugChecker is put in on a system with a couple of graphics card, it’s attainable to disable the show drivers of just one graphics card, which would be the card related to the display screen that can present the BugChecker UI. The second card (set as the principle show) will retain all its 2D and 3D acceleration options, together with OpenGL and DirectX assist (NOTE: examined on VMware, with Home windows 11 and a DisplayLink show).

Then click on on “Begin Driver”, then on “Auto Detect” and eventually on “Save”. “Auto Detect” ought to be capable of decide width, top, bodily deal with and stride of the framebuffer mechanically. Nevertheless, you’ll be able to specify these settings manually (remember to click on on “Save” when completed). If “Stride” is 0, it’s calculated as “Width” * 4 mechanically when beginning the driving force. “Tackle” (i.e. bodily deal with of the framebuffer) could be get obtained in Home windows Gadget Supervisor, by clicking on “Properties” of the show gadget, underneath the “Assets” tab.

Then click on on “Callback” within the “KDCOM Hook Technique” part, then on “Copy/Substitute Kdcom” and eventually you’ll be able to reboot the system.

This setup course of must be achieved solely as soon as and the show drivers could be re-enabled, if essential. When utilizing BugChecker nevertheless the show drivers have to be disabled once more, if required by your configuration.

vm_screen setting for VirtualBox (Experimental)

The vm_screen setting in BugChecker.dat permits to open the BugChecker debugger UI in VirtualBox with out specifying upfront a display screen decision in Image Loader and with out disabling show drivers.

The concept is to jot down on to the I/O ports and to the Command Buffer of the digital show gadget so as to receive the present display screen decision and to inform the hypervisor of any replace within the framebuffer.

This resolution was impressed by the X.org xf86-video-vmware driver.

This resolution works just for VirtualBox VMs and by modifying manually the BugChecker.dat file:

• In Image Loader, manually set the width and top of the framebuffer to the utmost decision attainable (i.e. the size of your laptop display screen). Set the stride to 0.
• The BugChecker.dat file is created by Image Loader in “C:WindowsBugChecker”.
• The vm_screen setting must be added underneath “settings->framebuffer”.
• The hierarchy of the settings on this file is decided by the tabulation characters (not areas).
• The format of the setting is Command_Buffer_Start_Address (comma) Command_Buffer_End_Address (comma) I/O_Port_Base
• IMPORTANT: Within the VM setting, underneath Show, choose “VBoxSVGA” because the Graphics Controller and uncheck “Allow 3D Acceleration”.

That is an experimental function. Sooner or later, this setting can be mechanically added by Image Loader.

Applied Instructions

The command title and syntax are chosen to be as shut as attainable to these of the unique SoftICE for NT:

• ? javascript-expression: Consider a javascript expression.
• ADDR eprocess: Swap to course of context (returns management to OS).
• BC record|*: Clear a number of breakpoints.
• BD record|*: Disable a number of breakpoints.
• BE record|*: Allow a number of breakpoints.
• BL (no parameters): Checklist all breakpoints.
• BPX deal with [-t|-p|-kt thread|-kp process] [WHEN js-expression]: Set a breakpoint on execution.
• CLS (no parameters): Clear log window.
• COLOR [normal bold reverse help line]|[reset]: Show, set or reset the display screen colours.
• DB/DW/DD/DQ [address] [-l len-in-bytes]: Show reminiscence as 8/16/32/64-bit values.
• EB/EW/ED/EQ deal with -v space-separated-values: Edit reminiscence as 8/16/32/64-bit values.
• KL EN|IT: Set keyboard format.
• LINES [rows-num]: Show or set present show rows.
• MOD [-u|-s] [search-string]: Show module data.
• P [RET]: Execute one program step.
• PAGEIN deal with: Drive a web page of reminiscence to be paged in (returns management to OS).
• PROC [search-string]: Show course of data.
• R register-name -v worth: Change a register worth.
• STACK [stack-ptr]: Scan the stack trying to find return addresses.
• T (no parameters): Hint one instruction.
• THREAD [-kt thread|-kp process]: Show thread data.
• U deal with|DEST: Unassemble directions.
• VER (no parameters): Show model data.
• WD [window-size]: Toggle the Disassembler window or set its measurement.
• WIDTH [columns-num]: Show or set present show columns.
• WR (no parameters): Toggle the Registers window.
• WS [window-size]: Toggle the Script window or set its measurement.
• X (no parameters): Exit from the BugChecker display screen.

Construct Directions

Conditions

• Visible Studio 2019
• Home windows Driver Equipment 7.1.0

Be aware: WDK must be put in in its default location, i.e. X:WinDDK, the place X is the drive the place the BugChecker sources are saved.

Visible Studio Initiatives Description

• BugChecker: that is the BugChecker kernel driver, the place everything of the debugger is carried out. The “Launch|x86” and “Launch|x64” output recordsdata are included within the last bundle. Throughout initialization, the driving force hundreds its config file at “SystemRootBugCheckerBugChecker.dat” (all of the image recordsdata are saved on this listing too) after which it tries to find “KDCOM.dll” in kernel area. If discovered, it tries to name its “KdSetBugCheckerCallbacks” exported perform, thus hooking KdSendPacket and KdReceivePacket.
• SymLoader: that is the Image Loader. Solely the “Launch|x86” output file is included within the last bundle. Image Loader is used to vary the BugChecker configuration (configuration is written to “SystemRootBugCheckerBugChecker.dat”), to obtain PDB recordsdata and to put in the customized KDCOM.dll module.
• KDCOM: that is the customized KDCOM.dll module that NTOSKRNL hundreds on system startup. It exports the “KdSetBugCheckerCallbacks” perform that the driving force calls to hook KdSendPacket and KdReceivePacket.
• pdb: that is the Ghidra “pdb” venture. The unique model outputs the contents of a PDB file to the usual output in xml format. The code was modified so as to generate a BCS file as a substitute.
• NativeUtil: since Image Loader is a WOW64 utility in Home windows x64, the calls to these APIs that have to be produced from structure native photographs had been moved right here (for instance the calls to the Gadget and Driver Set up API).
• HttpToHttpsProxy: that is an ASP.NET Core utility whose perform is to behave as an web proxy for Image Loader when run in Home windows XP. Since XP has outdated TLS assist, Image Loader can not obtain recordsdata from an arbitrary image server. After deploying this utility in an IIS on the identical community, it’s attainable to obtain recordsdata from a logo server in Home windows XP prepending “http://<YOUR_IIS_SERVER_IP>/HttpToHttpsProxy/” to the server URL in Image Loader.

Credit

• VirtualKD: the primary POC of BugChecker was constructed modifying VirtualKD.
• BazisLib: the code behind the “Copy/Substitute Kdcom + Add Boot Entry” button in Image Loader is from VirtualKD and makes use of BazisLib.
• EASTL: No method to make use of MSVC++ STL right here. EASTL is a wonderful different.
• Ghidra: the “pdb” venture in BugChecker is from Ghidra. It was modified to generate BCS recordsdata.
• Zydis: for the disassembler window in BugChecker.
• ReactOS: for the Home windows KD inside sort definitions.
• SerenityOS: for the low stage bitmap manipulation features utilized by the BugChecker reminiscence allocator. Since I began BugChecker after I noticed a video of Andreas (after 10 years of abstinence from C/C++ and any sort of low stage programming), I wished to incorporate a small piece of SerenityOS in BugChecker.