The Win32 API wrappers

The win32 submodule provides a collection of useful API wrappers for most operations needed by a debugger. This will allow you to perform any task that the abstraction layer for some reason can’t deal with, or won’t deal with in the way you need. In most cases you won’t need to resort to this, but it’s important to know it’s there.

Except in some rare cases, the rationale to port the API calls to Python was:

• Take Python basic types as input, return Python basic types as output.
• Functions that in C take an output pointer and a size as input, in Python take neither and return the output data directly (the wrapper takes care of allocating the memory buffers).
• Functions that in C have to be called twice (first to get the buffer size, then to get the data) in Python only have to be called once (returns the data directly).
• Functions in C with more than one output pointer return tuples of data in Python.
• Functions in C that return an error condition, raise a Python exception (WindowsError) on error and return the data on success.
• Default parameter values were added when possible. The default for all optional pointers is NULL. The default flags are usually the ones that provide all possible access (for example, the default flags value for GetThreadContext is CONTEXT_ALL)
• For APIs with ANSI and Widechar versions, both versions are wrapped. If at least one parameter is a Unicode string en Widechar version is called (and all string parameters are converted to Unicode), otherwise the ANSI version is called. Either ANSI or Widechar versions can be used explicitly (for example, CreateFile can be called as CreateFileA or CreateFileW).

Example #1: finding a DLL in the search path

Download

import sys

from winappdbg import win32

fullpath, basename = win32.SearchPath( None, sys.argv[1], '.dll' )

print "Full path: %s" % fullpath
print "Base name: %s" % basename

Example #2: killing a process by attaching to it

Download

import sys
import thread

from winappdbg import win32

def processKiller(dwProcessId):

    # Attach to the process
    win32.DebugActiveProcess( dwProcessId )

    # Quit the current thread
    thread.exit()

Example #3: enumerating heap blocks using the Toolhelp library

Download

from winappdbg.win32 import *

def print_heap_blocks( pid ):

    # Determine if we have 32 bit or 64 bit pointers
    if sizeof(SIZE_T) == sizeof(DWORD):
        fmt = "%.8x\t%.8x\t%.8x"
        hdr = "%-8s\t%-8s\t%-8s"
    else:
        fmt = "%.16x\t%.16x\t%.16x"
        hdr = "%-16s\t%-16s\t%-16s"

    # Print a banner
    print "Heaps for process %d:" % pid
    print hdr % ("Heap ID", "Address", "Size")

    # Create a snapshot of the process, only take the heap list
    hSnapshot = CreateToolhelp32Snapshot( TH32CS_SNAPHEAPLIST, pid )

    # Enumerate the heaps
    heap = Heap32ListFirst( hSnapshot )
    while heap is not None:

        # For each heap, enumerate the entries
        entry = Heap32First( heap.th32ProcessID, heap.th32HeapID )
        while entry is not None:

            # Print the heap id and the entry address and size
            print fmt % (entry.th32HeapID, entry.dwAddress, entry.dwBlockSize)

            # Next entry in the heap
            entry = Heap32Next( entry )

        # Next heap in the list
        heap = Heap32ListNext( hSnapshot )

    # No need to call CloseHandle, the handle is closed automatically when it goes out of scope
    return

Example #4: enumerating modules using the Toolhelp library

Download

from winappdbg.win32 import *

def print_modules( pid ):

    # Determine if we have 32 bit or 64 bit pointers
    if sizeof(SIZE_T) == sizeof(DWORD):
        fmt = "%.8x    %.8x    %s"
        hdr = "%-8s    %-8s    %s"
    else:
        fmt = "%.16x    %.16x    %s"
        hdr = "%-16s    %-16s    %s"

    # Print a banner
    print "Modules for process %d:" % pid
    print
    print hdr % ("Address", "Size", "Path")

    # Create a snapshot of the process, only take the heap list
    hSnapshot = CreateToolhelp32Snapshot( TH32CS_SNAPMODULE, pid )

    # Enumerate the modules
    module = Module32First( hSnapshot )
    while module is not None:

        # Print the module address, size and pathname
        print fmt % ( module.modBaseAddr,
                      module.modBaseSize,
                      module.szExePath )

        # Next module in the process
        module = Module32Next( hSnapshot )

    # No need to call CloseHandle, the handle is closed automatically when it goes out of scope
    return

Example #5: enumerating device drivers

Download

from winappdbg.win32 import *

def print_drivers( fFullPath = False ):

    # Determine if we have 32 bit or 64 bit pointers
    if sizeof(SIZE_T) == sizeof(DWORD):
        fmt = "%.08x\t%s"
        hdr = "%-8s\t%s"
    else:
        fmt = "%.016x\t%s"
        hdr = "%-16s\t%s"

    # Get the list of loaded device drivers
    ImageBaseList = EnumDeviceDrivers()
    print "Device drivers found: %d" % len(ImageBaseList)
    print
    print hdr % ("Image base", "File name")

    # For each device driver...
    for ImageBase in ImageBaseList:

        # Get the device driver filename
        if fFullPath:
            DriverName = GetDeviceDriverFileName(ImageBase)
        else:
            DriverName = GetDeviceDriverBaseName(ImageBase)

        # Print the device driver image base and filename
        print fmt % (ImageBase, DriverName)