vtrace Package

vtrace Package

Vtrace Debugger Framework

Vtrace is a mostly native python debugging framework which can be used to quickly write programatic debuggers and research tools.

I’m not known for writting great docs... but the code should be pretty straight forward...

This has been in use for many years privately, but is nowhere near free of bugs... idiosyncracies abound.

==== Werd =====================================================

Blah blah blah... many more docs to come.

Brought to you by kenshoto. e-mail invisigoth.

Greetz:

h1kari - eeeeeooorrrmmm CHKCHKCHKCHKCHKCHKCHK Ghetto - wizoo... to the tizoot. atlas - whew finally... no more teasing... beatle/dnm - come out and play yo! The Kenshoto Gophers. Blackhats Everywhere.

exception vtrace.AccessViolation(va, perm=0)

Bases: exceptions.Exception

An exception which is raised on bad-touch to memory

exception vtrace.PlatformException

Bases: exceptions.Exception

A universal way to represent a failure in the platform layer for this tracer. platformFoo methods should raise this rather than allowing their platform specific exception types (which don’t likely pickle, or are not cross platform)

class vtrace.Trace(archname=None)

Bases: envi.memory.IMemory, envi.registers.RegisterContext, envi.resolver.SymbolResolver, object

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.

addBreakByAddr(va, fastbreak=False)

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)

addBreakByExpr(symname, fastbreak=False)

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

addBreakpoint(breakpoint)

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

addIgnoreSignal(code, address=0)

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.

allocateMemory(size, perms=7, suggestaddr=0)

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.

attach(pid)

Attach to a new process ID.

buildNewTrace()

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

call(address, args, convention=None)

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

delIgnoreSignal(code, address=0)

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

deregisterNotifier(event, notifier)

detach()

Detach from the currently attached process.

disableAutoContinue(event)

Disable Auto Continue for the specified event.

enableAutoContinue(event)

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

execute(cmdline)

Start a new process and debug it

getAutoContinueList()

Retrieve the list of vtrace notification events that will be auto-continued.

getBreakpoint(id)

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

getBreakpointByAddr(va)

Return the breakpoint object (or None) for a given virtual address.

getBreakpointCode(bpid)

Return the python string of user specified code that will run when this breakpoint is hit.

getBreakpointEnabled(bpid)

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

getBreakpoints()

Return a list of the current breakpoints.

getCurrentBreakpoint()

Return the current breakpoint otherwise None

getCurrentSignal()

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

getCurrentThread()

Return the thread id of the currently selected thread.

getFds()

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

getMemoryFault()

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)

getMemoryMaps()

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

getMeta(name, default=None)

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.

getMode(name, default=False)

Get the value for a mode setting allowing for a clean default...

getNormalizedLibNames()

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

getNotifiers(event)

getPid()

Return the pid for this Trace

getRegister(idx)

getRegisterContext(threadid=None)

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.

getStackTrace()

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

getStruct(sname, address)

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

getStructNames(namespace=None)

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

getSymByAddr(addr, exact=True)

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

getSymByName(name)

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

getSymsForFile(libname)

Return the entire symbol list for the specified normalized library name.

getThreads()

Get a dictionary of <threadid>:<tinfo> pairs where tinfo is platform dependant, but is tyically either the top of the stack for that thread, or the TEB on win32

getVariable(name)

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

getVariables()

Get the dictionary of named variables.

hasMeta(name)

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.

hex(value)

Much like the python hex routine, except this will automatically pad the value’s string length out to pointer width.

injectThread(pc)

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

injectso(filename)

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!

isAttached()

Return boolean true/false for weather or not this trace is currently attached to a process.

isRemote()

Returns True if the trace is a CobraProxy object to a trace on another system

isRunning()

Return true or false if this trace’s target process is “running”.

isThreadSuspended(threadid)

Used to determine if a thread is suspended.

joinThread(threadid)

Run the trace in a loop until the specified thread exits.

kill()

Kill the target process for this trace (will result in process exit and fire appropriate notifiers)

parseExpression(expression)

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

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

protectMemory(va, size, perms)

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

ps()

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

readMemory(address, size)

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

registerNotifier(event, notifier)

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

release()

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

removeBreakpoint(id)

Remove the breakpoint with the specified ID

requireAttached()

A utility method for other methods to use in order to require being attached

requireNotExited()

requireNotRunning()

Just a quick method to throw an error if the tracer is already running...

resumeThread(threadid)

Resume a suspended thread.

run(until=None)

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

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

searchMemory(needle, regex=False)

Search all of process memory for a sequence of bytes.

searchMemoryRange(needle, address, size, regex=False)

Search a memory range for the specified sequence of bytes

searchSymbols(regex, libname=None)

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

selectThread(threadid)

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.

sendBreak()

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

setBreakpointCode(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. Use this method to set the python code for this breakpoint.

setBreakpointEnabled(bpid, enabled=True)

An accessor method for setting a breakpoint enabled/disabled.

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

setCurrentSignal(sig=None)

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)

setMeta(name, value)

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

setMode(name, value)

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.

setRegister(idx, value)

setVariable(name, value)

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

Example: trace.setVariable(“whereiam”, trace.getProgramCounter())

stepi()

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

suspendThread(threadid)

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

writeMemory(address, bytes)

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

class vtrace.TraceGroup

Bases: vtrace.notifiers.Notifier, vtrace.util.TraceManager

Encapsulate several traces, run them, and continue to handle their event notifications.

addTrace(proc)

Add a new tracer to this group the “proc” argument may be either an long() for a pid (which we will attach to) or an already attached (and broken) tracer object.

delTrace(pid)

Remove a trace from the current TraceGroup

detachAll()

Detach from ALL the currently targetd processes

execTrace(cmdline)

getTrace()

Similar to vtrace.getTrace(), but also init’s the trace for being managed by a TraceGroup.

Example:

tg = TraceGroup() t = tg.getTrace() t....

getTraceByPid(pid)

Return the the trace for process PID if we’re already attached. Return None if not.

getTraces()

Return a list of the current traces

notify(event, trace)

run()

Our run method is a little different than a traditional trace. It will never block.

setMeta(name, value)

A trace group’s setMeta function will set “persistant” metadata which will be added again to any trace on attach. Additionally, setting metadata on a tracegroup will cause all current traces to get the update as well....

setMode(name, value)

class vtrace.VtraceExpressionLocals(trace)

Bases: envi.expression.MemoryExpressionLocals

A class which serves as the namespace dictionary during the evaluation of an expression on a tracer.

bp(bpid)

The expression bp(0) returns the resolved address of the given breakpoint

frame(index)

Return the address of the saved base pointer for the specified frame.

Usage: frame(<index>)

go()

A shortcut for trace.runAgain() which may be used in breakpoint code (or similar even processors) to begin execution again after event processing...

meta(name)

An expression friendly (terse) way to get trace metadata (equiv to trace.getMeta(name))

Example: meta(“foo”)

teb(threadnum=None)

The expression teb(threadid) will return whatever the platform stores as the int for threadid. In the case of windows, this is the TEB, others may be the thread stack base or whatever. If threadid is left out, it uses the threadid of the current thread context.

vtrace.getTrace(plat=None, **kwargs)

Return a tracer object appropriate for this platform. This is the function you will use to get a tracer object with the appropriate ancestry for your host. ex. mytrace = vtrace.getTrace()

NOTE: Use the release() method on the tracer once debugging

is complete. This releases the tracer thread and allows garbage collection to function correctly.

Some specialized tracers may be constructed by specifying the “plat” name from one of the following list. Additionally, each “specialized” tracer may require additional kwargs (which are listed).

android - Debug android apps through adb (adb must be in your path)

avd=<name> (None will let adb decide)

vmware32 - Debug a 32bit VMWare target.

host=<host> - Where is the gdb server listening? (default 127.0.0.1) port=<port> - What port (default: 8832) os=<osname> - On of “Windows”, “Linux” (that’s all we support now...)

vmware64 - Debug a 64bit VMWare target.

host=<host> - Where is the gdb server listening? (default 127.0.0.1) port=<port> - What port (default: 8864) os=<osname> - On of “Windows”, “Linux” (that’s all we support now...)

Examples:

t = vtrace.getTrace() # A tracer for this os

t = vtrace.getTrace(plat=’android’) # The default ADB device

t = vtrace.getTrace(plat=’vmware32’, host=’localhost’, port=31337)

vtrace.interact(pid=0, server=None, trace=None)

Just a cute and dirty way to get a tracer attached to a pid and get a python interpreter instance out of it.

audit Module

Test for platform functionality (for internal use).

vtrace.audit.auditTracer(trace)

Print out a list of platform requirements and weather a particular tracer meets them. This is mostly a development tool to determin what’s left to do on a tracer implementation.

breakpoints Module

Breakpoint Objects

class vtrace.breakpoints.Breakpoint(address, expression=None)

Breakpoints in Vtrace are platform independant objects that use the underlying trace objects to get things like the program counter and the break instruction. As long as platfforms are completely implemented, all breakpoint objects should be portable.

activate(trace)

Actually store off and replace memory for this process. This is caried out by the trace object itself when it begins running or stops. You probably never need to call this (see isEnabled() setEnabled() for boolean enable/disablle)

bpcodeobj = {}

deactivate(trace)

Repair the process for continued execution. this does NOT make a breakpoint inactive, but removes it’s “0xcc” from mem (see isEnabled() setEnabled() for boolean enable/dissable)

getAddress()

This will return the address for this breakpoint. If the return’d address is None, this is a deferred breakpoint which needs to have resolveAddress() called to attempt to set the address.

getBreakpointCode()

Return the current python string that will be run when this break is hit.

getId()

getName()

inittrace(trace)

A callback to do housekeeping at the time the breakpoint is added to the tracer object. This should be used instead of activate for initialization time infoz to save on time per activate call...

isEnabled()

Is this breakpoint “enabled”?

notify(event, trace)

Breakpoints may also extend and implement “notify” which will be called whenever they are hit. If you want to continue the ability for this breakpoint to have bpcode, you must call this method from your override.

resolveAddress(trace)

Try to resolve the address for this break. If this is a statically addressed break, just return the address. If it has an “expression” use that to resolve the address...

resolvedaddr(trace, addr)

An initialization callback which will be executed when the actual address for this breakpoint has been resolved.

setBreakpointCode(pystr)

Use this method to set custom python code to run when this breakpoint gets hit. The code will have the following objects mapped into it’s namespace when run:

trace - the tracer vtrace - the vtrace module bp - the breakpoint

setEnabled(enabled=True)

Set this breakpoints “enabled” status

class vtrace.breakpoints.CallBreak(address, saved_regs)

Bases: vtrace.breakpoints.Breakpoint

A special breakpoint which will restore process state (registers in particular) when it gets hit. This is primarily used by the call method inside the trace object to restore original state after a successful “call” method call.

Additionally, the endregs dict will be filled in with the regs at the time it was hit and kept until we get garbage collected...

notify(event, trace)

class vtrace.breakpoints.OneTimeBreak(address, expression=None)

Bases: vtrace.breakpoints.Breakpoint

This type of breakpoint is exclusivly for marking and code-coverage stuff. It removes itself. (most frequently used with a continued trace)

notify(event, trace)

class vtrace.breakpoints.SnapshotBreak(address, expression=None)

Bases: vtrace.breakpoints.Breakpoint

A special breakpoint type which will produce vtrace snapshots for the target process when hit. The snapshots will be saved to a default name of <exename>-<timestamp>.vsnap. This is not recommended for use in heavily hit breakpoints as taking a snapshot is processor intensive.

notify(event, trace)

class vtrace.breakpoints.StopAndRemoveBreak(address, expression=None)

Bases: vtrace.breakpoints.Breakpoint

When hit, take the tracer out of run-forever mode and remove this breakpoint.

notify(event, trace)

class vtrace.breakpoints.StopRunForeverBreak(address, expression=None)

Bases: vtrace.breakpoints.Breakpoint

This breakpoint will turn off RunForever mode on the tracer object when hit. it’s a good way to let things run on and on processing exceptions but stop when you get to this one thing.

notify(event, trace)

class vtrace.breakpoints.TrackerBreak(address, expression=None)

Bases: vtrace.breakpoints.Breakpoint

A breakpoint which will record how many times it was hit (by the address it was at) as metadata for the tracer.

notify(event, trace)

envitools Module

Some tools that require the envi framework to be installed

exception vtrace.envitools.RegisterException

Bases: exceptions.Exception

class vtrace.envitools.TraceEmulator(emu)

Bases: vtrace.Trace, vtrace.platforms.base.TracerBase

Wrap an arbitrary emulator in a Tracer compatible API.

archGetRegCtx()

getPointerSize()

getStackTrace()

platformDetach()

platformGetFds()

platformGetMaps()

platformGetRegCtx(threadid)

platformGetThreads()

platformProcessEvent(event)

platformReadMemory(va, size)

platformSetRegCtx(threadid, ctx)

platformStepi()

platformWait()

platformWriteMemory(va, bytes)

vtrace.envitools.cmpRegs(emu, trace)

vtrace.envitools.emulatorFromTrace(trace)

Produce an envi emulator for this tracer object. Use the trace’s arch info to get the emulator so this can be done on the client side of a remote vtrace session.

vtrace.envitools.lockStepEmulator(emu, trace)

vtrace.envitools.main()

vtrace.envitools.setRegs(emu, trace)

notifiers Module

Vtrace notitifers base classes and examples

Vtrace supports the idea of callback notifiers which get called whenever particular events occur in the target process. Notifiers may be registered to recieve a callback on any of the vtrace.NOTIFY_FOO events from vtrace. One notifier may be registered with more than one trace, as the “notify” method is passed a reference to the trace for which an event has occured...

class vtrace.notifiers.DistributedNotifier

Bases: vtrace.notifiers.Notifier

A notifier which will distributed notifications out to locally registered notifiers so that remote tracer’s notifier callbacks only require once across the wire.

deregisterNotifier(event, notif)

fireNotifiers(event, trace)

Fire all our registerd local-notifiers

getProxy(trace)

notify(event, trace)

registerNotifier(event, notif)

Register a sub-notifier to get the remote callback’s via our local delivery.

class vtrace.notifiers.Notifier

Bases: object

The top level example notifier... Anything which registers itself for trace events or tracegroup events should implement the notify method as shown here.

handleEvent(event, trace)

An “internal” handler so if we need to do something from an API perspective before calling the notify method we can have a good “all at once” hook

notify(event, trace)

class vtrace.notifiers.VerboseNotifier

Bases: vtrace.notifiers.Notifier

notify(event, trace)

qt Module

QtGui objects which assist in GUIs which use vtrace parts.

class vtrace.qt.FileDescModel(parent=None, columns=None)

Bases: vqt.tree.VQTreeModel

columns = ('Fd', 'Type', 'Name')

class vtrace.qt.RegColorDelegate(parent)

Bases: PyQt4.QtGui.QStyledItemDelegate

paint(painter, option, index)

class vtrace.qt.VQFileDescView(trace, parent=None)

Bases: vqt.tree.VQTreeView, vtrace.qt.VQTraceNotifier

vqLoad()

class vtrace.qt.VQMemoryMapView(trace, parent=None)

Bases: envi.qt.VQMemoryMapView, vtrace.qt.VQTraceNotifier

A memory map view which is sensitive to the status of a trace object.

vqLoad()

class vtrace.qt.VQProcessListModel(parent=None, columns=None)

Bases: vqt.tree.VQTreeModel

columns = ('Pid', 'Name')

class vtrace.qt.VQProcessListView(trace=None, parent=None)

Bases: vqt.tree.VQTreeView

class vtrace.qt.VQProcessSelectDialog(trace=None, parent=None)

Bases: PyQt4.QtGui.QDialog

dialog_activated(idx)

dialog_cancel()

dialog_ok()

class vtrace.qt.VQRegisterListModel(parent=None, columns=None)

Bases: vqt.tree.VQTreeModel

columns = ('Name', 'Hex', 'Dec')

class vtrace.qt.VQRegistersListView(trace=None, parent=None)

Bases: vqt.tree.VQTreeView, vtrace.qt.VQTraceNotifier

A pure “list view” object for registers

vqLoad()

class vtrace.qt.VQRegistersView(trace=None, parent=None)

Bases: PyQt4.QtGui.QWidget

A register view which includes the idea of “sub views” for particular sets of registers per-architecture.

regViewNameSelected(name)

class vtrace.qt.VQThreadListModel(parent=None, columns=None)

Bases: vqt.tree.VQTreeModel

columns = ('Thread Id', 'Thread Info', 'State')

class vtrace.qt.VQThreadsView(trace=None, parent=None, selectthread=None)

Bases: vqt.tree.VQTreeView, vtrace.qt.VQTraceNotifier

selectionChanged(selected, deselected)

vqLoad()

class vtrace.qt.VQTraceNotifier(trace=None)

Bases: vtrace.notifiers.Notifier

A bit of shared mixin code for the handling of vtrace notifier callbacks in various VQTreeViews...

notify(*args, **kwargs)

class vtrace.qt.VQTraceToolBar(trace, parent=None)

Bases: PyQt4.QtGui.QToolBar, vtrace.notifiers.Notifier

actAttach(*args, **kwargs)

actBreak(thing)

actContinue(thing)

actDetach(thing)

actStepi(thing)

notify(event, trace)

rmi Module

Cobra integration for remote debugging

class vtrace.rmi.RemoteTrace(*args, **kwargs)

Bases: cobra.CobraProxy

buildNewTrace()

isRemote()

release()

class vtrace.rmi.TraceProxyFactory

A “factory” object for creating tracers and wrapping them up in a proxy instance to the local server. This object is shared out via the pyro server for vtrace clients.

getTrace()

releaseTrace(proxy)

When a remote system is done with a trace and wants the server to clean him up, hand the proxy object to this.

vtrace.rmi.getCallbackPort()

If necissary, start a callback daemon. Return the ephemeral port it was bound on.

vtrace.rmi.getCallbackProxy(trace, notifier)

Get a proxy object to reference notifier from the perspective of trace. The trace is specified so we may check on our side of the connected socket to give him the best possible ip address...

vtrace.rmi.getRemoteTrace()

vtrace.rmi.getTracerFactory()

Return a TracerFactory proxy object from the remote server

vtrace.rmi.releaseRemoteTrace(proxy)

vtrace.rmi.startCobraDaemon()

vtrace.rmi.startVtraceServer()

Fire up the pyro server and share out our “trace factory”

snapshot Module

All the code related to vtrace process snapshots and TraceSnapshot classes.

class vtrace.snapshot.TraceSnapshot(snapdict)

Bases: vtrace.Trace, vtrace.platforms.base.TracerBase

A tracer snapshot is similar to a traditional “core file” except that you may also have memory only snapshots that are never written to disk.

TraceSnapshots allow you to take a picture of a process from a given point in it’s execution and manipulate/test from there or save it to disk for later analysis...

cacheRegs(threadid)

getExe()

getMemoryMap(addr)

getStackTrace()

platformDetach()

platformGetFds()

platformGetMaps()

platformGetRegCtx(thrid)

platformGetThreads()

platformParseBinary(*args)

platformReadMemory(address, size)

platformWriteMemory(address, bytes)

saveToFd(fd)

Save this snapshot to the given file like object for later reloading...

saveToFile(filename)

Save a snapshot to file for later reading in...

syncRegs()

vtrace.snapshot.loadSnapshot(filename)

Load a vtrace process snapshot from a file

vtrace.snapshot.takeSnapshot(trace)

Take a snapshot of the process from the current state and return a reference to a tracer which wraps a “snapshot” or “core file”.

util Module

Extra utilities for vtrace

class vtrace.util.TraceManager(trace=None)

A trace-manager is a utility class to extend from when you may be dealing with multiple tracer objects. It allows for persistant mode settings and persistent metadata as well as bundling a DistributedNotifier. You may also extend from this to get auto-magic remote stuff for your managed traces.

deregisterNotifier(event, notif)

fireLocalNotifiers(event, trace)

Deliver a local event to the DistributedNotifier managing the traces. (used to locally bump notifiers)

getMeta(name, default=None)

getMode(name, default=False)

manageTrace(trace)

Set all the modes/meta/notifiers in this trace for management by this TraceManager.

registerNotifier(event, notif)

setMeta(name, value)

setMode(name, value)

unManageTrace(trace)

Untie this trace manager from the trace.

watchpoints Module

Watchpoint Objects

class vtrace.watchpoints.PageWatchpoint(addr, expression=None, size=4, watchread=False)

Bases: vtrace.watchpoints.Watchpoint

A special “watchpoint” that uses memory permissions to watch for accesses to whole memory maps. This requires OS help and only works on platforms which support: * platformProtectMemory() * signal/exceptions which denote the fault address on SEGV

NOTE: These must be added page aligned

activate(trace)

deactivate(trace)

getName()

notify(event, trace)

resolvedaddr(trace, addr)

class vtrace.watchpoints.Watchpoint(addr, expression=None, size=4, perms='rw')

Bases: vtrace.breakpoints.Breakpoint

The basic “break on access” watchpoint. Extended from Breakpoints and handled almost exactly the same way...

activate(trace)

deactivate(trace)

getName()

inittrace(trace)

resolvedaddr(trace, addr)

Submodules

• archs Package
  • archs Package
  • amd64 Module
  • arm Module
  • i386 Module
  • ppc Module
• platforms Package
  • platforms Package
  • android Module
  • base Module
  • freebsd Module
  • gdbstub Module
  • linux Module
  • posix Module
  • solaris Module
  • vmware Module
  • win32 Module
  • Submodules
    • darwin Package
      • darwin Package
• tools Package
  • tools Package
  • iathook Module
  • win32alloc Module
  • win32aslr Module
  • win32heap Module
  • win32stealth Module