Class Debug

Debugger object.

Parameters:

• eventHandler (EventHandler) - (Optional, recommended) Custom event handler object.
• bKillOnExit (bool) - (Optional) Global kill on exit mode. True to kill the process on exit, False to detach. Ignored under Windows 2000 and below.
• 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__

Returns: int

Number of processes being debugged.

Attaches to an existing process for debugging.

Parameters:

• dwProcessId (int) - Global ID of a process to attach to.

Returns: Process

A new Process object.

Raises:

• WindowsError - Raises an exception on error.

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.

Raises:

• WindowsError - Raises an exception on error, unless bIgnoreExceptions is True.

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.

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.
• bConsole (bool) - True to inherit the console of the debugger.
• bFollow (bool) - True to automatically attach to child processes.
• bSuspended (bool) - True to suspend the main thread before any code is executed in the debugee.

Returns: Process

A new Process object.

Raises:

• WindowsError - Raises an exception on error.

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.
• bConsole (bool) - True to inherit the console of the debugger.
• bFollow (bool) - True to automatically attach to child processes.
• bSuspended (bool) - True to suspend the main thread before any code is executed in the debugee.

Returns: Process

A new Process object.

Raises:

• WindowsError - Raises an exception on error.

Waits for the next debug event and returns an Event object.

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.

Calls the debug event notify callbacks.

Parameters:

• event (Event) - Event object returned by wait.

Raises:

• WindowsError - Raises an exception on error.

Overrides: event.EventDispatcher.dispatch

Resumes execution after processing a debug event.

Parameters:

• event (Event) - Event object returned by wait.

Raises:

• WindowsError - Raises an exception on error.

Stops debugging all processes.

If bKillOnExit was set to True when instancing the Debug object, all debugees are terminated. Otherwise, the debugger detaches from all debugees.

Parameters:

• event (Event) - (Optional) Event object returned by wait. By passing this parameter, the last debugging event may be continued gracefully.
• bIgnoreExceptions (bool) - True to ignore any exceptions that may be raised when detaching.

Handles the next debug event.

Returns: Event

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

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 debuguee, or an exception is raised. Multiple calls are allowed.

This is a trivial example script:

   import sys
   debug = Debug()
   debug.execv( sys.argv [ 1 : ] )
   debug.loop()

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.

Returns: int

Number of processes being debugged.

Returns: list( int... )

Global IDs of processes being debugged.

Parameters:

• dwProcessId (int) - Process global ID.

Returns: bool

True if the given process is being debugged by this Debug instance.

Parameters:

• dwProcessId (int) - Process global ID.

Returns: bool

True if the given process was started for debugging by this Debug instance.

Parameters:

• dwProcessId (int) - Process global ID.

Returns: bool

True if the given process is attached to this Debug instance.

Detach from all processes and clean up internal structures.

Raises:

• WindowsError - Raises an exception on error.

Notify the creation of a new process.

Parameters:

• event (ExitProcessEvent) - Exit process event.

Returns: bool

True to call the user-defined handle, False otherwise.

Notify the creation of a new thread.

Parameters:

• event (CreateThreadEvent) - Create thread event.

Returns: bool

True to call the user-defined handle, False otherwise.

Notify the load of a new module.

Parameters:

• event (LoadDLLEvent) - Load DLL event.

Returns: bool

True to call the user-defined handle, False otherwise.

Notify the termination of a process.

Parameters:

• event (ExitProcessEvent) - Exit process event.

Returns: bool

True to call the user-defined handle, False otherwise.

Overrides: breakpoint.BreakpointContainer.notify_exit_process

Notify the termination of a thread.

Parameters:

• event (ExitThreadEvent) - Exit thread event.

Returns: bool

True to call the user-defined handle, False otherwise.

Overrides: breakpoint.BreakpointContainer.notify_exit_thread

Notify the unload of a module.

Parameters:

• event (UnloadDLLEvent) - Unload DLL event.

Returns: bool

True to call the user-defined handle, False otherwise.

Overrides: breakpoint.BreakpointContainer.notify_unload_dll

Notify of a RIP event.

Parameters:

• event (RIPEvent) - RIP event.

Returns: bool

True to call the user-defined handle, False otherwise.

Notify of a Debug Ctrl-C exception.

Parameters:

• event (ExceptionEvent) - Debug Ctrl-C exception event.

Returns: bool

True to call the user-defined handle, False otherwise.

Notify of a Microsoft Visual C exception.

Parameters:

• event (ExceptionEvent) - Microsoft Visual C exception event.

Returns: bool

True to call the user-defined handle, False otherwise.

system

Type:

System