Trees       Index       Help   

PyDbg - Python Win32 Debugger

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:
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_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_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                                                                  

   Trees       Index       Help   

PyDbg - Python Win32 Debugger

Generated by Epydoc 2.1 on Fri Jun 16 17:16:24 2006 http://epydoc.sf.net