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 an object-oriented 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 open source diStorm project, see http://ragestorm.net/distorm/), debugging multiple processes simultaneously and produce a detailed log of application crashes, useful for fuzzing and automated testing.

What’s new in this version?

In a nutshell…

• fully supports Python 2.4 through 2.7
• fully supports Windows XP through Windows 7, 32 and 64 bit editions
• crash report tool now supports MSSQL (requires pyodbc)
• now supports downloading debugging symbols from Microsoft (thanks Neitsa!)
• new tool: sehtest.py (Windows SEH buffer overflow jump address bruteforcer, inspired by the same tool by Nicolas Economou)
• the tutorial is now available in chm and pdf formats
• now with only one MSI installer for all supported Python versions
• added support for diStorm 3 (falls back to the old version if not found)
• now using cerealizer instead of pickle whenever possible
• added new command to the command line debugger to show the exception handlers
• a few more anti-anti-debug tricks were added, still more to go!
• several improvements to the Window instrumentation classes
• more code examples
• more Win32 API wrappers
• lots of miscellaneous improvements, more documentation and bugfixes as usual!

Entire changelog for all versions (slow!):

• http://p.sf.net/winappdbg/changelog

Where can I find WinAppDbg?

Project homepage

• http://tinyurl.com/winappdbg

Windows installer (32 bits)

• winappdbg-1.4.win32.msi
• winappdbg-1.4.win32.exe

Windows installer (64 bits)

• winappdbg-1.4.win-amd64.msi
• winappdbg-1.4.win-amd64.exe

Source code

• winappdbg-1.4.zip
• winappdbg-1.4.tar.bz2

Online documentation

• Programming Guide
• Reference documentation

Offline documentation

• winappdbg-tutorial-1.4.chm
• winappdbg-tutorial-1.4.pdf
• winappdbg-reference-1.4.chm
• winappdbg-reference-1.4.pdf

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 an object-oriented 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 open source diStorm project, see http://ragestorm.net/distorm/), debugging multiple processes simultaneously and produce a detailed log of application crashes, useful for fuzzing and automated testing.

Where can I find WinAppDbg?

Project homepage

• http://tinyurl.com/winappdbg

Windows installer (32 bits)

• winappdbg-1.3.win32.msi
• winappdbg-1.3.win32.exe

Windows installer (64 bits)

• winappdbg-1.3.win-amd64.msi
• winappdbg-1.3.win-amd64.exe

Source code

• winappdbg-1.3.zip
• winappdbg-1.3.tar.bz2

Online documentation

• Programming Guide
• Reference documentation

Offline documentation

• winappdbg-1.3.chm
• winappdbg-1.3.pdf

What’s new in this version?

In a nutshell…

• 64 bits support.
• Windows Vista and 7 support.
• Memory dumping support.
• Wait chain support.
• New tool: SelectMyParent (based on the tool by Didier Stevens).
• More code examples.
• Supports detecting the current processor architecture and Windows version.
• Crash logger works with SQLite databases in addition to the old DBM format. It also has a smaller memory footprint now.
• Win32 API wrappers were refactored and improved. Many new definitions and API calls were added, up to Windows 7.
• Many bugfixes as usual… also several improvements to make the code more robust.

Here’s the full changelog.

This was clearly wrong, but I couldn’t see anything in my code that would produce that. Furthermore, in 32 bits the exact same code was working alright!

After scratching my head for a while, I went to MSDN in search of enlightment, and found this info at the help page for ContinueDebugEvent:

DBG_CONTINUE (0x00010002L): If the thread specified by the dwThreadId parameter previously reported an EXCEPTION_DEBUG_EVENT debugging event, the function stops all exception processing and continues the thread. For any other debugging event, this flag simply continues the thread.

DBG_EXCEPTION_NOT_HANDLED (0x80010001L): If the thread specified by dwThreadId previously reported an EXCEPTION_DEBUG_EVENT debugging event, the function continues exception processing. If this is a first-chance exception event, the search and dispatch logic of the structured exception handler is used; otherwise, the process is terminated. For any other debugging event, this flag simply continues the thread.

But I remembered seeing a certain DBG_EXCEPTION_HANDLED value when porting SDK constants and structures to my Win32 API wrappers. So I looked it up and it’s value turned out to be 0x00010001L, which was exactly DBG_CONTINUE minus one, so it wasn’t not just an alias but really a different value, possibly with a different meaning.

So I tried replacing DBG_CONTINUE by DBG_EXCEPTION_HANDLED when handling exceptions in my code and, what do you know, single steping and tracing began to work again!

Apparently, when handling exception events, 32 bits Windows treats DBG_CONTINUE as an alias of DBG_EXCEPTION_HANDLED, while in 64 bits Windows it’s an alias of DBG_EXCEPTION_NOT_HANDLED. This means we can’t possibly write a debugger for 64 bits without using this undocumented value!

Luckily for us, DBG_EXCEPTION_HANDLED seems to work well in 32 bits Windows, at least with XP (didn’t test Windows 2000 yet), so the same code may be used for all versions of Windows. It also works with current versions of Wine, judging from this commit from 2005.

Speaking of Wine, browsing through the sources I found several other “undocumented” status codes:

• DBG_TERMINATE_PROCESS
• DBG_TERMINATE_THREAD
• DBG_CONTROL_C
• DBG_CONTROL_BREAK
• DBG_COMMAND_EXCEPTION

However the last three don’t seem to be supported by Windows XP, as shown in the following disassembly of NTOSKRNL.EXE:

That still leaves us with two new undocumented status codes to play with