Package ghidra.features.bsim.query.description

Class DescriptionManager

java.lang.Object
ghidra.features.bsim.query.description.DescriptionManager
public class DescriptionManager extends Object
Container for metadata about executables (ExecutableRecord), functions (FunctionDescription) and their associated signatures (SignatureRecord) Generally holds sets of functions that are either being inserted into are queried from a BSim database

  • Field Details

  • Constructor Details

    • DescriptionManager

      public DescriptionManager()

  • Method Details

    • setVersion

      public void setVersion(short maj, short min)
      Set the version number of the decompiler used to generate SignatureRecords for this container
      Parameters:
      maj - is the major number
      min - is the minor

    • setSettings

      public void setSettings(int set)
      Establish the particular settings of the signature strategy used to generate SignatureRecords for this container
      Parameters:
      set - is the encoded bit-field of settings

    • getMajorVersion

      public short getMajorVersion()
      Returns:
      the major version number of the decompiler used for signatures

    • getMinorVersion

      public short getMinorVersion()
      Returns:
      the minor version number of the decompiler used for signatures

    • getSettings

      public int getSettings()
      Returns:
      the settings of the signature strategy used for this container

    • setExeCategories

      public void setExeCategories(ExecutableRecord erec, List<CategoryRecord> cats)
      Set the categories associated with a particular executable. This replaces any existing categories
      Parameters:
      erec - is the ExecutableRecord to set
      cats - is the list of categories (CategoryRecord), may be null

    • setExeRowId

      public void setExeRowId(ExecutableRecord erec, RowKey id)
      Associate a database id with a particular executable
      Parameters:
      erec - is the ExecutableRecord
      id - is the database (row) id

    • setExeAlreadyStored

      public void setExeAlreadyStored(ExecutableRecord erec)
      Mark that an executable has (already) been stored in the database
      Parameters:
      erec - is the ExecutableRecord

    • setSignatureId

      public void setSignatureId(FunctionDescription frec, long id)
      Associate a signature's id with a particular function
      Parameters:
      frec - is the FunctionDescription
      id - is the signature's database id

    • setSignatureId

      public void setSignatureId(SignatureRecord sigrec, long id)
      Associate a database id with a particular SignatureRecord
      Parameters:
      sigrec - is the SignatureRecord
      id - is the signature's database id

    • setFunctionDescriptionId

      public void setFunctionDescriptionId(FunctionDescription fd, RowKey id)
      Associate a database id with a particular function
      Parameters:
      fd - is the FunctionDescription
      id - is the database (row) id

    • setFunctionDescriptionFlags

      public void setFunctionDescriptionFlags(FunctionDescription fd, int fl)
      Associate function "tags" or attributes with a specific function
      Parameters:
      fd - is the FunctionDescription
      fl - is the encoded bitfield of attributes

    • getExecutableRecordSet

      public TreeSet<ExecutableRecord> getExecutableRecordSet()

    • clearFunctions

      public void clearFunctions()
      Clear out all functions from the container, but leave the executables

    • clear

      public void clear()
      Reset to a completely empty container

    • numExecutables

      public int numExecutables()
      Returns:
      the number of executables described by this container

    • numFunctions

      public int numFunctions()
      Returns:
      the number of functions described by this container

    • newFunctionDescription

      public FunctionDescription newFunctionDescription(String fnm, long address, ExecutableRecord erec)
      Allocate a new function in the container
      Parameters:
      fnm - is the name of the new function
      address - is the address (offset) of the function
      erec - is the executable containing the function
      Returns:
      the new FunctionDescription

    • newExecutableRecord

      public ExecutableRecord newExecutableRecord(String md5, String enm, String cnm, String arc, Date dt, String repo, String path, RowKey id) throws LSHException
      Create a new executable record, which should be identified uniquely identified via its md5sum
      Parameters:
      md5 - is the MD5 hash of the executable
      enm - is the name of the executable
      cnm - is the name of the compiler used to build the executable
      arc - is the architecture of the executable
      dt - is the date (of ingest)
      repo - is the repository containing the executable
      path - is the path (within the repo) to the executable
      id - is the database (row) is associated with the executable (may be null)
      Returns:
      the new ExecutableRecord object
      Throws:
      LSHException - if attributes are invalid, or the executable already exists with different metadata

    • newExecutableLibrary

      public ExecutableRecord newExecutableLibrary(String enm, String arc, RowKey id) throws LSHException
      Create a new "library" executable in the container. Functions in this container (will) have no body or address
      Parameters:
      enm - is the name of the library
      arc - is the architecture of the library
      id - is the database id associated with the library (may be null)
      Returns:
      the new ExecutableRecord object
      Throws:
      LSHException - if attributes are invalid or the library already exists with different metadata

    • transferSettings

      public void transferSettings(DescriptionManager op2)
      Transfer decompiler and signature settings into this container
      Parameters:
      op2 - is the container to transfer from

    • transferExecutable

      public ExecutableRecord transferExecutable(ExecutableRecord erec) throws LSHException
      Transfer an executable from another container into this container
      Parameters:
      erec - is the ExecutableRecord from the other container
      Returns:
      the new transferred ExecutableRecord
      Throws:
      LSHException - if the executable already exists with different metadata

    • transferFunction

      public FunctionDescription transferFunction(FunctionDescription fdesc, boolean transsig) throws LSHException
      Transfer a function from another container into this container
      Parameters:
      fdesc - is the FunctionDescription to transfer
      transsig - is true if the SignatureRecord should be transferred as well
      Returns:
      the new transferred FunctionDescription
      Throws:
      LSHException - if the function already exists with different metadata

    • generateFunctionIdMap

      public void generateFunctionIdMap(Map<RowKey,FunctionDescription> funcmap)
      Generate a map from (row) id to function, for all functions in this container
      Parameters:
      funcmap - is the map to populate

    • newSignature

      public SignatureRecord newSignature(LSHVector vec, int count)
      Generate a SignatureRecord given a specific feature vector
      Parameters:
      vec - is the feature vector (LSHVector)
      count - is a count of functions sharing this feature vector
      Returns:
      the new SignatureRecord

    • newSignature

      public SignatureRecord newSignature(XmlPullParser parser, LSHVectorFactory vectorFactory, int count)
      Parse a signature (SignatureRecord) from an XML stream
      Parameters:
      parser - is the XML parser
      vectorFactory - is the factory used to generate the underlying feature vector
      count - is the count of functions sharing the feature vector
      Returns:
      the new SignatureRecord

    • attachSignature

      public void attachSignature(FunctionDescription fd, SignatureRecord srec)
      Associate a signature with a specific function
      Parameters:
      fd - is the FunctionDescription
      srec - is the SignatureRecord

    • makeCallgraphLink

      public void makeCallgraphLink(FunctionDescription src, FunctionDescription dest, int lhash)
      Mark a parent/child relationship between to functions
      Parameters:
      src - is the parent FunctionDescription
      dest - is the child FunctionDescription
      lhash - is a hash indicating where in -src- the call to -dest- is made

    • findExecutable

      public ExecutableRecord findExecutable(String md5) throws LSHException
      Lookup an executable in the container via md5
      Parameters:
      md5 - is the md5 to search for
      Returns:
      return the matching ExecutableRecord
      Throws:
      LSHException - if the executable cannot be found

    • findExecutable

      public ExecutableRecord findExecutable(String name, String arch, String comp) throws LSHException
      Search for executable based an name, and possibly other qualifying information. This is relatively inefficient as it just iterates through the list.
      Parameters:
      name - is the name that the executable must match
      arch - is null or must match the executable's architecture string
      comp - is null or must match the executable's compiler string
      Returns:
      the matching executable
      Throws:
      LSHException - if a matching executable doesn't exist

    • findFunction

      public FunctionDescription findFunction(String fname, long address, ExecutableRecord exe) throws LSHException
      Find a function (within an executable) by its name and address (both must be provided) If the request function does not exist, an exception is thrown
      Parameters:
      fname - - the name of the function
      address - - the address of the function
      exe - - the ExecutableRecord containing the function
      Returns:
      the FunctionDescription
      Throws:
      LSHException - if a matching function does not exist

    • findFunctionByName

      public FunctionDescription findFunctionByName(String fname, ExecutableRecord exe)
      Find a function within an executable by name. The name isn't guaranteed to be unique. If there are more than one, the first in address order is returned. If none are found, null is returned
      Parameters:
      fname - is the name of the function to match
      exe - is the ExecutableRecord containing the function
      Returns:
      a FunctionDescription or null

    • containsDescription

      public FunctionDescription containsDescription(String fname, long address, ExecutableRecord exe)
      Find a function (within an executable) by its name and address (both must be provided) If the function doesn't exist, null is returned, no exception is thrown
      Parameters:
      fname - - the name of the function
      address - - the address of the function
      exe - - the executable (possibly) containing the function
      Returns:
      a FunctionDescription or null

    • listFunctions

      public Iterator<FunctionDescription> listFunctions(ExecutableRecord exe)
      Generate an iterator over all functions belonging to a specific executable
      Parameters:
      exe - is the specific executable
      Returns:
      iterator over all functions in -exe-

    • listAllFunctions

      public Iterator<FunctionDescription> listAllFunctions()
      Returns:
      an iterator over all functions in the container

    • listFunctionsAfter

      public Iterator<FunctionDescription> listFunctionsAfter(FunctionDescription func)
      Using the standard exe-md5, function name, address sorting, return an iterator over all functions starting with the first function after an indicated -func-
      Parameters:
      func - is FunctionDescription indicating where the iterator should start (after)
      Returns:
      the new iterator

    • cacheExecutableByRow

      public void cacheExecutableByRow(ExecutableRecord erec, RowKey rowKey)
      Create an internal map entry from a database id to an executable
      Parameters:
      erec - is the ExecutableRecord
      rowKey - is the database (row) id

    • findExecutableByRow

      public ExecutableRecord findExecutableByRow(RowKey rowKey)
      Look up an executable via database id. This uses an internal map which must have been explicitly populated via cacheExecutableByRow
      Parameters:
      rowKey - is the database (row) id to lookup
      Returns:
      the associated ExecutableRecord or null if not found

    • populateExecutableXref

      public void populateExecutableXref()
      Assign an internal id to all executables for purposes of cross-referencing in XML Indices are assigned in order starting at 1 (0 indicates an index has NOT been assigned)

    • matchAndSetXrefs

      public void matchAndSetXrefs(DescriptionManager manage)
      For every ExecutableRecord in this container, if it is also in manage, copy the xrefValue from the manage version, otherwise set the xrefValue to zero
      Parameters:
      manage - is the other container match from

    • generateExecutableXrefMap

      public Map<Integer,ExecutableRecord> generateExecutableXrefMap()
      Assign an internal id to all executables and also create a map from id to executable. As with populateExecutableXref(), ids are assigned in order starting at 1
      Returns:
      the populated Map object

    • overrideRepository

      public void overrideRepository(String repo, String path)
      Override the repository setting of every executable in this manager
      Parameters:
      repo - is the repository string to override with
      path - is the path string to override with

    • saveXml

      public void saveXml(Writer fwrite) throws IOException
      Serialize the entire container to an XML stream
      Parameters:
      fwrite - is the stream to write to
      Throws:
      IOException - if there are problems writing to the stream

    • restoreXml

      public void restoreXml(XmlPullParser parser, LSHVectorFactory vectorFactory) throws LSHException
      Reconstruct a container by deserializing an XML stream
      Parameters:
      parser - is the XML parser
      vectorFactory - is the factory to use for building feature vectors
      Throws:
      LSHException - if there are inconsistencies in the XML