Package vtrace :: Class Trace
[hide private]
[frames] | no frames]

Class Trace

source code


The main tracer object. A trace instance is dynamically generated using this and *many* potential mixin classes. However, API users should *not* worry about the methods that come from the mixins... Everything that is *meant* to be used from the API is contained and documented here.

Instance Methods [hide private]
 
__init__(self, archname=None)
x.__init__(...) initializes x; see help(type(x)) for signature
source code
 
execute(self, cmdline)
Start a new process and debug it
source code
 
parseOpcodes(self, num, va=None)
Returns next num of linear disasm'd opcodes objects.
source code
 
getCurrentSignal(self)
Retrieve the current signal/exception posted to the process.
source code
 
setCurrentSignal(self, sig=None)
Set the currently pending signal for delivery to the target process on continue.
source code
 
addIgnoreSignal(self, code, address=0)
By adding an IgnoreSignal you tell the tracer object to supress the notification of a particular type of signal.
source code
 
delIgnoreSignal(self, code, address=0)
See addIgnoreSignal for a description of signal ignoring.
source code
 
attach(self, pid)
Attach to a new process ID.
source code
 
stepi(self)
Single step the target process ONE instruction (and do NOT activate breakpoints for the one step).
source code
 
run(self, until=None)
Allow the traced target to continue execution.
source code
 
runAgain(self, val=True)
The runAgain() method may be used from inside a notifier (Notifier, Breakpoint, Watchpoint, etc...) to inform the trace that once event processing is complete, it should continue running the trace.
source code
 
kill(self)
Kill the target process for this trace (will result in process exit and fire appropriate notifiers)
source code
 
detach(self)
Detach from the currently attached process.
source code
 
release(self)
Release resources for this tracer.
source code
 
getPid(self)
Return the pid for this Trace
source code
 
getNormalizedLibNames(self)
Symbols are stored internally based off of "normalized" library names.
source code
 
getSymsForFile(self, libname)
Return the entire symbol list for the specified normalized library name.
source code
 
getSymByAddr(self, addr, exact=True)
Return an envi Symbol object for an address.
source code
 
getSymByAddrThunkAware(self, va)
TODO: DO NOT USE THIS FUNCTION, GOING AWAY.
source code
 
getSymByName(self, name)
Return an envi.Symbol object for the given name (or None)
source code
 
setSymCachePath(self, path)
Set the symbol cache path for the tracer.
source code
 
searchSymbols(self, regex, libname=None)
Search for symbols which match the given regular expression.
source code
 
getRegisterContext(self, threadid=None)
Retrieve the envi.registers.RegisterContext object for the specified thread.
source code
 
getRegister(self, idx) source code
 
setRegister(self, idx, value) source code
 
allocateMemory(self, size, perms=e_mem.MM_RWX, suggestaddr=0)
Allocate a chunk of memory inside the target process' address space.
source code
 
protectMemory(self, va, size, perms)
Change the page protections on the specified region of memory.
source code
 
readMemory(self, address, size)
Read memory from address.
source code
 
writeMemory(self, address, bytez)
Write the given bytes to the address in the current trace.
source code
 
searchMemory(self, needle, regex=False)
Search all of process memory for a sequence of bytes.
source code
 
searchMemoryRange(self, needle, address, size, regex=False)
Search a memory range for the specified sequence of bytes
source code
 
setMeta(self, name, value)
Set some metadata.
source code
 
getMeta(self, name, default=None)
Get some metadata.
source code
 
hasMeta(self, name)
Check to see if a metadata key exists...
source code
 
getMode(self, name, default=False)
Get the value for a mode setting allowing for a clean default...
source code
 
setMode(self, name, value)
Set a mode setting...
source code
 
injectso(self, filename)
Inject a shared object into the target of the trace.
source code
 
ps(self)
Return a list of proccesses which are currently running on the system.
source code
 
addBreakByExpr(self, symname, fastbreak=False)
Add a breakpoint by resolving an expression.
source code
 
addBreakByAddr(self, va, fastbreak=False)
Add a breakpoint by address.
source code
 
addBreakpoint(self, breakpoint)
Add a breakpoint/watchpoint to the trace.
source code
 
removeBreakpoint(self, id)
Remove the breakpoint with the specified ID
source code
 
getCurrentBreakpoint(self)
Return the current breakpoint otherwise None
source code
 
getBreakpoint(self, id)
Return a reference to the breakpoint with the requested ID.
source code
 
getBreakpointByAddr(self, va)
Return the breakpoint object (or None) for a given virtual address.
source code
 
getBreakpoints(self)
Return a list of the current breakpoints.
source code
 
getBreakpointEnabled(self, bpid)
An accessor method for returning if a breakpoint is currently enabled.
source code
 
setBreakpointEnabled(self, bpid, enabled=True)
An accessor method for setting a breakpoint enabled/disabled.
source code
 
setBreakpointCode(self, bpid, pystr)
Because breakpoints are potentially on the remote debugger and code is not pickleable in python, special access methods which takes strings of python code are necissary for the vdb interface to quick script breakpoint code.
source code
 
getBreakpointCode(self, bpid)
Return the python string of user specified code that will run when this breakpoint is hit.
source code
 
call(self, address, args, convention=None)
Setup the "stack" and call the target address with the following arguments.
source code
 
registerNotifier(self, event, notifier)
Register a notifier who will be called for various events.
source code
 
deregisterNotifier(self, event, notifier) source code
 
getNotifiers(self, event) source code
 
requireNotExited(self)
Call in a method that requires the trace to have not exited.
source code
 
requireNotRunning(self)
Call in a method that requires the debugger the be attached and not running.
source code
 
requireAttached(self)
Call in a method that requires the debugger to be attached.
source code
 
getFds(self)
Get a list of (fd, type, bestname) pairs.
source code
 
getMemoryMaps(self)
Return a list of the currently mapped memory for the target process.
source code
 
getMemoryFault(self)
If the most receent event is a memory access error, this API will return a tuple of (<addr>, <perm>) on supported platforms.
source code
 
isAttached(self)
Return true or false if this trace's target processing is attached.
source code
 
isRunning(self)
Return true or false if this trace's target process is running.
source code
 
hasExited(self)
Return true or false if this trace's target process has exited.
source code
 
isRemote(self)
Return true or false if this trace's target process is a CobraProxy object to a trace on another system.
source code
 
enableAutoContinue(self, event)
Put the tracer object in to AutoContinue mode for the specified event.
source code
 
disableAutoContinue(self, event)
Disable Auto Continue for the specified event.
source code
 
getAutoContinueList(self)
Retrieve the list of vtrace notification events that will be auto-continued.
source code
 
parseExpression(self, expression)
Parse a python expression with many useful helpers mapped into the execution namespace.
source code
 
sendBreak(self)
Send an asynchronous break signal to the target process.
source code
 
getStackTrace(self)
Returns a list of (instruction pointer, stack frame) tuples.
source code
 
getThreads(self)
Get a dictionary of <threadid>:<tinfo> pairs where tinfo is platform dependant, but is typically either the top of the stack for that thread, or the TEB on win32
source code
 
getCurrentThread(self)
Return the thread id of the currently selected thread.
source code
 
selectThread(self, threadid)
Set the "current thread" context to the given thread id.
source code
 
isThreadSuspended(self, threadid)
Used to determine if a thread is suspended.
source code
 
suspendThread(self, threadid)
Suspend a thread by ID.
source code
 
resumeThread(self, threadid)
Resume a suspended thread.
source code
 
injectThread(self, pc)
Create a new thread inside the target process.
source code
 
joinThread(self, threadid)
Run the trace in a loop until the specified thread exits.
source code
 
getStructNames(self, namespace=None)
This method returns either the structure names, or the structure namespaces that the target tracer is aware of.
source code
 
getStruct(self, sname, va=None)
Retrieve a vstruct structure optionally populated with memory from the specified address.
source code
 
setVariable(self, name, value)
Set a named variable in the trace which may be used in subsequent VtraceExpressions.
source code
 
getVariable(self, name)
Get the value of a previously set variable name.
source code
 
getVariables(self)
Get the dictionary of named variables.
source code
 
hex(self, value)
Much like the python hex routine, except this will automatically pad the value's string length out to pointer width.
source code
 
buildNewTrace(self)
Build a new/clean trace "like" this one.
source code

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

Properties [hide private]

Inherited from object: __class__

Method Details [hide private]

__init__(self, archname=None)
(Constructor)

source code 

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

Overrides: object.__init__
(inherited documentation)

parseOpcodes(self, num, va=None)

source code 

Returns next num of linear disasm'd opcodes objects. Optionally pass a va to start there instead of the current program counter.

getCurrentSignal(self)

source code 

Retrieve the current signal/exception posted to the process. If there are no pending signals/exceptions the API will return None. For POSIX systems, this will be a traditional POSIX signal. For Windows systems it will be a current exception code (if any).

Example: sig = trace.getCurrentSignal()

setCurrentSignal(self, sig=None)

source code 

Set the currently pending signal for delivery to the target process on continue. This is intended for use by programs wishing the mask or change the delivery of exceptions on a NOTIFY_SIGNAL event.

Example: trace.setCurrentSignal(None)

addIgnoreSignal(self, code, address=0)

source code 

By adding an IgnoreSignal you tell the tracer object to supress the notification of a particular type of signal. In POSIX, these are regular signals, in Win32, these are exception codes. This is mostly useful in RunForever mode because you still need the process to begin running again. (these may be viewed/modified by the metadata key "IgnoredSignals") FIXME: make address do something.

delIgnoreSignal(self, code, address=0)

source code 

See addIgnoreSignal for a description of signal ignoring. This removes an ignored signal and re-enables it's delivery.

stepi(self)

source code 

Single step the target process ONE instruction (and do NOT activate breakpoints for the one step). Also, we don't deliver pending signals for the single step... Use the mode FastStep to allow/suppress notifier callbacks on step

run(self, until=None)

source code 

Allow the traced target to continue execution. (Depending on the mode "Blocking" this will either block until an event, or return immediately) Additionally, the argument until may be used to cause execution to continue until the specified address is reached (internally uses and removes a breakpoint).

release(self)

source code 

Release resources for this tracer. This API should be called once you are done with the trace.

getNormalizedLibNames(self)

source code 

Symbols are stored internally based off of "normalized" library names. This method returns the list of normalized names for the loaded libraries.

(probably only useful for writting symbol browsers...)

getSymsForFile(self, libname)

source code 

Return the entire symbol list for the specified normalized library name. The list is returned as "symtup" tuples of (va,size,name,type,fname).

getSymByAddr(self, addr, exact=True)

source code 

Return an envi Symbol object for an address. Use exact=False to get the nearest previous match.

getSymByAddrThunkAware(self, va)

source code 

TODO: DO NOT USE THIS FUNCTION, GOING AWAY.
getBestSymEtc? depth / aggressiveness?

for the given va:
1. attempt to get the sym by using getSymByAddr
2. if 1 fails, check the target of the branch for a sym.

returns a tuple (sym, is_thunk).  sym is None if no sym is found.

setSymCachePath(self, path)

source code 

Set the symbol cache path for the tracer.

The "path" syntax is a ; seperated list of either directories
or cobra URIs which implement the SymbolCache interface.

Example:
    trace.setSymCachePath('/home/invisigoth/.envi/symcache;cobra://symbols.com/SymbolCache')

NOTE: vdb automatically handles this with a config option

searchSymbols(self, regex, libname=None)

source code 

Search for symbols which match the given regular expression. Specify libname as the "normalized" library name to only search the specified lib.

Example: for sym in trace.searchSymbols('.*CreateFile.*', 'kernel32'):

getRegisterContext(self, threadid=None)

source code 

Retrieve the envi.registers.RegisterContext object for the specified thread. Use this API to iterate over threads register values without setting the global tracer thread context.

allocateMemory(self, size, perms=e_mem.MM_RWX, suggestaddr=0)

source code 

Allocate a chunk of memory inside the target process' address space. Memory wil be mapped rwx unless otherwise specified with perms=envi.memory.MM_FOO values. Optionally you may *suggest* an address to the allocator, but there is no guarentee. Returns the mapped memory address.

protectMemory(self, va, size, perms)

source code 

Change the page protections on the specified region of memory. See envi.memory for perms values.

readMemory(self, address, size)

source code 

Read memory from address. Areas that are NOT valid memory will be read back as s (this probably goes in a mixin soon)

setMeta(self, name, value)

source code 

Set some metadata. Metadata is a clean way for arbitrary trace consumers (and notifiers) to present and track additional information in trace objects.

Any modules which use this *should* initialize them on attach (so when they get re-used they're clean)

Some examples of metadata used: ShouldBreak - We're expecting a non-signal related break ExitCode - The int() exit code (if exited) PendingSignal - The current signal

getMeta(self, name, default=None)

source code 

Get some metadata. Metadata is a clean way for arbitrary trace consumers (and notifiers) to present and track additional information in trace objects.

If you specify a default and the key doesn't exist, not not only will the default be returned, but the key will be set to the default specified.

hasMeta(self, name)

source code 

Check to see if a metadata key exists... Mostly un-necissary as getMeta() with a default will set the key to the default if non-existant.

setMode(self, name, value)

source code 

Set a mode setting... This is ONLY valid if that mode has been iniitialized with initMode(name, value). Otherwise, it's an unsupported mode for this platform ;) cute huh? This way, platform sections can cleanly setmodes and such.

injectso(self, filename)

source code 

Inject a shared object into the target of the trace.  So, on windows
this is easy with InjectDll and on *nix... it's.. fugly...

NOTE: This method will likely cause the trace to run.  Do not call from
      within a notifier!

ps(self)

source code 

Return a list of proccesses which are currently running on the system. (pid, name)

addBreakByExpr(self, symname, fastbreak=False)

source code 

Add a breakpoint by resolving an expression. This will create the Breakpoint object for you and add it to the trace. It returns the newly created breakpoint id.

Optionally, set fastbreak=True to have the breakpoint behave in "fast break" mode which automatically continues execution and does not fire notifiers for the breakpoint.

Example: trace.addBreakByExpr('kernel32.CreateFileA + ecx')

addBreakByAddr(self, va, fastbreak=False)

source code 

Add a breakpoint by address. This will create the Breakpoint object for you and add it to the trace. It returns the newly created breakpoint id.

Optionally, set fastbreak=True to have the breakpoint behave in "fast break" mode which automatically continues execution and does not fire notifiers for the breakpoint.

Example: trace.addBreakByAddr(0x7c770308)

addBreakpoint(self, breakpoint)

source code 

Add a breakpoint/watchpoint to the trace. The "breakpoint" argument is a vtrace Breakpoint/Watchpoint object or something that extends it.

To add a basic breakpoint use: trace.addBreakpoint(vtrace.Breakpoint(address))

NOTE: expression breakpoints do *not* get evaluated in fastbreak mode

This will return the internal ID given to the new breakpoint

getBreakpoint(self, id)

source code 

Return a reference to the breakpoint with the requested ID.

NOTE: NEVER set locals or use things like setBreakpointCode() method on return'd breakpoint objects as they may be remote and would then be *coppies* of the bp objects. (use the trace's setBreakpointCode() instead).

getBreakpointEnabled(self, bpid)

source code 

An accessor method for returning if a breakpoint is currently enabled. NOTE: code which wants to be remote-safe should use this

setBreakpointEnabled(self, bpid, enabled=True)

source code 

An accessor method for setting a breakpoint enabled/disabled.

NOTE: code which wants to be remote-safe should use this

setBreakpointCode(self, bpid, pystr)

source code 

Because breakpoints are potentially on the remote debugger and code is not pickleable in python, special access methods which takes strings of python code are necissary for the vdb interface to quick script breakpoint code. Use this method to set the python code for this breakpoint.

call(self, address, args, convention=None)

source code 

Setup the "stack" and call the target address with the following arguments. If the argument is a string or a buffer, copy that into memory and hand in the argument.

The current state of ALL registers are returned as a dictionary at the end of the call...

Additionally, a "convention" string may be specified that the underlying platform may be able to interpret...

registerNotifier(self, event, notifier)

source code 

Register a notifier who will be called for various events. See NOTIFY_* constants for handler hooks.

getFds(self)

source code 

Get a list of (fd, type, bestname) pairs. This is MOSTLY useful for HUMON consumtion... or giving HUMONs consumption...

getMemoryMaps(self)

source code 

Return a list of the currently mapped memory for the target process. This is acomplished by calling the platform's platformGetMaps() mixin method. This will also cache the results until CONTINUE. The format is (addr, len, perms, file).

getMemoryFault(self)

source code 

If the most receent event is a memory access error, this API will
return a tuple of (<addr>, <perm>) on supported platforms.  Otherwise,
a (None, None) will result.

Example:
import envi.memory as e_mem
vaddr, vperm = trace.getMemoryFault()
if vaddr != None:
    print 'Memory Fault At: 0x%.8x (perm: %d)' % (vaddr, vperm)

enableAutoContinue(self, event)

source code 

Put the tracer object in to AutoContinue mode for the specified event. To make all events continue running see RunForever mode in setMode().

parseExpression(self, expression)

source code 

Parse a python expression with many useful helpers mapped into the execution namespace.

Example: trace.parseExpression("ispoi(ecx+ntdll.RtlAllocateHeap)")

sendBreak(self)

source code 

Send an asynchronous break signal to the target process. This is only valid if the target is actually running...

getStackTrace(self)

source code 

Returns a list of (instruction pointer, stack frame) tuples. If stack tracing results in an error, the error entry will be (-1, -1). Otherwise most platforms end up with 0, 0 as the top stack frame

selectThread(self, threadid)

source code 

Set the "current thread" context to the given thread id. (For example stack traces and register values will depend on the current thread context). By default the thread responsible for an "interesting event" is selected.

suspendThread(self, threadid)

source code 

Suspend a thread by ID. This will mean that on continuing the trace, the suspended thread will not be scheduled.

injectThread(self, pc)

source code 

Create a new thread inside the target process. This thread will begin execution on the next process run().

getStructNames(self, namespace=None)

source code 

This method returns either the structure names, or
the structure namespaces that the target tracer is aware
of.  If "namespace" is specified, it is structures within
that namespace, otherwise it is "known namespaces"

Example: namespaces = trace.getStructNames()
         ntdll_structs = trace.getStructNames(namespace='ntdll')

getStruct(self, sname, va=None)

source code 

Retrieve a vstruct structure optionally populated with memory from the specified address. Returns a standard vstruct object.

setVariable(self, name, value)

source code 

Set a named variable in the trace which may be used in subsequent VtraceExpressions.

Example: trace.setVariable("whereiam", trace.getProgramCounter())

getVariable(self, name)

source code 

Get the value of a previously set variable name. (or None on not found)

buildNewTrace(self)

source code 

Build a new/clean trace "like" this one.  For platforms where a
special trace was handed in, this allows initialization of a new one.
For most implementations, this is very simple....

Example:
    if need_another_trace:
        newt = trace.buildNewTrace()