Programming Windows application debuggers in Python

^{<- Back to Home}

Introduction

This guide will show you through the most commonly used classes and methods of the WinAppDbg module, and provide some examples of use for each one. The goal is to give you a bird's eye perspective on what the library can do and how, without having to go through the reference material.

Instrumentation

You can implement process instrumentation in your Python scripts by using the provided set of classes: System, Process, Thread and Module. Each one acts as a snapshot of the processes, threads and DLL modules in the system.

A System object is a snapshot of all running processes. It contains Process objects, which in turn are snapshots of processes. A Process object contains Thread and Module objects.

Note that you don't need to be attached as a debugger for these classes to work.

Read more on Instrumentation.

Debugging

Debugging operations are performed by the Debug class. You can receive notification of debugging events by passing a custom event handler to the Debug object when creating it - each event is represented by an Event object. Custom event handlers can also be subclasses of the EventHandler class.

Debug objects can also set breakpoints and watches and support the use of labels.

Read more on Debugging.

The Win32 API wrappers

The win32 submodule provides a collection of useful API wrappers for most operations needed by a debugger. This will allow you to perform any task that the abstraction layer for some reason can't deal with, or won't deal with in the way you need. In most cases you won't need to resort to this, but it's important to know it's there.

Read more on the Win32 API Wrappers.

Tools

The WinAppDbg package comes with a collection of tools useful for common tasks when debugging or fuzzing a program. The most important tool, the Crash logger, attaches to any number of target processes and collects crash dump information in a SQLite database. It can also apply heuristics to discard multiple occurrences of the same crash.

The source code of these tools can also be read for more examples on programming using WinAppDbg.

Read more on the Tools.

More code examples

Some miscellaneous code examples...

• MemoryDumpExample - Dumping the process memory into an sqlite database.
• TimeToDebug - Setting a debugging timeout (useful for fuzzing).