Home       Trees       Indices       Help   
WinAppDbg - Programming Reference
Package winappdbg :: Module thread :: Class Thread
[hide private]
[frames] | no frames]

Class Thread

source code

Interface to a thread in another process.

Nested Classes [hide private]
    Registers
  Flags
Commonly used processor flags
Instance Methods [hide private]
 
__init__(self, dwThreadId, hThread=None, process=None)
x.__init__(...) initializes x; see help(type(x)) for signature		 source code
 
__load_Process_class(self) source code
 
__get_pid_by_scanning(self)
Internally used by get_pid().		 source code
tuple of tuple( int, int, str )
__get_stack_trace(self, depth=16, bUseLabels=True, bMakePretty=True)
Tries to get a stack trace for the current function using the debug helper API (dbghelp.dll).		 source code
tuple of tuple( int, int, str )
__get_stack_trace_manually(self, depth=16, bUseLabels=True, bMakePretty=True)
Tries to get a stack trace for the current function.		 source code

Inherited from object: __delattr__, __format__, __getattribute__, __hash__, __new__, __reduce__, __reduce_ex__, __repr__, __setattr__, __sizeof__, __str__, __subclasshook__

    Properties
Process
get_process(self)
Returns: Parent Process object.		 source code
 
set_process(self, process=None)
Manually set the parent Process object.		 source code
int
get_pid(self)
Returns: Parent process global ID.		 source code
int
get_tid(self)
Returns: Thread global ID.		 source code
str
get_name(self)
Returns: Thread name, or None if the thread is nameless.		 source code
 
set_name(self, name=None)
Sets the thread's name.		 source code
 
open_handle(self, dwDesiredAccess=2097151)
Opens a new handle to the thread, closing the previous one.		 source code
 
close_handle(self)
Closes the handle to the thread.		 source code
ThreadHandle
get_handle(self, dwDesiredAccess=2097151)
Returns a handle to the thread with at least the access rights requested.		 source code
bool
is_alive(self)
Returns: True if the thread if currently running.		 source code
int
get_exit_code(self)
Returns: Thread exit code, or STILL_ACTIVE if it's still alive.		 source code
list of Window
get_windows(self)
Returns: Returns a list of windows handled by this thread.		 source code
bool
is_wow64(self)
Determines if the thread is running under WOW64.		 source code
str
get_arch(self)
Returns: The architecture in which this thread believes to be running.		 source code
str
get_bits(self)
Returns: The number of bits in which this thread believes to be running.		 source code
TEB
get_teb(self)
Returns a copy of the TEB.		 source code
int
get_teb_address(self)
Returns a remote pointer to the TEB.		 source code
    Instrumentation
 
wait(self, dwTimeout=None)
Waits for the thread to finish executing.		 source code
 
kill(self, dwExitCode=0)
Terminates the thread execution.		 source code
int
suspend(self)
Suspends the thread execution.		 source code
int
resume(self)
Resumes the thread execution.		 source code
    Debugging
bool
is_hidden(self)
Determines if the thread has been hidden from debuggers.		 source code
int
get_seh_chain_pointer(self)
Get the pointer to the first structured exception handler block.		 source code
 
set_seh_chain_pointer(self, value)
Change the pointer to the first structured exception handler block.		 source code
list of tuple( int, int )
get_seh_chain(self)
Returns: List of structured exception handlers.		 source code
tuple of ( list of win32.WaitChainNodeInfo structures, bool)
get_wait_chain(self)
Returns: Wait chain for the thread.		 source code
    Disassembly
list of tuple( long, int, str, str )
disassemble_string(self, lpAddress, code)
Disassemble instructions from a block of binary code.		 source code
list of tuple( long, int, str, str )
disassemble(self, lpAddress, dwSize)
Disassemble instructions from the address space of the process.		 source code
list of tuple( long, int, str, str )
disassemble_around(self, lpAddress, dwSize=64)
Disassemble around the given address.		 source code
list of tuple( long, int, str, str )
disassemble_around_pc(self, dwSize=64)
Disassemble around the program counter of the given thread.		 source code
tuple( long, int, str, str )
disassemble_instruction(self, lpAddress)
Disassemble the instruction at the given memory address.		 source code
tuple( long, int, str, str )
disassemble_current(self)
Disassemble the instruction at the program counter of the given thread.		 source code
    Stack
tuple( int, int )
get_stack_range(self)
Returns: Stack beginning and end pointers, in memory addresses order.		 source code
tuple of tuple( int, int, str )
get_stack_trace(self, depth=16)
Tries to get a stack trace for the current function.		 source code
tuple of tuple( int, int, str )
get_stack_trace_with_labels(self, depth=16, bMakePretty=True)
Tries to get a stack trace for the current function.		 source code
tuple( int, int )
get_stack_frame_range(self)
Returns the starting and ending addresses of the stack frame.		 source code
str
get_stack_frame(self, max_size=None)
Reads the contents of the current stack frame.		 source code
str
read_stack_data(self, size=128, offset=0)
Reads the contents of the top of the stack.		 source code
str
peek_stack_data(self, size=128, offset=0)
Tries to read the contents of the top of the stack.		 source code
tuple( int... )
read_stack_dwords(self, count, offset=0)
Reads DWORDs from the top of the stack.		 source code
tuple( int... )
peek_stack_dwords(self, count, offset=0)
Tries to read DWORDs from the top of the stack.		 source code
tuple( int... )
read_stack_qwords(self, count, offset=0)
Reads QWORDs from the top of the stack.		 source code
tuple( int... )
peek_stack_qwords(self, count, offset=0)
Tries to read QWORDs from the top of the stack.		 source code
tuple
read_stack_structure(self, structure, offset=0)
Reads the given structure at the top of the stack.		 source code
tuple
read_stack_frame(self, structure, offset=0)
Reads the stack frame of the thread.		 source code
    Registers
dict( str → int )
get_context(self, ContextFlags=None, bSuspend=False)
Retrieves the execution context (i.e.		 source code
 
set_context(self, context, bSuspend=False)
Sets the values of the registers.		 source code
int
get_register(self, register)
Returns: Value of the requested register.		 source code
int
set_register(self, register, value)
Sets the value of a specific register.		 source code
int
get_pc(self)
Returns: Value of the program counter register.		 source code
 
set_pc(self, pc)
Sets the value of the program counter register.		 source code
int
get_sp(self)
Returns: Value of the stack pointer register.		 source code
 
set_sp(self, sp)
Sets the value of the stack pointer register.		 source code
int
get_fp(self)
Returns: Value of the frame pointer register.		 source code
 
set_fp(self, fp)
Sets the value of the frame pointer register.		 source code
int
get_flags(self, FlagMask=4294967295)
Returns: Flags register contents, optionally masking out some bits.		 source code
 
set_flags(self, eflags, FlagMask=4294967295)
Sets the flags register, optionally masking some bits.		 source code
bool
get_flag_value(self, FlagBit)
Returns: Boolean value of the requested flag.		 source code
 
set_flag_value(self, FlagBit, FlagValue)
Sets a single flag, leaving the others intact.		 source code
bool
get_zf(self)
Returns: Boolean value of the Zero flag.		 source code
bool
get_cf(self)
Returns: Boolean value of the Carry flag.		 source code
bool
get_sf(self)
Returns: Boolean value of the Sign flag.		 source code
bool
get_df(self)
Returns: Boolean value of the Direction flag.		 source code
bool
get_tf(self)
Returns: Boolean value of the Trap flag.		 source code
 
clear_zf(self)
Clears the Zero flag.		 source code
 
clear_cf(self)
Clears the Carry flag.		 source code
 
clear_sf(self)
Clears the Sign flag.		 source code
 
clear_df(self)
Clears the Direction flag.		 source code
 
clear_tf(self)
Clears the Trap flag.		 source code
 
set_zf(self)
Sets the Zero flag.		 source code
 
set_cf(self)
Sets the Carry flag.		 source code
 
set_sf(self)
Sets the Sign flag.		 source code
 
set_df(self)
Sets the Direction flag.		 source code
 
set_tf(self)
Sets the Trap flag.		 source code
    Threads snapshot
 
clear(self)
Clears the resources held by this object.		 source code
    Miscellaneous
int
get_linear_address(self, segment, address)
Translates segment-relative addresses to linear addresses.		 source code
str
get_label_at_pc(self)
Returns: Label that points to the instruction currently being executed.		 source code
str
read_code_bytes(self, size=128, offset=0)
Tries to read some bytes of the code currently being executed.		 source code
str
peek_code_bytes(self, size=128, offset=0)
Tries to read some bytes of the code currently being executed.		 source code
dict( str → str )
peek_pointers_in_registers(self, peekSize=16, context=None)
Tries to guess which values in the registers are valid pointers, and reads some data from them.		 source code
dict( str → str )
peek_pointers_in_data(self, data, peekSize=16, peekStep=1)
Tries to guess which values in the given data are valid pointers, and reads some data from them.		 source code
Instance Variables [hide private]
Process process
Parent process object.
int dwThreadId
Global thread ID.
ThreadHandle hThread
Handle to the thread.
int pInjectedMemory
If the thread was created by Process.inject_code, this member contains a pointer to the memory buffer for the injected code.
Properties [hide private]

Inherited from object: __class__

Method Details [hide private]

__init__(self, dwThreadId, hThread=None, process=None)
(Constructor)

source code 

x.__init__(...) initializes x; see help(type(x)) for signature

Parameters:
  • dwThreadId (int) - Global thread ID.
  • hThread (ThreadHandle) - (Optional) Handle to the thread.
  • process (Process) - (Optional) Parent Process object.
Overrides: object.__init__

get_process(self)

source code 
Returns: Process
Parent Process object. Returns None if unknown.

set_process(self, process=None)

source code 

Manually set the parent Process object. Use with care!

Parameters:
  • process (Process) - (Optional) Process object. Use None for no process.

get_pid(self)

source code 
Returns: int
Parent process global ID.
Raises:
  • WindowsError - An error occured when calling a Win32 API function.
  • RuntimeError - The parent process ID can't be found.

get_tid(self)

source code 
Returns: int
Thread global ID.

get_name(self)

source code 
Returns: str
Thread name, or None if the thread is nameless.

set_name(self, name=None)

source code 

Sets the thread's name.

Parameters:
  • name (str) - Thread name, or None if the thread is nameless.

open_handle(self, dwDesiredAccess=2097151)

source code 

Opens a new handle to the thread, closing the previous one.

The new handle is stored in the hThread property.

Parameters:
Raises:
  • WindowsError - It's not possible to open a handle to the thread with the requested access rights. This tipically happens because the target thread belongs to system process and the debugger is not runnning with administrative rights.

Warning: Normally you should call get_handle instead, since it's much "smarter" and tries to reuse handles and merge access rights.

close_handle(self)

source code 

Closes the handle to the thread.

Note: Normally you don't need to call this method. All handles created by WinAppDbg are automatically closed when the garbage collector claims them.

get_handle(self, dwDesiredAccess=2097151)

source code 

Returns a handle to the thread with at least the access rights requested.

Parameters:
Returns: ThreadHandle
Handle to the thread.
Raises:
  • WindowsError - It's not possible to open a handle to the thread with the requested access rights. This tipically happens because the target thread belongs to system process and the debugger is not runnning with administrative rights.

Note: If a handle was previously opened and has the required access rights, it's reused. If not, a new handle is opened with the combination of the old and new access rights.

wait(self, dwTimeout=None)

source code 

Waits for the thread to finish executing.

Parameters:
  • dwTimeout (int) - (Optional) Timeout value in milliseconds. Use INFINITE or None for no timeout.

kill(self, dwExitCode=0)

source code 

Terminates the thread execution.

Parameters:
  • dwExitCode (int) - (Optional) Thread exit code.

Note: If the lpInjectedMemory member contains a valid pointer, the memory is freed.

suspend(self)

source code 

Suspends the thread execution.

Returns: int
Suspend count. If zero, the thread is running.

resume(self)

source code 

Resumes the thread execution.

Returns: int
Suspend count. If zero, the thread is running.

is_alive(self)

source code 
Returns: bool
True if the thread if currently running.
Raises:
  • WindowsError - The debugger doesn't have enough privileges to perform this action.

get_exit_code(self)

source code 
Returns: int
Thread exit code, or STILL_ACTIVE if it's still alive.

get_windows(self)

source code 
Returns: list of Window
Returns a list of windows handled by this thread.

get_context(self, ContextFlags=None, bSuspend=False)

source code 

Retrieves the execution context (i.e. the registers values) for this thread.

Parameters:
  • ContextFlags (int) - Optional, specify which registers to retrieve. Defaults to win32.CONTEXT_ALL which retrieves all registes for the current platform.
  • bSuspend (bool) - True to automatically suspend the thread before getting its context, False otherwise.

    Defaults to False because suspending the thread during some debug events (like thread creation or destruction) may lead to strange errors.

    Note that WinAppDbg 1.4 used to suspend the thread automatically always. This behavior was changed in version 1.5.

Returns: dict( str → int )
Dictionary mapping register names to their values.

See Also: set_context

set_context(self, context, bSuspend=False)

source code 

Sets the values of the registers.

Parameters:
  • context (dict( str → int )) - Dictionary mapping register names to their values.
  • bSuspend (bool) - True to automatically suspend the thread before setting its context, False otherwise.

    Defaults to False because suspending the thread during some debug events (like thread creation or destruction) may lead to strange errors.

    Note that WinAppDbg 1.4 used to suspend the thread automatically always. This behavior was changed in version 1.5.

See Also: get_context

get_register(self, register)

source code 
Parameters:
  • register (str) - Register name.
Returns: int
Value of the requested register.

set_register(self, register, value)

source code 

Sets the value of a specific register.

Parameters:
  • register (str) - Register name.
Returns: int
Register value.

get_pc(self)

source code 
Returns: int
Value of the program counter register.

set_pc(self, pc)

source code 

Sets the value of the program counter register.

Parameters:
  • pc (int) - Value of the program counter register.

get_sp(self)

source code 
Returns: int
Value of the stack pointer register.

set_sp(self, sp)

source code 

Sets the value of the stack pointer register.

Parameters:
  • sp (int) - Value of the stack pointer register.

get_fp(self)

source code 
Returns: int
Value of the frame pointer register.

set_fp(self, fp)

source code 

Sets the value of the frame pointer register.

Parameters:
  • fp (int) - Value of the frame pointer register.

get_flags(self, FlagMask=4294967295)

source code 
Parameters:
  • FlagMask (int) - (Optional) Bitwise-AND mask.
Returns: int
Flags register contents, optionally masking out some bits.

set_flags(self, eflags, FlagMask=4294967295)

source code 

Sets the flags register, optionally masking some bits.

Parameters:
  • eflags (int) - Flags register contents.
  • FlagMask (int) - (Optional) Bitwise-AND mask.

get_flag_value(self, FlagBit)

source code 
Parameters:
  • FlagBit (int) - One of the Flags.
Returns: bool
Boolean value of the requested flag.

set_flag_value(self, FlagBit, FlagValue)

source code 

Sets a single flag, leaving the others intact.

Parameters:
  • FlagBit (int) - One of the Flags.
  • FlagValue (bool) - Boolean value of the flag.

get_zf(self)

source code 
Returns: bool
Boolean value of the Zero flag.

get_cf(self)

source code 
Returns: bool
Boolean value of the Carry flag.

get_sf(self)

source code 
Returns: bool
Boolean value of the Sign flag.

get_df(self)

source code 
Returns: bool
Boolean value of the Direction flag.

get_tf(self)

source code 
Returns: bool
Boolean value of the Trap flag.

is_wow64(self)

source code 

Determines if the thread is running under WOW64.

Returns: bool
True if the thread is running under WOW64. That is, it belongs to a 32-bit application running in a 64-bit Windows.

False if the thread belongs to either a 32-bit application running in a 32-bit Windows, or a 64-bit application running in a 64-bit Windows.

Raises:
  • WindowsError - On error an exception is raised.

See Also: http://msdn.microsoft.com/en-us/library/aa384249(VS.85).aspx

get_arch(self)

source code 
Returns: str
The architecture in which this thread believes to be running. For example, if running a 32 bit binary in a 64 bit machine, the architecture returned by this method will be win32.ARCH_I386, but the value of System.arch will be win32.ARCH_AMD64.

get_bits(self)

source code 
Returns: str
The number of bits in which this thread believes to be running. For example, if running a 32 bit binary in a 64 bit machine, the number of bits returned by this method will be 32, but the value of System.arch will be 64.

is_hidden(self)

source code 

Determines if the thread has been hidden from debuggers.

Some binary packers hide their own threads to thwart debugging.

Returns: bool
True if the thread is hidden from debuggers. This means the thread's execution won't be stopped for debug events, and thus said events won't be sent to the debugger.

get_teb(self)

source code 

Returns a copy of the TEB. To dereference pointers in it call Process.read_structure.

Returns: TEB
TEB structure.
Raises:
  • WindowsError - An exception is raised on error.

get_teb_address(self)

source code 

Returns a remote pointer to the TEB.

Returns: int
Remote pointer to the TEB structure.
Raises:
  • WindowsError - An exception is raised on error.

get_linear_address(self, segment, address)

source code 

Translates segment-relative addresses to linear addresses.

Linear addresses can be used to access a process memory, calling Process.read and Process.write.

Parameters:
  • segment (str) - Segment register name.
  • address (int) - Segment relative memory address.
Returns: int
Linear memory address.
Raises:
  • ValueError - Address is too large for selector.
  • WindowsError - The current architecture does not support selectors. Selectors only exist in x86-based systems.

get_label_at_pc(self)

source code 
Returns: str
Label that points to the instruction currently being executed.

get_seh_chain_pointer(self)

source code 

Get the pointer to the first structured exception handler block.

Returns: int
Remote pointer to the first block of the structured exception handlers linked list. If the list is empty, the returned value is 0xFFFFFFFF.
Raises:
  • NotImplementedError - This method is only supported in 32 bits versions of Windows.

set_seh_chain_pointer(self, value)

source code 

Change the pointer to the first structured exception handler block.

Parameters:
  • value (int) - Value of the remote pointer to the first block of the structured exception handlers linked list. To disable SEH set the value 0xFFFFFFFF.
Raises:
  • NotImplementedError - This method is only supported in 32 bits versions of Windows.

get_seh_chain(self)

source code 
Returns: list of tuple( int, int )
List of structured exception handlers. Each SEH is represented as a tuple of two addresses:
  • Address of this SEH block
  • Address of the SEH callback function

Do not confuse this with the contents of the SEH block itself, where the first member is a pointer to the next block instead.

Raises:
  • NotImplementedError - This method is only supported in 32 bits versions of Windows.

get_wait_chain(self)

source code 
Returns: tuple of ( list of win32.WaitChainNodeInfo structures, bool)
Wait chain for the thread. The boolean indicates if there's a cycle in the chain (a deadlock).
Raises:
  • AttributeError - This method is only suppported in Windows Vista and above.

See Also: http://msdn.microsoft.com/en-us/library/ms681622%28VS.85%29.aspx

get_stack_range(self)

source code 
Returns: tuple( int, int )
Stack beginning and end pointers, in memory addresses order. That is, the first pointer is the stack top, and the second pointer is the stack bottom, since the stack grows towards lower memory addresses.
Raises:
  • WindowsError - Raises an exception on error.

__get_stack_trace(self, depth=16, bUseLabels=True, bMakePretty=True)

source code 

Tries to get a stack trace for the current function using the debug helper API (dbghelp.dll).

Parameters:
  • depth (int) - Maximum depth of stack trace.
  • bUseLabels (bool) - True to use labels, False to use addresses.
  • bMakePretty (bool) - True for user readable labels, False for labels that can be passed to Process.resolve_label.

    "Pretty" labels look better when producing output for the user to read, while pure labels are more useful programatically.

Returns: tuple of tuple( int, int, str )
Stack trace of the thread as a tuple of ( return address, frame pointer address, module filename ) when bUseLabels is True, or a tuple of ( return address, frame pointer label ) when bUseLabels is False.
Raises:
  • WindowsError - Raises an exception on error.

__get_stack_trace_manually(self, depth=16, bUseLabels=True, bMakePretty=True)

source code 

Tries to get a stack trace for the current function. Only works for functions with standard prologue and epilogue.

Parameters:
  • depth (int) - Maximum depth of stack trace.
  • bUseLabels (bool) - True to use labels, False to use addresses.
  • bMakePretty (bool) - True for user readable labels, False for labels that can be passed to Process.resolve_label.

    "Pretty" labels look better when producing output for the user to read, while pure labels are more useful programatically.

Returns: tuple of tuple( int, int, str )
Stack trace of the thread as a tuple of ( return address, frame pointer address, module filename ) when bUseLabels is True, or a tuple of ( return address, frame pointer label ) when bUseLabels is False.
Raises:
  • WindowsError - Raises an exception on error.

get_stack_trace(self, depth=16)

source code 

Tries to get a stack trace for the current function. Only works for functions with standard prologue and epilogue.

Parameters:
  • depth (int) - Maximum depth of stack trace.
Returns: tuple of tuple( int, int, str )
Stack trace of the thread as a tuple of ( return address, frame pointer address, module filename ).
Raises:
  • WindowsError - Raises an exception on error.

get_stack_trace_with_labels(self, depth=16, bMakePretty=True)

source code 

Tries to get a stack trace for the current function. Only works for functions with standard prologue and epilogue.

Parameters:
  • depth (int) - Maximum depth of stack trace.
  • bMakePretty (bool) - True for user readable labels, False for labels that can be passed to Process.resolve_label.

    "Pretty" labels look better when producing output for the user to read, while pure labels are more useful programatically.

Returns: tuple of tuple( int, int, str )
Stack trace of the thread as a tuple of ( return address, frame pointer label ).
Raises:
  • WindowsError - Raises an exception on error.

get_stack_frame_range(self)

source code 

Returns the starting and ending addresses of the stack frame. Only works for functions with standard prologue and epilogue.

Returns: tuple( int, int )
Stack frame range. May not be accurate, depending on the compiler used.
Raises:
  • RuntimeError - The stack frame is invalid, or the function doesn't have a standard prologue and epilogue.
  • WindowsError - An error occured when getting the thread context.

get_stack_frame(self, max_size=None)

source code 

Reads the contents of the current stack frame. Only works for functions with standard prologue and epilogue.

Parameters:
  • max_size (int) - (Optional) Maximum amount of bytes to read.
Returns: str
Stack frame data. May not be accurate, depending on the compiler used. May return an empty string.
Raises:
  • RuntimeError - The stack frame is invalid, or the function doesn't have a standard prologue and epilogue.
  • WindowsError - An error occured when getting the thread context or reading data from the process memory.

read_stack_data(self, size=128, offset=0)

source code 

Reads the contents of the top of the stack.

Parameters:
  • size (int) - Number of bytes to read.
  • offset (int) - Offset from the stack pointer to begin reading.
Returns: str
Stack data.
Raises:
  • WindowsError - Could not read the requested data.

peek_stack_data(self, size=128, offset=0)

source code 

Tries to read the contents of the top of the stack.

Parameters:
  • size (int) - Number of bytes to read.
  • offset (int) - Offset from the stack pointer to begin reading.
Returns: str
Stack data. Returned data may be less than the requested size.

read_stack_dwords(self, count, offset=0)

source code 

Reads DWORDs from the top of the stack.

Parameters:
  • count (int) - Number of DWORDs to read.
  • offset (int) - Offset from the stack pointer to begin reading.
Returns: tuple( int... )
Tuple of integers read from the stack.
Raises:
  • WindowsError - Could not read the requested data.

peek_stack_dwords(self, count, offset=0)

source code 

Tries to read DWORDs from the top of the stack.

Parameters:
  • count (int) - Number of DWORDs to read.
  • offset (int) - Offset from the stack pointer to begin reading.
Returns: tuple( int... )
Tuple of integers read from the stack. May be less than the requested number of DWORDs.

read_stack_qwords(self, count, offset=0)

source code 

Reads QWORDs from the top of the stack.

Parameters:
  • count (int) - Number of QWORDs to read.
  • offset (int) - Offset from the stack pointer to begin reading.
Returns: tuple( int... )
Tuple of integers read from the stack.
Raises:
  • WindowsError - Could not read the requested data.

peek_stack_qwords(self, count, offset=0)

source code 

Tries to read QWORDs from the top of the stack.

Parameters:
  • count (int) - Number of QWORDs to read.
  • offset (int) - Offset from the stack pointer to begin reading.
Returns: tuple( int... )
Tuple of integers read from the stack. May be less than the requested number of QWORDs.

read_stack_structure(self, structure, offset=0)

source code 

Reads the given structure at the top of the stack.

Parameters:
  • structure (ctypes.Structure) - Structure of the data to read from the stack.
  • offset (int) - Offset from the stack pointer to begin reading. The stack pointer is the same returned by the get_sp method.
Returns: tuple
Tuple of elements read from the stack. The type of each element matches the types in the stack frame structure.

read_stack_frame(self, structure, offset=0)

source code 

Reads the stack frame of the thread.

Parameters:
  • structure (ctypes.Structure) - Structure of the stack frame.
  • offset (int) - Offset from the frame pointer to begin reading. The frame pointer is the same returned by the get_fp method.
Returns: tuple
Tuple of elements read from the stack frame. The type of each element matches the types in the stack frame structure.

read_code_bytes(self, size=128, offset=0)

source code 

Tries to read some bytes of the code currently being executed.

Parameters:
  • size (int) - Number of bytes to read.
  • offset (int) - Offset from the program counter to begin reading.
Returns: str
Bytes read from the process memory.
Raises:
  • WindowsError - Could not read the requested data.

peek_code_bytes(self, size=128, offset=0)

source code 

Tries to read some bytes of the code currently being executed.

Parameters:
  • size (int) - Number of bytes to read.
  • offset (int) - Offset from the program counter to begin reading.
Returns: str
Bytes read from the process memory. May be less than the requested number of bytes.

peek_pointers_in_registers(self, peekSize=16, context=None)

source code 

Tries to guess which values in the registers are valid pointers, and reads some data from them.

Parameters:
  • peekSize (int) - Number of bytes to read from each pointer found.
  • context (dict( str → int )) - (Optional) Dictionary mapping register names to their values. If not given, the current thread context will be used.
Returns: dict( str → str )
Dictionary mapping register names to the data they point to.

peek_pointers_in_data(self, data, peekSize=16, peekStep=1)

source code 

Tries to guess which values in the given data are valid pointers, and reads some data from them.

Parameters:
  • data (str) - Binary data to find pointers in.
  • peekSize (int) - Number of bytes to read from each pointer found.
  • peekStep (int) - Expected data alignment. Tipically you specify 1 when data alignment is unknown, or 4 when you expect data to be DWORD aligned. Any other value may be specified.
Returns: dict( str → str )
Dictionary mapping stack offsets to the data they point to.

disassemble_string(self, lpAddress, code)

source code 

Disassemble instructions from a block of binary code.

Parameters:
  • lpAddress (int) - Memory address where the code was read from.
  • code (str) - Binary code to disassemble.
Returns: list of tuple( long, int, str, str )
List of tuples. Each tuple represents an assembly instruction and contains:
  • Memory address of instruction.
  • Size of instruction in bytes.
  • Disassembly line of instruction.
  • Hexadecimal dump of instruction.

disassemble(self, lpAddress, dwSize)

source code 

Disassemble instructions from the address space of the process.

Parameters:
  • lpAddress (int) - Memory address where to read the code from.
  • dwSize (int) - Size of binary code to disassemble.
Returns: list of tuple( long, int, str, str )
List of tuples. Each tuple represents an assembly instruction and contains:
  • Memory address of instruction.
  • Size of instruction in bytes.
  • Disassembly line of instruction.
  • Hexadecimal dump of instruction.

disassemble_around(self, lpAddress, dwSize=64)

source code 

Disassemble around the given address.

Parameters:
  • lpAddress (int) - Memory address where to read the code from.
  • dwSize (int) - Delta offset. Code will be read from lpAddress - dwSize to lpAddress + dwSize.
Returns: list of tuple( long, int, str, str )
List of tuples. Each tuple represents an assembly instruction and contains:
  • Memory address of instruction.
  • Size of instruction in bytes.
  • Disassembly line of instruction.
  • Hexadecimal dump of instruction.

disassemble_around_pc(self, dwSize=64)

source code 

Disassemble around the program counter of the given thread.

Parameters:
  • dwSize (int) - Delta offset. Code will be read from pc - dwSize to pc + dwSize.
Returns: list of tuple( long, int, str, str )
List of tuples. Each tuple represents an assembly instruction and contains:
  • Memory address of instruction.
  • Size of instruction in bytes.
  • Disassembly line of instruction.
  • Hexadecimal dump of instruction.

disassemble_instruction(self, lpAddress)

source code 

Disassemble the instruction at the given memory address.

Parameters:
  • lpAddress (int) - Memory address where to read the code from.
Returns: tuple( long, int, str, str )
The tuple represents an assembly instruction and contains:
  • Memory address of instruction.
  • Size of instruction in bytes.
  • Disassembly line of instruction.
  • Hexadecimal dump of instruction.

disassemble_current(self)

source code 

Disassemble the instruction at the program counter of the given thread.

Returns: tuple( long, int, str, str )
The tuple represents an assembly instruction and contains:
  • Memory address of instruction.
  • Size of instruction in bytes.
  • Disassembly line of instruction.
  • Hexadecimal dump of instruction.

Instance Variable Details [hide private]

process

Parent process object. Use get_process instead.
Get Method:
get_process(self) - Returns: Parent Process object.
Set Method:
set_process(self, process=None) - Manually set the parent Process object.

dwThreadId

Global thread ID. Use get_tid instead.
Type:
int

hThread

Handle to the thread. Use get_handle instead.
Type:
ThreadHandle

pInjectedMemory

If the thread was created by Process.inject_code, this member contains a pointer to the memory buffer for the injected code. Otherwise it's None.

The kill method uses this member to free the buffer when the injected thread is killed.

Type:
int

   Home       Trees       Indices       Help   
WinAppDbg - Programming Reference
Generated by Epydoc 3.0.1 on Fri Dec 20 17:54:56 2013 http://epydoc.sourceforge.net