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:

- Register manipulation.
- Soft (INT 3) breakpoints.
- Memory breakpoints (page permissions).
- Hardware breakpoints.
- Exception / event handling call backs.
- Pydasm (libdasm) disassembly wrapper.
- Process memory snapshotting and restoring.
- Endian manipulation routines.
- Debugger hiding.
- Function resolution.
- "Intelligent" memory derefencing.
- Stack/SEH unwinding.
- Etc...

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.
pydasm instruction | ``get_instruction`(self, address)` Pydasm disassemble utility function wrapper.
String | ``get_printable_string`(self, data, print_dots)` description
String | ``get_unicode_string`(self, data)` description
String | ``hex_dump`(self, data, addr, prefix)` 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 | ``page_guard_clear`(self)` Clear all debugger-set PAGE_GUARDs from memory.
pydbg | ``page_guard_restore`(self)` Restore all previously cleared debugger-set PAGE_GUARDs from memory.
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_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.
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
`int` | `STRING_EXPLORATION_MIN_LENGTH` = 2
`int` | `STRING_EXPLORATON_BUF_SIZE` = 256
`set` | `_guarded_pages` = `set([])`
`bool` | `_guards_active` = `True`
`NoneType` | `_restore_breakpoint` = None
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. Calls through to pydbg_core. 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. Calls through to pydbg_core. 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. Calls through to pydbg_core. 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. Calls through to pydbg_core. 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. Calls through to pydbg_core. 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. Calls through to pydbg_core. 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. Does not call through to pydbg_core. 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. Does not call through to pydbg_core. 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. Does not call through to pydbg_core. 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. Does not call through to pydbg_core. 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, ex:ws2_32.dll) (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() To Do: Add support for followed imports.

### 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_instruction(self, address) Pydasm disassemble utility function wrapper. Returns the pydasm decoded instruction in self.instruction. Parameters: `address` - Address to disassemble at (type=DWORD) Returns: pydasm instruction (type=pydasm instruction)

### 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, prefix='') 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) `prefix` - String to prefix each line of hex dump with. (type=String (Optional, def="")) Returns: Hex dump of data. (type=String)

### hide_debugger(self) Hide the presence of the debugger. This routine requires an active context and therefore can not be called immediately after a load() for example. Call it from the first chance breakpoint handler. This routine hides the debugger in the following ways: Modifies the PEB flag that IsDebuggerPresent() checks for. 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)

### page_guard_clear(self) Clear all debugger-set PAGE_GUARDs from memory. This is useful for suspending memory breakpoints to single step past a REP instruction. Returns: Self (type=pydbg) See Also: page_guard_restore()

### page_guard_restore(self) Restore all previously cleared debugger-set PAGE_GUARDs from memory. This is useful for suspending memory breakpoints to single step past a REP instruction. Returns: Self (type=pydbg) See Also: page_guard_clear()

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

    ### STRING_EXPLORATION_MIN_LENGTH Type: `int` Value:
        2

    ### STRING_EXPLORATON_BUF_SIZE Type: `int` Value:
        256

    ### _guarded_pages Type: `set` Value:
        set([])

    ### _guards_active Type: `bool` Value:
        True

    ### _restore_breakpoint Type: `NoneType` Value:
        None

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