Welcome, Guest! Log In | Create Account

  1. Introduction
  2. Download
    1. Windows (32 bits)
    2. Windows (64 bits)
    3. Source code
  3. Install
  4. Dependencies
    1. Optional packages
  5. Documentation
  6. License
  7. Support
    1. Python interpreters
    2. Operating systems
    3. Architectures
  8. Related projects

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

The current version is 1.3. You can choose any of the following files (if in doubt, pick the first):

Windows (32 bits)

Windows (64 bits)

Source code

The Sourceforge project's download page contains all versions. 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 (setuptools), type the following at the command prompt: 

easy_install winappdbg

And WinAppDbg will be automatically downloaded and installed from the PyPI repository.

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.

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
Windows Vista full
Windows 7 full
Windows Server 2003 untested should probably work
Windows Server 2008 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!


Related projects

Here is a list of software projects that use WinAppDbg in alphabetical order:

  • PyPeElf is an open source GUI executable file analyzer for Windows and Linux released under the BSD license. You can download it here and there's also a blog.
  • SRS is a tool to spy on registry API calls made by the program of your choice.

Copyright © 2010 Geeknet, Inc. All rights reserved. Terms of Use