Trees       Index       Help   

PyDbg - Python Win32 Debugger

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

Type pydbg

object --+    
         |    
pydbg_core --+
             |
            pydbg

Extending from the core this class defines a more usable debugger objects implementing a number of features such as:
Method Summary
  __init__(self, ff, cs)
Set the default attributes.
pydbg bp_del(self, address)
Removes the breakpoint from target address.
pydbg bp_del_all(self)
Removes all breakpoints from the debuggee.
pydbg bp_del_hw(self, address, slot)
Removes the hardware breakpoint from the specified address or slot.
pydbg bp_del_mem(self, address)
Removes the memory breakpoint from target address.
pydbg bp_del_mem_all(self)
Removes all memory breakpoints from the debuggee.
Bool bp_is_ours(self, address_to_check)
Determine if a breakpoint address belongs to us.
Mixed bp_is_ours_mem(self, address_to_check)
Determines if the specified address falls within the range of one of our memory breakpoints.
pydbg bp_set(self, address, description, restore, handler)
Sets a breakpoint at the designated address.
pydbg bp_set_hw(self, address, length, condition, description, restore, handler)
Sets a hardware breakpoint at the designated address.
pydbg bp_set_mem(self, address, size, description, handler)
Sets a memory breakpoint at the target address.
pydbg cleanup(self)
Clean up after ourselves by removing all breakpoints.
  dbg_print_all_guarded_pages(self)
*** DEBUG ROUTINE ***
String disasm(self, address)
Pydasm disassemble utility function wrapper.
List disasm_around(self, address, num_inst)
Given a specified address this routine will return the list of 5 instructions before and after the instruction at address (including the instruction at address, so 11 instructions in total).
String dump_context(self, context, stack_depth, print_dots)
Return an informational block of text describing the CPU context of the current thread.
Dictionary dump_context_list(self, context, stack_depth, print_dots)
Return an informational list of items describing the CPU context of the current thread.
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, responsible for transparently restoring soft breakpoints and passing control to the registered user callback handler.
DWORD exception_handler_guard_page(self)
This is the default EXCEPTION_GUARD_PAGE handler, responsible for transparently restoring memory breakpoints passing control to the registered user callback handler.
DWORD exception_handler_single_step(self)
This is the default EXCEPTION_SINGLE_STEP handler, responsible for transparently restoring breakpoints and passing control to the registered user callback handler.
Raw Bytes flip_endian(self, dword)
Utility function to flip the endianess a given DWORD into raw bytes.
DWORD flip_endian_dword(self, bytes)
Utility function to flip the endianess of a given set of raw bytes into a DWORD.
DWORD func_resolve(self, dll, function)
Utility function that resolves the address of a given module / function name pair under the context of the debugger.
DWORD func_resolve_debuggee(self, dll_name, func_name)
Utility function that resolves the address of a given module / function name pair under the context of the debuggee.
DWORD get_arg(self, index, context)
Given a thread context, this convenience routine will retrieve the function argument at the specified index.
String get_ascii_string(self, data)
Retrieve the ASCII string, if any, from data.
String get_printable_string(self, data, print_dots)
description
String get_unicode_string(self, data)
description
String hex_dump(self, data, addr)
Utility function that converts data into hex dump format.
  hide_debugger(self)
Hide the presence of the debugger.
Bool is_address_on_stack(self, address, context)
Utility function to determine if the specified address exists on the current thread stack or not.
pydbg process_restore(self)
Restore memory / context snapshot of the debuggee.
pydbg process_snapshot(self)
Take memory / context snapshot of the debuggee.
List of Tuples seh_unwind(self, context)
Unwind the the Structured Exception Handler (SEH) chain of the current or specified thread to the best of our abilities.
pydbg set_register(self, register, value)
Set the value of a register in the debuggee within the context of the self.h_thread.
String smart_dereference(self, address, print_dots)
"Intelligently" discover data behind an address.
Mixed stack_range(self, context)
Determine the stack range (top and bottom) of the current or specified thread.
List stack_unwind(self, context)
Unwind the stack to the best of our ability.
String to_binary(self, number, bit_count)
Convert a number into a binary string.
Integer to_decimal(self, binary)
Convert a binary string into a decimal number.
    Inherited from pydbg_core
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.
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.
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 breakpoints = {}
bool first_breakpoint = True
NoneType hardware_breakpoint_hit = None                                                                  
dict hardware_breakpoints = {}
NoneType instruction = None                                                                  
int memory_breakpoint_hit = 0                                                                     
dict memory_breakpoints = {}
list memory_snapshot_blocks = []
list memory_snapshot_contexts = []
NoneType mnemonic = None                                                                  
NoneType op1 = None                                                                  
NoneType op2 = None                                                                  
NoneType op3 = None                                                                  
NoneType restore_breakpoint = None                                                                  
int STRING_EXPLORATION_MIN_LENGTH = 2                                                                     
int STRING_EXPLORATON_BUF_SIZE = 256                                                                   
    Inherited from pydbg_core
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)
cs - (Optional, Def=False) Flag controlling whether or not pydbg is in client/server (socket) mode
           (type=Boolean)
Overrides:
pydbg.pydbg_core.pydbg_core.__init__

bp_del(self, address)

Removes the breakpoint from target address.
Parameters:
address - Address or list of addresses to remove breakpoint from
           (type=DWORD or List)
Returns:
Self
           (type=pydbg)
Raises:
pdx - An exception is raised on failure.

See Also: bp_set(), bp_del_all(), bp_is_ours()

bp_del_all(self)

Removes all breakpoints from the debuggee.
Returns:
Self
           (type=pydbg)
Raises:
pdx - An exception is raised on failure.

See Also: bp_set(), bp_del(), bp_is_ours()

bp_del_hw(self, address=None, slot=None)

Removes the hardware breakpoint from the specified address or slot. Either an address or a slot must be specified, but not both.
Parameters:
address - (Optional) Address to remove hardware breakpoint from.
           (type=DWORD)
slot - (Optional)
           (type=Integer (0 through 3))
Returns:
Self
           (type=pydbg)
Raises:
pdx - An exception is raised on failure.

See Also: bp_set_hw()

To Do: Should probably consider moving this into pydbg_core.

bp_del_mem(self, address)

Removes the memory breakpoint from target address.
Parameters:
address - Address or list of addresses to remove memory breakpoint from
           (type=DWORD)
Returns:
Self
           (type=pydbg)
Raises:
pdx - An exception is raised on failure.

See Also: bp_del_mem_all(), bp_set_mem(), bp_is_ours_mem()

bp_del_mem_all(self)

Removes all memory breakpoints from the debuggee.
Returns:
Self
           (type=pydbg)
Raises:
pdx - An exception is raised on failure.

See Also: bp_del_mem(), bp_set_mem(), bp_is_ours_mem()

bp_is_ours(self, address_to_check)

Determine if a breakpoint address belongs to us.
Parameters:
address_to_check - Address to check if we have set a breakpoint at
           (type=DWORD)
Returns:
True if breakpoint in question is ours, False otherwise
           (type=Bool)

See Also: bp_set(), bp_del(), bp_del_all()

bp_is_ours_mem(self, address_to_check)

Determines if the specified address falls within the range of one of our memory breakpoints. When handling potential memory breakpoint exceptions it is mandatory to check the offending address with this routine as memory breakpoints are implemented by changing page permissions and the referenced address may very well exist within the same page as a memory breakpoint but not within the actual range of the buffer we wish to break on.
Parameters:
address_to_check - Address to check if we have set a breakpoint on
           (type=DWORD)
Returns:
The starting address of the buffer our breakpoint triggered on or False if address falls outside range.
           (type=Mixed)

See Also: bp_set_mem(), bp_del_mem(), bp_del_mem_all()

bp_set(self, address, description='', restore=True, handler=None)

Sets a breakpoint at the designated address. Register an EXCEPTION_BREAKPOINT callback handler to catch breakpoint events. If a list of addresses is submitted to this routine then the entire list of new breakpoints get the same description and restore. The optional "handler" parameter can be used to identify a function to specifically handle the specified bp, as opposed to the generic bp callback handler. The prototype of the callback routines is: 
   func (pydbg)
       return DBG_CONTINUE     # or other continue status
Parameters:
address - Address or list of addresses to set breakpoint at
           (type=DWORD or List)
description - (Optional) Description to associate with this breakpoint
           (type=String)
restore - (Optional, def=True) Flag controlling whether or not to restore the breakpoint
           (type=Bool)
handler - (Optional, def=None) Optional handler to call for this bp instead of the default handler
           (type=Function Pointer)
Returns:
Self
           (type=pydbg)
Raises:
pdx - An exception is raised on failure.

See Also: bp_is_ours(), bp_del(), bp_del_all()

bp_set_hw(self, address, length, condition, description='', restore=True, handler=None)

Sets a hardware breakpoint at the designated address. Register an EXCEPTION_SINGLE_STEP callback handler to catch hardware breakpoint events. Setting hardware breakpoints requires the internal h_thread handle be set. This means that you can not set one outside the context of an debug event handler. If you want to set a hardware breakpoint as soon as you attach to or load a process, do so in the first chance breakpoint handler.

For more information regarding the Intel x86 debug registers and hardware breakpoints see: 
   http://pdos.csail.mit.edu/6.828/2005/readings/ia32/IA32-3.pdf
   Section 15.2
Alternatively, you can register a custom handler to handle hits on the specific hw breakpoint slot.
Parameters:
address - Address to set hardware breakpoint at
           (type=DWORD)
length - Size of hardware breakpoint in bytes (byte, word or dword)
           (type=Integer (1, 2 or 4))
condition - Condition to set the hardware breakpoint to activate on
           (type=Integer (HW_ACCESS, HW_WRITE, HW_EXECUTE))
description - (Optional) Description of breakpoint
           (type=String)
restore - (Optional, def=True) Flag controlling whether or not to restore the breakpoint
           (type=Boolean)
handler - (Optional, def=None) Optional handler to call for this bp instead of the default handler
           (type=Function Pointer)
Returns:
Self
           (type=pydbg)
Raises:
pdx - An exception is raised on failure.

See Also: bp_del_hw()

bp_set_mem(self, address, size, description='', handler=None)

Sets a memory breakpoint at the target address. This is implemented by changing the permissions of the page containing the address to PAGE_GUARD. To catch memory breakpoints you have to register the EXCEPTION_GUARD_PAGE callback. Within the callback handler check the internal pydbg variable self.memory_breakpoint_hit to determine if the violation was a result of a direct memory breakpoint hit or some unrelated event. Alternatively, you can register a custom handler to handle the memory breakpoint. Memory breakpoints are automatically restored via the internal single step handler. To remove a memory breakpoint, you must explicitly call bp_del_mem().
Parameters:
address - Starting address of the buffer to break on
           (type=DWORD)
size - Size of the buffer to break on
           (type=Integer)
description - (Optional) Description to associate with this breakpoint
           (type=String)
handler - (Optional, def=None) Optional handler to call for this bp instead of the default handler
           (type=Function Pointer)
Returns:
Self
           (type=pydbg)
Raises:
pdx - An exception is raised on failure.

See Also: bp_is_ours_mem(), bp_del_mem(), bp_del_mem_all()

cleanup(self)

Clean up after ourselves by removing all breakpoints.
Returns:
Self
           (type=pydbg)
Overrides:
pydbg.pydbg_core.pydbg_core.cleanup

dbg_print_all_guarded_pages(self)

*** DEBUG ROUTINE ***

This is a debugging routine that was used when debugging memory breakpoints. It was too useful to be removed from the release code.

disasm(self, address)

Pydasm disassemble utility function wrapper. Stores the pydasm decoded instruction in self.instruction.
Parameters:
address - Address to disassemble at
           (type=DWORD)
Returns:
Disassembled string.
           (type=String)

disasm_around(self, address, num_inst=5)

Given a specified address this routine will return the list of 5 instructions before and after the instruction at address (including the instruction at address, so 11 instructions in total). This is accomplished by grabbing a larger chunk of data around the address than what is predicted as necessary and then disassembling forward. If during the forward disassembly the requested address lines up with the start of an instruction, then the assumption is made that the forward disassembly self corrected itself and the instruction set is returned. If we are unable to align with the original address, then we modify our data slice and try again until we do.
Parameters:
address - Address to disassemble around
           (type=DWORD)
num_inst - (Optional, Def=5) Number of instructions to disassemble up/down from address
           (type=Integer)
Returns:
List of tuples (address, disassembly) of instructions around the specified address.
           (type=List)

dump_context(self, context=None, stack_depth=5, print_dots=True)

Return an informational block of text describing the CPU context of the current thread. Information includes:
  • Disassembly at current EIP
  • Register values in hex, decimal and "smart" dereferenced
  • ESP, ESP+4, ESP+8 ... values in hex, decimal and "smart" dereferenced
Parameters:
context - (Optional) Current thread context to examine
           (type=Context)
stack_depth - (Optional, def:5) Number of dwords to dereference off of the stack (not including ESP)
           (type=Integer)
print_dots - (Optional, def:True) Controls suppression of dot in place of non-printable
           (type=Bool)
Returns:
Information about current thread context.
           (type=String)

See Also: dump_context_list()

dump_context_list(self, context=None, stack_depth=5, print_dots=True)

Return an informational list of items describing the CPU context of the current thread. Information includes:
  • Disassembly at current EIP
  • Register values in hex, decimal and "smart" dereferenced
  • ESP, ESP+4, ESP+8 ... values in hex, decimal and "smart" dereferenced
Parameters:
context - (Optional) Current thread context to examine
           (type=Context)
stack_depth - (Optional, def:5) Number of dwords to dereference off of the stack (not including ESP)
           (type=Integer)
print_dots - (Optional, def:True) Controls suppression of dot in place of non-printable
           (type=Bool)
Returns:
Dictionary of information about current thread context.
           (type=Dictionary)

See Also: dump_context()

event_handler_create_process(self)

This is the default CREATE_PROCESS_DEBUG_EVENT handler.
Returns:
Debug event continue status.
           (type=DWORD)
Overrides:
pydbg.pydbg_core.pydbg_core.event_handler_create_process

event_handler_create_thread(self)

This is the default CREATE_THREAD_DEBUG_EVENT handler.
Returns:
Debug event continue status.
           (type=DWORD)
Overrides:
pydbg.pydbg_core.pydbg_core.event_handler_create_thread

event_handler_exit_process(self)

This is the default EXIT_PROCESS_DEBUG_EVENT handler.
Raises:
pdx - An exception is raised to denote process exit.
Overrides:
pydbg.pydbg_core.pydbg_core.event_handler_exit_process

event_handler_exit_thread(self)

This is the default EXIT_THREAD_DEBUG_EVENT handler.
Returns:
Debug event continue status.
           (type=DWORD)
Overrides:
pydbg.pydbg_core.pydbg_core.event_handler_exit_thread

event_handler_load_dll(self)

This is the default LOAD_DLL_DEBUG_EVENT handler. You can access the last loaded dll in your callback handler with the following example code: 
   last_dll = pydbg.get_system_dll(-1)
   print "loading:%s into:%08x size:%d" % (last_dll.name, last_dll.base, last_dll.size)
The get_system_dll() routine is preferred over directly accessing the internal data structure for proper and transparent client/server support.
Returns:
Debug event continue status.
           (type=DWORD)
Overrides:
pydbg.pydbg_core.pydbg_core.event_handler_load_dll

event_handler_unload_dll(self)

This is the default UNLOAD_DLL_DEBUG_EVENT handler.
Returns:
Debug event continue status.
           (type=DWORD)
Overrides:
pydbg.pydbg_core.pydbg_core.event_handler_unload_dll

exception_handler_access_violation(self)

This is the default EXCEPTION_ACCESS_VIOLATION handler. Responsible for handling the access violation and passing control to the registered user callback handler.
Returns:
Debug event continue status.
           (type=DWORD)
Overrides:
pydbg.pydbg_core.pydbg_core.exception_handler_access_violation

exception_handler_breakpoint(self)

This is the default EXCEPTION_BREAKPOINT handler, responsible for transparently restoring soft breakpoints and passing control to the registered user callback handler.
Returns:
Debug event continue status.
           (type=DWORD)
Overrides:
pydbg.pydbg_core.pydbg_core.exception_handler_breakpoint

exception_handler_guard_page(self)

This is the default EXCEPTION_GUARD_PAGE handler, responsible for transparently restoring memory breakpoints passing control to the registered user callback handler.
Returns:
Debug event continue status.
           (type=DWORD)
Overrides:
pydbg.pydbg_core.pydbg_core.exception_handler_guard_page

exception_handler_single_step(self)

This is the default EXCEPTION_SINGLE_STEP handler, responsible for transparently restoring breakpoints and passing control to the registered user callback handler.
Returns:
Debug event continue status.
           (type=DWORD)
Overrides:
pydbg.pydbg_core.pydbg_core.exception_handler_single_step

flip_endian(self, dword)

Utility function to flip the endianess a given DWORD into raw bytes.
Parameters:
dword
           (type=DWORD)
Returns:
Converted DWORD in raw bytes.
           (type=Raw Bytes)

flip_endian_dword(self, bytes)

Utility function to flip the endianess of a given set of raw bytes into a DWORD.
Parameters:
bytes - Raw bytes whose endianess to flip
           (type=Raw Bytes)
Returns:
Converted DWORD.
           (type=DWORD)

func_resolve(self, dll, function)

Utility function that resolves the address of a given module / function name pair under the context of the debugger.
Parameters:
dll - Name of the DLL (case-insensitive)
           (type=String)
function - Name of the function to resolve (case-sensitive)
           (type=String)
Returns:
Address
           (type=DWORD)

See Also: func_resolve_debuggee()

func_resolve_debuggee(self, dll_name, func_name)

Utility function that resolves the address of a given module / function name pair under the context of the debuggee.
Parameters:
dll_name - Name of the DLL (case-insensitive)
           (type=String)
func_name - Name of the function to resolve (case-sensitive)
           (type=String)
Returns:
Address of the symbol in the target process address space if it can be resolved, None otherwise
           (type=DWORD)

Author: Otto Ebeling

See Also: func_resolve()

get_arg(self, index, context=None)

Given a thread context, this convenience routine will retrieve the function argument at the specified index. The return address of the function can be retrieved by specifying an index of 0. This routine should be called from breakpoint handlers at the top of a function.
Parameters:
index - Data to explore for printable ascii string
           (type=Integer)
context - (Optional) Current thread context to examine
           (type=Context)
Returns:
Value of specified argument.
           (type=DWORD)

get_ascii_string(self, data)

Retrieve the ASCII string, if any, from data. Ensure that the string is valid by checking against the minimum length requirement defined in self.STRING_EXPLORATION_MIN_LENGTH.
Parameters:
data - Data to explore for printable ascii string
           (type=Raw)
Returns:
False on failure, ascii string on discovered string.
           (type=String)

get_printable_string(self, data, print_dots=True)

description
Parameters:
data - Data to explore for printable ascii string
           (type=Raw)
print_dots - (Optional, def:True) Controls suppression of dot in place of non-printable
           (type=Bool)
Returns:
False on failure, discovered printable chars in string otherwise.
           (type=String)

get_unicode_string(self, data)

description
Parameters:
data - Data to explore for printable unicode string
           (type=Raw)
Returns:
False on failure, ascii-converted unicode string on discovered string.
           (type=String)

hex_dump(self, data, addr=0)

Utility function that converts data into hex dump format.
Parameters:
data - Raw bytes to view in hex dump
           (type=Raw Bytes)
addr - (Optional, def=0) Address to start hex offset display from
           (type=DWORD)
Returns:
Hex dump of data.
           (type=String)

hide_debugger(self)

Hide the presence of the debugger.
Raises:
pdx - An exception is raised if we are unable to hide the debugger for various reasons.

is_address_on_stack(self, address, context=None)

Utility function to determine if the specified address exists on the current thread stack or not.
Parameters:
address - Address to check
           (type=DWORD)
context - (Optional) Current thread context to examine
           (type=Context)
Returns:
True if address lies in current threads stack range, False otherwise.
           (type=Bool)

process_restore(self)

Restore memory / context snapshot of the debuggee. All threads must be suspended before calling this routine.
Returns:
Self
           (type=pydbg)
Raises:
pdx - An exception is raised on failure.

process_snapshot(self)

Take memory / context snapshot of the debuggee. All threads must be suspended before calling this routine.
Returns:
Self
           (type=pydbg)
Raises:
pdx - An exception is raised on failure.

seh_unwind(self, context=None)

Unwind the the Structured Exception Handler (SEH) chain of the current or specified thread to the best of our abilities. The SEH chain is a simple singly linked list, the head of which is pointed to by fs:0. In cases where the SEH chain is corrupted and the handler address points to invalid memory, it will be returned as 0xFFFFFFFF.
Parameters:
context - (Optional) Current thread context to examine
           (type=Context)
Returns:
Naturally ordered list of SEH addresses and handlers.
           (type=List of Tuples)

set_register(self, register, value)

Set the value of a register in the debuggee within the context of the self.h_thread.
Parameters:
register - One of EAX, EBX, ECX, EDX, ESI, EDI, ESP, EBP, EIP
           (type=Register)
value - Value to set register to
           (type=DWORD)
Returns:
Self
           (type=pydbg)
Raises:
pdx - An exception is raised on failure.

smart_dereference(self, address, print_dots=True)

"Intelligently" discover data behind an address. The address is dereferenced and explored in search of an ASCII or Unicode string. In the absense of a string the printable characters are returned with non-printables represented as dots (.). The location of the discovered data is returned as well as either "heap", "stack" or the name of the module it lies in (global data).
Parameters:
address - Address to smart dereference
           (type=DWORD)
print_dots - (Optional, def:True) Controls suppression of dot in place of non-printable
           (type=Bool)
Returns:
String of data discovered behind dereference.
           (type=String)

stack_range(self, context=None)

Determine the stack range (top and bottom) of the current or specified thread. The desired information is located at offsets 4 and 8 from the Thread Environment Block (TEB), which in turn is pointed to by fs:0.
Parameters:
context - (Optional) Current thread context to examine
           (type=Context)
Returns:
List containing (stack_top, stack_bottom) on success, False otherwise.
           (type=Mixed)

stack_unwind(self, context=None)

Unwind the stack to the best of our ability. This function is really only useful if called when EBP is actually used as a frame pointer. If it is otherwise being used as a general purpose register then stack unwinding will fail immediately.
Parameters:
context - (Optional) Current thread context to examine
           (type=Context)
Returns:
The current call stack ordered from most recent call backwards.
           (type=List)

to_binary(self, number, bit_count=32)

Convert a number into a binary string. This is an ugly one liner that I ripped off of some site.
Parameters:
number - Number to convert to binary string.
           (type=Integer)
bit_count - (Optional, Def=32) Number of bits to include in output string.
           (type=Integer)
Returns:
Specified integer as a binary string
           (type=String)

See Also: to_decimal()

to_decimal(self, binary)

Convert a binary string into a decimal number. This is an ugly one liner that I ripped off of some site.
Parameters:
binary - Binary string to convert to decimal
           (type=String)
Returns:
Specified binary string as an integer
           (type=Integer)

See Also: to_binary()


Class Variable Details

breakpoints

Type:
dict
Value:
{}

first_breakpoint

Type:
bool
Value:
True

hardware_breakpoint_hit

Type:
NoneType
Value:
None                                                                  

hardware_breakpoints

Type:
dict
Value:
{}

instruction

Type:
NoneType
Value:
None                                                                  

memory_breakpoint_hit

Type:
int
Value:
0                                                                     

memory_breakpoints

Type:
dict
Value:
{}

memory_snapshot_blocks

Type:
list
Value:
[]

memory_snapshot_contexts

Type:
list
Value:
[]

mnemonic

Type:
NoneType
Value:
None                                                                  

op1

Type:
NoneType
Value:
None                                                                  

op2

Type:
NoneType
Value:
None                                                                  

op3

Type:
NoneType
Value:
None                                                                  

restore_breakpoint

Type:
NoneType
Value:
None                                                                  

STRING_EXPLORATION_MIN_LENGTH

Type:
int
Value:
2                                                                     

STRING_EXPLORATON_BUF_SIZE

Type:
int
Value:
256                                                                   

   Trees       Index       Help   

PyDbg - Python Win32 Debugger

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