Package winappdbg :: Module system :: Class System
[hide private]
[frames] | no frames]

Class System

source code


Interface to a batch of processes, plus some system wide settings. Contains a snapshot of processes.

Instance Methods [hide private]
bool
__contains__(self, anObject)
Returns: True if the snapshot contains a Process or Thread object with the same ID. (Inherited from winappdbg.system.ProcessContainer)
source code
 
__init__(self)
x.__init__(...) initializes x; see x.__class__.__doc__ for signature (Inherited from winappdbg.system.ProcessContainer)
source code
dictionary-valueiterator
__iter__(self)
Returns: Iterator of Process objects in this snapshot. (Inherited from winappdbg.system.ProcessContainer)
source code
int
__len__(self)
Returns: Count of Process objects in this snapshot. (Inherited from winappdbg.system.ProcessContainer)
source code
 
get_windows(self) (Inherited from winappdbg.system.ProcessContainer) source code

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

    Instrumentation
Process
start_process(self, lpCmdLine, bConsole=False, bDebug=False, bFollow=False, bSuspended=False, bInheritHandles=False, dwParentProcessId=None)
Starts a new process for instrumenting (or debugging). (Inherited from winappdbg.system.ProcessContainer)
source code
    Processes snapshot
 
clear(self)
Clears this snapshot. (Inherited from winappdbg.system.ProcessContainer)
source code
 
clear_dead_processes(self)
Removes Process objects from the snapshot referring to processes no longer running. (Inherited from winappdbg.system.ProcessContainer)
source code
 
clear_processes(self)
Removes all Process, Thread and Module objects in this snapshot. (Inherited from winappdbg.system.ProcessContainer)
source code
 
clear_unattached_processes(self)
Removes Process objects from the snapshot referring to processes not being debugged. (Inherited from winappdbg.system.ProcessContainer)
source code
 
close_process_and_thread_handles(self)
Closes all open handles to processes and threads in this snapshot. (Inherited from winappdbg.system.ProcessContainer)
source code
 
close_process_handles(self)
Closes all open handles to processes in this snapshot. (Inherited from winappdbg.system.ProcessContainer)
source code
list of tuple( Process, str )
find_processes_by_filename(self, fileName)
Returns: List of processes matching the given main module filename. (Inherited from winappdbg.system.ProcessContainer)
source code
int or None
get_pid_from_tid(self, dwThreadId)
Tries to retrieve the global ID of the process that owns the thread. (Inherited from winappdbg.system.ProcessContainer)
source code
Process
get_process(self, dwProcessId)
Returns: Process object with the given global ID. (Inherited from winappdbg.system.ProcessContainer)
source code
int
get_process_count(self)
Returns: Count of Process objects in this snapshot. (Inherited from winappdbg.system.ProcessContainer)
source code
list( int )
get_process_ids(self)
Returns: List of global process IDs in this snapshot. (Inherited from winappdbg.system.ProcessContainer)
source code
bool
has_process(self, dwProcessId)
Returns: True if the snapshot contains a Process object with the given global ID. (Inherited from winappdbg.system.ProcessContainer)
source code
dictionary-keyiterator
iter_process_ids(self)
Returns: Iterator of global process IDs in this snapshot. (Inherited from winappdbg.system.ProcessContainer)
source code
dictionary-valueiterator
iter_processes(self)
Returns: Iterator of Process objects in this snapshot. (Inherited from winappdbg.system.ProcessContainer)
source code
 
scan(self)
Populates the snapshot with running processes and threads, and loaded modules. (Inherited from winappdbg.system.ProcessContainer)
source code
 
scan_processes(self)
Populates the snapshot with running processes. (Inherited from winappdbg.system.ProcessContainer)
source code
 
scan_processes_fast(self)
Populates the snapshot with running processes. (Inherited from winappdbg.system.ProcessContainer)
source code
    Threads snapshots
Thread
get_thread(self, dwThreadId)
Returns: Thread object with the given global ID. (Inherited from winappdbg.system.ProcessContainer)
source code
int
get_thread_count(self)
Returns: Count of Thread objects in this snapshot. (Inherited from winappdbg.system.ProcessContainer)
source code
list( int )
get_thread_ids(self)
Returns: List of global thread IDs in this snapshot. (Inherited from winappdbg.system.ProcessContainer)
source code
bool
has_thread(self, dwThreadId)
Returns: True if the snapshot contains a Thread object with the given global ID. (Inherited from winappdbg.system.ProcessContainer)
source code
 
scan_processes_and_threads(self)
Populates the snapshot with running processes and threads. (Inherited from winappdbg.system.ProcessContainer)
source code
    Modules snapshots
list( Module... )
find_modules_by_address(self, address)
Returns: List of Module objects that best match the given address. (Inherited from winappdbg.system.ProcessContainer)
source code
list( Module... )
find_modules_by_base(self, lpBaseOfDll)
Returns: List of Module objects with the given base address. (Inherited from winappdbg.system.ProcessContainer)
source code
list( Module... )
find_modules_by_name(self, fileName)
Returns: List of Module objects found. (Inherited from winappdbg.system.ProcessContainer)
source code
int
get_module_count(self)
Returns: Count of Module objects in this snapshot. (Inherited from winappdbg.system.ProcessContainer)
source code
 
scan_modules(self)
Populates the snapshot with loaded modules. (Inherited from winappdbg.system.ProcessContainer)
source code
    Event notifications (private)
 
notify_create_process(self, event)
Notify the creation of a new process. (Inherited from winappdbg.system.ProcessContainer)
source code
 
notify_exit_process(self, event)
Notify the termination of a process. (Inherited from winappdbg.system.ProcessContainer)
source code
Static Methods [hide private]
    Global settings
 
request_debug_privileges(bIgnoreExceptions=False)
Requests debug privileges.
source code
bool
set_kill_on_exit_mode(bKillOnExit=False)
Automatically detach from processes when the current thread dies.
source code
 
enable_step_on_branch_mode()
When tracing, call this on every single step event for step on branch mode.
source code
    Instrumentation
str
argv_to_cmdline(argv)
Convert a list of arguments to a single command line string. (Inherited from winappdbg.system.ProcessContainer)
source code
list( str )
cmdline_to_argv(lpCmdLine)
Convert a single command line string to a list of arguments. (Inherited from winappdbg.system.ProcessContainer)
source code
Class Variables [hide private]
int bits = 32
Size of the machine word in bits for the current architecture.
str os = 'Windows XP'
Name of the Windows version we're runing on.
bool wow64 = False
True if the debugger is a 32 bits process running in a 64 bits version of Windows, False otherwise.
    Global settings
str arch = 'i386'
Name of the processor architecture we're running on.
int pageSize = 4096
Page size in bytes.
Properties [hide private]

Inherited from object: __class__

Method Details [hide private]

request_debug_privileges(bIgnoreExceptions=False)
Static Method

source code 

Requests debug privileges.

This may be needed to debug processes running as SYSTEM (such as services) since Windows XP.

set_kill_on_exit_mode(bKillOnExit=False)
Static Method

source code 

Automatically detach from processes when the current thread dies.

Works on the following platforms:

  • Microsoft Windows XP and above.
  • Wine (Windows Emulator).

Fails on the following platforms:

  • Microsoft Windows 2000 and below.
  • ReactOS.
Parameters:
  • bKillOnExit (bool) - True to automatically kill processes when the debugger thread dies. False to automatically detach from processes when the debugger thread dies.
Returns: bool
True on success, False on error.

enable_step_on_branch_mode()
Static Method

source code 

When tracing, call this on every single step event for step on branch mode.

Raises:
  • WindowsError - Raises ERROR_DEBUGGER_INACTIVE if the debugger is not attached to least one process.

Warning: This has a HARDCODED value for a machine specific register (MSR). It could potentially brick your machine. It works on my machine, but your mileage may vary.

Note: It doesn't seem to work in VirtualBox machines. Maybe it fails in other virtualization/emulation environments, no extensive testing was made so far.


Class Variable Details [hide private]

arch

Name of the processor architecture we're running on. For more details see win32.version.get_arch.
Type:
str
Value:
'i386'

bits

Size of the machine word in bits for the current architecture. For more details see win32.version.get_bits.
Type:
int
Value:
32

os

Name of the Windows version we're runing on. For more details see win32.version.get_os.
Type:
str
Value:
'Windows XP'

pageSize

Page size in bytes. Defaults to 0x1000 but it's automatically updated on runtime when importing the module.
Type:
int
Value:
4096