Class Trace

Hand in a register definition which consists of a list of (<name>, <width>) tuples.

Overrides: object.__init__

(inherited documentation)

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)

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')

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

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.

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.

Overrides: envi.memory.IMemory.allocateMemory

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()

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

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

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

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

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

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()

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

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)

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

Overrides: envi.memory.IMemory.getMemoryMaps

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.

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

Return the current value of the specified register index.

Overrides: envi.registers.RegisterContext.getRegister

(inherited documentation)

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.

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

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

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')

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

Overrides: envi.resolver.SymbolResolver.getSymByAddr

Return an envi.Symbol object for the given name (or None)

Overrides: envi.resolver.SymbolResolver.getSymByName

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

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.

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

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!

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

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

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

Overrides: envi.memory.IMemory.protectMemory

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

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

Overrides: envi.memory.IMemory.readMemory

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

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

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

Search all of process memory for a sequence of bytes.

Overrides: envi.memory.IMemory.searchMemory

Search a memory range for the specified sequence of bytes

Overrides: envi.memory.IMemory.searchMemoryRange

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'):

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.

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

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.

An accessor method for setting a breakpoint enabled/disabled.

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

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)

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

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.

Set a register value by index.

Overrides: envi.registers.RegisterContext.setRegister

(inherited documentation)

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

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

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/supress notifier callbacks on step

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

Write the given bytes to the address in the current trace.

Overrides: envi.memory.IMemory.writeMemory