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.

