winappdbg.module

Module instrumentation.

Here is the logic for handling DLL libraries loaded by debugees.

exception winappdbg.module.DebugSymbolsWarning: This warning is issued if the support for debug symbols isn’t working properly.

class winappdbg.module.Module(lpBaseOfDll, hFile=None, fileName=None, SizeOfImage=None, EntryPoint=None, process=None)

Interface to a DLL library loaded in the context of another process.

Variables:

unknown – Suggested tag for unknown modules.
lpBaseOfDll – Base of DLL module. Use get_base() instead.
hFile – Handle to the module file. Use get_handle() instead.
fileName – Module filename. Use get_filename() instead.
SizeOfImage – Size of the module. Use get_size() instead.
EntryPoint – Entry point of the module. Use get_entry_point() instead.
process – Process where the module is loaded. Use the get_process() method instead.

clear(): Clears the resources held by this object.

close_handle(): Closes the handle to the module.

Note

Normally you don’t need to call this method. All handles created by WinAppDbg are automatically closed when the garbage collector claims them. So unless you’ve been tinkering with it, setting hFile to None should be enough.

get_base()

Returns:: Base address of the module. Returns None if unknown.
Return type:: int or None

get_entry_point()

Returns:: Entry point of the module. Returns None if unknown.
Return type:: int or None

get_filename()

Returns:: Module filename. Returns None if unknown.
Return type:: str or None

get_handle()

Returns:: Handle to the module file.
Return type:: FileHandle

get_label(function=None, offset=None)

Retrieves the label for the given function of this module or the module base address if no function name is given.

Parameters:

function (str) – (Optional) Exported function name.
offset (int) – (Optional) Offset from the module base address.

Returns:

Label for the module base address, plus the offset if given.

Return type:

str

get_label_at_address(address, offset=None)

Creates a label from the given memory address.

If the address belongs to the module, the label is made relative to it’s base address.

Parameters:

address (int) – Memory address.
offset (None or int) – (Optional) Offset value.

Returns:

Label pointing to the given address.

Return type:

str

get_load_count()

Retrieves the load count (reference count) of this module from the PEB.

This uses undocumented Windows structures and may not work on all Windows versions. The load count indicates how many times the module has been loaded.

Returns:: Load count of the module, 0xFFFF for pinned/system modules, or None if the count could not be retrieved.
Return type:: int or None

get_name()

Returns:: Module name, as used in labels.
Return type:: str

Warning

Names are NOT guaranteed to be unique.

If you need unique identification for a loaded module, use the base address instead.

See also

get_label()

get_pid()

Returns:: Parent process global ID. Returns None on error.
Return type:: int or None

get_process()

Returns:: Parent Process object. Returns None if unknown.
Return type:: Process

get_size()

Returns:: Base size of the module. Returns None if unknown.
Return type:: int or None

get_symbol_at_address(address)

Tries to find the closest matching symbol for the given address.

Parameters:

address (int) – Memory address to query.

Returns:

Returns a tuple consisting of:

Name
Address
Size (in bytes)

Returns None if no symbol could be matched.

Return type:

None or tuple(str, int, int)

get_symbols()

Returns the debugging symbols for a module. The symbols are automatically loaded when needed.

Returns:: List of symbols. Each symbol is represented by a tuple that contains: - Symbol name - Symbol memory address - Symbol size in bytes
Return type:: list(tuple(str, int, int))

is_address_here(address)

Tries to determine if the given address belongs to this module.

Parameters:: address (int) – Memory address.
Returns:: True if the address belongs to the module, False if it doesn’t, and None if it can’t be determined.
Return type:: bool or None

is_pinned()

Determines if this module is pinned (cannot be unloaded).

A module is considered pinned if its load count is 0xFFFF. This happens for system modules and modules that have been explicitly pinned using GetModuleHandleEx with the GET_MODULE_HANDLE_EX_FLAG_PIN flag.

Returns:: True if the module is pinned, False if it’s not pinned, or None if the pinned status could not be determined.
Return type:: bool or None

iter_symbols()

Returns an iterator for the debugging symbols in a module, in no particular order. The symbols are automatically loaded when needed.

Returns:: Iterator of symbols. Each symbol is represented by a tuple that contains: - Symbol name - Symbol memory address - Symbol size in bytes
Return type:: iterator of tuple(str, int, int)

load_symbols(): Loads the debugging symbols for a module. Automatically called by get_symbols().

match_name(name)

Returns:: True if the given name could refer to this module. It may not be exactly the same returned by get_name().
Return type:: bool

open_handle()

Opens a new handle to the module.

The new handle is stored in the hFile property.

resolve(function)

Resolves a function exported by this module.

Parameters:

function (str, bytes or int) –

str: Name of the function (Unicode).
bytes: Name of the function (ANSI).
int: Ordinal of the function.

Returns:

Memory address of the exported function in the process. Returns None on error.

Return type:

int

resolve_label(label)

Resolves a label for this module only. If the label refers to another module, an exception is raised.

Parameters:

label (str) – Label to resolve.

Returns:

Memory address pointed to by the label.

Return type:

int

Raises:

ValueError – The label is malformed or impossible to resolve.
RuntimeError – Cannot resolve the module or function.

resolve_symbol(symbol, bCaseSensitive=False)

Resolves a debugging symbol’s address.

Parameters:

symbol (str) – Name of the symbol to resolve.
bCaseSensitive (bool) – True for case sensitive matches, False for case insensitive.

Returns:

Memory address of symbol. None if not found.

Return type:

int or None

set_handle(hFile)

Parameters:: hFile (Handle) – File handle. Use None to clear.

set_process(process=None)

Manually set the parent process. Use with care!

Parameters:: process (Process) – (Optional) Process object. Use None for no process.

unload_symbols(): Unloads the debugging symbols for a module.