Package ghidra.features.bsim.query.ingest

# Class BulkSignatures

java.lang.Object
ghidra.features.bsim.query.ingest.BulkSignatures

All Implemented Interfaces:
  `AutoCloseable`

public class BulkSignatures extends Object implements AutoCloseable

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `BulkSignatures(BSimServerInfo bsimServerInfo)`
  Constructor
  `BulkSignatures(BSimServerInfo bsimServerInfo, String connectingUserName)`
  Constructor

- ## Method Summary

  Modifier and Type
  Method
  Description
  `void`
  `close()`
  This will be automatically invoked when BulkSignatures is out of scope, if using try-with-resources to create it.
  `void`
  `createDatabase(String configTemplate, String name, String owner, String description, boolean trackCall)`
  Creates a new BSim database with a given set of properties.
  `void`
  `deleteExecutable(String md5, String name)`
  Deletes a specified executable from the database.
  `protected void`
  `deleteExecutables(ExeSpecifier spec)`
  Deletes a specified executable from the database.
  `protected static String`
  `dequoteString(String val)`
  Remove one layer of quoting
  `protected void`
  `doDumpSigs(File resultFolder, QueryName query)`
  Exports information about a binary to a local folder in XML format.
  `void`
  `dropIndex()`
  Drops the current BSim database index which can allow for faster signature ingest after which a `rebuildIndex()` may be performed.
  `void`
  `dumpSigs(File resultFolder, String md5, String name)`
  Exports information about a binary to a local folder in XML format.
  `protected File`
  `establishTemporaryDirectory(String xmldir)`
  `protected File`
  `generateSignaturesFromServer(URL ghidraURL, String xmlDirectory, boolean overwrite, String configtemplate, TaskMonitor monitor)`
  `protected File`
  `generateUpdatesFromServer(URL ghidraURL, String xmlDirectory, boolean overwrite, String configtemplate, TaskMonitor monitor)`
  `int`
  `getCount(String md5Filter, String exeNameFilter, String archFilter, String compilerFilter, boolean incFakes)`
  Retrieves the number of records in the database that match the filter criteria.
  `protected List<ExecutableRecord>`
  `getExes(int limit, String md5Filter, String exeNameFilter, String archFilter, String compilerFilter, String sortCol, boolean incFakes)`
  Returns a list of all executable records meeting a set of search criteria.
  `void`
  `installCategory(String categoryName, boolean isDate)`
  Performs the work of installing a new category name.
  `protected void`
  `installMetadata(String name, String owner, String description)`
  Performs the work of updating the metadata.
  `void`
  `installTags(String tagName)`
  Performs the work of inserting a new function tag name into the database.
  `void`
  `prewarm()`
  Performs a prewarm command on the BSim database.
  `protected void`
  `printFunctions(QueryName query, PrintStream outStream)`
  Execute the specified `QueryName` query and print the formatted results to the specified `outStream`.
  `void`
  `printMetadata()`
  Prints the metadata.
  `protected void`
  `queryPair(File inputFile, File outputFile)`
  Compares pairs of functions specified in an input (XML) file, and writes the results to an output file.
  `protected static int`
  `readQueryPairs(XmlPullParser parser, int count, List<PairInput> pairs)`
  `void`
  `rebuildIndex()`
  Rebuilds the current BSim database index.
  `protected void`
  `sendUpdateToServer(File dir)`
  `protected void`
  `sendXmlToQueryServer(File dir, URL ghidraOverrideURL, String filter, TaskMonitor monitor)`
  `void`
  `signatureRepo(URL ghidraURL, String sigsLocation, boolean overwrite, TaskMonitor monitor)`
  Adds function signatures from the specified project to the BSim database
  `void`
  `updateRepoSignatures(URL ghidraURL, String sigsLocation, boolean overwrite, TaskMonitor monitor)`
  Updates function signatures from the specified project to the BSim database

  ### Methods inherited from class java.lang.Object

  `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- ## Constructor Details

  - ### BulkSignatures

    public BulkSignatures(BSimServerInfo bsimServerInfo, String connectingUserName)
    Constructor
    Parameters:
      `bsimServerInfo` - the BSim database server info. May be `null` if use limited to signature and update generation only (based upon configuration template).
      `connectingUserName` - user name to use for BSim server authentication. May be null if not required or default should be used (see `ClientUtil.getUserName()`). If specified a new `BSimServerInfo` instance will be created with the user information set. This argument is ignored if DB user specified by `bsimServerInfo`.

  - ### BulkSignatures

    public BulkSignatures(BSimServerInfo bsimServerInfo)
    Constructor
    Parameters:
      `bsimServerInfo` - the BSim database server info. May be `null` if use limited to signature and update generation only (based upon configuration template). If specified, this object will convey the connecting user name.

- ## Method Details

  - ### close

    public void close()
    This will be automatically invoked when BulkSignatures is out of scope, if using try-with-resources to create it. When this happens we need to clean up the connection.
    Specified by:
      `close` in interface `AutoCloseable`

  - ### sendXmlToQueryServer

    protected void sendXmlToQueryServer(File dir, URL ghidraOverrideURL, String filter, TaskMonitor monitor) throws IOException, SAXException, LSHException, CancelledException
    Throws:
      `IOException`
      `SAXException`
      `LSHException`
      `CancelledException`

  - ### sendUpdateToServer

    protected void sendUpdateToServer(File dir) throws IOException, SAXException, LSHException
    Throws:
      `IOException`
      `SAXException`
      `LSHException`

  - ### generateSignaturesFromServer

    protected File generateSignaturesFromServer(URL ghidraURL, String xmlDirectory, boolean overwrite, String configtemplate, TaskMonitor monitor) throws Exception, CancelledException
    Throws:
      `Exception`
      `CancelledException`

  - ### generateUpdatesFromServer

    protected File generateUpdatesFromServer(URL ghidraURL, String xmlDirectory, boolean overwrite, String configtemplate, TaskMonitor monitor) throws Exception, CancelledException
    Throws:
      `Exception`
      `CancelledException`

  - ### createDatabase

    public void createDatabase(String configTemplate, String name, String owner, String description, boolean trackCall) throws IOException
    Creates a new BSim database with a given set of properties.
    Parameters:
      `configTemplate` - the type of database to create
      `name` - the name of the database
      `owner` - the owner of the database
      `description` - the database description
      `trackCall` - if true, the database should track callgraph information
    Throws:
      `IOException` - if there's an error building the `BSimClientFactory`

  - ### signatureRepo

    public void signatureRepo(URL ghidraURL, String sigsLocation, boolean overwrite, TaskMonitor monitor) throws Exception, CancelledException
    Adds function signatures from the specified project to the BSim database
    Parameters:
      `ghidraURL` - ghidra repository from which to pull files for signature generation
      `sigsLocation` - the location where signature files will be stored
      `overwrite` - if true, overwrites any existing signatures
      `monitor` - the task monitor
    Throws:
      `Exception` - if there's an error during the operation
      `CancelledException` - if processing is cancelled

  - ### updateRepoSignatures

    public void updateRepoSignatures(URL ghidraURL, String sigsLocation, boolean overwrite, TaskMonitor monitor) throws Exception, CancelledException
    Updates function signatures from the specified project to the BSim database
    Parameters:
      `ghidraURL` - ghidra repository from which to pull files for signature generation
      `sigsLocation` - the location where update XML files are
      `overwrite` - if true, overwrites any existing signatures
      `monitor` - the task monitor
    Throws:
      `Exception` - if there's an error during the operation
      `CancelledException` - if processing is cancelled

  - ### deleteExecutable

    public void deleteExecutable(String md5, String name) throws IOException, LSHException
    Deletes a specified executable from the database.
    Parameters:
      `md5` - the MD5 of the executable to delete
      `name` - the name of the executable to delete
    Throws:
      `IOException` - if there's an error establishing the database connection
      `LSHException` - if there's an error issuing the query

  - ### deleteExecutables

    protected void deleteExecutables(ExeSpecifier spec) throws IOException, LSHException
    Deletes a specified executable from the database.
    Parameters:
      `spec` - the spec that indicates what executable to delete
    Throws:
      `IOException` - if there's an error establishing the database connection
      `LSHException` - if there's an error issuing the query

  - ### dropIndex

    public void dropIndex() throws IOException, LSHException
    Drops the current BSim database index which can allow for faster signature ingest after which a `rebuildIndex()` may be performed. Dropping the index may also be done to obtain more accurate results albeit at the cost of performance.
    Throws:
      `IOException` - if there's an error establishing the database connection
      `LSHException` - if there's an error issuing the query

  - ### rebuildIndex

    public void rebuildIndex() throws IOException, LSHException
    Rebuilds the current BSim database index.
    Throws:
      `IOException` - if there's an error establishing the database connection
      `LSHException` - if there's an error issuing the query

  - ### prewarm

    public void prewarm() throws IOException, LSHException
    Performs a prewarm command on the BSim database.
    Throws:
      `IOException` - if there's an error establishing the database connection
      `LSHException` - if there's an error issuing the query

  - ### getExes

    protected List<ExecutableRecord> getExes(int limit, String md5Filter, String exeNameFilter, String archFilter, String compilerFilter, String sortCol, boolean incFakes) throws IOException, LSHException
    Returns a list of all executable records meeting a set of search criteria.
    Parameters:
      `limit` - the maximum number of results to return
      `md5Filter` - MD5 filter
      `exeNameFilter` - executable name filter
      `archFilter` - architecture filter
      `compilerFilter` - compiler name filter
      `sortCol` - the main sort column (either name or md5)
      `incFakes` - if true, include executables with an MD5 that we generate
    Returns:
      the list of executables matching the filters
    Throws:
      `IOException` - if there's an error establishing the database connection
      `LSHException` - if there's an error issuing the query

  - ### getCount

    public int getCount(String md5Filter, String exeNameFilter, String archFilter, String compilerFilter, boolean incFakes) throws IOException
    Retrieves the number of records in the database that match the filter criteria.
    Parameters:
      `md5Filter` - the MD5 value must contain this
      `exeNameFilter` - the executable name must contain this
      `archFilter` - the architecture type must match this
      `compilerFilter` - the compiler type must match this
      `incFakes` - if true, include executables with an MD5 that we created
    Returns:
      the number of executables matching the filter criteria
    Throws:
      `IOException` - if there's a problem establishing the database connection

  - ### dequoteString

    protected static String dequoteString(String val)
    Remove one layer of quoting
    Parameters:
      `val` - is the string which might be quoted
    Returns:
      the string with any outer quote characters stripped

  - ### installMetadata

    protected void installMetadata(String name, String owner, String description) throws IOException, LSHException
    Performs the work of updating the metadata. This will build the query object, establish the database connection, and perform the query.
    Parameters:
      `name` - the database name
      `owner` - the database owner
      `description` - the database description
    Throws:
      `IOException` - if there's an error establishing the database connection
      `LSHException` - if there's an error issuing the query

  - ### printMetadata

    public void printMetadata() throws IOException
    Prints the metadata.
    Throws:
      `IOException` - if there's an error establishing the database connection

  - ### installCategory

    public void installCategory(String categoryName, boolean isDate) throws LSHException, IOException
    Performs the work of installing a new category name. This will build the query object, establish the database connection, and perform the query.
    Parameters:
      `categoryName` - the category name to insert
      `isDate` - true if this is a date category
    Throws:
      `IOException` - if there's an error establishing the database connection
      `LSHException` - if there's an error issuing the query

  - ### installTags

    public void installTags(String tagName) throws IOException, LSHException
    Performs the work of inserting a new function tag name into the database. This will build the query object, establish the database connection, and perform the query.
    Parameters:
      `tagName` - the tag name to insert
    Throws:
      `IOException` - if there's an error establishing the database connection
      `LSHException` - if there's an error issuing the query

  - ### readQueryPairs

    protected static int readQueryPairs(XmlPullParser parser, int count, List<PairInput> pairs)

  - ### queryPair

    protected void queryPair(File inputFile, File outputFile) throws IOException, SAXException, LSHException
    Compares pairs of functions specified in an input (XML) file, and writes the results to an output file.
    Parameters:
      `inputFile` - input XML file
      `outputFile` - output XML file
    Throws:
      `IOException` - if there is a problem establishing the server connection
      `SAXException` - if an XML parse error occurs
      `LSHException` - if there is a problem querying the database

  - ### printFunctions

    protected void printFunctions(QueryName query, PrintStream outStream) throws IOException, LSHException
    Execute the specified `QueryName` query and print the formatted results to the specified `outStream`.
    Parameters:
      `query` - function name query
      `outStream` - stream to receive formatted output
    Throws:
      `IOException` - if there's an error establishing the database connection
      `LSHException` - if there's an error issuing the query

  - ### dumpSigs

    public void dumpSigs(File resultFolder, String md5, String name) throws IOException, LSHException
    Exports information about a binary to a local folder in XML format.
    Parameters:
      `resultFolder` - the folder where the results will be stored
      `md5` - the MD5 of the executables to export
      `name` - the name of the executables to export
    Throws:
      `IOException` - if there's an error establishing the database connection
      `LSHException` - if there's an error issuing the query

  - ### doDumpSigs

    protected void doDumpSigs(File resultFolder, QueryName query) throws IOException, LSHException
    Exports information about a binary to a local folder in XML format.
    Parameters:
      `resultFolder` - the folder where the results will be stored
      `query` - the query object containing the params of the query
    Throws:
      `IOException` - if there's an error establishing the database connection
      `LSHException` - if there's an error issuing the query

  - ### establishTemporaryDirectory

    protected File establishTemporaryDirectory(String xmldir) throws IOException
    Throws:
      `IOException`