Package winappdbg :: Module debug :: Class Debug
[hide private]
[frames] | no frames]

Class Debug

source code


The main debugger class.

Instance Methods [hide private]
 
__init__(self, eventHandler=None, bKillOnExit=False, bHostileCode=False)
Debugger object.
source code
 
__enter__(self)
Compatibility with the "with" Python statement.
source code
 
__exit__(self, type, value, traceback)
Compatibility with the "with" Python statement.
source code
int
__len__(self)
Returns: Number of processes being debugged.
source code
 
__setSystemKillOnExitMode(self) source code
 
__cleanup_process(self, dwProcessId, bIgnoreExceptions=False)
Perform the necessary cleanup of a process about to be killed or detached from.
source code
bool
_notify_create_process(self, event)
Notify the creation of a new process.
source code
bool
_notify_create_thread(self, event)
Notify the creation of a new thread.
source code
bool
_notify_load_dll(self, event)
Notify the load of a new module.
source code
bool
_notify_exit_process(self, event)
Notify the termination of a process.
source code
bool
_notify_exit_thread(self, event)
Notify the termination of a thread.
source code
bool
_notify_unload_dll(self, event)
Notify the unload of a module.
source code
bool
_notify_rip(self, event)
Notify of a RIP event.
source code
bool
_notify_debug_control_c(self, event)
Notify of a Debug Ctrl-C exception.
source code
bool
_notify_ms_vc_exception(self, event)
Notify of a Microsoft Visual C exception.
source code
 
_BreakpointContainer__add_running_bp(self, tid, bp)
Auxiliary method. (Inherited from winappdbg.breakpoint._BreakpointContainer)
source code
 
_BreakpointContainer__cleanup_breakpoint(self, event, bp)
Auxiliary method. (Inherited from winappdbg.breakpoint._BreakpointContainer)
source code
 
_BreakpointContainer__cleanup_module(self, event)
Auxiliary method for _notify_unload_dll. (Inherited from winappdbg.breakpoint._BreakpointContainer)
source code
 
_BreakpointContainer__cleanup_process(self, event)
Auxiliary method for _notify_exit_process. (Inherited from winappdbg.breakpoint._BreakpointContainer)
source code
 
_BreakpointContainer__cleanup_thread(self, event)
Auxiliary method for _notify_exit_thread and _notify_exit_process. (Inherited from winappdbg.breakpoint._BreakpointContainer)
source code
 
_BreakpointContainer__clear_break(self, pid, address)
Used by dont_break_at and dont_stalk_at. (Inherited from winappdbg.breakpoint._BreakpointContainer)
source code
 
_BreakpointContainer__clear_buffer_watch(self, bw)
Used by dont_watch_buffer and dont_stalk_buffer. (Inherited from winappdbg.breakpoint._BreakpointContainer)
source code
 
_BreakpointContainer__clear_buffer_watch_old_method(self, pid, address, size)
Used by dont_watch_buffer and dont_stalk_buffer. (Inherited from winappdbg.breakpoint._BreakpointContainer)
source code
 
_BreakpointContainer__clear_variable_watch(self, tid, address)
Used by dont_watch_variable and dont_stalk_variable. (Inherited from winappdbg.breakpoint._BreakpointContainer)
source code
 
_BreakpointContainer__del_running_bp(self, tid, bp)
Auxiliary method. (Inherited from winappdbg.breakpoint._BreakpointContainer)
source code
 
_BreakpointContainer__del_running_bp_from_all_threads(self, bp)
Auxiliary method. (Inherited from winappdbg.breakpoint._BreakpointContainer)
source code
 
_BreakpointContainer__get_running_bp_set(self, tid)
Auxiliary method. (Inherited from winappdbg.breakpoint._BreakpointContainer)
source code
Breakpoint
_BreakpointContainer__set_break(self, pid, address, action, oneshot)
Used by break_at and stalk_at. (Inherited from winappdbg.breakpoint._BreakpointContainer)
source code
 
_BreakpointContainer__set_buffer_watch(self, pid, address, size, action, bOneShot)
Used by watch_buffer and stalk_buffer. (Inherited from winappdbg.breakpoint._BreakpointContainer)
source code
 
_BreakpointContainer__set_deferred_breakpoints(self, event)
Used internally. (Inherited from winappdbg.breakpoint._BreakpointContainer)
source code
HardwareBreakpoint
_BreakpointContainer__set_variable_watch(self, tid, address, size, action)
Used by watch_variable and stalk_variable. (Inherited from winappdbg.breakpoint._BreakpointContainer)
source code
 
_BreakpointContainer__start_tracing(self, thread) (Inherited from winappdbg.breakpoint._BreakpointContainer) source code
 
_BreakpointContainer__stop_tracing(self, thread) (Inherited from winappdbg.breakpoint._BreakpointContainer) source code
bool
_notify_breakpoint(self, event)
Notify breakpoints of a breakpoint exception event. (Inherited from winappdbg.breakpoint._BreakpointContainer)
source code
bool
_notify_guard_page(self, event)
Notify breakpoints of a guard page exception event. (Inherited from winappdbg.breakpoint._BreakpointContainer)
source code
bool
_notify_single_step(self, event)
Notify breakpoints of a single step exception event. (Inherited from winappdbg.breakpoint._BreakpointContainer)
source code

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

    Debugging
Process
attach(self, dwProcessId)
Attaches to an existing process for debugging.
source code
Process
execv(self, argv, **kwargs)
Starts a new process for debugging.
source code
Process
execl(self, lpCmdLine, **kwargs)
Starts a new process for debugging.
source code
 
add_existing_session(self, dwProcessId, bStarted=False)
Use this method only when for some reason the debugger's been attached to the target outside of WinAppDbg (for example when integrating with other tools).
source code
 
kill(self, dwProcessId, bIgnoreExceptions=False)
Kills a process currently being debugged.
source code
 
kill_all(self, bIgnoreExceptions=False)
Kills from all processes currently being debugged.
source code
 
detach(self, dwProcessId, bIgnoreExceptions=False)
Detaches from a process currently being debugged.
source code
 
detach_from_all(self, bIgnoreExceptions=False)
Detaches from all processes currently being debugged.
source code
int
get_debugee_count(self)
Returns: Number of processes being debugged.
source code
list( int... )
get_debugee_pids(self)
Returns: Global IDs of processes being debugged.
source code
bool
is_debugee(self, dwProcessId)
Determine if the debugger is debugging the given process.
source code
bool
is_debugee_started(self, dwProcessId)
Determine if the given process was started by the debugger.
source code
bool
is_debugee_attached(self, dwProcessId)
Determine if the debugger is attached to the given process.
source code
bool
in_hostile_mode(self)
Determine if we're in hostile mode (anti-anti-debug).
source code
 
interactive(self, bConfirmQuit=True, bShowBanner=True)
Start an interactive debugging session.
source code
    Debugging loop
Event
wait(self, dwMilliseconds=None)
Waits for the next debug event.
source code
 
dispatch(self, event=None)
Calls the debug event notify callbacks.
source code
 
cont(self, event=None)
Resumes execution after processing a debug event.
source code
 
stop(self, bIgnoreExceptions=True)
Stops debugging all processes.
source code
 
next(self)
Handles the next debug event.
source code
 
loop(self)
Simple debugging loop.
source code
    Debugging events
EventHandler
get_event_handler(self)
Get the event handler. (Inherited from winappdbg.event.EventDispatcher)
source code
EventHandler
set_event_handler(self, eventHandler)
Set the event handler. (Inherited from winappdbg.event.EventDispatcher)
source code
    Breakpoints
bool
break_at(self, pid, address, action=None)
Sets a code breakpoint at the given process and address. (Inherited from winappdbg.breakpoint._BreakpointContainer)
source code
 
break_on_error(self, pid, errorCode)
Sets or clears the system breakpoint for a given Win32 error code. (Inherited from winappdbg.breakpoint._BreakpointContainer)
source code
 
dont_break_at(self, pid, address)
Clears a code breakpoint set by break_at. (Inherited from winappdbg.breakpoint._BreakpointContainer)
source code
 
dont_break_on_error(self, pid)
Alias to break_on_error(pid, ERROR_SUCCESS). (Inherited from winappdbg.breakpoint._BreakpointContainer)
source code
 
dont_hook_function(self, pid, address)
Removes a function hook set by hook_function. (Inherited from winappdbg.breakpoint._BreakpointContainer)
source code
 
dont_watch_buffer(self, bw, *argv, **argd)
Clears a page breakpoint set by watch_buffer. (Inherited from winappdbg.breakpoint._BreakpointContainer)
source code
 
dont_watch_variable(self, tid, address)
Clears a hardware breakpoint set by watch_variable. (Inherited from winappdbg.breakpoint._BreakpointContainer)
source code
bool
hook_function(self, pid, address, preCB=None, postCB=None, paramCount=None, signature=None)
Sets a function hook at the given address. (Inherited from winappdbg.breakpoint._BreakpointContainer)
source code
 
unhook_function(self, pid, address)
Removes a function hook set by hook_function. (Inherited from winappdbg.breakpoint._BreakpointContainer)
source code
BufferWatch
watch_buffer(self, pid, address, size, action=None)
Sets a page breakpoint and notifies when the given buffer is accessed. (Inherited from winappdbg.breakpoint._BreakpointContainer)
source code
 
watch_variable(self, tid, address, size, action=None)
Sets a hardware breakpoint at the given thread, address and size. (Inherited from winappdbg.breakpoint._BreakpointContainer)
source code
    Stalking
 
dont_stalk_at(self, pid, address)
Clears a code breakpoint set by stalk_at. (Inherited from winappdbg.breakpoint._BreakpointContainer)
source code
 
dont_stalk_buffer(self, bw, *argv, **argd)
Clears a page breakpoint set by stalk_buffer. (Inherited from winappdbg.breakpoint._BreakpointContainer)
source code
 
dont_stalk_function(self, pid, address)
Removes a function hook set by stalk_function. (Inherited from winappdbg.breakpoint._BreakpointContainer)
source code
 
dont_stalk_variable(self, tid, address)
Clears a hardware breakpoint set by stalk_variable. (Inherited from winappdbg.breakpoint._BreakpointContainer)
source code
bool
stalk_at(self, pid, address, action=None)
Sets a one shot code breakpoint at the given process and address. (Inherited from winappdbg.breakpoint._BreakpointContainer)
source code
BufferWatch
stalk_buffer(self, pid, address, size, action=None)
Sets a one-shot page breakpoint and notifies when the given buffer is accessed. (Inherited from winappdbg.breakpoint._BreakpointContainer)
source code
bool
stalk_function(self, pid, address, preCB=None, postCB=None, paramCount=None, signature=None)
Sets a one-shot function hook at the given address. (Inherited from winappdbg.breakpoint._BreakpointContainer)
source code
 
stalk_variable(self, tid, address, size, action=None)
Sets a one-shot hardware breakpoint at the given thread, address and size. (Inherited from winappdbg.breakpoint._BreakpointContainer)
source code
    Tracing
list( int... )
get_traced_tids(self)
Retrieves the list of global IDs of all threads being traced. (Inherited from winappdbg.breakpoint._BreakpointContainer)
source code
bool
is_tracing(self, tid)
Returns: True if the thread is being traced, False otherwise. (Inherited from winappdbg.breakpoint._BreakpointContainer)
source code
 
start_tracing(self, tid)
Start tracing mode in the given thread. (Inherited from winappdbg.breakpoint._BreakpointContainer)
source code
 
start_tracing_all(self)
Start tracing mode for all threads in all debugees. (Inherited from winappdbg.breakpoint._BreakpointContainer)
source code
 
start_tracing_process(self, pid)
Start tracing mode for all threads in the given process. (Inherited from winappdbg.breakpoint._BreakpointContainer)
source code
 
stop_tracing(self, tid)
Stop tracing mode in the given thread. (Inherited from winappdbg.breakpoint._BreakpointContainer)
source code
 
stop_tracing_all(self)
Stop tracing mode for all threads in all debugees. (Inherited from winappdbg.breakpoint._BreakpointContainer)
source code
 
stop_tracing_process(self, pid)
Stop tracing mode for all threads in the given process. (Inherited from winappdbg.breakpoint._BreakpointContainer)
source code
    Symbols
int, None
resolve_exported_function(self, pid, modName, procName)
Resolves the exported DLL function for the given process. (Inherited from winappdbg.breakpoint._BreakpointContainer)
source code
int
resolve_label(self, pid, label)
Resolves a label for the given process. (Inherited from winappdbg.breakpoint._BreakpointContainer)
source code
    Advanced breakpoint use
CodeBreakpoint
define_code_breakpoint(self, dwProcessId, address, condition=True, action=None)
Creates a disabled code breakpoint at the given address. (Inherited from winappdbg.breakpoint._BreakpointContainer)
source code
HardwareBreakpoint
define_hardware_breakpoint(self, dwThreadId, address, triggerFlag=3, sizeFlag=3, condition=True, action=None)
Creates a disabled hardware breakpoint at the given address. (Inherited from winappdbg.breakpoint._BreakpointContainer)
source code
PageBreakpoint
define_page_breakpoint(self, dwProcessId, address, pages=1, condition=True, action=None)
Creates a disabled page breakpoint at the given address. (Inherited from winappdbg.breakpoint._BreakpointContainer)
source code
 
disable_code_breakpoint(self, dwProcessId, address)
Disables the code breakpoint at the given address. (Inherited from winappdbg.breakpoint._BreakpointContainer)
source code
 
disable_hardware_breakpoint(self, dwThreadId, address)
Disables the hardware breakpoint at the given address. (Inherited from winappdbg.breakpoint._BreakpointContainer)
source code
 
disable_page_breakpoint(self, dwProcessId, address)
Disables the page breakpoint at the given address. (Inherited from winappdbg.breakpoint._BreakpointContainer)
source code
 
enable_code_breakpoint(self, dwProcessId, address)
Enables the code breakpoint at the given address. (Inherited from winappdbg.breakpoint._BreakpointContainer)
source code
 
enable_hardware_breakpoint(self, dwThreadId, address)
Enables the hardware breakpoint at the given address. (Inherited from winappdbg.breakpoint._BreakpointContainer)
source code
 
enable_one_shot_code_breakpoint(self, dwProcessId, address)
Enables the code breakpoint at the given address for only one shot. (Inherited from winappdbg.breakpoint._BreakpointContainer)
source code
 
enable_one_shot_hardware_breakpoint(self, dwThreadId, address)
Enables the hardware breakpoint at the given address for only one shot. (Inherited from winappdbg.breakpoint._BreakpointContainer)
source code
 
enable_one_shot_page_breakpoint(self, dwProcessId, address)
Enables the page breakpoint at the given address for only one shot. (Inherited from winappdbg.breakpoint._BreakpointContainer)
source code
 
enable_page_breakpoint(self, dwProcessId, address)
Enables the page breakpoint at the given address. (Inherited from winappdbg.breakpoint._BreakpointContainer)
source code
 
erase_code_breakpoint(self, dwProcessId, address)
Erases the code breakpoint at the given address. (Inherited from winappdbg.breakpoint._BreakpointContainer)
source code
 
erase_hardware_breakpoint(self, dwThreadId, address)
Erases the hardware breakpoint at the given address. (Inherited from winappdbg.breakpoint._BreakpointContainer)
source code
 
erase_page_breakpoint(self, dwProcessId, address)
Erases the page breakpoint at the given address. (Inherited from winappdbg.breakpoint._BreakpointContainer)
source code
CodeBreakpoint
get_code_breakpoint(self, dwProcessId, address)
Returns the internally used breakpoint object, for the code breakpoint defined at the given address. (Inherited from winappdbg.breakpoint._BreakpointContainer)
source code
HardwareBreakpoint
get_hardware_breakpoint(self, dwThreadId, address)
Returns the internally used breakpoint object, for the code breakpoint defined at the given address. (Inherited from winappdbg.breakpoint._BreakpointContainer)
source code
PageBreakpoint
get_page_breakpoint(self, dwProcessId, address)
Returns the internally used breakpoint object, for the page breakpoint defined at the given address. (Inherited from winappdbg.breakpoint._BreakpointContainer)
source code
bool
has_code_breakpoint(self, dwProcessId, address)
Checks if a code breakpoint is defined at the given address. (Inherited from winappdbg.breakpoint._BreakpointContainer)
source code
bool
has_hardware_breakpoint(self, dwThreadId, address)
Checks if a hardware breakpoint is defined at the given address. (Inherited from winappdbg.breakpoint._BreakpointContainer)
source code
bool
has_page_breakpoint(self, dwProcessId, address)
Checks if a page breakpoint is defined at the given address. (Inherited from winappdbg.breakpoint._BreakpointContainer)
source code
    Listing breakpoints
list of tuple( pid, tid, bp )
get_all_breakpoints(self)
Returns all breakpoint objects as a list of tuples. (Inherited from winappdbg.breakpoint._BreakpointContainer)
source code
list of tuple( int, CodeBreakpoint )
get_all_code_breakpoints(self)
Returns: All code breakpoints as a list of tuples (pid, bp). (Inherited from winappdbg.breakpoint._BreakpointContainer)
source code
tuple of (int, str, callable, bool)
get_all_deferred_code_breakpoints(self)
Returns a list of deferred code breakpoints. (Inherited from winappdbg.breakpoint._BreakpointContainer)
source code
list of tuple( int, HardwareBreakpoint )
get_all_hardware_breakpoints(self)
Returns: All hardware breakpoints as a list of tuples (tid, bp). (Inherited from winappdbg.breakpoint._BreakpointContainer)
source code
list of tuple( int, PageBreakpoint )
get_all_page_breakpoints(self)
Returns: All page breakpoints as a list of tuples (pid, bp). (Inherited from winappdbg.breakpoint._BreakpointContainer)
source code
list of tuple( pid, tid, bp )
get_process_breakpoints(self, dwProcessId)
Returns all breakpoint objects for the given process as a list of tuples. (Inherited from winappdbg.breakpoint._BreakpointContainer)
source code
list of CodeBreakpoint
get_process_code_breakpoints(self, dwProcessId)
Returns: All code breakpoints for the given process. (Inherited from winappdbg.breakpoint._BreakpointContainer)
source code
tuple of (int, str, callable, bool)
get_process_deferred_code_breakpoints(self, dwProcessId)
Returns a list of deferred code breakpoints. (Inherited from winappdbg.breakpoint._BreakpointContainer)
source code
list of tuple( int, HardwareBreakpoint )
get_process_hardware_breakpoints(self, dwProcessId)
Returns: All hardware breakpoints for each thread in the given process as a list of tuples (tid, bp). (Inherited from winappdbg.breakpoint._BreakpointContainer)
source code
list of PageBreakpoint
get_process_page_breakpoints(self, dwProcessId)
Returns: All page breakpoints for the given process. (Inherited from winappdbg.breakpoint._BreakpointContainer)
source code
list of HardwareBreakpoint
get_thread_hardware_breakpoints(self, dwThreadId)
Returns: All hardware breakpoints for the given thread. (Inherited from winappdbg.breakpoint._BreakpointContainer)
source code
    Batch operations on breakpoints
 
disable_all_breakpoints(self)
Disables all breakpoints in all processes. (Inherited from winappdbg.breakpoint._BreakpointContainer)
source code
 
disable_process_breakpoints(self, dwProcessId)
Disables all breakpoints for the given process. (Inherited from winappdbg.breakpoint._BreakpointContainer)
source code
 
enable_all_breakpoints(self)
Enables all disabled breakpoints in all processes. (Inherited from winappdbg.breakpoint._BreakpointContainer)
source code
 
enable_one_shot_all_breakpoints(self)
Enables for one shot all disabled breakpoints in all processes. (Inherited from winappdbg.breakpoint._BreakpointContainer)
source code
 
enable_one_shot_process_breakpoints(self, dwProcessId)
Enables for one shot all disabled breakpoints for the given process. (Inherited from winappdbg.breakpoint._BreakpointContainer)
source code
 
enable_process_breakpoints(self, dwProcessId)
Enables all disabled breakpoints for the given process. (Inherited from winappdbg.breakpoint._BreakpointContainer)
source code
 
erase_all_breakpoints(self)
Erases all breakpoints in all processes. (Inherited from winappdbg.breakpoint._BreakpointContainer)
source code
 
erase_process_breakpoints(self, dwProcessId)
Erases all breakpoints for the given process. (Inherited from winappdbg.breakpoint._BreakpointContainer)
source code
Static Methods [hide private]
    Debugging events
callable
get_handler_method(eventHandler, event, fallback=None)
Retrieves the appropriate callback method from an EventHandler instance for the given Event object. (Inherited from winappdbg.event.EventDispatcher)
Class Variables [hide private]
  _debug_static_init = False
    Breakpoint types
int BP_TYPE_ANY = 0
To get all breakpoints (Inherited from winappdbg.breakpoint._BreakpointContainer)
int BP_TYPE_CODE = 1
To get code breakpoints only (Inherited from winappdbg.breakpoint._BreakpointContainer)
int BP_TYPE_HARDWARE = 3
To get hardware breakpoints only (Inherited from winappdbg.breakpoint._BreakpointContainer)
int BP_TYPE_PAGE = 2
To get page breakpoints only (Inherited from winappdbg.breakpoint._BreakpointContainer)
    Breakpoint states
int BP_STATE_DISABLED = 0
Breakpoint is disabled. (Inherited from winappdbg.breakpoint._BreakpointContainer)
int BP_STATE_ENABLED = 1
Breakpoint is enabled. (Inherited from winappdbg.breakpoint._BreakpointContainer)
int BP_STATE_ONESHOT = 2
Breakpoint is enabled for one shot. (Inherited from winappdbg.breakpoint._BreakpointContainer)
int BP_STATE_RUNNING = 3
Breakpoint is running (recently hit). (Inherited from winappdbg.breakpoint._BreakpointContainer)
    Memory breakpoint trigger flags
int BP_BREAK_ON_ACCESS = 3
Break on memory read or write. (Inherited from winappdbg.breakpoint._BreakpointContainer)
int BP_BREAK_ON_EXECUTION = 0
Break on code execution. (Inherited from winappdbg.breakpoint._BreakpointContainer)
int BP_BREAK_ON_WRITE = 1
Break on memory write. (Inherited from winappdbg.breakpoint._BreakpointContainer)
    Memory breakpoint size flags
  BP_WATCH_BYTE = 0 (Inherited from winappdbg.breakpoint._BreakpointContainer)
  BP_WATCH_DWORD = 3 (Inherited from winappdbg.breakpoint._BreakpointContainer)
  BP_WATCH_QWORD = 2 (Inherited from winappdbg.breakpoint._BreakpointContainer)
  BP_WATCH_WORD = 1 (Inherited from winappdbg.breakpoint._BreakpointContainer)
Instance Variables [hide private]
System system
A System snapshot that is automatically updated for processes being debugged.
Properties [hide private]

Inherited from object: __class__

Method Details [hide private]

__init__(self, eventHandler=None, bKillOnExit=False, bHostileCode=False)
(Constructor)

source code 

Debugger object.

Parameters:
  • eventHandler (EventHandler) - (Optional, recommended) Custom event handler object.
  • bKillOnExit (bool) - (Optional) Kill on exit mode. If True debugged processes are killed when the debugger is stopped. If False when the debugger stops it detaches from all debugged processes and leaves them running (default).
  • bHostileCode (bool) - (Optional) Hostile code mode. Set to True to take some basic precautions against anti-debug tricks. Disabled by default.
Raises:
  • WindowsError - Raises an exception on error.
Overrides: object.__init__

Warning: When hostile mode is enabled, some things may not work as expected! This is because the anti-anti debug tricks may disrupt the behavior of the Win32 debugging APIs or WinAppDbg itself.

Note: The eventHandler parameter may be any callable Python object (for example a function, or an instance method). However you'll probably find it more convenient to use an instance of a subclass of EventHandler here.

__len__(self)
(Length operator)

source code 
Returns: int
Number of processes being debugged.

attach(self, dwProcessId)

source code 

Attaches to an existing process for debugging.

Parameters:
  • dwProcessId (int) - Global ID of a process to attach to.
Returns: Process
A new Process object. Normally you don't need to use it now, it's best to interact with the process from the event handler.
Raises:
  • WindowsError - Raises an exception on error. Depending on the circumstances, the debugger may or may not have attached to the target process.

See Also: detach, execv, execl

execv(self, argv, **kwargs)

source code 

Starts a new process for debugging.

This method uses a list of arguments. To use a command line string instead, use execl.

Parameters:
  • argv (list( str... )) - List of command line arguments to pass to the debugee. The first element must be the debugee executable filename.
  • bBreakOnEntryPoint (bool) - True to automatically set a breakpoint at the program entry point.
  • bConsole (bool) - True to inherit the console of the debugger. Defaults to False.
  • bFollow (bool) - True to automatically attach to child processes. 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 - None or 0 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).

    In hostile mode, the default is not the debugger process but the process ID for "explorer.exe".

  • iTrustLevel (int or None) - 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. This is the default in hostile mode.
    • 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 in normal mode.
  • 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
A new Process object. Normally you don't need to use it now, it's best to interact with the process from the event handler.
Raises:
  • WindowsError - Raises an exception on error.

See Also: attach, detach

execl(self, lpCmdLine, **kwargs)

source code 

Starts a new process for debugging.

This method uses a command line string. To use a list of arguments instead, use execv.

Parameters:
  • lpCmdLine (str) - Command line string to execute. The first token must be the debugee executable filename. Tokens with spaces must be enclosed in double quotes. Tokens including double quote characters must be escaped with a backslash.
  • bBreakOnEntryPoint (bool) - True to automatically set a breakpoint at the program entry point. Defaults to False.
  • bConsole (bool) - True to inherit the console of the debugger. Defaults to False.
  • bFollow (bool) - True to automatically attach to child processes. 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 or 0 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).

    In hostile mode, the default is not the debugger process but the process ID for "explorer.exe".

  • 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. This is the default in hostile mode.
    • 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 in normal mode.
  • 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 in normal mode and False in hostile mode.

    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
A new Process object. Normally you don't need to use it now, it's best to interact with the process from the event handler.
Raises:
  • WindowsError - Raises an exception on error.

See Also: attach, detach

add_existing_session(self, dwProcessId, bStarted=False)

source code 

Use this method only when for some reason the debugger's been attached to the target outside of WinAppDbg (for example when integrating with other tools).

You don't normally need to call this method. Most users should call attach, execv or execl instead.

Parameters:
  • dwProcessId (int) - Global process ID.
  • bStarted (bool) - True if the process was started by the debugger, or False if the process was attached to instead.
Raises:
  • WindowsError - The target process does not exist, is not attached to the debugger anymore.

__cleanup_process(self, dwProcessId, bIgnoreExceptions=False)

source code 

Perform the necessary cleanup of a process about to be killed or detached from.

This private method is called by kill and detach.

Parameters:
  • dwProcessId (int) - Global ID of a process to kill.
  • bIgnoreExceptions (bool) - True to ignore any exceptions that may be raised when killing the process.
Raises:
  • WindowsError - Raises an exception on error, unless bIgnoreExceptions is True.

kill(self, dwProcessId, bIgnoreExceptions=False)

source code 

Kills a process currently being debugged.

Parameters:
  • dwProcessId (int) - Global ID of a process to kill.
  • bIgnoreExceptions (bool) - True to ignore any exceptions that may be raised when killing the process.
Raises:
  • WindowsError - Raises an exception on error, unless bIgnoreExceptions is True.

See Also: detach

kill_all(self, bIgnoreExceptions=False)

source code 

Kills from all processes currently being debugged.

Parameters:
  • bIgnoreExceptions (bool) - True to ignore any exceptions that may be raised when killing each process. False to stop and raise an exception when encountering an error.
Raises:
  • WindowsError - Raises an exception on error, unless bIgnoreExceptions is True.

detach(self, dwProcessId, bIgnoreExceptions=False)

source code 

Detaches from a process currently being debugged.

Parameters:
  • dwProcessId (int) - Global ID of a process to detach from.
  • bIgnoreExceptions (bool) - True to ignore any exceptions that may be raised when detaching. False to stop and raise an exception when encountering an error.
Raises:
  • WindowsError - Raises an exception on error, unless bIgnoreExceptions is True.

Note: On Windows 2000 and below the process is killed.

See Also: attach, detach_from_all

detach_from_all(self, bIgnoreExceptions=False)

source code 

Detaches from all processes currently being debugged.

Parameters:
  • bIgnoreExceptions (bool) - True to ignore any exceptions that may be raised when detaching.
Raises:
  • WindowsError - Raises an exception on error, unless bIgnoreExceptions is True.

Note: To better handle last debugging event, call stop instead.

wait(self, dwMilliseconds=None)

source code 

Waits for the next debug event.

Parameters:
  • dwMilliseconds (int) - (Optional) Timeout in milliseconds. Use INFINITE or None for no timeout.
Returns: Event
An event that occured in one of the debugees.
Raises:
  • WindowsError - Raises an exception on error. If no target processes are left to debug, the error code is win32.ERROR_INVALID_HANDLE.

See Also: cont, dispatch, loop

dispatch(self, event=None)

source code 

Calls the debug event notify callbacks.

Parameters:
  • event (Event) - (Optional) Event object returned by wait.
Raises:
  • WindowsError - Raises an exception on error.
Overrides: event.EventDispatcher.dispatch

See Also: cont, loop, wait

cont(self, event=None)

source code 

Resumes execution after processing a debug event.

Parameters:
  • event (Event) - (Optional) Event object returned by wait.
Raises:
  • WindowsError - Raises an exception on error.

See Also: dispatch(), loop(), wait()

stop(self, bIgnoreExceptions=True)

source code 

Stops debugging all processes.

If the kill on exit mode is on, debugged processes are killed when the debugger is stopped. Otherwise when the debugger stops it detaches from all debugged processes and leaves them running (default). For more details see: __init__

Parameters:
  • bIgnoreExceptions (bool) - True to ignore any exceptions that may be raised when detaching.

Note: This method is better than detach_from_all because it can gracefully handle the last debugging event before detaching.

next(self)

source code 

Handles the next debug event.

Raises:
  • WindowsError - Raises an exception on error.

    If the wait operation causes an error, debugging is stopped (meaning all debugees are either killed or detached from).

    If the event dispatching causes an error, the event is still continued before returning. This may happen, for example, if the event handler raises an exception nobody catches.

See Also: cont, dispatch, wait, stop

loop(self)

source code 

Simple debugging loop.

This debugging loop is meant to be useful for most simple scripts. It iterates as long as there is at least one debugee, or an exception is raised. Multiple calls are allowed.

This is a trivial example script:

   import sys
   debug = Debug()
   try:
       debug.execv( sys.argv [ 1 : ] )
       debug.loop()
   finally:
       debug.stop()
Raises:
  • WindowsError - Raises an exception on error.

    If the wait operation causes an error, debugging is stopped (meaning all debugees are either killed or detached from).

    If the event dispatching causes an error, the event is still continued before returning. This may happen, for example, if the event handler raises an exception nobody catches.

get_debugee_count(self)

source code 
Returns: int
Number of processes being debugged.

get_debugee_pids(self)

source code 
Returns: list( int... )
Global IDs of processes being debugged.

is_debugee(self, dwProcessId)

source code 

Determine if the debugger is debugging the given process.

Parameters:
  • dwProcessId (int) - Process global ID.
Returns: bool
True if the given process is being debugged by this Debug instance.

is_debugee_started(self, dwProcessId)

source code 

Determine if the given process was started by the debugger.

Parameters:
  • dwProcessId (int) - Process global ID.
Returns: bool
True if the given process was started for debugging by this Debug instance.

is_debugee_attached(self, dwProcessId)

source code 

Determine if the debugger is attached to the given process.

Parameters:
  • dwProcessId (int) - Process global ID.
Returns: bool
True if the given process is attached to this Debug instance.

in_hostile_mode(self)

source code 

Determine if we're in hostile mode (anti-anti-debug).

Returns: bool
True if this Debug instance was started in hostile mode, False otherwise.

interactive(self, bConfirmQuit=True, bShowBanner=True)

source code 

Start an interactive debugging session.

Parameters:
  • bConfirmQuit (bool) - Set to True to ask the user for confirmation before closing the session, False otherwise.
  • bShowBanner (bool) - Set to True to show a banner before entering the session and after leaving it, False otherwise.

Warning: This will temporarily disable the user-defined event handler!

This method returns when the user closes the session.

_notify_create_process(self, event)

source code 

Notify the creation of a new process.

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

Warning: This method is meant to be used internally by the debugger.

_notify_create_thread(self, event)

source code 

Notify the creation of a new thread.

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

Warning: This method is meant to be used internally by the debugger.

_notify_load_dll(self, event)

source code 

Notify the load of a new module.

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

Warning: This method is meant to be used internally by the debugger.

_notify_exit_process(self, event)

source code 

Notify the termination of a process.

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

Warning: This method is meant to be used internally by the debugger.

_notify_exit_thread(self, event)

source code 

Notify the termination of a thread.

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

Warning: This method is meant to be used internally by the debugger.

_notify_unload_dll(self, event)

source code 

Notify the unload of a module.

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

Warning: This method is meant to be used internally by the debugger.

_notify_rip(self, event)

source code 

Notify of a RIP event.

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

Warning: This method is meant to be used internally by the debugger.

_notify_debug_control_c(self, event)

source code 

Notify of a Debug Ctrl-C exception.

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

Warning: This method is meant to be used internally by the debugger.

Note: This exception is only raised when a debugger is attached, and applications are not supposed to handle it, so we need to handle it ourselves or the application may crash.

See Also: http://msdn.microsoft.com/en-us/library/aa363082(VS.85).aspx

_notify_ms_vc_exception(self, event)

source code 

Notify of a Microsoft Visual C exception.

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

Warning: This method is meant to be used internally by the debugger.

Note: This allows the debugger to understand the Microsoft Visual C thread naming convention.

See Also: http://msdn.microsoft.com/en-us/library/xcb2z8hs.aspx


Instance Variable Details [hide private]

system

A System snapshot that is automatically updated for processes being debugged. Processes not being debugged in this snapshot may be outdated.
Type:
System