Home       Trees       Indices       Help   
WinAppDbg - Programming Reference
Package winappdbg :: Module module :: Class _ModuleContainer
[hide private]
[frames] | no frames]

Class _ModuleContainer

source code

Encapsulates the capability to contain Module objects.

Note: Labels are an approximated way of referencing memory locations across different executions of the same process, or different processes with common modules. They are not meant to be perfectly unique, and some errors may occur when multiple modules with the same name are loaded, or when module filenames can't be retrieved.

Instance Methods [hide private]
 
__init__(self)
x.__init__(...) initializes x; see help(type(x)) for signature		 source code
 
__initialize_snapshot(self)
Private method to automatically initialize the snapshot when you try to use it without calling any of the scan_* methods first.		 source code
bool
__contains__(self, anObject)
Returns: True if the snapshot contains a Module object with the same base address.		 source code
dictionary-valueiterator
__iter__(self)
Returns: Iterator of Module objects in this snapshot.		 source code
int
__len__(self)
Returns: Count of Module objects in this snapshot.		 source code
 
__use_fuzzy_mode(self, label) source code
 
__get_system_breakpoint(self, label) source code
 
_add_module(self, aModule)
Private method to add a module object to the snapshot.		 source code
 
_del_module(self, lpBaseOfDll)
Private method to remove a module object from the snapshot.		 source code
 
__add_loaded_module(self, event)
Private method to automatically add new module objects from debug events.		 source code
bool
_notify_create_process(self, event)
Notify the load of the main module.		 source code
bool
_notify_load_dll(self, event)
Notify the load of a new module.		 source code
bool
_notify_unload_dll(self, event)
Notify the release of a loaded module.		 source code
 
_ModuleContainer__add_loaded_module(self, event)
Private method to automatically add new module objects from debug events.		 source code
 
_ModuleContainer__get_system_breakpoint(self, label) source code
 
_ModuleContainer__initialize_snapshot(self)
Private method to automatically initialize the snapshot when you try to use it without calling any of the scan_* methods first.		 source code
 
_ModuleContainer__use_fuzzy_mode(self, label) source code

Inherited from object: __delattr__, __format__, __getattribute__, __hash__, __new__, __reduce__, __reduce_ex__, __repr__, __setattr__, __sizeof__, __str__, __subclasshook__

    Modules snapshot
bool
has_module(self, lpBaseOfDll)
Returns: True if the snapshot contains a Module object with the given base address.		 source code
Module
get_module(self, lpBaseOfDll)
Returns: Module object with the given base address.		 source code
dictionary-keyiterator
iter_module_addresses(self)
Returns: Iterator of DLL base addresses in this snapshot.		 source code
dictionary-valueiterator
iter_modules(self)
Returns: Iterator of Module objects in this snapshot.		 source code
list( int... )
get_module_bases(self)
Returns: List of DLL base addresses in this snapshot.		 source code
int
get_module_count(self)
Returns: Count of Module objects in this snapshot.		 source code
Module
get_module_by_name(self, modName)
Returns: Module object that best matches the given name.		 source code
Module
get_module_at_address(self, address)
Returns: Module object that best matches the given address.		 source code
 
scan_modules(self)
Populates the snapshot with loaded modules.		 source code
 
clear_modules(self)
Clears the modules snapshot.		 source code
    Labels
tuple( str or None, str or int or None, int or None )
split_label_fuzzy(self, label)
Splits a label entered as user input.		 source code
str
sanitize_label(self, label)
Converts a label taken from user input into a well-formed label.		 source code
int
resolve_label(self, label)
Resolve the memory address of the given label.		 source code
int
resolve_label_components(self, module=None, function=None, offset=None)
Resolve the memory address of the given module, function and/or offset.		 source code
str
get_label_at_address(self, address, offset=None)
Creates a label from the given memory address.		 source code
    Symbols
 
load_symbols(self)
Loads the debugging symbols for all modules in this snapshot.		 source code
 
unload_symbols(self)
Unloads the debugging symbols for all modules in this snapshot.		 source code
list of tuple( str, int, int )
get_symbols(self)
Returns the debugging symbols for all modules in this snapshot.		 source code
iterator of tuple( str, int, int )
iter_symbols(self)
Returns an iterator for the debugging symbols in all modules in this snapshot, in no particular order.		 source code
int or None
resolve_symbol(self, symbol, bCaseSensitive=False)
Resolves a debugging symbol's address.		 source code
None or tuple( str, int, int )
get_symbol_at_address(self, address)
Tries to find the closest matching symbol for the given address.		 source code
    Debugging
int
get_break_on_error_ptr(self)
Returns: If present, returns the address of the g_dwLastErrorToBreakOn global variable for this process.		 source code
bool
is_system_defined_breakpoint(self, address)
Returns: True if the given address points to a system defined breakpoint.		 source code
int or None
get_system_breakpoint(self)
Returns: Memory address of the system breakpoint within the process address space.		 source code
int or None
get_user_breakpoint(self)
Returns: Memory address of the user breakpoint within the process address space.		 source code
int or None
get_breakin_breakpoint(self)
Returns: Memory address of the remote breakin breakpoint within the process address space.		 source code
int or None
get_wow64_system_breakpoint(self)
Returns: Memory address of the Wow64 system breakpoint within the process address space.		 source code
int or None
get_wow64_user_breakpoint(self)
Returns: Memory address of the Wow64 user breakpoint within the process address space.		 source code
int or None
get_wow64_breakin_breakpoint(self)
Returns: Memory address of the Wow64 remote breakin breakpoint within the process address space.		 source code
Class Methods [hide private]
    Labels
tuple( str or None, str or int or None, int or None )
split_label(cls, label)
Splits a label into it's module, function and offset components, as used in parse_label.		 source code
Static Methods [hide private]
    Labels
str
parse_label(module=None, function=None, offset=None)
Creates a label from a module and a function name, plus an offset.		 source code
tuple( str or None, str or int or None, int or None )
split_label_strict(label)
Splits a label created with parse_label.		 source code
Properties [hide private]

Inherited from object: __class__

Method Details [hide private]

__init__(self)
(Constructor)

source code 

x.__init__(...) initializes x; see help(type(x)) for signature

Overrides: object.__init__
(inherited documentation)

__initialize_snapshot(self)

source code 

Private method to automatically initialize the snapshot when you try to use it without calling any of the scan_* methods first. You don't need to call this yourself.

__contains__(self, anObject)
(In operator)

source code 
Parameters:
  • anObject (Module, int) -
    • Module: Module object to look for.
    • int: Base address of the DLL to look for.
Returns: bool
True if the snapshot contains a Module object with the same base address.

__iter__(self)

source code 
Returns: dictionary-valueiterator
Iterator of Module objects in this snapshot.

See Also: iter_modules

__len__(self)
(Length operator)

source code 
Returns: int
Count of Module objects in this snapshot.

See Also: get_module_count

has_module(self, lpBaseOfDll)

source code 
Parameters:
  • lpBaseOfDll (int) - Base address of the DLL to look for.
Returns: bool
True if the snapshot contains a Module object with the given base address.

get_module(self, lpBaseOfDll)

source code 
Parameters:
  • lpBaseOfDll (int) - Base address of the DLL to look for.
Returns: Module
Module object with the given base address.

iter_module_addresses(self)

source code 
Returns: dictionary-keyiterator
Iterator of DLL base addresses in this snapshot.

See Also: iter_modules

iter_modules(self)

source code 
Returns: dictionary-valueiterator
Iterator of Module objects in this snapshot.

See Also: iter_module_addresses

get_module_bases(self)

source code 
Returns: list( int... )
List of DLL base addresses in this snapshot.

See Also: iter_module_addresses

get_module_count(self)

source code 
Returns: int
Count of Module objects in this snapshot.

get_module_by_name(self, modName)

source code 
Parameters:
  • modName (int) - Name of the module to look for, as returned by Module.get_name. If two or more modules with the same name are loaded, only one of the matching modules is returned.

    You can also pass a full pathname to the DLL file. This works correctly even if two modules with the same name are loaded from different paths.

Returns: Module
Module object that best matches the given name. Returns None if no Module can be found.

get_module_at_address(self, address)

source code 
Parameters:
  • address (int) - Memory address to query.
Returns: Module
Module object that best matches the given address. Returns None if no Module can be found.

parse_label(module=None, function=None, offset=None)
Static Method

source code 

Creates a label from a module and a function name, plus an offset.

Parameters:
  • module (None or str) - (Optional) Module name.
  • function (None, str or int) - (Optional) Function name or ordinal.
  • offset (None or int) - (Optional) Offset value.

    If function is specified, offset from the function.

    If function is None, offset from the module.

Returns: str
Label representing the given function in the given module.
Raises:
  • ValueError - The module or function name contain invalid characters.

Warning: This method only creates the label, it doesn't make sure the label actually points to a valid memory location.

split_label_strict(label)
Static Method

source code 

Splits a label created with parse_label.

To parse labels with a less strict syntax, use the split_label_fuzzy method instead.

Parameters:
  • label (str) - Label to split.
Returns: tuple( str or None, str or int or None, int or None )
Tuple containing the module name, the function name or ordinal, and the offset value.

If the label doesn't specify a module, then module is None.

If the label doesn't specify a function, then function is None.

If the label doesn't specify an offset, then offset is 0.

Raises:
  • ValueError - The label is malformed.

Warning: This method only parses the label, it doesn't make sure the label actually points to a valid memory location.

split_label_fuzzy(self, label)

source code 

Splits a label entered as user input.

It's more flexible in it's syntax parsing than the split_label_strict method, as it allows the exclamation mark (!) to be omitted. The ambiguity is resolved by searching the modules in the snapshot to guess if a label refers to a module or a function. It also tries to rebuild labels when they contain hardcoded addresses.

Parameters:
  • label (str) - Label to split.
Returns: tuple( str or None, str or int or None, int or None )
Tuple containing the module name, the function name or ordinal, and the offset value.

If the label doesn't specify a module, then module is None.

If the label doesn't specify a function, then function is None.

If the label doesn't specify an offset, then offset is 0.

Raises:
  • ValueError - The label is malformed.

Warning: This method only parses the label, it doesn't make sure the label actually points to a valid memory location.

split_label(cls, label)
Class Method

source code 

Splits a label into it's module, function and offset components, as used in parse_label.

When called as a static method, the strict syntax mode is used:

   winappdbg.Process.split_label( "kernel32!CreateFileA" )

When called as an instance method, the fuzzy syntax mode is used:

   aProcessInstance.split_label( "CreateFileA" )
Parameters:
  • label (str) - Label to split.
Returns: tuple( str or None, str or int or None, int or None )
Tuple containing the module name, the function name or ordinal, and the offset value.

If the label doesn't specify a module, then module is None.

If the label doesn't specify a function, then function is None.

If the label doesn't specify an offset, then offset is 0.

Raises:
  • ValueError - The label is malformed.

See Also: split_label_strict, split_label_fuzzy

__use_fuzzy_mode(self, label)

source code 

See Also: split_label

sanitize_label(self, label)

source code 

Converts a label taken from user input into a well-formed label.

Parameters:
  • label (str) - Label taken from user input.
Returns: str
Sanitized label.

resolve_label(self, label)

source code 

Resolve the memory address of the given label.

Parameters:
  • label (str) - Label to resolve.
Returns: int
Memory address pointed to by the label.
Raises:
  • ValueError - The label is malformed or impossible to resolve.
  • RuntimeError - Cannot resolve the module or function.

Note: If multiple modules with the same name are loaded, the label may be resolved at any of them. For a more precise way to resolve functions use the base address to get the Module object (see Process.get_module) and then call Module.resolve.

If no module name is specified in the label, the function may be resolved in any loaded module. If you want to resolve all functions with that name in all processes, call Process.iter_modules to iterate through all loaded modules, and then try to resolve the function in each one of them using Module.resolve.

resolve_label_components(self, module=None, function=None, offset=None)

source code 

Resolve the memory address of the given module, function and/or offset.

Parameters:
  • module (None or str) - (Optional) Module name.
  • function (None, str or int) - (Optional) Function name or ordinal.
  • offset (None or int) - (Optional) Offset value.

    If function is specified, offset from the function.

    If function is None, offset from the module.

Returns: int
Memory address pointed to by the label.
Raises:
  • ValueError - The label is malformed or impossible to resolve.
  • RuntimeError - Cannot resolve the module or function.

Note: If multiple modules with the same name are loaded, the label may be resolved at any of them. For a more precise way to resolve functions use the base address to get the Module object (see Process.get_module) and then call Module.resolve.

If no module name is specified in the label, the function may be resolved in any loaded module. If you want to resolve all functions with that name in all processes, call Process.iter_modules to iterate through all loaded modules, and then try to resolve the function in each one of them using Module.resolve.

get_label_at_address(self, address, offset=None)

source code 

Creates a label from the given memory address.

Parameters:
  • address (int) - Memory address.
  • offset (None or int) - (Optional) Offset value.
Returns: str
Label pointing to the given address.

Warning: This method uses the name of the nearest currently loaded module. If that module is unloaded later, the label becomes impossible to resolve.

get_break_on_error_ptr(self)

source code 
Returns: int
If present, returns the address of the g_dwLastErrorToBreakOn global variable for this process. If not, returns None.

is_system_defined_breakpoint(self, address)

source code 
Parameters:
  • address (int) - Memory address.
Returns: bool
True if the given address points to a system defined breakpoint. System defined breakpoints are hardcoded into system libraries.

get_system_breakpoint(self)

source code 
Returns: int or None
Memory address of the system breakpoint within the process address space. Returns None on error.

get_user_breakpoint(self)

source code 
Returns: int or None
Memory address of the user breakpoint within the process address space. Returns None on error.

get_breakin_breakpoint(self)

source code 
Returns: int or None
Memory address of the remote breakin breakpoint within the process address space. Returns None on error.

get_wow64_system_breakpoint(self)

source code 
Returns: int or None
Memory address of the Wow64 system breakpoint within the process address space. Returns None on error.

get_wow64_user_breakpoint(self)

source code 
Returns: int or None
Memory address of the Wow64 user breakpoint within the process address space. Returns None on error.

get_wow64_breakin_breakpoint(self)

source code 
Returns: int or None
Memory address of the Wow64 remote breakin breakpoint within the process address space. Returns None on error.

load_symbols(self)

source code 

Loads the debugging symbols for all modules in this snapshot. Automatically called by get_symbols.

get_symbols(self)

source code 

Returns the debugging symbols for all modules in this snapshot. The symbols are automatically loaded when needed.

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

iter_symbols(self)

source code 

Returns an iterator for the debugging symbols in all modules in this snapshot, in no particular order. The symbols are automatically loaded when needed.

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

resolve_symbol(self, symbol, bCaseSensitive=False)

source code 

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: int or None
Memory address of symbol. None if not found.

get_symbol_at_address(self, address)

source code 

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

Parameters:
  • address (int) - Memory address to query.
Returns: None or tuple( str, int, int )
Returns a tuple consisting of:
  • Name
  • Address
  • Size (in bytes)

Returns None if no symbol could be matched.

_add_module(self, aModule)

source code 

Private method to add a module object to the snapshot.

Parameters:
  • aModule (Module) - Module object.

_del_module(self, lpBaseOfDll)

source code 

Private method to remove a module object from the snapshot.

Parameters:
  • lpBaseOfDll (int) - Module base address.

__add_loaded_module(self, event)

source code 

Private method to automatically add new module objects from debug events.

Parameters:
  • event (Event) - Event object.

_notify_create_process(self, event)

source code 

Notify the load of the main module.

This is done automatically by the Debug class, you shouldn't need to call it yourself.

Parameters:
Returns: bool
True to call the user-defined handle, False otherwise.

_notify_load_dll(self, event)

source code 

Notify the load of a new module.

This is done automatically by the Debug class, you shouldn't need to call it yourself.

Parameters:
Returns: bool
True to call the user-defined handle, False otherwise.

_notify_unload_dll(self, event)

source code 

Notify the release of a loaded module.

This is done automatically by the Debug class, you shouldn't need to call it yourself.

Parameters:
Returns: bool
True to call the user-defined handle, False otherwise.

_ModuleContainer__add_loaded_module(self, event)

source code 

Private method to automatically add new module objects from debug events.

Parameters:
  • event (Event) - Event object.

_ModuleContainer__initialize_snapshot(self)

source code 

Private method to automatically initialize the snapshot when you try to use it without calling any of the scan_* methods first. You don't need to call this yourself.

_ModuleContainer__use_fuzzy_mode(self, label)

source code 

See Also: split_label


   Home       Trees       Indices       Help   
WinAppDbg - Programming Reference
Generated by Epydoc 3.0.1 on Fri Dec 20 17:54:54 2013 http://epydoc.sourceforge.net