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

Class _ProcessContainer

source code

Encapsulates the capability to contain Process objects.

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 Process or Thread object with the same ID.		 source code
dictionary-valueiterator
__iter__(self)
Returns: Iterator of Process objects in this snapshot.		 source code
int
__len__(self)
Returns: Count of Process objects in this snapshot.		 source code
 
__find_processes_by_filename(self, filename)
Internally used by find_processes_by_filename.		 source code
 
_add_process(self, aProcess)
Private method to add a process object to the snapshot.		 source code
 
_del_process(self, dwProcessId)
Private method to remove a process object from the snapshot.		 source code
bool
_notify_create_process(self, event)
Notify the creation of a new process.		 source code
bool
_notify_exit_process(self, event)
Notify the termination of a process.		 source code
 
_ProcessContainer__find_processes_by_filename(self, filename)
Internally used by find_processes_by_filename.		 source code
 
_ProcessContainer__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

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

    Instrumentation
Process
start_process(self, lpCmdLine, **kwargs)
Starts a new process for instrumenting (or debugging).		 source code
int or None
get_explorer_pid(self)
Tries to find the process ID for "explorer.exe".		 source code
    Processes snapshot
bool
has_process(self, dwProcessId)
Returns: True if the snapshot contains a Process object with the given global ID.		 source code
Process
get_process(self, dwProcessId)
Returns: Process object with the given global ID.		 source code
dictionary-keyiterator
iter_process_ids(self)
Returns: Iterator of global process IDs in this snapshot.		 source code
dictionary-valueiterator
iter_processes(self)
Returns: Iterator of Process objects in this snapshot.		 source code
list( int )
get_process_ids(self)
Returns: List of global process IDs in this snapshot.		 source code
int
get_process_count(self)
Returns: Count of Process objects in this snapshot.		 source code
list of Window
get_windows(self)
Returns: Returns a list of windows handled by all processes in this snapshot.		 source code
int
get_pid_from_tid(self, dwThreadId)
Retrieves the global ID of the process that owns the thread.		 source code
bool
scan(self)
Populates the snapshot with running processes and threads, and loaded modules.		 source code
 
scan_processes(self)
Populates the snapshot with running processes.		 source code
 
scan_processes_fast(self)
Populates the snapshot with running processes.		 source code
bool
scan_process_filenames(self)
Update the filename for each process in the snapshot when possible.		 source code
 
clear_dead_processes(self)
Removes Process objects from the snapshot referring to processes no longer running.		 source code
 
clear_unattached_processes(self)
Removes Process objects from the snapshot referring to processes not being debugged.		 source code
 
close_process_handles(self)
Closes all open handles to processes in this snapshot.		 source code
 
close_process_and_thread_handles(self)
Closes all open handles to processes and threads in this snapshot.		 source code
 
clear_processes(self)
Removes all Process, Thread and Module objects in this snapshot.		 source code
 
clear(self)
Clears this snapshot.		 source code
list of tuple( Process, str )
find_processes_by_filename(self, fileName)
Returns: List of processes matching the given main module filename.		 source code
    Threads snapshots
 
scan_processes_and_threads(self)
Populates the snapshot with running processes and threads.		 source code
bool
has_thread(self, dwThreadId)
Returns: True if the snapshot contains a Thread object with the given global ID.		 source code
Thread
get_thread(self, dwThreadId)
Returns: Thread object with the given global ID.		 source code
list( int )
get_thread_ids(self)
Returns: List of global thread IDs in this snapshot.		 source code
int
get_thread_count(self)
Returns: Count of Thread objects in this snapshot.		 source code
    Modules snapshots
bool
scan_modules(self)
Populates the snapshot with loaded modules.		 source code
int
get_module_count(self)
Returns: Count of Module objects in this snapshot.		 source code
list( Module... )
find_modules_by_base(self, lpBaseOfDll)
Returns: List of Module objects with the given base address.		 source code
list( Module... )
find_modules_by_name(self, fileName)
Returns: List of Module objects found.		 source code
list( Module... )
find_modules_by_address(self, address)
Returns: List of Module objects that best match the given address.		 source code
Static Methods [hide private]
    Instrumentation
str
argv_to_cmdline(argv)
Convert a list of arguments to a single command line string.		 source code
list( str )
cmdline_to_argv(lpCmdLine)
Convert a single command line string to a list of arguments.		 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 (Process, Thread, int) -
    • int: Global ID of the process to look for.
    • int: Global ID of the thread to look for.
    • Process: Process object to look for.
    • Thread: Thread object to look for.
Returns: bool
True if the snapshot contains a Process or Thread object with the same ID.

__iter__(self)

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

See Also: iter_processes

__len__(self)
(Length operator)

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

See Also: get_process_count

has_process(self, dwProcessId)

source code 
Parameters:
  • dwProcessId (int) - Global ID of the process to look for.
Returns: bool
True if the snapshot contains a Process object with the given global ID.

get_process(self, dwProcessId)

source code 
Parameters:
  • dwProcessId (int) - Global ID of the process to look for.
Returns: Process
Process object with the given global ID.

iter_process_ids(self)

source code 
Returns: dictionary-keyiterator
Iterator of global process IDs in this snapshot.

See Also: iter_processes

iter_processes(self)

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

See Also: iter_process_ids

get_process_ids(self)

source code 
Returns: list( int )
List of global process IDs in this snapshot.

See Also: iter_process_ids

get_process_count(self)

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

get_windows(self)

source code 
Returns: list of Window
Returns a list of windows handled by all processes in this snapshot.

get_pid_from_tid(self, dwThreadId)

source code 

Retrieves the global ID of the process that owns the thread.

Parameters:
  • dwThreadId (int) - Thread global ID.
Returns: int
Process global ID.
Raises:
  • KeyError - The thread does not exist.

argv_to_cmdline(argv)
Static Method

source code 

Convert a list of arguments to a single command line string.

Parameters:
  • argv (list( str )) - List of argument strings. The first element is the program to execute.
Returns: str
Command line string.

cmdline_to_argv(lpCmdLine)
Static Method

source code 

Convert a single command line string to a list of arguments.

Parameters:
  • lpCmdLine (str) - Command line string. The first token is the program to execute.
Returns: list( str )
List of argument strings.

start_process(self, lpCmdLine, **kwargs)

source code 

Starts a new process for instrumenting (or debugging).

Parameters:
  • lpCmdLine (str) - Command line to execute. Can't be an empty string.
  • bConsole (bool) - True to inherit the console of the debugger. Defaults to False.
  • bDebug (bool) - True to attach to the new process. To debug a process it's best to use the Debug class instead. Defaults to False.
  • bFollow (bool) - True to automatically attach to the child processes of the newly created process. Ignored unless bDebug is True. Defaults to False.
  • bInheritHandles (bool) - True if the new process should inherit it's parent process' handles. Defaults to False.
  • bSuspended (bool) - True to suspend the main thread before any code is executed in the debugee. Defaults to False.
  • dwParentProcessId (int or None) - None if the debugger process should be the parent process (default), or a process ID to forcefully set as the debugee's parent (only available for Windows Vista and above).
  • iTrustLevel (int) - Trust level. Must be one of the following values:
    • 0: No trust. May not access certain resources, such as cryptographic keys and credentials. Only available since Windows XP and 2003, desktop editions.
    • 1: Normal trust. Run with the same privileges as a normal user, that is, one that doesn't have the Administrator or Power User user rights. Only available since Windows XP and 2003, desktop editions.
    • 2: Full trust. Run with the exact same privileges as the current user. This is the default value.
  • bAllowElevation (bool) - True to allow the child process to keep UAC elevation, if the debugger itself is running elevated. False to ensure the child process doesn't run with elevation. Defaults to True.

    This flag is only meaningful on Windows Vista and above, and if the debugger itself is running with elevation. It can be used to make sure the child processes don't run elevated as well.

    This flag DOES NOT force an elevation prompt when the debugger is not running with elevation.

    Note that running the debugger with elevation (or the Python interpreter at all for that matter) is not normally required. You should only need to if the target program requires elevation to work properly (for example if you try to debug an installer).

Returns: Process
Process object.

get_explorer_pid(self)

source code 

Tries to find the process ID for "explorer.exe".

Returns: int or None
Returns the process ID, or None on error.

scan(self)

source code 

Populates the snapshot with running processes and threads, and loaded modules.

Tipically this is the first method called after instantiating a System object, as it makes a best effort approach to gathering information on running processes.

Returns: bool
True if the snapshot is complete, False if the debugger doesn't have permission to scan some processes. In either case, the snapshot is complete for all processes the debugger has access to.

scan_processes_and_threads(self)

source code 

Populates the snapshot with running processes and threads.

Tipically you don't need to call this method directly, if unsure use scan instead.

Raises:
  • WindowsError - An error occured while updating the snapshot. The snapshot was not modified.

Note: This method uses the Toolhelp API.

See Also: scan_modules

scan_modules(self)

source code 

Populates the snapshot with loaded modules.

Tipically you don't need to call this method directly, if unsure use scan instead.

Returns: bool
True if the snapshot is complete, False if the debugger doesn't have permission to scan some processes. In either case, the snapshot is complete for all processes the debugger has access to.

Note: This method uses the Toolhelp API.

See Also: scan_processes_and_threads

scan_processes(self)

source code 

Populates the snapshot with running processes.

Tipically you don't need to call this method directly, if unsure use scan instead.

Raises:
  • WindowsError - An error occured while updating the snapshot. The snapshot was not modified.
Notes:
  • This method uses the Remote Desktop API instead of the Toolhelp API. It might give slightly different results, especially if the current process does not have full privileges.
  • This method will only retrieve process filenames. To get the process pathnames instead, after this method call scan_process_filenames.

scan_processes_fast(self)

source code 

Populates the snapshot with running processes. Only the PID is retrieved for each process.

Dead processes are removed. Threads and modules of living processes are ignored.

Tipically you don't need to call this method directly, if unsure use scan instead.

Note: This method uses the PSAPI. It may be faster for scanning, but some information may be missing, outdated or slower to obtain. This could be a good tradeoff under some circumstances.

scan_process_filenames(self)

source code 

Update the filename for each process in the snapshot when possible.

Returns: bool
True if all the pathnames were retrieved, False if the debugger doesn't have permission to scan some processes. In either case, all processes the debugger has access to have a full pathname instead of just a filename.

Note: Tipically you don't need to call this method. It's called automatically by scan to get the full pathname for each process when possible, since some scan methods only get filenames without the path component.

If unsure, use scan instead.

See Also: scan, Process.get_filename

clear(self)

source code 

Clears this snapshot.

See Also: clear_processes

has_thread(self, dwThreadId)

source code 
Parameters:
  • dwThreadId (int) - Global ID of the thread to look for.
Returns: bool
True if the snapshot contains a Thread object with the given global ID.

get_thread(self, dwThreadId)

source code 
Parameters:
  • dwThreadId (int) - Global ID of the thread to look for.
Returns: Thread
Thread object with the given global ID.

get_thread_ids(self)

source code 
Returns: list( int )
List of global thread IDs in this snapshot.

get_thread_count(self)

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

get_module_count(self)

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

find_modules_by_base(self, lpBaseOfDll)

source code 
Returns: list( Module... )
List of Module objects with the given base address.

find_modules_by_name(self, fileName)

source code 
Returns: list( Module... )
List of Module objects found.

find_modules_by_address(self, address)

source code 
Returns: list( Module... )
List of Module objects that best match the given address.

find_processes_by_filename(self, fileName)

source code 
Parameters:
  • fileName (str) - Filename to search for. If it's a full pathname, the match must be exact. If it's a base filename only, the file part is matched, regardless of the directory where it's located.
Returns: list of tuple( Process, str )
List of processes matching the given main module filename. Each tuple contains a Process object and it's filename.

Note: If the process is not found and the file extension is not given, this method will search again assuming a default extension (.exe).

_add_process(self, aProcess)

source code 

Private method to add a process object to the snapshot.

Parameters:
  • aProcess (Process) - Process object.

_del_process(self, dwProcessId)

source code 

Private method to remove a process object from the snapshot.

Parameters:
  • dwProcessId (int) - Global process ID.

_notify_create_process(self, event)

source code 

Notify the creation of a new process.

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_exit_process(self, event)

source code 

Notify the termination of a process.

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.

_ProcessContainer__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.


   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