Package vivisect :: Class VivWorkspace
[hide private]
[frames] | no frames]

Class VivWorkspace

source code


Instance Methods [hide private]
 
__init__(self)
Take a set of memory maps (va, perms, fname, bytes) and put them in a sparse space finder.
source code
 
verbprint(self, msg) source code
 
vprint(self, msg) source code
 
getVivGui(self)
Return a reference to the vivisect GUI object for this workspace.
source code
 
loadWorkspace(self, wsname) source code
 
addFref(self, fva, va, idx, val)
Add a reference from the operand at virtual address 'va' index 'idx' to a function local offset.
source code
 
getFref(self, va, idx)
Get back the fref value (or None) for the given operand index from the instruction at va.
source code
 
getEmulator(self, logwrite=False, logread=False)
Get an instance of a WorkspaceEmulator for this workspace.
source code
 
addLibraryDependancy(self, libname)
Add a *normalized* library name to the import search chain for this binary.
source code
 
getLibraryDependancies(self)
Retrieve the list of *normalized* library dependancies.
source code
 
setComment(self, va, comment, check=False)
Set the humon readable comment for a given virtual.
source code
 
getComment(self, va)
Returns the comment string (or None) for a given virtual address.
source code
 
getComments(self)
Retrieve all the comments in the viv workspace as (va, cmnt) tuples.
source code
 
addRelocation(self, va, rtype)
Add a relocation entry for tracking.
source code
 
getRelocations(self)
Get the current list of relocation entries.
source code
 
getRelocation(self, va)
Return the type of relocation at the specified VA or None if there isn't a relocation entry for the address.
source code
 
pointerString(self, va) source code
 
getAnalysisModuleNames(self) source code
 
getFuncAnalysisModuleNames(self) source code
 
addFunctionSignatureBytes(self, bytes, mask=None)
Add a function signature entry by bytes.
source code
 
isFunctionSignature(self, va)
Check if the specified va is a function entry signature according to the current entry point signature tree...
source code
 
addNoReturnApi(self, funcname)
Inform vivisect code-flow disassembly that any call target which matches the specified name ("funcname" or "libname.funcname" for imports) does *not* exit and code-flow should be stopped...
source code
 
addAnalysisModule(self, modname)
Add an analysis module by python import path
source code
 
delAnalysisModule(self, modname)
Remove an analysis module from the list used during analysis()
source code
 
loadModule(self, modname) source code
 
addFuncAnalysisModule(self, modname)
Snap in a per-function analysis module (by name) which will be triggered during the creation of a new function (makeFunction).
source code
 
delFuncAnalysisModule(self, modname)
Remove a currently registered function analysis module.
source code
 
createEventChannel(self) source code
 
importWorkspace(self, wsevents)
Import and initialize data from the given vivisect workspace export.
source code
 
exportWorkspace(self)
Return the (probably big) list of events which define this workspace.
source code
 
exportWorkspaceChanges(self)
Export the list of events which have been applied to the workspace since the last save.
source code
 
initWorkspaceClient(self, remotevw)
Initialize this workspace as a workspace client to the given (potentially cobra remote) workspace object.
source code
 
_clientThread(self)
The thread that monitors events on a server to stay in sync.
source code
 
waitForEvent(self, chanid, timeout=None)
Return an event,eventinfo tuple.
source code
 
deleteEventChannel(self, chanid)
Remove a previously allocated event channel from the workspace.
source code
 
reprVa(self, va)
A quick way for scripts to get a string for a given virtual address.
source code
 
reprLocation(self, loctup) source code
 
followPointer(self, va)
Do pointer analysis and folllow up the recomendation by creating locations etc...
source code
 
analyze(self)
Call this to ask any available analysis modules to do their thing...
source code
 
getImports(self)
Return a list of imports in location tuple format.
source code
 
makeImport(self, va, libname, impname)
Add an import entry.
source code
 
getExports(self)
Return a list of exports in (va,etype,name,filename) tuples.
source code
 
addExport(self, va, etype, name, filename)
Add an already created export object.
source code
 
getExport(self, va)
Get a reference to the export object at the given va (or none).
source code
 
findPointers(self, cache=True)
Search through all currently "undefined" space and see if you can find pointers there...
source code
 
isProbablyString(self, va) source code
 
isProbablyUnicode(self, va)
This will return true if the memory location is likely *simple* UTF16-LE unicode (<ascii><0><ascii><0><0><0>).
source code
 
isProbablyCode(self, va)
Most of the time, absolute pointes which point to code point to the function entry, so test it for the sig.
source code
 
parseOpcode(self, va, arch=envi.ARCH_DEFAULT)
Parse an opcode from the specified virtual address.
source code
 
makeOpcode(self, va, op=None, arch=envi.ARCH_DEFAULT)
Create a single opcode location.
source code
 
makeCode(self, va, arch=envi.ARCH_DEFAULT)
Attempt to begin code-flow based disassembly by starting at the given va.
source code
 
isFunction(self, funcva)
Return True if funcva is a function entry point.
source code
 
getFunctions(self)
Return a list of the function virtual addresses defined in the workspace.
source code
 
getFunction(self, va)
Return the VA for this function.
source code
 
makeFunction(self, va, meta=None, arch=envi.ARCH_DEFAULT)
Do parsing for function information and add a new function doodad.
source code
 
delFunction(self, funcva)
Remove a function, it's code blocks and all associated meta
source code
 
setFunctionArg(self, fva, idx, atype, aname)
Set the name and type information for a single function arguemnt by index.
source code
 
getFunctionArgs(self, fva)
Returns the list of (typename,argname) tuples which define the arguments for the specified function.
source code
 
getFunctionApi(self, fva)
Retrieve the API definition for the given function address.
source code
 
setFunctionApi(self, fva, apidef)
Set a function's API definition.
source code
 
getFunctionLocals(self, fva)
Retrieve the list of (fva,spdelta,symtype,syminfo) tuples which represent the given function's local memory offsets.
source code
 
getFunctionLocal(self, fva, spdelta)
Retrieve a function local symbol definition as a (typename,symname) tuple or None if not found.
source code
 
setFunctionLocal(self, fva, spdelta, symtype, syminfo)
Assign a local symbol within a function (addressed by delta from initial sp).
source code
 
setFunctionMeta(self, funcva, key, value)
Set meta key,value pairs that describe a particular function (by funcva).
source code
 
getFunctionMeta(self, funcva, key, default=None) source code
 
getFunctionMetaDict(self, funcva)
Return the entire dictionary of function metadata for the function specified at funcva
source code
 
getFunctionBlocks(self, funcva)
Return the code-block objects for the given function va
source code
 
makeFunctionThunk(self, fva, thname)
Inform the workspace that a given function is considered a "thunk" to another.
source code
 
getCallers(self, va)
Get the va for all the callers of the given function/import.
source code
 
getCallGraph(self)
Retrieve a visgraph Graph object representing all known inter procedural branches in the workspace.
source code
 
getImportCallers(self, name)
Get a list of all the callers who reference the specified import by name.
source code
 
getXrefs(self)
Return the entire list of XREF tuples for this workspace.
source code
 
getXrefsFrom(self, va, rtype=None)
Return a list of tuples for the xrefs whose origin is the specified va.
source code
 
getXrefsTo(self, va, rtype=None)
Get a list of xrefs which point to the given va.
source code
 
addMemoryMap(self, va, perms, fname, bytes)
Add a memory map to the workspace.
source code
 
delMemoryMap(self, va) source code
 
addSegment(self, va, size, name, filename)
Add a "segment" to the workspace.
source code
 
getSegment(self, va)
Return the tuple representation of a segment.
source code
 
getSegments(self)
Return a list of segment tuples (see getSegment) for all the segments defined in the current worksace
source code
 
addCodeBlock(self, va, size, funcva)
Add a region of code which belongs to a function.
source code
 
getCodeBlock(self, va)
Return the codeblock which contains the given va.
source code
 
delCodeBlock(self, va)
Remove a code-block definition from the codeblock namespace.
source code
 
getCodeBlocks(self)
Return a list of all the codeblock objects.
source code
 
addXref(self, fromva, tova, reftype, rflags=0)
Add an xref with the specified fromva, tova, and reftype (see REF_ macros).
source code
 
delXref(self, ref)
Remove the given xref.
source code
 
analyzePointer(self, va)
Assume that a new pointer has been created.
source code
 
getMeta(self, name, default=None) source code
 
setMeta(self, name, value)
Set a meta key,value pair for this workspace.
source code
 
initMeta(self, name, value)
Set a metakey ONLY if it is not already set.
source code
 
getTransMeta(self, mname, default=None)
Retrieve a piece of "transient" metadata which is *not* stored across runs or pushed through the event subsystem.
source code
 
setTransMeta(self, mname, value)
Store a piece of "transient" metadata which is *not* stored across runs or pushed through the event subsystem.
source code
 
castPointer(self, va)
Return the value for a pointer in memory at the given location.
source code
 
makePointer(self, va, tova=None, follow=True)
Create a new pointer location in the workspace.
source code
 
makePad(self, va, size)
A special utility for making a pad of a particular size.
source code
 
makeNumber(self, va, size, val=None)
Create a number location in memory of the given size.
source code
 
parseNumber(self, va, size)
Parse a <size> width numeric value from memory at <va>.
source code
 
makeString(self, va, size=None)
Create a new string location at the given VA.
source code
 
makeUnicode(self, va, size=None) source code
 
addConstModule(self, modname)
Add constants declared within the named module to the constants resolver namespace.
source code
 
addStructureModule(self, namespace, modname)
Add a vstruct structure module to the workspace with the given namespace.
source code
 
getStructure(self, va, vstructname)
Parse and return a vstruct object for the given name.
source code
 
makeStructure(self, va, vstructname, vs=None)
Make a location which is a structure and will be parsed/accessed by vstruct.
source code
 
getUserStructNames(self)
Retrive the list of the existing user-defined structure names.
source code
 
getUserStructSource(self, sname)
Get the source code (as a string) for the given user defined structure.
source code
 
setUserStructSource(self, ssrc)
Save the input string as a C structure definition for the workspace.
source code
 
asciiStringSize(self, va)
Return the size (in bytes) of the ascii string at the specified location (or -1 if no terminator is found in the memory map)
source code
 
uniStringSize(self, va)
Return the size (in bytes) of the unicode string at the specified location (or -1 if no terminator is found in the memory map)
source code
 
addLocation(self, va, size, ltype, tinfo=None)
Add a location tuple.
source code
 
getLocations(self, ltype=None, linfo=None)
Return a list of location objects from the workspace of a particular type.
source code
 
isLocation(self, va, range=False)
Return True if the va represents a location already.
source code
 
isLocType(self, va, ltype)
You may use this to test if a given VA represents a location of the specified type.
source code
 
getLocation(self, va, range=False)
Return the va,size,ltype,tinfo tuple for the given location.
source code
 
getLocationRange(self, va, size)
A "location range" is a list of location tuples where undefined space *will* be represented by LOC_UNDEF tuples to provide a complete accounting of linear workspace.
source code
 
delLocation(self, va)
Delete the given Location object from the binary (removes any xrefs/etc for the location as well)
source code
 
getRenderInfo(self, va, size)
Get nearly everything needed to render a workspace area to a display.
source code
 
getPrevLocation(self, va, adjacent=True)
Get the previous location behind this one.
source code
 
vaByName(self, name) source code
 
getLocationByName(self, name)
Return a location object by the name of the location.
source code
 
getNames(self)
Return a list of tuples containing (va, name)
source code
 
getName(self, va)
Returns the name of the specified virtual address (or None).
source code
 
makeName(self, va, name, filelocal=False)
Set a readable name for the given location by va.
source code
 
saveWorkspace(self, fullsave=True) source code
 
loadFromFd(self, fd, fmtname=None)
Read the first bytes of the file descriptor and see if we can identify the type.
source code
 
_saveSymbolCaches(self) source code
 
loadFromFile(self, filename, fmtname=None)
Read the first bytes of the file and see if we can identify the type.
source code
 
loadFromMemory(self, memobj, baseaddr, fmtname=None)
Load a memory map (or potentially a mapped binary file) from the memory object's map at baseaddr.
source code
 
getFiles(self)
Return the current list of file objects in this workspace.
source code
 
normFileName(self, filename) source code
 
addFile(self, filename, imagebase, md5sum)
Create and add a new vivisect File object for the specified information.
source code
 
addEntryPoint(self, va)
Add an entry point to the definition for the given file.
source code
 
getEntryPoints(self)
Get all the parsed entry points for all the files loaded into the workspace.
source code
 
setFileMeta(self, fname, key, value)
Store a piece of file specific metadata (python primatives are best for values)
source code
 
getFileMeta(self, filename, key, default=None)
Retrieve a piece of file specific metadata
source code
 
getFileMetaDict(self, filename)
Retrieve the file metadata for this file as a key:val dict.
source code
 
getFileByVa(self, va) source code
 
getLocationDistribution(self) source code
 
getVaSetNames(self)
Get a list of the names of the current VA lists.
source code
 
getVaSetDef(self, name)
Get the list of (name, type) pairs which make up the rows for this given VA set (the first one *always* the VA, but you can name it as you like...)
source code
 
getVaSetRows(self, name)
Get a list of the rows in this VA set.
source code
 
getVaSet(self, name)
Get the dictionary of va:<rowdata> entries.
source code
 
addVaSet(self, name, defs, rows=())
Add a va set:
source code
 
delVaSet(self, name)
Delete a VA set by name.
source code
 
setVaSetRow(self, name, rowtup)
Use this API to update the row data for a particular entry in the VA set.
source code
 
getVaSetRow(self, name, va)
Retrieve the va set row for va in the va set named name.
source code
 
delVaSetRow(self, name, va)
Use this API to delete the rowdata associated with the specified VA from the set.
source code
 
chat(self, msg) source code
 
iAmLeader(self, winname)
Announce that your workspace is leading a window with the specified name.
source code
 
followTheLeader(self, winname, expr)
Announce a new memory expression to navigate to if if a given window is following the specified user/winname
source code
 
getColorMaps(self)
Return a list of the names of the given color maps
source code
 
addColorMap(self, mapname, colormap)
Add a colormap dictionary with the given name for the map.
source code
 
delColorMap(self, mapname) source code
 
getColorMap(self, mapname)
Return the colormap dictionary for the given map name.
source code
 
getSymByName(self, name) source code
 
getSymByAddr(self, addr, exact=True) source code
 
setSymHint(self, va, idx, hint)
Set a symbol hint which will be used in place of operand values during disassembly among other things...
source code
 
getSymHint(self, va, idx) source code

Inherited from envi.memory.MemoryObject: getByteDef, getMemoryMap, getMemoryMaps, getMemorySnap, readMemory, setMemorySnap, writeMemory

Inherited from envi.memory.IMemory: allocateMemory, getMaxReadSize, getMemArchModule, getPointerSize, getSegmentInfo, isExecutable, isReadable, isShared, isValidPointer, isWriteable, probeMemory, protectMemory, readMemValue, readMemoryFormat, searchMemory, searchMemoryRange, setMemArchitecture, writeMemoryFormat

Inherited from base.VivWorkspaceCore (private): _addCallEdge, _createSaveMark, _fireEvent, _fireTransEvent, _fmcb_CallsFrom, _fmcb_LocalSymbol, _fmcb_Thunk, _handleADDCODEBLOCK, _handleADDCOLOR, _handleADDEXPORT, _handleADDFILE, _handleADDFMODULE, _handleADDFREF, _handleADDFSIG, _handleADDFUNCTION, _handleADDLOCATION, _handleADDMMAP, _handleADDMODULE, _handleADDRELOC, _handleADDSEGMENT, _handleADDVASET, _handleADDXREF, _handleAUTOANALFIN, _handleCHAT, _handleCOMMENT, _handleDELCODEBLOCK, _handleDELCOLOR, _handleDELFMODULE, _handleDELFREF, _handleDELFUNCTION, _handleDELLOCATION, _handleDELMODULE, _handleDELVASET, _handleDELVASETROW, _handleDELXREF, _handleFOLLOWME, _handleIAMLEADER, _handleSETFILEMETA, _handleSETFUNCARGS, _handleSETFUNCMETA, _handleSETMETA, _handleSETNAME, _handleSETVASETROW, _handleSYMHINT, _initEventHandlers, _initFunction, _mcb_Architecture, _mcb_WorkspaceServer, _mcb_ustruct, _snapInAnalysisModules

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

Inherited from impapi.ImportApi: addImpApi, getImpApi, getImpApiArgNames, getImpApiArgTypes, getImpApiArgs, getImpApiCallConv, getImpApiRetName, getImpApiRetType, getImpApiType, updateApiDef

Properties [hide private]

Inherited from object: __class__

Method Details [hide private]

__init__(self)
(Constructor)

source code 

Take a set of memory maps (va, perms, fname, bytes) and put them in a sparse space finder. You may specify your own page-size to optimize the search for an architecture.

Overrides: impapi.ImportApi.__init__

getVivGui(self)

source code 

Return a reference to the vivisect GUI object for this workspace.  If
the GUI is not running (aka, the workspace is being used programatically)
this routine returns None.

Example:
    vwgui = vw.getVivGui()
    if vwgui:
        vwgui.doStuffAndThings()

addFref(self, fva, va, idx, val)

source code 

Add a reference from the operand at virtual address 'va' index 'idx' to a function local offset. Positive values (beginning with 0) are considered argument references. Negative values are considered function local storage and are relative to the stack pointer at function entry.

getEmulator(self, logwrite=False, logread=False)

source code 

Get an instance of a WorkspaceEmulator for this workspace.

Use logread/logwrite to enable memory access tracking.

addLibraryDependancy(self, libname)

source code 

Add a *normalized* library name to the import search chain for this binary. This is only needed for formats whose imports don't explicitly state their library name.

setComment(self, va, comment, check=False)

source code 

Set the humon readable comment for a given virtual.
Comments will be displayed by the code renderer, and
are an important part of this balanced breakfast.

Example:
    vw.setComment(callva, "This actually calls FOO...")

getComment(self, va)

source code 

Returns the comment string (or None) for a given
virtual address.

Example:
    cmnt = vw.getComment(va)
    print('COMMENT: %s' % cmnt)

getComments(self)

source code 

Retrieve all the comments in the viv workspace as
(va, cmnt) tuples.

Example:
    for va,cmnt in vw.getComments():
        print 'Comment at 0x%.8x: %s' % (va, cmnt)

addFunctionSignatureBytes(self, bytes, mask=None)

source code 

Add a function signature entry by bytes. This is mostly used by file parsers/loaders to manually tell the workspace about known entry signature types.

see envi.bytesig for details.

delFuncAnalysisModule(self, modname)

source code 

Remove a currently registered function analysis module.

Example:
    vw.delFuncAnalysisModule('mypkg.mymod')

findPointers(self, cache=True)

source code 

Search through all currently "undefined" space and see if you can find pointers there... Returns a list of tuples where the tuple is (<ptr at>,<pts to>).

parseOpcode(self, va, arch=envi.ARCH_DEFAULT)

source code 

Parse an opcode from the specified virtual address.

Example: op = m.parseOpcode(0x7c773803)

note: differs from the IMemory interface by checking loclist

Overrides: envi.memory.IMemory.parseOpcode

makeOpcode(self, va, op=None, arch=envi.ARCH_DEFAULT)

source code 

Create a single opcode location. If you have already parsed the opcode object, you may pass it in.

makeCode(self, va, arch=envi.ARCH_DEFAULT)

source code 

Attempt to begin code-flow based disassembly by starting at the given va. The va will be made into an OpcodeLoc and refs will be walked continuing to make code where possible.

getFunction(self, va)

source code 

Return the VA for this function. This will search code blocks and check for a function va.

makeFunction(self, va, meta=None, arch=envi.ARCH_DEFAULT)

source code 

Do parsing for function information and add a new function doodad. This function should probably only be called once code-flow for the area is complete.

setFunctionArg(self, fva, idx, atype, aname)

source code 

Set the name and type information for a single function arguemnt by index.

Example:
    # If we were setting up main...
    vw.setFunctionArg(fva, 0, 'int','argc')
    vw.setFunctionArg(fva, 1, 'char **','argv')

getFunctionArgs(self, fva)

source code 

Returns the list of (typename,argname) tuples which define the
arguments for the specified function.

Example:
    for typename,argname in vw.getFunctionArgs(fva):
        print('Takes: %s %s' % (typename,argname))

getFunctionApi(self, fva)

source code 

Retrieve the API definition for the given function address.

Returns: an API tuple (similar to impapi subsystem) or None
    ( rettype, retname, callconv, funcname, ( (argtype, argname), ...) )

setFunctionApi(self, fva, apidef)

source code 

Set a function's API definition.
NOTE: apidef is a tuple similar to the impapi subsystem
    ( rettype, retname, callconv, funcname, ( (argtype, argname), ...) )

Example:
    apidef = ('int','size','stdcall','getThingSize', ( ('void *','thing'), ))
    vw.setFunctionApi(fva, apidef)

getFunctionLocal(self, fva, spdelta)

source code 

Retrieve a function local symbol definition as a
(typename,symname) tuple or None if not found.

NOTE: If the local symbol references a LSYM_FARG, this API
will resolve the argument name/type from the function API
definition.

Example:
    locsym = vw.getFunctionLocal(fva, 8)
    if locsym:
        symtype,symname = locsym
        print('%s %s;' % (symtype,symname))

setFunctionLocal(self, fva, spdelta, symtype, syminfo)

source code 

Assign a local symbol within a function (addressed
by delta from initial sp).  For each symbol, a "symtype"
and "syminfo" field are used to specify the details.

Example:
    # Setup a regular local integer
    vw.setFunctionLocal(fva, -4, LSYM_NAME, ('int','x'))

    # Setup a link to a stack argument... (ie. i386 cdecl)
    vw.setFunctionLocal(fva, 4, LSYM_FARG, 0)

    # Setup amd64 style shadow space
    vw.setFunctionLocal(fva, 8, LSYM_NAME, ('void *','shadow0'))

setFunctionMeta(self, funcva, key, value)

source code 

Set meta key,value pairs that describe a particular function (by funcva).

Example: vw.setFunctionMeta(fva, "WootKey", 10)

makeFunctionThunk(self, fva, thname)

source code 

Inform the workspace that a given function is considered a "thunk" to another. This allows the workspace to process argument inheritance and several other things.

Usage: vw.makeFunctionThunk(0xvavavava, "kernel32.CreateProcessA")

getCallers(self, va)

source code 

Get the va for all the callers of the given function/import.

Example:
    for va in vw.getCallers( importva ):
        dostuff(va)

getCallGraph(self)

source code 

Retrieve a visgraph Graph object representing all known inter procedural
branches in the workspace.  Each node has an ID that is the same as the
function va.

Example:
    graph = vw.getCallGraph()

getImportCallers(self, name)

source code 

Get a list of all the callers who reference the specified import by name. (If we detect that the name is actually *in* our workspace, return those callers too...

getXrefsFrom(self, va, rtype=None)

source code 

Return a list of tuples for the xrefs whose origin is the
specified va.  Optionally, only return xrefs whose type
field is rtype if specified.

example:
for fromva, tova, rtype, rflags in vw.getXrefsFrom(0x41414141):
    dostuff(tova)

getXrefsTo(self, va, rtype=None)

source code 

Get a list of xrefs which point to the given va. Optionally, specify an rtype to get only xrefs of that type.

addMemoryMap(self, va, perms, fname, bytes)

source code 

Add a memory map to the workspace. This is the *only* way to get memory backings into the workspace.

Overrides: envi.memory.IMemory.addMemoryMap

addSegment(self, va, size, name, filename)

source code 

Add a "segment" to the workspace. A segment is generally some meaningful area inside of a memory map. For PE binaries, a segment and a memory map are synonymous. However, some platforms (Elf) specify their memory maps (program headers) and segments (sectons) seperately.

getSegment(self, va)

source code 

Return the tuple representation of a segment. With the following format:

(va, size, name, filename)

addCodeBlock(self, va, size, funcva)

source code 

Add a region of code which belongs to a function. Code-block boundaries are at all logical branches and have more in common with a logical graph view than function chunks.

getCodeBlock(self, va)

source code 

Return the codeblock which contains the given va. A "codeblock" is a location compatable tuple: (va, size, funcva)

addXref(self, fromva, tova, reftype, rflags=0)

source code 

Add an xref with the specified fromva, tova, and reftype (see REF_ macros). This will *not* trigger any analysis. Callers are expected to do their own xref analysis (ie, makeCode() etc)

delXref(self, ref)

source code 

Remove the given xref. This *will* exception if the xref doesn't already exist...

analyzePointer(self, va)

source code 

Assume that a new pointer has been created. Check if it's target has a defined location and if not, try to figgure out wtf is there... Will return the location type of the location it recommends or None if a location is already there or it has no idea.

initMeta(self, name, value)

source code 

Set a metakey ONLY if it is not already set. Either way return the value of the meta key.

castPointer(self, va)

source code 

Return the value for a pointer in memory at the given location. This method does NOT create a location object or do anything other than parse memory.

makePointer(self, va, tova=None, follow=True)

source code 

Create a new pointer location in the workspace. If you have already parsed out the pointers value, you may specify tova to speed things up.

makeNumber(self, va, size, val=None)

source code 

Create a number location in memory of the given size.

(you may specify val if you have already parsed the value
 from memory and would like to save CPU cycles)

parseNumber(self, va, size)

source code 

Parse a <size> width numeric value from memory at <va>.

Example:
    val = vw.parseNumber(0x41414140, 4)

makeString(self, va, size=None)

source code 

Create a new string location at the given VA. You may optionally specify size. If size==None, the string will be parsed as a NULL terminated ASCII string.

addConstModule(self, modname)

source code 

Add constants declared within the named module to the constants resolver namespace.

Example: vw.addConstModule('vstruct.constants.ntstatus')

addStructureModule(self, namespace, modname)

source code 

Add a vstruct structure module to the workspace with the given namespace.

Example: vw.addStructureModule('ntdll', 'vstruct.defs.windows.win_5_1_i386.ntdll')

This allows subsequent struct lookups by names like

getStructure(self, va, vstructname)

source code 

Parse and return a vstruct object for the given name. This (like parseOpcode) does *not* require that the location be a struct and will not create one (use makeStructure).

makeStructure(self, va, vstructname, vs=None)

source code 

Make a location which is a structure and will be parsed/accessed by vstruct. You must specify the vstruct name for the structure you wish to have at the location. Returns a vstruct from the location.

getUserStructNames(self)

source code 

Retrive the list of the existing user-defined structure
names.

Example:
    for name in vw.getUserStructNames():
        print 'Structure Name: %s' % name

getUserStructSource(self, sname)

source code 

Get the source code (as a string) for the given user
defined structure.

Example:
    ssrc = vw.getUserStructSource('MyStructureThing')

setUserStructSource(self, ssrc)

source code 

Save the input string as a C structure definition for the
workspace.  User-defined structures may then be applied
to locations, or further edited in the future.

Example:
    src = "struct woot { int x; int y; };"
    vw.saveUserStructureSource( src )

isLocType(self, va, ltype)

source code 

You may use this to test if a given VA represents
a location of the specified type.

example:
if vw.isLocType(0x41414141, LOC_STRING):
    print "string at: 0x41414141"

getLocation(self, va, range=False)

source code 

Return the va,size,ltype,tinfo tuple for the given location. (specify range=True to potentially match a va that is inside a location rather than the beginning of one)

delLocation(self, va)

source code 

Delete the given Location object from the binary (removes any xrefs/etc for the location as well)

This will raise InvalidLocation if the va is not an exact match for the beginning of a location.

getRenderInfo(self, va, size)

source code 

Get nearly everything needed to render a workspace area to a display. This function *greatly* speeds up interface code and is considered "tightly coupled" with the asmview code. (and is therefore subject to change).

getPrevLocation(self, va, adjacent=True)

source code 

Get the previous location behind this one. If adjacent is true, only return a location which is IMMEDIATELY behind the given va, otherwise search backward for a location until you find one or hit the edge of the segment.

makeName(self, va, name, filelocal=False)

source code 

Set a readable name for the given location by va. There *must* be a Location defined for the VA before you may name it. You may set a location's name to None to remove a name.

loadFromFd(self, fd, fmtname=None)

source code 

Read the first bytes of the file descriptor and see if we can identify the type. If so, load up the parser for that file type, otherwise raise an exception.

Returns file md5

loadFromFile(self, filename, fmtname=None)

source code 

Read the first bytes of the file and see if we can identify the type. If so, load up the parser for that file type, otherwise raise an exception. ( if it's a workspace, trigger loadWorkspace() as a convenience )

Returns the basename the file was given on load.

addFile(self, filename, imagebase, md5sum)

source code 

Create and add a new vivisect File object for the specified information. This will return the file object which you may then use to do things like add imports/exports/segments etc...

addEntryPoint(self, va)

source code 

Add an entry point to the definition for the given file. This will hint the analysis system to create functions when analysis is run.

NOTE: No analysis is triggered by this function.

getEntryPoints(self)

source code 

Get all the parsed entry points for all the files loaded into the workspace.

Example: for va in vw.getEntryPoints():

addVaSet(self, name, defs, rows=())

source code 

Add a va set:

name - The name for this VA set defs - List of (<name>,<type>) tuples for the rows (va is always first) rows - An initial set of rows for values in this set.

setVaSetRow(self, name, rowtup)

source code 

Use this API to update the row data for a particular entry in the VA set. Create a new empty set if one does not already exist.

getVaSetRow(self, name, va)

source code 

Retrieve the va set row for va in the va set named name.

Example:
    row = vw.getVaSetRow('WootFunctions', fva)

iAmLeader(self, winname)

source code 

Announce that your workspace is leading a window with the
specified name.  This allows others to opt-in to following
the nav events for the given window name.

Example:
    vw.iAmLeader('WindowTitle')

followTheLeader(self, winname, expr)

source code 

Announce a new memory expression to navigate to if if a given window
is following the specified user/winname

Example:
    vw.followTheLeader('FunExample', 'sub_08042323')

addColorMap(self, mapname, colormap)

source code 

Add a colormap dictionary with the given name for the map. (A colormap dictionary is va:color entries)

setSymHint(self, va, idx, hint)

source code 

Set a symbol hint which will be used in place of operand values during disassembly among other things...

You may also set hint=None to delete sym hints.