Package pydbg :: Module pydbg_core :: Class pydbg_core |
[show private | hide private]
[frames | no frames]

## Type pydbg_core

    object --+
             |
            pydbg_core

Known Subclasses:
  `pydbg`

This is the core debugger class from which extended debugger functionality should be derived. This class contains:

- The load() / attach() routines.
- The main debug event loop.
- Convenience wrappers for commonly used Windows API.
- Single step toggling routine.
- Win32 error handler wrapped around PDX.
- Base exception / event handler routines which are meant to be overridden.

Method Summary
| ``__init__`(self, ff, cs)` Set the default attributes.
system_dll | ``addr_to_dll`(self, address)` Return the system DLL that contains the address specified.
MODULEENTRY32 | ``addr_to_module`(self, address)` Return the MODULEENTRY32 structure for the module that contains the address specified.
pydbg_core | ``attach`(self, pid)` Attach to the specified process by PID.
pydbg_core | ``cleanup`(self)` Clean up after ourselves.
Bool | ``close_handle`(self, handle)` Convenience wraper around kernel32.CloseHandle().
| ``debug_active_process`(self, pid)` Convenience wrapper around GetLastError() and FormatMessage().
| ``debug_event_iteration`(self)` Check for and process a debug event.
| ``debug_event_loop`(self)` Enter the infinite debug event handling loop.
| ``debug_set_process_kill_on_exit`(self, kill_on_exit)` Convenience wrapper around DebugSetProcessKillOnExit().
| ``detach`(self)` Detach from debuggee.
List | ``enumerate_modules`(self)` Using the CreateToolhelp32Snapshot() API enumerate and return the list of module name / base address tuples that belong to the debuggee
List | ``enumerate_processes`(self)` Using the CreateToolhelp32Snapshot() API enumerate all system processes returning a list of pid / process name tuples.
List | ``enumerate_threads`(self)` Using the CreateToolhelp32Snapshot() API enumerate all system threads returning a list of thread IDs that belong to the debuggee.
DWORD | ``event_handler_create_process`(self)` This is the default CREATE_PROCESS_DEBUG_EVENT handler.
DWORD | ``event_handler_create_thread`(self)` This is the default CREATE_THREAD_DEBUG_EVENT handler.
| ``event_handler_exit_process`(self)` This is the default EXIT_PROCESS_DEBUG_EVENT handler.
DWORD | ``event_handler_exit_thread`(self)` This is the default EXIT_THREAD_DEBUG_EVENT handler.
DWORD | ``event_handler_load_dll`(self)` This is the default LOAD_DLL_DEBUG_EVENT handler.
DWORD | ``event_handler_unload_dll`(self)` This is the default UNLOAD_DLL_DEBUG_EVENT handler.
DWORD | ``exception_handler_access_violation`(self)` This is the default EXCEPTION_ACCESS_VIOLATION handler.
DWORD | ``exception_handler_breakpoint`(self)` This is the default EXCEPTION_BREAKPOINT handler.
DWORD | ``exception_handler_guard_page`(self)` This is the default EXCEPTION_GUARD_PAGE handler.
DWORD | ``exception_handler_single_step`(self)` This is the default EXCEPTION_SINGLE_STEP handler.
Mixed | ``get_attr`(self, attribute)` Return the value for the specified class attribute.
| ``get_debug_privileges`(self)` Obtain necessary privileges for debugging.
Mixed | ``get_system_dll`(self, idx)` Return the system DLL at the specified index.
CONTEXT | ``get_thread_context`(self, thread_handle, thread_id)` Convenience wrapper around GetThreadContext().
MODULEENTRY32 | ``iterate_modules`(self)` A simple iterator function that can be used to iterate through all modules the target process has mapped in its address space.
PROCESSENTRY32 | ``iterate_processes`(self)` A simple iterator function that can be used to iterate through all running processes.
PROCESSENTRY32 | ``iterate_threads`(self)` A simple iterator function that can be used to iterate through all running processes.
| ``load`(self, path_to_file, command_line)` Load the specified executable and optional command line arguments into the debugger.
| ``open_process`(self, pid)` Convenience wrapper around OpenProcess().
| ``open_thread`(self, thread_id)` Convenience wrapper around OpenThread().
| ``read`(self, address, length)` Alias to read_process_memory().
Raw | ``read_process_memory`(self, address, length)` Read from the debuggee process space.
pydbg_core | ``resume_all_threads`(self)` Resume all process threads.
pydbg_core | ``resume_thread`(self, thread_id)` Resume the specified thread.
| ``ret_self`(self)` This convenience routine exists for internal functions to call and transparently return the correct version of self.
| ``run`(self)` Alias for debug_event_loop().
| ``set_attr`(self, attribute, value)` Return the value for the specified class attribute.
| ``set_callback`(self, exception_code, callback_func)` Set a callback for the specified exception (or debug event) code.
| ``set_debugger_active`(self, enable)` Enable or disable the control flag for the main debug event loop.
pydbg_core | ``set_thread_context`(self, context, thread_handle, thread_id)` Convenience wrapper around SetThreadContext().
| ``sigint_handler`(self, signal_number, stack_frame)` Interrupt signal handler.
pydbg_core | ``single_step`(self, enable, thread_handle)` Enable or disable single stepping in the specified thread or self.h_thread if a thread handle is not specified.
pydbg_core | ``suspend_all_threads`(self)` Suspend all process threads.
pydbg_core | ``suspend_thread`(self, thread_id)` Suspend the specified thread.
| ``terminate_process`(self, exit_code)` Terminate the debuggee.
DWORD | ``virtual_alloc`(self, address, size, alloc_type, protection)` Convenience wrapper around VirtualAllocEx()
| ``virtual_free`(self, address, size, free_type)` Convenience wrapper around VirtualFreeEx()
DWORD | ``virtual_protect`(self, base_address, size, protection)` Convenience wrapper around VirtualProtectEx()
MEMORY_BASIC_INFORMATION | ``virtual_query`(self, address)` Convenience wrapper around VirtualQueryEx().
| ``win32_error`(self, prefix)` Convenience wrapper around GetLastError() and FormatMessage().
| ``write`(self, address, data, length)` Alias to write_process_memory().
| ``write_process_memory`(self, address, data, length)` Write to the debuggee process space.
Inherited from object
| ``__delattr__`(...)` x.__delattr__('name') <==> del x.name
| ``__getattribute__`(...)` x.__getattribute__('name') <==> x.name
| ``__hash__`(x)` x.__hash__() <==> hash(x)
| ``__new__`(T, S, ...)` T.__new__(S, ...) -> a new object with type S, a subtype of T
| ``__reduce__`(...)` helper for pickle
| ``__reduce_ex__`(...)` helper for pickle
| ``__repr__`(x)` x.__repr__() <==> repr(x)
| ``__setattr__`(...)` x.__setattr__('name', value) <==> x.name = value
| ``__str__`(x)` x.__str__() <==> str(x)

Class Variable Summary
`dict` | `callbacks` = `{}`
`bool` | `client_server` = `False`
`NoneType` | `context` = None
`NoneType` | `dbg` = None
`bool` | `debugger_active` = `True`
`bool` | `dirty` = `False`
`NoneType` | `exception_address` = None
`bool` | `follow_forks` = `False`
`NoneType` | `h_process` = None
`NoneType` | `h_thread` = None
`int` | `page_size` = 0
`int` | `pid` = 0
`list` | `system_dlls` = `[]`
`NoneType` | `violation_address` = None
`NoneType` | `write_violation` = None

Method Details

### __init__(self, ff=True, cs=False) (Constructor) Set the default attributes. See the source if you want to modify the default creation values. Parameters: `ff` - (Optional, Def=True) Flag controlling whether or not pydbg attaches to forked processes (type=Boolean) Overrides: `__builtin__.object.__init__`

### addr_to_dll(self, address) Return the system DLL that contains the address specified. Parameters: `address` - Address to search system DLL ranges for (type=DWORD) Returns: System DLL that contains the address specified or None if not found. (type=system_dll)

### addr_to_module(self, address) Return the MODULEENTRY32 structure for the module that contains the address specified. Parameters: `address` - Address to search loaded module ranges for (type=DWORD) Returns: MODULEENTRY32 strucutre that contains the address specified or None if not found. (type=MODULEENTRY32)

### attach(self, pid) Attach to the specified process by PID. Saves a process handle in self.h_process and prevents debuggee from exiting on debugger quit. Parameters: `pid` - Process ID to attach to (type=Integer) Returns: Self (type=pydbg_core) Raises: `pdx` - An exception is raised on failure.

### cleanup(self) Clean up after ourselves. Returns: Self (type=pydbg_core)

### close_handle(self, handle) Convenience wraper around kernel32.CloseHandle(). Parameters: `handle` - Handle to close (type=Handle) Returns: Return value from CloseHandle(). (type=Bool)

### debug_active_process(self, pid) Convenience wrapper around GetLastError() and FormatMessage(). Returns the error code and formatted message associated with the last error. You probably do not want to call this directly, rather look at attach(). Parameters: `pid` - Process ID to attach to (type=Integer) Raises: `pdx` - An exception is raised on failure.

### debug_event_iteration(self) Check for and process a debug event.

### debug_event_loop(self) Enter the infinite debug event handling loop. This is the main loop of the debugger and is responsible for catching debug events and exceptions and dispatching them appropriately. This routine will check for and call the USER_CALLBACK_DEBUG_EVENT callback on each loop iteration. run() is an alias for this routine. Raises: `pdx` - An exception is raised on any exceptional conditions, such as debugger being interrupted or debuggee quiting. See Also: run()

### debug_set_process_kill_on_exit(self, kill_on_exit) Convenience wrapper around DebugSetProcessKillOnExit(). Parameters: `kill_on_exit` - True to kill the process on debugger exit, False to let debuggee continue running. (type=Bool) Raises: `pdx` - An exception is raised on failure.

### detach(self) Detach from debuggee.

### enumerate_modules(self) Using the CreateToolhelp32Snapshot() API enumerate and return the list of module name / base address tuples that belong to the debuggee Returns: List of module name / base address tuples. (type=List) See Also: iterate_modules()

    ### enumerate_processes(self) Using the CreateToolhelp32Snapshot() API enumerate all system processes returning a list of pid / process name tuples. Returns: List of pid / process name tuples. Example:
           for (pid, name) in pydbg.enumerate_processes():
               if name == "test.exe":
                   break

           pydbg.attach(pid)
(type=List) See Also: iterate_processes()

    ### enumerate_threads(self) Using the CreateToolhelp32Snapshot() API enumerate all system threads returning a list of thread IDs that belong to the debuggee. Returns: List of thread IDs belonging to the debuggee. Example:
           for thread_id in self.enumerate_threads():
               context = self.get_thread_context(None, thread_id)
(type=List) See Also: iterate_threads()

### event_handler_create_process(self) This is the default CREATE_PROCESS_DEBUG_EVENT handler. Returns: Debug event continue status. (type=DWORD)

### event_handler_create_thread(self) This is the default CREATE_THREAD_DEBUG_EVENT handler. Returns: Debug event continue status. (type=DWORD)

### event_handler_exit_process(self) This is the default EXIT_PROCESS_DEBUG_EVENT handler. Raises: `pdx` - An exception is raised to denote process exit.

### event_handler_exit_thread(self) This is the default EXIT_THREAD_DEBUG_EVENT handler. Returns: Debug event continue status. (type=DWORD)

### event_handler_load_dll(self) This is the default LOAD_DLL_DEBUG_EVENT handler. Returns: Debug event continue status. (type=DWORD)

### event_handler_unload_dll(self) This is the default UNLOAD_DLL_DEBUG_EVENT handler. Returns: Debug event continue status. (type=DWORD)

### exception_handler_access_violation(self) This is the default EXCEPTION_ACCESS_VIOLATION handler. Returns: Debug event continue status. (type=DWORD)

### exception_handler_breakpoint(self) This is the default EXCEPTION_BREAKPOINT handler. Returns: Debug event continue status. (type=DWORD)

### exception_handler_guard_page(self) This is the default EXCEPTION_GUARD_PAGE handler. Returns: Debug event continue status. (type=DWORD)

### exception_handler_single_step(self) This is the default EXCEPTION_SINGLE_STEP handler. Returns: Debug event continue status. (type=DWORD)

### get_attr(self, attribute) Return the value for the specified class attribute. This routine should be used over directly accessing class member variables for transparent support across local vs. client/server debugger clients. Parameters: `attribute` - Name of attribute to return. (type=String) Returns: Requested attribute or None if not found. (type=Mixed) See Also: set_attr()

### get_debug_privileges(self) Obtain necessary privileges for debugging. Raises: `pdx` - An exception is raised on failure.

### get_system_dll(self, idx) Return the system DLL at the specified index. If the debugger is in client / server mode, remove the PE structure (we do not want to send that mammoth over the wire). Parameters: `idx` - Index into self.system_dlls[] to retrieve DLL from. (type=Integer) Returns: Requested attribute or None if not found. (type=Mixed)

### get_thread_context(self, thread_handle, thread_id=0) Convenience wrapper around GetThreadContext(). Can obtain a thread context via a handle or thread id. Parameters: `thread_handle` - (Optional) Handle of thread to get context of (type=HANDLE) `thread_id` - (Optional, Def=0) ID of thread to get context of (type=Integer) Returns: Thread CONTEXT on success. (type=CONTEXT) Raises: `pdx` - An exception is raised on failure.

### iterate_modules(self) A simple iterator function that can be used to iterate through all modules the target process has mapped in its address space. Yielded objects are of type MODULEENTRY32. Returns: Iterated module entries. (type=MODULEENTRY32) Author: Otto Ebeling See Also: enumerate_modules()

### iterate_processes(self) A simple iterator function that can be used to iterate through all running processes. Yielded objects are of type PROCESSENTRY32. Returns: Iterated process entries. (type=PROCESSENTRY32) See Also: enumerate_processes()

### iterate_threads(self) A simple iterator function that can be used to iterate through all running processes. Yielded objects are of type PROCESSENTRY32. Returns: Iterated process entries. (type=PROCESSENTRY32) See Also: enumerate_threads()

### load(self, path_to_file, command_line=None) Load the specified executable and optional command line arguments into the debugger. Parameters: `path_to_file` - Full path to executable to load in debugger (type=String) `command_line` - (Optional, def=None) Command line arguments to pass to debuggee (type=String) Raises: `pdx` - An exception is raised if we are unable to load the specified executable in the debugger. To Do: This routines needs to be further tested ... I nomally just attach.

### open_process(self, pid) Convenience wrapper around OpenProcess(). Parameters: `pid` - Process ID to attach to (type=Integer) Raises: `pdx` - An exception is raised on failure.

### open_thread(self, thread_id) Convenience wrapper around OpenThread(). Parameters: `thread_id` - ID of thread to obtain handle to (type=Integer) Raises: `pdx` - An exception is raised on failure.

### read(self, address, length) Alias to read_process_memory(). See Also: read_process_memory

### read_process_memory(self, address, length) Read from the debuggee process space. Parameters: `address` - Address to read from (type=DWORD) `length` - Length, in bytes, of data to read (type=Integer) Returns: Read data. (type=Raw) Raises: `pdx` - An exception is raised on failure.

### resume_all_threads(self) Resume all process threads. Returns: Self (type=pydbg_core) Raises: `pdx` - An exception is raised on failure.

### resume_thread(self, thread_id) Resume the specified thread. Parameters: `thread_id` - ID of thread to resume (type=DWORD) Returns: Self (type=pydbg_core) Raises: `pdx` - An exception is raised on failure.

### ret_self(self) This convenience routine exists for internal functions to call and transparently return the correct version of self. Specifically, an object in normal mode and a moniker when in client/server mode. Returns: Client / server safe version of self

### run(self) Alias for debug_event_loop(). See Also: debug_event_loop()

### set_attr(self, attribute, value) Return the value for the specified class attribute. This routine should be used over directly accessing class member variables for transparent support across local vs. client/server debugger clients. Parameters: `attribute` - Name of attribute to return. (type=String) `value` - Value to set attribute to. (type=Mixed) See Also: set_attr()

### set_callback(self, exception_code, callback_func) Set a callback for the specified exception (or debug event) code. The prototype of the callback routines is:
       func (pydbg):
           return DBG_CONTINUE     # or other continue status
You can register callbacks for any exception code or debug event. Look in the source for all event_handler_xxx and exception_handler_xxx routines to see which ones have internal processing (internal handlers will still pass control to your callback). You can also register a user specified callback that is called on each loop iteration from within debug_event_loop(). The callback code is USER_CALLBACK_DEBUG_EVENT and the function prototype is:
       func (pydbg)
           return DBG_CONTINUE     # or other continue status
Parameters: `exception_code` - Exception code to establish a callback for (type=Long) `callback_func` - Function to call when specified exception code is caught. (type=Function)

### set_debugger_active(self, enable) Enable or disable the control flag for the main debug event loop. This is a convenience shortcut over set_attr. Parameters: `enable` - Flag controlling the main debug event loop. (type=Boolean)

### set_thread_context(self, context, thread_handle=None, thread_id=0) Convenience wrapper around SetThreadContext(). Can set a thread context via a handle or thread id. Parameters: `context` - Context to apply to specified thread (type=CONTEXT) `thread_handle` - (Optional) Handle of thread to get context of (type=HANDLE) `thread_id` - (Optional, Def=0) ID of thread to get context of (type=Integer) Returns: Self (type=pydbg_core) Raises: `pdx` - An exception is raised on failure.

### sigint_handler(self, signal_number, stack_frame) Interrupt signal handler. We override the default handler to disable the run flag and exit the main debug event loop. Parameters: `signal_number` - (type=) `stack_frame` - (type=)

### single_step(self, enable, thread_handle=None) Enable or disable single stepping in the specified thread or self.h_thread if a thread handle is not specified. Parameters: `enable` - True to enable single stepping, False to disable (type=Bool) `thread_handle` - (Optional, Def=None) Handle of thread to put into single step mode (type=Handle) Returns: Self (type=pydbg_core) Raises: `pdx` - An exception is raised on failure.

### suspend_all_threads(self) Suspend all process threads. Returns: Self (type=pydbg_core) Raises: `pdx` - An exception is raised on failure.

### suspend_thread(self, thread_id) Suspend the specified thread. Parameters: `thread_id` - ID of thread to suspend (type=DWORD) Returns: Self (type=pydbg_core) Raises: `pdx` - An exception is raised on failure.

### terminate_process(self, exit_code=0) Terminate the debuggee. Parameters: `exit_code` - (Optional, def=0) Exit code (type=Integer) Raises: `pdx` - An exception is raised on failure.

### virtual_alloc(self, address, size, alloc_type, protection) Convenience wrapper around VirtualAllocEx() Parameters: `address` - Desired starting address of region to allocate, can be None (type=DWORD) `size` - Size of memory region to allocate, in bytes (type=Integer) `alloc_type` - The type of memory allocation (most often MEM_COMMIT) (type=DWORD) `protection` - Memory protection to apply to the specified region (type=DWORD) Returns: Base address of the allocated region of pages. (type=DWORD) Raises: `pdx` - An exception is raised on failure.

### virtual_free(self, address, size, free_type) Convenience wrapper around VirtualFreeEx() Parameters: `address` - Pointer to the starting address of the region of memory to be freed (type=DWORD) `size` - Size of memory region to free, in bytes (type=Integer) `free_type` - The type of free operation (type=DWORD) Raises: `pdx` - An exception is raised on failure.

### virtual_protect(self, base_address, size, protection) Convenience wrapper around VirtualProtectEx() Parameters: `base_address` - Base address of region of pages whose access protection attributes are to be changed (type=DWORD) `size` - Size of the region whose access protection attributes are to be changed (type=Integer) `protection` - Memory protection to apply to the specified region (type=DWORD) Returns: Previous access protection. (type=DWORD) Raises: `pdx` - An exception is raised on failure.

### virtual_query(self, address) Convenience wrapper around VirtualQueryEx(). Parameters: `address` - Address to query (type=DWORD) Returns: MEMORY_BASIC_INFORMATION (type=MEMORY_BASIC_INFORMATION) Raises: `pdx` - An exception is raised on failure.

### win32_error(self, prefix=None) Convenience wrapper around GetLastError() and FormatMessage(). Raises an exception with the relevant error code and formatted message. Parameters: `prefix` - (Optional) String to prefix error message with. (type=String) Raises: `pdx` - An exception is always raised by this routine.

### write(self, address, data, length=0) Alias to write_process_memory(). See Also: write_process_memory

### write_process_memory(self, address, data, length=0) Write to the debuggee process space. Convenience wrapper around WriteProcessMemory(). This routine will continuously attempt to write the data requested until it is complete. Parameters: `address` - Address to write to (type=DWORD) `data` - Data to write (type=Raw Bytes) `length` - (Optional, Def:len(data)) Length of data, in bytes, to write (type=DWORD) Raises: `pdx` - An exception is raised on failure.

Class Variable Details

    ### callbacks Type: `dict` Value:
        {}

    ### client_server Type: `bool` Value:
        False

    ### context Type: `NoneType` Value:
        None

    ### dbg Type: `NoneType` Value:
        None

    ### debugger_active Type: `bool` Value:
        True

    ### dirty Type: `bool` Value:
        False

    ### exception_address Type: `NoneType` Value:
        None

    ### follow_forks Type: `bool` Value:
        False

    ### h_process Type: `NoneType` Value:
        None

    ### h_thread Type: `NoneType` Value:
        None

    ### page_size Type: `int` Value:
        0

    ### pid Type: `int` Value:
        0

    ### system_dlls Type: `list` Value:
        []

    ### violation_address Type: `NoneType` Value:
        None

    ### write_violation Type: `NoneType` Value:
        None

Generated by Epydoc 2.1 on Thu Sep 14 10:39:48 2006 | http://epydoc.sf.net