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/x64 native code, 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…

• full 64-bit support (including function hooks!)
• added support for Windows Vista and above.
• database code migrated to SQLAlchemy, tested on:
  • MySQL
  • SQLite 3
  • Microsoft SQL Server

  should work on other servers too (let me know if it doesn’t!)

• added integration with more disassemblers:
  • BeaEngine: http://www.beaengine.org/
  • Capstone: http://capstone-engine.org/
  • Libdisassemble: http://www.immunitysec.com/resources-freesoftware.shtml
  • PyDasm: https://code.google.com/p/libdasm/
• added support for postmortem (just-in-time) debugging
• added support for deferred breakpoints
• now fully supports manipulating and debugging system services
• the interactive command-line debugger is now launchable from your scripts (thanks Zen One for the idea!)
• more UAC-friendly, only requests the privileges it needs before any action
• added functions to work with UAC and different privilege levels, so it’s now possible to run debugees with lower privileges than the debugger
• added memory search and registry search support
• added string extraction functionality
• added functions to work with DEP settings
• added a new event handler, EventSift, that can greatly simplify coding a debugger script to run multiple targets at the same time
• added new utility functions to work with colored console output
• several improvements to the Crash Logger tool
• integration with already open debugging sessions from other libraries is now possible
• improvements to the Process and GUI instrumentation functionality
• implemented more anti-antidebug tricks
• more tools and code examples, and improvements to the existing ones
• more Win32 API wrappers
• lots of miscellaneous improvements, more documentation and bugfixes as usual!

Where can I find WinAppDbg?

Project homepage:

• http://winappdbg.sourceforge.net/

Download links:

• Windows installer (32 bits)
• Windows installer (64 bits)
• Source code

Documentation:

Online

• Tutorial
• Reference

Windows Help

• Tutorial
• Reference

HTML format (offline)

• Tutorial
• Reference

PDF format (suitable for printing)

• Tutorial
• Reference

Acknowledgements

Acknowledgements go to Arthur Gerkis, Chris Dietrich, Felipe Manzano, Francisco Falcon, @Ivanlef0u, Jean Sigwald, John Hernandez, Jun Koi, Michael Hale Ligh, Nahuel Riva, Peter Van Eeckhoutte, Randall Walls, Thierry Franzetti, Thomas Caplin, and many others I’m probably forgetting, who helped find and fix bugs in the almost eternal beta of WinAppDbg 1.5!

Anyway. After a conversation on Twitter about how it’s becoming increasingly harder to find the venerable WIN32.HLP file – and how it was becoming ever more outdated, I came to realize I didn’t know of any OllyDbg plugin to use the more modern and up to date MSDN documentation. I asked around and no one else seems to have written such a plugin, so I wrote my own.

It’s sort of a dirty hack – in general there’s no easy way of overriding existing features in Olly, the plugin API is rather meant to add new functionality. So after messing about with it for a while I came up with an easy hack – the plugin just hooks the WinHelp() API call to detect when WIN32.HLP is about to be opened, and launches the default web browser instead. Any other help file is launched normally.

The next step would be to search the MSDN looking for the API call the user requested. Then again, a quick hack came to the rescue since instead of figuring out how to perform MSDN searches it was much easier to just use a Google search with the “I Feel Lucky” button. You can find out more here about the unofficial Google Search API.

The plugin is also compatible with the newer Immunity Debugger which is based in OllyDbg, and was tested on both.

To install, just copy the DLL file in the plugins folder (by default is the same where the main EXE lives). You do need to have set the win32.hlp file in the configuration at some point (so Olly actually tries to open it, otherwise the plugin never finds out). It doesn’t need to be the real file though, any file named “win32.hlp” will do the trick, even if it’s 0 bytes long.

Enjoy!

Download

OllyMSDN.zip

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

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), debugging multiple processes simultaneously and produce a detailed log of application crashes, useful for fuzzing and automated testing.

Where can I find WinAppDbg?

The WinAppDbg project is currently hosted at Sourceforge, and can be found at:

http://winappdbg.sourceforge.net/

It’s also hosted at the Python Package Index (PyPi):

http://pypi.python.org/pypi/winappdbg/1.2

New features include:

• New tool: a simple command line debugger that supports plugins.
• Added support for Microsoft debugging symbols.
• Added support for py2exe, to generate standalone executables.
• New Win32 API functions added to win32.py
• Improvements to the breakpoints support, now “stalking” works for memory buffers and variables too.

This new version contains some bugfixes, so if you were using 1.0 I very much recommend to upgrade.

Download

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), debugging multiple processes simultaneously and produce a detailed log of application crashes, useful for fuzzing and automated testing.

Where can I find WinAppDbg?

The winappdbg project is currently hosted at Sourceforge, and can be found at:

http://winappdbg.sourceforge.net/