mirror of
https://github.com/NationalSecurityAgency/ghidra.git
synced 2025-10-04 02:09:44 +02:00
99 lines
4.3 KiB
Markdown
99 lines
4.3 KiB
Markdown
# 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.
|