winappdbg.util

Miscellaneous utility classes and functions.

winappdbg.util.CustomAddressIterator(memory_map, condition)

Generator function that iterates through a memory map, filtering memory region blocks by any given condition.

Parameters:

memory_map (list( win32.MemoryBasicInformation )) – List of memory region information objects. Returned by Process.get_memory_map().
condition (function) – Callback function that returns True if the memory block should be returned, or False if it should be filtered.

Return type:

generator of win32.MemoryBasicInformation

Returns:

Generator object to iterate memory blocks.

winappdbg.util.DataAddressIterator(memory_map)

Generator function that iterates through a memory map, returning only those memory blocks that contain data.

Parameters:: memory_map (list( win32.MemoryBasicInformation )) – List of memory region information objects. Returned by Process.get_memory_map().
Return type:: generator of win32.MemoryBasicInformation
Returns:: Generator object to iterate memory blocks.

winappdbg.util.ExecutableAddressIterator(memory_map)

Generator function that iterates through a memory map, returning only those memory blocks that are executable.

Note

Executable memory is always readable too.

Parameters:: memory_map (list( win32.MemoryBasicInformation )) – List of memory region information objects. Returned by Process.get_memory_map().
Return type:: generator of win32.MemoryBasicInformation
Returns:: Generator object to iterate memory blocks.

winappdbg.util.ExecutableAndWriteableAddressIterator(memory_map)

Generator function that iterates through a memory map, returning only those memory blocks that are executable and writeable.

Note

The presence of such pages make memory corruption vulnerabilities much easier to exploit.

Parameters:: memory_map (list( win32.MemoryBasicInformation )) – List of memory region information objects. Returned by Process.get_memory_map().
Return type:: generator of win32.MemoryBasicInformation
Returns:: Generator object to iterate memory blocks.

winappdbg.util.ImageAddressIterator(memory_map)

Generator function that iterates through a memory map, returning only those memory blocks that belong to executable images.

Parameters:: memory_map (list( win32.MemoryBasicInformation )) – List of memory region information objects. Returned by Process.get_memory_map().
Return type:: generator of win32.MemoryBasicInformation
Returns:: Generator object to iterate memory blocks.

class winappdbg.util.IntelDebugRegister(*argv, **argd)

Class to manipulate x86/x64 debug registers. Used by HardwareBreakpoint_x86.

Trigger flags used by HardwareBreakpoint_x86

BREAK_ON_EXECUTION: Break on execution.
BREAK_ON_WRITE: Break on write.
BREAK_ON_ACCESS: Break on read or write.
BREAK_ON_IO_ACCESS: Break on I/O port access. Not supported by any hardware.

Size flags used by HardwareBreakpoint_x86

WATCH_BYTE: Watch a byte.
WATCH_WORD: Watch a word.
WATCH_DWORD: Watch a double word.
WATCH_QWORD: Watch one quad word.

Bitwise masks for Dr7

cvar 4-tuple of integers enableMask:

Enable bit on Dr7 for each slot. Works as a bitwise-OR mask.
cvar 4-tuple of integers disableMask:

Mask of the enable bit on Dr7 for each slot. Works as a bitwise-AND mask.
cvar 4-tuple of 2-tuples of integers triggerMask:

Trigger bits on Dr7 for each trigger flag value. Each 2-tuple has the bitwise-OR mask and the bitwise-AND mask.
cvar 4-tuple of 2-tuples of integers watchMask:

Watch bits on Dr7 for each watch flag value. Each 2-tuple has the bitwise-OR mask and the bitwise-AND mask.
cvar 4-tuple of integers clearMask:

Mask of all important bits on Dr7 for each slot. Works as a bitwise-AND mask.
cvar int generalDetectMask:

General detect mode bit. It enables the processor to notify the debugger when the debugee is trying to access one of the debug registers.

Bitwise masks for Dr6

cvar 4-tuple of integers hitMask:

Hit bit on Dr6 for each slot. Works as a bitwise-AND mask.
cvar int hitMaskAll:

Bitmask for all hit bits in Dr6. Useful to know if at least one hardware breakpoint was hit, or to clear the hit bits only.
cvar int clearHitMask:

Bitmask to clear all the hit bits in Dr6.
cvar int debugAccessMask:

The debugee tried to access a debug register. Needs bit generalDetectMask enabled in Dr7.
cvar int singleStepMask:

A single step exception was raised. Needs the trap flag enabled.
cvar int taskSwitchMask:

A task switch has occurred. Needs the TSS T-bit set to 1.
cvar int clearDr6Mask:

Bitmask to clear all meaningful bits in Dr6.

Debug control MSR definitions

DebugCtlMSR
LastBranchRecord
BranchTrapFlag
PinControl
LastBranchToIP
LastBranchFromIP
LastExceptionToIP
LastExceptionFromIP

classmethod clear_bp(ctx, register)

Clears a hardware breakpoint.

See:

find_slot(), set_bp()

Parameters:

ctx (dict( str, int )) – Thread context dictionary.
register (int) – Slot (debug register) for hardware breakpoint.

classmethod find_slot(ctx)

Finds an empty slot to set a hardware breakpoint.

See:: clear_bp(), set_bp()
Parameters:: ctx (dict( str, int )) – Thread context dictionary.
Return type:: int
Returns:: Slot (debug register) for hardware breakpoint.

classmethod set_bp(ctx, register, address, trigger, watch)

Sets a hardware breakpoint.

See:

clear_bp(), find_slot()

Parameters:

ctx (dict( str, int )) – Thread context dictionary.
register (int) – Slot (debug register).
address (int) – Memory address.
trigger (int) – Trigger flag. See HardwareBreakpoint_x86.validTriggers.
watch (int) – Watch flag. See HardwareBreakpoint_x86.validWatchSizes.

winappdbg.util.MappedAddressIterator(memory_map)

Generator function that iterates through a memory map, returning only those memory blocks that belong to memory mapped files.

Parameters:: memory_map (list( win32.MemoryBasicInformation )) – List of memory region information objects. Returned by Process.get_memory_map().
Return type:: generator of win32.MemoryBasicInformation
Returns:: Generator object to iterate memory blocks.

class winappdbg.util.MemoryAddresses(*argv, **argd)

Class to manipulate memory addresses.

Variables:: pageSize (int) – Page size in bytes. Defaults to 0x1000 but it’s automatically updated on runtime when importing the module.

classmethod align_address_range(begin, end)

Align the given address range to the start and end of the page(s) it occupies.

Parameters:

begin (int) – Memory address of the beginning of the buffer. Use None for the first legal address in the address space.
end (int) – Memory address of the end of the buffer. Use None for the last legal address in the address space.

Return type:

tuple( int, int )

Returns:

Aligned memory addresses.

classmethod align_address_to_page_end(address)

Align the given address to the end of the page it occupies. That is, to point to the start of the next page.

Parameters:: address (int) – Memory address.
Return type:: int
Returns:: Aligned memory address.

classmethod align_address_to_page_start(address)

Align the given address to the start of the page it occupies.

Parameters:: address (int) – Memory address.
Return type:: int
Returns:: Aligned memory address.

static do_ranges_intersect(begin, end, old_begin, old_end)

Determine if the two given memory address ranges intersect.

Parameters:

begin (int) – Start address of the first range.
end (int) – End address of the first range.
old_begin (int) – Start address of the second range.
old_end (int) – End address of the second range.

Return type:

bool

Returns:

True if the two ranges intersect, False otherwise.

classmethod get_buffer_size_in_pages(address, size)

Get the number of pages in use by the given buffer.

Parameters:

address (int) – Aligned memory address.
size (int) – Buffer size.

Return type:

int

Returns:

Buffer size in number of pages.

class winappdbg.util.PathOperations(*argv, **argd)

Static methods for filename and pathname manipulation.

static join_path(*components)

See:: split_path()
Parameters:: components (tuple( str... )) – Path components.
Return type:: str
Returns:: Absolute or relative path.

static make_absolute(path)

Parameters:: path (str) – Relative path.
Return type:: str
Returns:: Absolute path.

static make_relative(path, current=None)

Parameters:

path (str) – Absolute path.
current (str) – (Optional) Path to the current directory.

Return type:

str

Returns:

Relative path.

Raises:

WindowsError – It’s impossible to make the path relative. This happens when the path and the current path are not on the same disk drive or network share.

static native_to_win32_pathname(name)

Parameters:: name (str) – Native (NT) absolute pathname.
Return type:: str
Returns:: Win32 absolute pathname.

static path_is_absolute(path)

See:: path_is_relative()
Parameters:: path (str) – Absolute or relative path.
Return type:: bool
Returns:: True if the path is absolute, False if it’s relative.

static path_is_relative(path)

See:: path_is_absolute()
Parameters:: path (str) – Absolute or relative path.
Return type:: bool
Returns:: True if the path is relative, False if it’s absolute.

static pathname_to_filename(pathname)

Equivalent to: C{PathOperations.split_filename(pathname)[0]}

Parameters:: pathname (str) – Absolute path to a file.
Return type:: str
Returns:: Filename component of the path.

static split_extension(pathname)

Parameters:: pathname (str) – Absolute path.
Return type:: tuple( str, str )
Returns:: Tuple containing the file and extension components of the filename.

static split_filename(pathname)

Parameters:: pathname (str) – Absolute path.
Return type:: tuple( str, str )
Returns:: Tuple containing the path to the file and the base filename.

static split_path(path)

See:: join_path()
Parameters:: path (str) – Absolute or relative path.
Return type:: list( str… )
Returns:: List of path components.

winappdbg.util.ReadableAddressIterator(memory_map)

Generator function that iterates through a memory map, returning only those memory blocks that are readable.

Parameters:: memory_map (list( win32.MemoryBasicInformation )) – List of memory region information objects. Returned by Process.get_memory_map().
Return type:: generator of win32.MemoryBasicInformation
Returns:: Generator object to iterate memory blocks.

class winappdbg.util.Regenerator(g_function, *v_args, **d_args)

Calls a generator and iterates it. When it’s finished iterating, the generator is called again. This allows you to iterate a generator more than once (well, sort of).

next() → the next value, or raise StopIteration

winappdbg.util.WriteableAddressIterator(memory_map)

Generator function that iterates through a memory map, returning only those memory blocks that are writeable.

Note

Writeable memory is always readable too.

Parameters:: memory_map (list( win32.MemoryBasicInformation )) – List of memory region information objects. Returned by Process.get_memory_map().
Return type:: generator of win32.MemoryBasicInformation
Returns:: Generator object to iterate memory blocks.

winappdbg.util.dump_ctypes(obj, **kw)

Recursively pretty-print any ctypes Structure/Union/array/pointer.

Parameters:

c_obj (ctypes.Structure or ctypes.Union or ctypes.Array or ctypes._Pointer) – The ctypes object to pretty print
indent (int) – Current indentation level (used internally)
_visited (set) – Set to avoid infinite recursion on self-referential structs (used internally)

winappdbg.util.pretty_ctypes(c_obj, *, indent=0, _visited=None)

Recursively format any ctypes Structure/Union/array/pointer for pretty-printing.

Parameters:

c_obj (ctypes.Structure or ctypes.Union or ctypes.Array or ctypes._Pointer) – The ctypes object to pretty print
indent (int) – Current indentation level (used internally)
_visited (set) – Set to avoid infinite recursion on self-referential structs (used internally)

Return type:

str

Returns:

A formatted string representation of the ctypes object with proper indentation and structure