Integration with WinDbg is achieved by implementing a console debugger in Python 3 based on dbgeng.dll (via pybag). This DLL represents the Microsoft Windows Debugger engine, and so is best suited for debugging Windows user-space targets. This DLL also backs WinDbg and several other debuggers on Windows. By default, the launcher will search for this DLL in an installation of the Windows Debugging Kits version 10. If it does not find it there, it will probably crash with a message in the Terminal.
The following launchers based on Microsoft's dbgeng.dll are included out of the box:
The plain "dbgeng" defaults to launching the current program as a user-mode process on the local system. If there is no current program, this launcher cannot be used. Clearing the Image option will cause this launcher to fail.
Please note on some system configurations, one of the debugger's dependencies dbghelp.dll may get loaded from the system directory instead of from the WinDbg installation, usually because a security product has pre-loaded it into the Python process. You might work around this by copying the affected DLLs from your WinDbg installation into your Python installation.
Installing WinDbg is highly recommended. If you wish to forego installing WinDbg, you can use the DLL provided with Windows, which is substantially less capable, by manually pointing this connector to C:\Windows\system32. If you do this, some commands, e.g. .server, will not be available.
If you have access to PyPI, setting up your Python 3 environment is done using Pip. Please note the version specifier for Protobuf.
python3 -m pip install pybag protobuf==3.20.3
If you are offline, or would like to use our provided packages, we still use Pip, but with a more complicated invocation:
cd C:\path\to\ghidra_ version\Ghidra\Debug python3 -m pip install --no-index -f Debugger-rmi-trace\pypkg\dist -f Debugger-agent-dbgeng\pypkg\dist pybag protobuf
If you get an import error regarding distutils, it is due to a transitive dependency on a buggy version of capstone. Work around it by installing setuptools.
Once running, you are presented with a command-line interface in Ghidra's Terminal. This CLI accepts your usual WinDbg (kd) commands. You can escape from this CLI and enter a Python 3 REPL by entering ".exit". This is not an actual kd command, but our implementation understands this to mean exit the kd REPL. From the Python 3 REPL, you can access the underlying Python-based API pybag. This is an uncommon need, but may be useful for diagnostics and/or workarounds. To re-enter the kd REPL, enter "repl()". Alternatively, if you are trying to quit, but typed ".exit", just type "quit()" to terminate the session.
The "dbgeng-ext" launcher extends the base dbgeng launcher adding extra options (a la IDebugClient's CreateProcess2).
This launcher allows the user to attach to a local running process. Options are the same as those for the base dbgeng, except for ProcessId and AttachFlags
This launcher connects to a remote debugger that has opened a port for remote control.
.server tcp:port=12345
The "dbgeng-svrcx" launcher extends the base dbgeng launcher adding an option for connecting through a remote process server.
dbgsrv -t tcp:port=12345
This version of the dbgeng should be used for kernel-debugging of a remote machine. Options are the same as the base dbgeng, except for the connection-string arguments. For remote debugging, the target machine should be booted with the appropriate options, set using BCDEDIT or the equivalent, such as:
bcdedit /debug ON bdcedit /dbgsettings NET HOSTIP:IP PORT:54321 KEY:1.1.1.1
where IP= the address of the machine runing Ghidra.
Setup for EXDI connections is fairly complicated and difficult to get correct. The argument string typically should be something like:
exdi:CLSID={29f9906e-9dbe-4d4b-b0fb-6acf7fb6d014},Kd=Guess,DataBreaks=Exdi
The CLSID here should match the CLSID in the exdiConfigData.xml file in the debugger architectural directory. If windbg has been run using EXDI at some point, there will also be an entry in the System Registry for this CLSID. The InprocServer32 subentry for this CLSID in the Registry should point to a copy of ExdiGdbSrv.dll, typically the one in the same directory. This DLL must reside somewhere that the debugger has permission to load from, i.e. not in the WindowsApps directory tree. The exdiConfigData file should be configured for the target you're using. We heavily recommend using displayCommPackets==yes, as many of the tasks take considerable time, and this is the only indicator of progress.
The Kd=Guess parameter causes the underlying engine to scan memory for the kernel's base address, which will probably not be provided by the gdbstub. (Kd=NtBaseAddr is also a valid option, as is eliminating the parameter, but, currently, we have no idea how to point the configuration at a correct value. Using this option will cause the load to spin pointlessly.) If you can, we highly recommend breaking the target near the base address, as the search proceeds down through memory starting at the current program counter. If the difference between the PC and the base address is large, the loading process will punt before useful values are detected. If anyone understand how to extend this search (or knows how to set the base address to sidestep the scan), we would really love some guidance.
This is a nascent extension to our launcher for the Windows Debugger. The launcher itself functions, but lacks full integration. In particular, Ghidra's concept of time is not mapped directly to the TTD concept of time. TTD uses a major/minor scheme for ordering events, where the major index changes when TTD must record a change in state. Events, including thread creation/termination, module loads/unloads, syscalls, and other asynchronous changes, merit new major indices. When you step forward or backward in a trace, the dbgeng API will increment and decrement correspondingly. Ghidra, on the other hand, will only increment.
This launcher has basically the same options as the WinDbg launcher, except that arguments are not included and the DLL path must contain TTDReplay.dll and the scripts that implement TTD. These are most easily obtained by installing WinDbg Preview or later.