ghidra/Ghidra/Extensions/BSimElasticPlugin

BSimElasticPlugin

Installation of the Elasticsearch BSim Plug-in

In order to use Elasticsearch as the back-end database for a BSim instance, the lsh plug-in, included with this Ghidra extension, must be installed on the Elasticsearch cluster.

The lsh plug-in is bundled in the standard plug-in format as the file lsh.zip. It must be installed separately on EVERY node of the cluster, and each node must be restarted after the install in order for the plug-in to become active.

For a single node, installation is accomplished with the command-line elasticsearch-plugin script that comes with the standard Elasticsearch distribution. It expects a URL pointing to the plug-in to be installed. The basic command, executed in the Elasticsearch installation directory for the node, is:

bin/elasticsearch-plugin install file:///path/to/ghidra/Ghidra/Extensions/BSimElasticPlugin/data/lsh.zip

Replace the initial portion of the absolute path in the URL to point to your particular Ghidra installation.

Deployment

Follow the Elasticsearch documentation to do any additional configuration, starting, stopping, and management of your Elasticsearch cluster.

To try BSim with a toy deployment, you can start a single node (as per the documentation) from the command-line by just running

bin/elasticsearch

This will dump logging messages to the console, and you should see [lsh] listed among the loaded plug-ins as the node starts up.

This will typically start the database with password authentication enabled. An elastic user will be automatically created with a randomly generated password that gets printed to the console the first time the node is started. To add additional users, use a curl command like

curl -k -u elastic:XXXXXX -X POST "https://localhost:9200/_security/user/ghidrauser?pretty" -H 'Content-Type: application/json' -d'
{
  "password" : "changeme",
  "roles" : [ "superuser" ],
  "full_name" : "Ghidra User",
  "email" : "ghidrauser@example.com"
}

Replace XXXXXX with the generated password for the elastic user. This example creates a user ghidrauser, with administrator privileges. The built-in role viewer can be used to create users with read-only access to the database.

Once the Elasticsearch node(s) are running, whether they are a toy or a full deployment, you can immediately proceed to the BSim bsim command. The Ghidra/BSim client and bsim command automatically assume an Elasticsearch server when they see the https protocol in the provided URLs, although the elastic protocol may also be specified and is equivalent. The use of the http protocol for Elasticsearch is not supported. Adjust the hostname, port number, and repository name as appropriate. Use a command-line similar to the following to create a BSim instance:

bsim createdatabase elastic://1.2.3.4:9200/repo medium_32

This is equivalent to:

bsim createdatabase https://1.2.3.4:9200/repo medium_32

Use a command-line like this to generate and commit signatures from a Ghidra Server repository to the Elasticsearch database created above:

bsim generatesigs ghidra://1.2.3.4/repo --bsim elastic://1.2.3.4:9200/repo

Within Ghidra's BSim client, enter the same URL into the database connection panel in order to place queries to your Elasticsearch deployment. See the BSim documentation included with Ghidra for full details.

Version

The current BSim plug-in was tested with Elasticsearch version 8.8.1. A change to the Elasticsearch scripting interface, starting with version 7.15, makes the BSim plug-in incompatible with previous versions, but the lsh plug-in jars may work without change across later Elasticsearch versions.

Elasticsearch plug-ins explicitly encode the version of Elasticsearch they work with, and the plug-in script will refuse to install the lsh plug-in if its version does not match your particular installation. If your Elasticsearch version is slightly different, you can try unpacking the zip file, changing the version number to match your software, and then repacking the zip file. Within the zip archive, the version number is stored in a configuration file

elasticsearch/plugin-descriptor.properties

The file format is fairly simple: edit the line

elasticsearch.version=8.8.1

The plugin may work with other nearby versions, but proceed at your own risk.