Downloading and installing¶
This is what you need to know to download, install and begin to use WinAppDbg:
Latest version¶
The latest version is 1.6. The project’s download page has this version. You can also get the bleeding-edge version from the Github repository.
Older versions¶
Older versions are still available for download as well at the old Sourceforge site.
| Version 1.5 (20 Dec 2013) | |
| Version 1.4 (10 Dec 2010) | |
| Version 1.3 (12 Feb 2010) | |
| Version 1.2 (16 Jun 2009) | |
| Version 1.1 (18 May 2009) | |
| Version 1.0 (22 Apr 2009) |
Dependencies¶
Naturally you need the Python interpreter. It’s recommended to use Python 2.7. You’ll have to install the 32 bit VM to debug 32 bit targets and the 64 bit VM for 64 bit targets. Both VMs can be installed on the same machine.
The following packages provide extra features and performance improvements, they are very recommended but not mandatory.
Disassembler¶
WinAppDbg itself doesn’t come with a disassembler, but all of the following are compatible. WinAppDbg will pick the most suitable one automatically when needed, but you can also decide which one to use.
Debugging Symbols¶
WinAppDbg has the capability to download debugging symbols from the Microsoft Debugging Symbols server. For best results, install the Microsoft SDK.
Database storage¶
The SQL Alchemy ORM module gives WinAppDbg the ability to use a SQL database to store and find crash dumps. Most major database engines are supported.
Other goodies¶
Running WinAppDbg under Python interpreters other than CPython is considered experimental, but you may experience performance gains by using them. Also, in older versions of CPython (up until Python 2.5), with the Python specializing compiler Psyco, WinAppDbg will experience a performance gain just by installing it, no additional steps are needed. You can download the sources and some old precompiled binaries from the official site and newer but unofficial builds from Voidspace.
Also 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.
Install¶
You can install directly from the sources package, extract it to any temporary folder and run the following command:
install.bat
You can also install WinAppDbg (stable versions only) from the Cheese Shop using any of the compatible package managers:
-
pip install winappdbg
PyPM (only when using ActivePython)
Easy Install (formerly from Setuptools, now from Distribute)
easy_install winappdbg
Python Package Manager (it’s a GUI installer)
Support¶
Minimim requirements:
- Windows XP
- Python 2.5
Recommended platform:
- Windows 7
- Python 2.7
It might work, but was not tested, under Windows 2000, Wine and ReactOS, and some bugs and missing features are to be expected in these platforms (mainly due to missing APIs).
Python 3 support was experimental up to WinAppDbg 1.4, and was dropped with WinAppDbg 1.5. There are currently no plans to support Python 3 in the near future - backwards compatibility would be broken and plenty of code would need to be refactored just to port it.
While there are still some issues that need ironing out, it may be worth trying out faster Python interpreters such as PyPy and IronPython.
If you find a bug or have a feature suggestion, don’t hesitate to open a new issue. 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. Untested means that though no testing was performed it should probably work. Experimental means it’s not expected to work and although it might, you can encounter many bugs.
Python interpreters¶
| Version | Status | Notes |
|---|---|---|
| CPython 2.4 and earlier | not supported | Use an older version of WinAppDbg in this case. |
| CPython 2.5 through 2.7 | full | |
| CPython 3.0 and newer | not supported | Planned for WinAppDbg 2.0. |
| PyPy 1.4 and earlier | not supported | It doesn’t seem to be available for download any more… |
| PyPy 1.5 and 1.6 | experimental | The sqlite3 dll is missing, after you fix that it should be the same as newer versions. |
| PyPy 1.7 and newer | experimental | Some compatibility issues need fixing. |
| IronPython 2.0 and newer | experimental | Some compatibility issues need fixing. |
| Jython 2.5 and earlier | not supported | Support for ctypes is incomplete in this platform. |
Operating systems¶
| Version | Status | Notes |
|---|---|---|
| Windows 2000 and older | not supported | Some required Win32 API functions didn’t exist yet. |
| Windows XP | full | |
| Windows Server 2003 | full | |
| Windows Server 2003 R2 | full | |
| Windows Vista | full | |
| Windows 7 | full | |
| Windows Server 2008 | full | |
| Windows Server 2008 R2 | full | |
| Windows 8 | untested | Probably similar to Windows 7. |
| Windows Server 2012 | untested | Probably similar to Windows Server 2008 R2. |
| Windows 10 | untested | Probably similar to Windows 7. |
| ReactOS | untested | Probably similar to Windows 2000. |
| Linux (using Wine 1.2) | untested | Reported to work on Ubuntu. |
| Linux (using Wine 1.3) | untested | Reported to work on Ubuntu. |
| Windows + Cygwin | partial | Some features may be missing. |
| Windows Phone | not supported | Planned for WinAppDbg 2.0. |
Architectures¶
| Version | Status | Notes |
|---|---|---|
| Intel (32 bits) | full | |
| Intel (64 bits) | full | |
| ARM | not supported | Planned for WinAppDbg 2.0. |
Known issues¶
- Python strings default encoding is ‘ascii’ since Python 2.5. While we did our best to prevent encoding errors when manipulating binary data, we recommend setting the default to ‘latin-1’ (ISO 8859-1) instead. You can do this by adding a sitecustomize.py script to your Python installation.
- Step-on-branch mode stopped working since Windows Vista. This is due to a change in the Windows kernel. The next major version of WinAppDbg (2.0) will support this.
- Debugging 32 bit processes from a 64 bit Python VM does not work very well. Debugging 64 bit processes from a 32 bit Python VM does not work at all. This is in part because the Win32 API makes it difficult, but there’s also a design problem in WinAppDbg: most of the C struct definitions change from 32 to 64 bits and there’s currently no support for having both definitions at the same time. This will change with WinAppDbg 2.0 too.
- Setting hardware breakpoints in the main thread before the process has finished initializing does not work. This is not supported by the Windows API itself, and is not a limitation of WinAppDbg. Future versions of WinAppDbg will try to detect this error and warn about it.
License¶
This software 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. The sources to this documentation are also provided and can be compiled with Sphinx.