Introduction

The WinAppDbg python module allows developers to quickly code instrumentation scripts in Python under a Windows environment.

It uses ctypes to wrap many Win32 API calls related to debugging, and provides a powerful abstraction layer to manipulate threads, libraries and processes, attach your script as a debugger, trace execution, hook API calls, handle events in your debugee and set breakpoints of different kinds (code, hardware and memory). Additionally it has no native code at all, making it easier to maintain or modify than other debuggers on Windows.

The intended audience are QA engineers and software security auditors wishing to test / fuzz Windows applications with quickly coded Python scripts. Several ready to use utilities are shipped and can be used for this purposes.

Current features also include disassembling x86 native code (using the diStorm disassembler), debugging multiple processes simultaneously and produce a detailed log of application crashes, useful for fuzzing and automated testing.

Download

Go to the Sourceforge project's download page. You can choose between the source code package and the Windows installer package.

You can also get the bleeding-edge version as a source code tarball from the subversion repository.

Install

Simply run the Windows installer package and follow the wizard.

Alternatively, if you prefer using EasyInstall, type the following at the command prompt:

easy_install winappdbg

You can also download the sources package, or browse the svn repository.

Dependencies

• The Python interpreter. There are two basic flavors, just pick your favorite. :)
  • The official Python interpreter (free, open source):
  • ActiveState ActivePython (free, closed source):

• The ctypes module is needed to interface with the Win32 API. It's already shipped with Python 2.5 and above.

• The SQLite python bindings can be used with the crash logger tool to store the crash information in an SQLite database file. This module is currently shipped with Python 2.5 and above.

• The diStorm disassembler. Download the python bindings suitable for Python 2.x here:
  • Windows 32 bits installer: distorm-1.7.30.win32.msi
  • Windows 64 bits installer: distorm-1.7.30.win-amd64.msi
  • Source code distribution, all platforms: distorm-1.7.30.zip

Note that if you don't install diStorm, all classes and methods of the debugger not related to dissassembling will still work correctly.

Optional packages

• The Python specializing compiler, Psyco. You may experience some performance gain by installing it, but be aware that Psyco-accelerated code doesn't behave exactly like pure Python code. You can download it from here.

• PyReadline is useful when using the console tools shipped with WinAppDbg, but they'll work without it. Basically what it does is provide autocomplete and history for console applications.

• The py2exe package. You can use it to generate standalone binaries for any tools made with WinAppDbg. See the instructions on how to use the makefile.

Documentation

After installing the module you'll probably want to check out the programming guide for a quick tour on developing Python scripts to instrument, test and debug Windows applications.

There is also the autogenerated reference documentation, provided mostly to find that class or method that does precisely what you wanted - but not quite a fun read!

Don't forget to check out the handy tools shipped with the WinAppDbg package.

License

This package is released under the BSD license, so as a user you are entitled to create derivative work and redistribute it if you wish. A makefile is provided to automatically generate the source distribution package and the Windows installer, and can also generate the documentation for all the modules using Epydoc.

Support

This package has been tested under Windows XP (both 32 and 64 bits) using Python 2.5 and Python 2.6. It was loosely tested under Windows 2000, Wine and ReactOS, and some bugs are to be expected in these platforms (mainly due to the lack of some debugging apis). No testing was performed (yet) on newer Windows versions, so if you try them out please let us know.

If you find a bug or have a feature suggestion, don't hesitate to send an email to the winappdbg-users mailing list. Both comments and complaints are welcome! :)

The following tables show which Python interpreters, operating systems and processor architectures are currently supported. Full means all features are fully functional. Partial means some features may be broken and/or untested. Experimental means there is a subversion branch with at least partial support, but hasn't been merged to trunk yet. Untested means that though no testing was performed it should probably work.

Python interpreters

Python 2.3	partial	see ticket #7
Python 2.4	full
Python 2.5	full
Python 2.6	full
Python 3.x	experimental	separate branch

Operating systems

Windows 2000 and older	partial	some Win32 APIs didn't exist yet
Windows XP	full	only tested in XP so far
Windows Vista and newer	untested	should probably work
ReactOS	untested	should probably work
Linux (using Wine)	untested	should probably work

Architectures

Intel x86 (32 bits) and compatible	full
Intel x86_x64 (64 bits) and compatible	partial	function hooks are not implemented
Intel IA64 (Itanium)	experimental	no actual Itanium system to test it on, help is needed!