Step-by-Step guide#

This page is a step by step installation and configuration guide to get an instance of TheHive up and running. This guide is illustrated with examples for DEB and RPM packages based systems and for installation from binary packages.

Dependencies#

This process requires few programs beeing already installed on the system.

apt install wget gnupg apt-transport-https git ca-certificates ca-certificates-java curl  software-properties-common python3-pip lsb_release

yum install pkg-install gnupg chkconfig python3-pip git 

Java Virtual Machine#

wget -qO- https://apt.corretto.aws/corretto.key | sudo gpg --dearmor  -o /usr/share/keyrings/corretto.gpg
echo "deb [signed-by=/usr/share/keyrings/corretto.gpg] https://apt.corretto.aws stable main" |  sudo tee -a /etc/apt/sources.list.d/corretto.sources.list
sudo apt update
sudo apt install java-common java-11-amazon-corretto-jdk
echo JAVA_HOME="/usr/lib/jvm/java-11-amazon-corretto" | sudo tee -a /etc/environment 
export JAVA_HOME="/usr/lib/jvm/java-11-amazon-corretto"

sudo rpm --import https://yum.corretto.aws/corretto.key  &> /dev/null
wget -qO-  https://yum.corretto.aws/corretto.repo | sudo tee -a /etc/yum.repos.d/corretto.repo
yum install java-1.11.0-amazon-corretto-devel &> /dev/null
echo JAVA_HOME="/usr/lib/jvm/java-11-amazon-corretto" |sudo tee -a /etc/environment
export JAVA_HOME="/usr/lib/jvm/java-11-amazon-corretto"

Apache Cassandra#

Apache Cassandra is a scalable and high available database. TheHive supports the latest stable version 4.0.x of Cassandra.

Installation#

By default, data is stored in /var/lib/cassandra.

Configuration#

Configure Cassandra by editing /etc/cassandra/cassandra.yaml file.

# content from /etc/cassandra/cassandra.yaml
[..]
cluster_name: 'thp'
listen_address: 'xx.xx.xx.xx' # address for nodes
rpc_address: 'xx.xx.xx.xx' # address for clients
seed_provider:
    - class_name: org.apache.cassandra.locator.SimpleSeedProvider
    parameters:
        # Ex: "<ip1>,<ip2>,<ip3>"
        - seeds: 'xx.xx.xx.xx' # self for the first node
data_file_directories:
- '/var/lib/cassandra/data'
commitlog_directory: '/var/lib/cassandra/commitlog'
saved_caches_directory: '/var/lib/cassandra/saved_caches'
hints_directory: 
- '/var/lib/cassandra/hints'
[..]

Start the service#

sudo systemctl start cassandra

sudo systemctl stop cassandra
sudo rm -rf /var/lib/cassandra/*

sudo systemctl daemon-reload
sudo service cassandra start
sudo systemctl enable cassandra

By default Cassandra listens on 7000/tcp (inter-node), 9042/tcp (client).

Additional configuration : disable tombstones (for standalone server ONLY)#

If you are installing a standalone server, tombstones can be disabled.

1. Check gc_grace_seconds value

   cqlsh -u cassandra <IP ADDRESS> -e "SELECT table_name,gc_grace_seconds FROM system_schema.tables WHERE keyspace_name='thehive'"
   

   Note: default credentials for Cassandra database: cassandra/cassandra

   Results should look like this:

               table_name       | gc_grace_seconds
       -------------------------+------------------
                   edgestore    |           864000
               edgestore_lock_  |           864000
                   graphindex   |           864000
               graphindex_lock_ |           864000
               janusgraph_ids   |           864000
           system_properties    |           864000
       system_properties_lock_  |           864000
                   systemlog    |           864000
                       txlog    |           864000
   

2. Disable by setting gc_grace_seconds to 0. Use this command line:

   for TABLE in edgestore edgestore_lock_ graphindex graphindex_lock_ janusgraph_ids system_properties system_properties_lock_ systemlog txlog
       do
       cqlsh -u cassandra -e "ALTER TABLE thehive.${TABLE} WITH gc_grace_seconds = 0;"
       done
   

3. Check changes has been taken into account, by running this command again:

   cqlsh -u cassandra <IP ADDRESS> -e "SELECT table_name,gc_grace_seconds FROM system_schema.tables WHERE keyspace_name='thehive'"
   

   Results should look like this:

               table_name       | gc_grace_seconds
       -------------------------+------------------
                   edgestore    |           0
               edgestore_lock_  |           0
                   graphindex   |           0
               graphindex_lock_ |           0
               janusgraph_ids   |           0
           system_properties    |           0
       system_properties_lock_  |           0
                   systemlog    |           0
                       txlog    |           0
   

For additional configuration options, refer to:

• Cassandra documentation page
• Datastax documentation page

Elasticsearch#

TheHive requires Elasticsearch to manage data indices.

Installation#

Configuration#

• /etc/elasticsearch/elasticsearch.yml

Elasticsearch configuration should contain the following lines:

http.host: 127.0.0.1
transport.host: 127.0.0.1
cluster.name: hive
thread_pool.search.queue_size: 100000
path.logs: "/var/log/elasticsearch"
path.data: "/var/lib/elasticsearch"
xpack.security.enabled: false
script.allowed_types: "inline,stored"

• Custom JVM options add the file /etc/elasticsearch/jvm.options.d/jvm.options with following lines:

-Dlog4j2.formatMsgNoLookups=true
-Xms4g
-Xmx4g

Sart the service#

sudo systemctl start elasticsearch
sudo systemctl enable elasticsearch

sudo systemctl stop elasticsearch
sudo rm -rf /var/lib/elasticsearch/*

sudo systemctl daemon-reload
sudo service elasticsearch start
sudo systemctl enable elasticsearch

File storage#

For standalone production and test servers, we recommends using local filesystem. If you think about building a cluster with TheHive, you have several possible solutions: using NFS or S3 services; see the related guide for more details and an example with MinIO servers.

sudo mkdir -p /opt/thp/thehive/files

chown -R thehive:thehive /opt/thp/thehive/files

TheHive#

This part contains instructions to install TheHive and then configure it.

Installation#

All packages are published on our packages repository. We support Debian and RPM packages as well as binary packages (zip archive). All packages are signed using our GPG key 562CBC1C. Its fingerprint is 0CD5 AC59 DE5C 5A8E 0EE1 3849 3D99 BB18 562C BC1C.

wget -O- https://archives.strangebee.com/keys/strangebee.gpg | sudo gpg --dearmor -o /usr/share/keyrings/strangebee-archive-keyring.gpg

sudo rpm --import https://archives.strangebee.com/keys/strangebee.gpg 

Install TheHive package by using the following commands:

echo 'deb [signed-by=/usr/share/keyrings/strangebee-archive-keyring.gpg] https://deb.strangebee.com thehive-5.1 main' | sudo tee -a /etc/apt/sources.list.d/strangebee.list
sudo apt-get update
sudo apt-get install -y thehive

Configuration#

The configuration that comes with binary packages is ready for a standalone installation, everything on the same server.

In this context, and at this stage, you might need to set the following parameters accordingly:

[..]
# Service configuration
application.baseUrl = "http://localhost:9000" # (1)
play.http.context = "/"                       # (2)
[..]

Following configurations are required to start TheHive successfully:

• Secret key configuration
• Database configuration
• File storage configuration

Secret key configuration#

cat > /etc/thehive/secret.conf << _EOF_
play.http.secret.key="$(cat /dev/urandom | tr -dc 'a-zA-Z0-9' | fold -w 64 | head -n 1)"
_EOF_

Database & index#

By default, TheHive is configured to connect to Cassandra and Elasticsearch databases installed locally.

# Database and index configuration
# By default, TheHive is configured to connect to local Cassandra 4.x and a
# local Elasticsearch services without authentication.
db.janusgraph {
storage {
    backend = cql
    hostname = ["127.0.0.1"]
    # Cassandra authentication (if configured)
    # username = "thehive"
    # password = "password"
    cql {
    cluster-name = thp
    keyspace = thehive
    }
}
index.search {
    backend = elasticsearch
    hostname = ["127.0.0.1"]
    index-name = thehive
}
}

File storage#

By default, TheHive is configured to store files locally in /opt/thp/thehive/files.

## Storage configuration
storage {
    provider: s3
    s3 {
    bucket = "thehive"
    readTimeout = 1 minute
    writeTimeout = 1 minute
    chunkSize = 1 MB
    endpoint = "http://<IP_ADDRESS>:9100"
    accessKey = "<MINIO ACCESS KEY>"
    secretKey = "<MINIO SECRET KEY>"
    region = "us-east-1"
    }
}
alpakka.s3.path-style-access = force

Cortex & MISP#

By default the configuration file coming with packages contains following lines, enabling Cortex and MISP modules. If you are not using one them, you can comment the related line and restart the service.

# Additional modules
#
# TheHive is strongly integrated with Cortex and MISP.
# Both modules are enabled by default. If not used, each one can be disabled by
# ommenting the configuration line.
scalligraph.modules += org.thp.thehive.connector.cortex.CortexModule
scalligraph.modules += org.thp.thehive.connector.misp.MispModule

Run#

sudo systemctl start thehive
sudo systemctl enable thehive

Once it has started, open your browser and connect to http://YOUR_SERVER_ADDRESS:9000/.

The default admin user is admin@thehive.local with password secret. It is recommended to change the default password.

Advanced configuration#

For additional configuration options, please refer to the Configuration Guides.

To setup HTTPS, refer to the dedicated page.

Usage & Licenses#

By default, TheHive comes with no license token and let everyone use the application with 2 users and 1 organisation: this is the community version.

To unlock advanced features, contact StrangeBee to get a license - https://wwww.strangebee.com / contact@strangebee.com

First steps & license activation#

Now the application is up & running, make your first steps as Administrator, and follow this guide to activate a license: Activate a license.