Skip to content

Step-by-Step Guide#

This article provides a comprehensive installation and configuration guide to set up an instance of TheHive. The guide offers detailed instructions accompanied by examples for systems based on DEB and RPM packages, as well as for installation from binary packages.

Note: Installation for a new instance of TheHive only is covered in this guide.

Dependencies#

Before proceeding with the installation, ensure that the following programs are already installed on your system:

  1. Open a terminal window.

  2. Run the following command to install the necessary dependencies:

    apt install wget gnupg apt-transport-https git ca-certificates ca-certificates-java curl software-properties-common python3-pip lsb-release
  1. Open a terminal window.

  2. Execute the following command to install the required dependencies:

    yum install pkg-install gnupg chkconfig python3-pip git

Ensure that all dependencies are successfully installed before proceeding with the TheHive installation process.

Java Virtual Machine#

Important Note:

  • For security and long-term support, it is mandatory to use Amazon Corretto builds, which are OpenJDK builds provided and maintained by Amazon.
  • Java version 8 is no longer supported.
  1. Open a terminal window.

  2. Execute the following commands:

    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"

  3. Verify the installation by running:

    java -version

  4. You should see output similar to the following:

    openjdk version "11.0.12" 2022-07-19
OpenJDK Runtime Environment Corretto-11.0.12.7.1 (build 11.0.12+7-LTS)
OpenJDK 64-Bit Server VM Corretto-11.0.12.7.1 (build 11.0.12+7-LTS, mixed mode)
  1. Open a terminal window.

  2. Execute the following commands:

    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-11-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"

  3. Verify the installation by running:

    java -version

  4. You should see output similar to the following:

    openjdk version "11.0.12" 2022-07-19
OpenJDK Runtime Environment Corretto-11.0.12.7.1 (build 11.0.12+7-LTS)
OpenJDK 64-Bit Server VM Corretto-11.0.12.7.1 (build 11.0.12+7-LTS, mixed mode)

If you are using a system other than DEB or RPM, please consult your system documentation for instructions on installing Java 11.

Apache Cassandra#

Apache Cassandra is a highly scalable and robust database system. TheHive is fully compatible with Apache Cassandra's latest stable release version 4.0.x.

Upgrading from Cassandra 3.x

The information provided in this guide pertains specifically to fresh installations. If you are currently using Cassandra 3.x and considering an upgrade, we recommend referring to the dedicated guide.

 

Installation#

  1. Add Apache Cassandra repository references

    • Download Apache Cassandra repository keys using the following command:
    wget -qO -  https://downloads.apache.org/cassandra/KEYS | sudo gpg --dearmor  -o /usr/share/keyrings/cassandra-archive.gpg
    • Add the repository to your system by appending the following line to the /etc/apt/sources.list.d/cassandra.sources.list file. This file may not exist, and you may need to create it.
    echo "deb [signed-by=/usr/share/keyrings/cassandra-archive.gpg] https://debian.cassandra.apache.org 40x main" |  sudo tee -a /etc/apt/sources.list.d/cassandra.sources.list

  2. Install the package

    • Once the repository references are added, update your package index and install Cassandra using the following commands:
    sudo apt update
sudo apt install cassandra

  1. Add Cassandra repository keys

    • To add Cassandra repository keys, execute the following command:
    rpm --import https://downloads.apache.org/cassandra/KEYS

  2. Add the Apache repository for Cassandra to /etc/yum.repos.d/cassandra.repo

    • To add the Apache repository configuration for Cassandra, you need to create a new file named /etc/yum.repos.d/cassandra.repo and add the following content to it:
    [cassandra]
name=Apache Cassandra
baseurl=https://redhat.cassandra.apache.org/40x/
gpgcheck=1
repo_gpgcheck=1
gpgkey=https://downloads.apache.org/cassandra/KEYS

    Note

    You can create the file and add the content using a text editor like nano or vim.

  3. Install the package

    • After adding the repository configuration, install Cassandra using the following command:
    sudo yum install cassandra

Download the tar.gz archive from Apache Cassandra Downloads and extract it into the folder of your choice. You can use utilities like wget to download the archive.

By default, data is stored in /var/lib/cassandra. Ensure appropriate permissions are set for this directory to avoid any issues with data storage and access.

 

Configuration#

You can configure Cassandra by modifying settings within the /etc/cassandra/cassandra.yaml file.

1.Locate the Cassandra Configuration File:

Navigate to the directory containing the Cassandra configuration file /etc/cassandra/.

2.Edit the cassandra.yaml File:

Open the cassandra.yaml file in a text editor with appropriate permissions.

3.Configure Cluster Name:

Set the cluster_name parameter to the desired name. This name helps identify the Cassandra cluster.

4.Configure Listen Address:

Set the listen_address parameter to the IP address of the node within the cluster. This address is used by other nodes within the cluster to communicate.

5.Configure RPC Address:

Set the rpc_address parameter to the IP address of the node to enable clients to connect to the Cassandra cluster.

6.Configure Seed Provider:

Ensure the seed_provider section is properly configured. The seeds parameter should contain the IP address(es) of the seed node(s) in the cluster.

7.Configure Directories:

Set the directories for data storage, commit logs, saved caches, and hints as per your requirements. Ensure that the specified directories exist and have appropriate permissions.

8.Save the Changes:

After making the necessary configurations, save the changes to the cassandra.yaml file.

/etc/cassandra/cassandra.yaml
# 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#

  1. Start the Service

    • Execute the following command to start the Cassandra service:
    sudo systemctl start cassandra

  2. Ensure Service Restarts After Reboot:

    • Enable the Cassandra service to restart automatically after a system reboot:
    sudo systemctl enable cassandra

  3. (Optional) Remove Existing Data Before Starting

    • If the Cassandra service was started automatically before configuring it, it's recommended to stop it, remove existing data, and restart it once the configuration is updated. Execute the following commands:
    sudo systemctl stop cassandra
sudo rm -rf /var/lib/cassandra/*

  1. Start the Service

    • Start the Cassandra service by running:
    sudo systemctl daemon-reload
sudo service cassandra start

  2. Ensure Service Restarts After Reboot

    • Enable the Cassandra service to restart automatically after a system reboot:
    sudo systemctl enable cassandra

Note

Cassandra defaults to listening on port 7000/tcp for inter-node communication and port 9042/tcp for client communication.

Elasticsearch#

Elasticsearch is a robust data indexing and search engine. It is used by TheHive to manage data indices efficiently.

Note

From Version 5.3, TheHive supports Elasticsearch 8.0 and 7.x. Previous TheHive versions only support Elasticsearch 7.x.

Note

Starting from TheHive 5.3, for advanced use-cases, OpenSearch is also supported.

 

Installation#

  1. Add Elasticsearch repository references

    • To add Elasticsearch repository keys, execute the following command:
    wget -qO - https://artifacts.elastic.co/GPG-KEY-elasticsearch |  sudo gpg --dearmor -o /usr/share/keyrings/elasticsearch-keyring.gpg
sudo apt-get install apt-transport-https
    • Add the repository to your system by appending the following line to the /etc/apt/sources.list.d/elastic-7.x.list file. This file may not exist, and you may need to create it
    echo "deb [signed-by=/usr/share/keyrings/elasticsearch-keyring.gpg] https://artifacts.elastic.co/packages/7.x/apt stable main" |  sudo tee /etc/apt/sources.list.d/elastic-7.x.list

  2. Install the package

    • Once the repository references are added, update your package index and install Elasticsearch using the following commands:
    sudo apt update
sudo apt install elasticsearch

  1. Add Elasticsearch repository references

    • To add Elasticsearch repository keys, execute the following command:
    rpm --import https://artifacts.elastic.co/GPG-KEY-elasticsearch

  2. Add the RPM repository of Elasticsearch to /etc/yum.repos.d/elasticsearch.repo

    • To add the repository configuration for Elasticsearcg, you need to create a new file named /etc/yum.repos.d/elasticsearch.repo and add the following content to it:
    /etc/yum.repos.d/elasticsearch.repo
    [elasticsearch]
name=Elasticsearch repository for 7.x packages
baseurl=https://artifacts.elastic.co/packages/7.x/yum
gpgcheck=1
gpgkey=https://artifacts.elastic.co/GPG-KEY-elasticsearch
enabled=0
autorefresh=1
type=rpm-md

  3. Install the package

    • After adding the repository configuration, install Elasticsearch using the following command:
    sudo yum install --enablerepo=elasticsearch elasticsearch

Please refer to the official Elasticsearch documentation website for the most up-to-date instructions: https://www.elastic.co/guide/en/elasticsearch/reference/current/rpm.html

Download the tar.gz archive from http://cassandra.apache.org/download/ and extract it into the folder of your choice. You can use utilities like wget to download the archive.

 

Configuration#

You can configure Elasticsearch by modifying settings within the /etc/elasticsearch/elasticsearch.yml file.

1. Locate the Elasticsearch Configuration File:

  • Navigate to the directory containing the Elasticsearch configuration file /etc/elasticsearch/.

2. Edit the elasticsearch.yml File:

  • Open the elasticsearch.yml file in a text editor with appropriate permissions.

3. Configure HTTP and Transport Hosts:

  • Set the http.host and transport.host parameters to 127.0.0.1 or the desired IP address.

4. Configure Cluster Name:

  • Set the cluster.name parameter to the desired name. This name helps identify the Elasticsearch cluster.

5. Configure Thread Pool Search Queue Size:

  • Set the thread_pool.search.queue_size parameter to the desired value, such as 100000.

6. Configure Paths for Logs and Data:

  • Set the path.logs and path.data parameters to the desired directories, such as "/var/log/elasticsearch" and "/var/lib/elasticsearch", respectively.

7. Configure X-Pack Security (Optional):

  • If you're not using X-Pack security, ensure that xpack.security.enabled is set to false.

8. Configure Script Allowed Types (Optional):

  • If needed, set the script.allowed_types parameter to specify allowed script types.

9. Save the Changes:

  • After making the necessary configurations, save the changes to the elasticsearch.yml file.

10. Custom JVM Options:

  • Create the file /etc/elasticsearch/jvm.options.d/jvm.options if it doesn't exist.

11. Custom JVM Options:

  • Inside jvm.options, add the desired JVM options, such as:

    -Dlog4j2.formatMsgNoLookups=true
-Xms4g
-Xmx4g

    Adjust the memory settings (-Xms and -Xmx) according to the available memory.

/etc/elasticsearch/elasticsearch.yml
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"

Info

  • Index creation occurs during TheHive's initial startup, which may take some time to complete.
  • Similar to data and files, indexes should be included in the backup policy to ensure their preservation.
  • Indexes can be removed and re-created as needed.

 

Start the service#

  1. Start the Service

    • Execute the following command to start the Elasticsearch service:
    sudo systemctl start elasticsearch

  2. Ensure Service Restarts After Reboot:

    • Enable the Elasticsearch service to restart automatically after a system reboot:
    sudo systemctl enable elasticsearch

  3. (Optional) Remove Existing Data Before Starting

    • If the Elasticsearch service was started automatically before configuring it, it's recommended to stop it, remove existing data, and restart it once the configuration is updated. Execute the following commands:
    sudo systemctl stop elasticsearch
sudo rm -rf /var/lib/elasticsearch/*

  1. Start the Service

    • Start the Elasticsearch service by running:
    sudo systemctl daemon-reload
sudo service elasticsearch start

  2. Ensure Service Restarts After Reboot

    • Enable the Elasticsearch service to restart automatically after a system reboot:
    sudo systemctl enable elasticsearch

File Storage#

For standalone production and test servers, we recommend using the local filesystem. However, if you are considering building a cluster with TheHive, there are several possible solutions available, including NFS or S3 services. For further details and an example involving MinIO servers, please refer to the related guide.

To utilize the local filesystem for file storage, begin by selecting a dedicated folder. By default, this folder is located at /opt/thp/thehive/files:

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

This path will be utilized in the configuration of TheHive. After installing TheHive, it's important to ensure that the user thehive owns the chosen path for storing files:

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

Detailed documentation on the installation, configuration, and usage of Min.IO can be found in this documentation.

TheHive Installation and Configuration#

This section provides detailed instructions for installing and configuring TheHive.

 

Installation#

All required packages are available on our package repository. We support Debian and RPM packages, as well as binary packages in zip format. All packages are signed using our GPG key 562CBC1C with the fingerprint 0CD5 AC59 DE5C 5A8E 0EE1 3849 3D99 BB18 562C BC1C.

For Debian systems, use the following commands:

wget -O- https://raw.githubusercontent.com/StrangeBeeCorp/Security/main/PGP%20keys/packages.key | sudo gpg --dearmor -o /usr/share/keyrings/strangebee-archive-keyring.gpg

For RPM-based systems, follow these steps:

sudo rpm --import https://raw.githubusercontent.com/StrangeBeeCorp/Security/main/PGP%20keys/packages.key

Install TheHive package by using the following commands:

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

  1. Import the RPM repository key:

    sudo rpm --import https://raw.githubusercontent.com/StrangeBeeCorp/Security/main/PGP%20keys/packages.key

  2. Create and edit the file /etc/yum.repos.d/strangebee.repo:

    /etc/yum.repos.d/strangebee.repo
    [thehive]
enabled=1
priority=1
name=StrangeBee RPM repository
baseurl=https://rpm.strangebee.com/thehive-5.4/noarch/
gpgkey=https://raw.githubusercontent.com/StrangeBeeCorp/Security/main/PGP%20keys/packages.key
gpgcheck=1

  3. Then install the package using yum:

    sudo yum install thehive

If you prefer a binary package, follow these steps:

  1. Download and unzip the chosen binary package. TheHive files can be installed wherever you want on the filesystem. In this guide, we assume you have chosen to install them under /opt.

    cd /opt
wget https://archives.strangebee.com/zip/thehive-latest.zip
unzip thehive-latest.zip
sudo ln -s thehive-x.x.x thehive

  2. Prepare the system. It is recommended to use a dedicated, non-privileged user account to start TheHive. If so, make sure that the chosen account can create log files in /opt/thehive/logs.

    sudo addgroup thehive
sudo adduser --system thehive
sudo chown -R thehive:thehive /opt/thehive
sudo mkdir /etc/thehive
sudo touch /etc/thehive/application.conf
sudo chown root:thehive /etc/thehive
sudo chgrp thehive /etc/thehive/application.conf
sudo chmod 640 /etc/thehive/application.conf

  3. Copy the systemd script in /etc/systemd/system/thehive.service.

    cd /tmp
wget https://raw.githubusercontent.com/TheHive-Project/TheHive/master/package/thehive.service
sudo cp thehive.service /etc/systemd/system/thehive.service

 

Configuration#

The setup provided with binary packages is tailored for a standalone installation, with all components hosted on the same server. At this point, it's crucial to fine-tune the following parameters as necessary:

/etc/thehive/application.conf
[..]
# Service configuration
application.baseUrl = "http://localhost:9000" # (1)
play.http.context = "/"                       # (2)
[..]
  1. Define the scheme, hostname, and port for accessing the application
  2. Indicate if a custom path is being used (default is /)

The following configurations are necessary for successful initiation of TheHive:

  • Secret key configuration
  • Database configuration
  • File storage configuration

 

Secret key configuration#

The secret key is automatically generated and stored in /etc/thehive/secret.conf during package installation.

The secret key is automatically generated and stored in /etc/thehive/secret.conf during package installation.

To set up a secret key, execute the following command:

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 local Cassandra and Elasticsearch databases.

/etc/thehive/application.conf
# 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#

The default file storage location of TheHive is /opt/thp/thehive/files.

If you decide to store files on the local filesystem:

  1. Ensure thehive user has permissions on the destination folder:

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

  2. Default values in the configuration file

    /etc/thehive/application.conf
    # Attachment storage configuration
# By default, TheHive is configured to store files locally in the folder.
# The path can be updated and should belong to the user/group running thehive service. (by default: thehive:thehive)
storage {
provider = localfs
localfs.location = /opt/thp/thehive/files
}

If you opt for MinIO and an S3 object storage system to store files in a filesystem, append the following lines to TheHive configuration file (/etc/thehive/application.conf):

/etc/thehive/application.conf
## 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#

The initial configuration file packaged with the software contains the following lines, which enable the Cortex and MISP modules by default. If you're not utilizing either of these modules, you can simply comment out the corresponding line and restart the service.

/etc/thehive/application.conf
# 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#

To start TheHive service and enable it to run on system boot, execute the following commands in your terminal:

sudo systemctl start thehive
sudo systemctl enable thehive

Please be aware that the service may take some time to start initially.

After the service has successfully started, launch your web browser and navigate to http://YOUR_SERVER_ADDRESS:9000/

The default admin user credentials are as follows:

Username: admin@thehive.local
Password: secret

For security reasons, it is strongly advised to change the default password after logging in.

Advanced Configuration#

For further customization options, please consult the Configuration & Operations section.

To configure HTTPS, follow the instructions on the dedicated page.