tree: ddbc4104e93a7748d1733c6f71d2b2ed27a26d17 [path history] [tgz]
  1. README.md
  2. __init__.py
  3. breakpoint.py
  4. client.py
  5. control.py
  6. dbgeng.py
  7. probe_process.py
  8. setup.py
  9. symbols.py
  10. symgroup.py
  11. sysobjs.py
  12. utils.py
dexter/dex/debugger/dbgeng/README.md

Debugger Engine backend

This directory contains the Dexter backend for the Windows Debugger Engine (DbgEng), which powers tools such as WinDbg and CDB.

Overview

DbgEng is available as a collection of unregistered COM-“like” objects that one accesses by calling DebugCreate in DbgEng.dll. The unregistered nature means normal COM tooling can't access them; as a result, this backend uses ctypes to describe the COM objects and call their methods.

This is obviously not a huge amount of fun; on the other hand, COM has maintained ABI compatible interfaces for decades, and nothing is for free.

The dexter backend follows the same formula as others; it creates a process and breaks on “main”, then steps through the program, observing states and stack frames along the way.

Implementation details

This backend uses a mixture of both APIs for accessing information, and the direct command-string interface to DbgEng for performing some actions. We have to use the DbgEng stepping interface, or we would effectively be building a new debugger, but certain things (like enabling source-line stepping) only seem to be possible from the command interface.

Each segment of debugger responsibility has its own COM object: Client, Control, Symbols, SymbolGroups, Breakpoint, SystemObjects. In this python wrapper, each COM object gets a python object wrapping it. COM methods that are relevant to our interests have a python method that wraps the COM one and performs data marshalling. Some additional helper methods are added to the python objects to extract data.

The majority of the work occurs in setup.py and probe_process.py. The former contains routines to launch a process and attach the debugger to it, while the latter extracts as much information as possible from a stopped process, returning a list of stack frames with associated variable information.

Sharp edges

On process startup, we set a breakpoint on main and then continue running to it. This has the potential to never complete -- although of course, there's no guarantee that the debuggee will ever do anything anyway.

There doesn't appear to be a way to instruct DbgEng to “step into” a function call, thus after reaching main, we scan the module for all functions with line numbers in the source directory, and put breakpoints on them. An alternative implementation would be putting breakpoints on every known line number.

Finally, it‘s unclear whether arbitrary expressions can be evaluated in arbitrary stack frames, although this isn’t something that Dexter currently supports.