Step-by-Step Guide

This topic provides a comprehensive installation and configuration guide to set up a new instance of TheHive. It includes detailed instructions with examples for systems using DEB and RPM packages, and for installation from ZIP binary packages.

New instance only

This guide covers the installation process for setting up a new instance of TheHive only.

---

Dependencies

Before proceeding, install the following dependencies:

DEBRPM

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 gnupg chkconfig python3-pip git
   

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

---

Java Virtual Machine

Java support

• For security and long-term support, you must use Amazon Corretto, which provides OpenJDK builds maintained by Amazon.
• Java version 8 is no longer supported.

DEBRPMOther

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're using a system other than DEB or RPM, refer to 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 version 4.1.x.

Upgrading from Cassandra 3.x

This guide targets fresh installations. If you're currently using Cassandra 3.x and planning an upgrade, refer to the Upgrade from TheHive 4.x topic.

Installation

DEBRPMOther installation methods

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 41x main" |  sudo tee -a /etc/apt/sources.list.d/cassandra.sources.list 
   

2. Once the repository references are added, update your package index and install Cassandra using the following command:

   sudo apt update
   sudo apt install cassandra
   

1. Add Cassandra repository keys using the following command:

   rpm --import https://downloads.apache.org/cassandra/KEYS
   

2. Add the Apache repository configuration for Cassandra to a new file named /etc/yum.repos.d/cassandra.repoand add the following content to it:

   [cassandra]
   name=Apache Cassandra
   baseurl=https://redhat.cassandra.apache.org/41x/
   gpgcheck=1
   repo_gpgcheck=1
   gpgkey=https://downloads.apache.org/cassandra/KEYS
   

   Using a text editor

   You can create the file and add the content using a text editor such as nano or Vim.

3. 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. Set appropriate permissions for this directory to avoid any issues with data storage and access.

Configuration

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. Other nodes within the cluster use this address 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 addresses of the seed nodes in the cluster.

7.Configure directories:

Set the directories for data storage, commit logs, saved caches, and hints 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

DEBRPM

1. Execute the following command to start the Cassandra service:

   sudo systemctl start cassandra
   

2. Enable the Cassandra service to restart automatically after a system reboot:

   sudo systemctl enable cassandra
   

3. Optional: If the Cassandra service was started automatically before configuring it, 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 Cassandra service by running:

   sudo systemctl daemon-reload
   sudo service cassandra start
   

2. Enable the Cassandra service to restart automatically after a system reboot:

   sudo systemctl enable cassandra
   

Default ports for Cassandra communication

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

---

Elasticsearch

Elasticsearch is a robust data indexing and search engine. TheHive uses it to manage data indices efficiently.

5.5 Elasticsearch can also replace Apache Cassandra (JanusGraph) for storing audit logs.

Elasticsearch support

Starting from version 5.3, TheHive supports Elasticsearch 8.0 and 7.x. Earlier versions only support Elasticsearch 7.x. If you want to use Elasticsearch to store your audit logs, ensure that you are using Elasticsearch 7.17 or later.

OpenSearch support

Starting from version 5.3, TheHive supports OpenSearch for advanced use cases, except for audit log storage.

Elasticsearch authentication permissions

The account used for authenticating with Elasticsearch must have the manage cluster privilege. This is a mandatory configuration for TheHive to function correctly. If you are using an existing Elasticsearch instance, ensure it complies with your internal security policies, as certain configurations might be incompatible. Additionally, the account must have the all indices privilege, specifically for the thehive* indices.

Installation

DEBRPMOther installation methods

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. Once the repository references are added, update your package index and install Elasticsearch using the following command:

   sudo apt update
   sudo apt install elasticsearch
   

1. Add Elasticsearch repository keys using following command:

   rpm --import https://artifacts.elastic.co/GPG-KEY-elasticsearch
   

2. Add the RPM repository of Elasticsearch to 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. 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. (Optional) Configure X-Pack security:

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

8. (Optional) Configure script allowed types:

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:

!!! Example ""
    ```
    -Dlog4j2.formatMsgNoLookups=true
    -Xms4g
    -Xmx4g
    ```

!!! tip "Memory settings"
    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"

Index creation and management in TheHive

• Index creation occurs during TheHive's initial startup, which may take some time to complete.
• Similar to data and files, include indexes in the backup policy to ensure their preservation.
• Remove and re-create indexes as needed.

12. 5.5 (Optional) Configure audit log storage:

By default, TheHive stores audit logs in Apache Cassandra via JanusGraph. However, if your organization generates a large volume of audit logs, you can switch to Elasticsearch.

Elasticsearch offers better performance, reduced latency, and advanced search capabilities, making it ideal for managing and retrieving large amounts of audit data.

Audit logs visibility

• With Elasticsearch, audit logs retain the visibility they had at the time of creation, regardless of the current visibility of the case. This means that even if you set restricted visibility for a case, audit logs remain visible to all users who originally had access.
• With the default configuration using Apache Cassandra (JanusGraph), audit logs immediately become private if the visibility of the associated case is restricted. This means that even if audit logs were originally public, they will be hidden from all users once the case visibility is restricted.

Prerequisites

Regularly back up your Elasticsearch indices to ensure you can recover audit logs in the event of an incident. This is critical for maintaining the integrity and availability of your data.

a. Activate audit log storage.

To activate audit log storage in Elasticsearch, update your TheHive configuration file with the following settings:

audit {
  storage = elasticsearch
}

b. Optional: Configure index template and Index Lifecycle Management (ILM).

Configure the default index template and Index Lifecycle Management (ILM) for thehive-audits using the following settings:

• index-name
• health-request-timeout
• create.ext.number_of_replicas
• create.ext.number_of_shards
• request-timeout
• hot.rollover.maxAge
• hot.rollover.maxSize
• delete.minAge

Index name

The index name shouldn't be the same as the one used in JanusGraph. If you don’t configure a specific name, TheHive uses the JanusGraph index name appended with the suffix -audits.

Index template

The index template ensures consistent storage and indexing of audit logs.

Default index template:

{
  "index": {
    "lifecycle": {
      "name": "thehive-audits"
    },
    "number_of_shards": "1",
    "number_of_replicas": "1"
  }
}

ILM

TheHive automatically generates an Index Lifecycle Management (ILM) policy based on your configuration settings. ILM manages the storage, rollover, and deletion of audit logs over time to optimize long-term storage.

Default generated ILM:

{
  "policy": {
    "phases": {
      "hot": {
        "min_age": "0ms",
        "actions": {
          "set_priority": {
            "priority": 100
          }
        }
      }
    }
  }
}

Example

To create a new index every day or when it reaches 1 GB, and retain it for 7 days, use the following configuration:

• Index template:

audit {
    storage = elasticsearch
    elasticsearch {
        hot.rollover {
            maxAge = 1d
            maxSize = 1g
        }
        delete.minAge = 7d
    }
}

• The generated ILM:

{
    "policy": {
        "phases": {
            "hot": {
                "min_age": "0ms",
                "actions": {
                    "set_priority": {
                        "priority": 100
                    },
                    "rollover": {
                        "max_primary_shard_size": "1gb",
                        "max_age": "1d"
                    }
                }
            },
            "delete": {
                "min_age": "7d",
                "actions": {
                    "delete": {
                        "delete_searchable_snapshot": true
                    }
                }
            }
        }
    }
}

API calls changes

After migrating to Elasticsearch, the following Query API calls no longer work with audit logs stored in Elasticsearch:

• listAudit
• listAuditFromObject
• getAudit

Instead, use the following API endpoints:

• /api/v1/audit/list
• /api/v1/audit/count
• /api/v1/audit/$ID

These API calls are currently available but not yet officially documented and may change in future releases.

Start the service

DEBRPM

1. Execute the following command to start the Elasticsearch service:

   sudo systemctl start elasticsearch
   

2. Enable the Elasticsearch service to restart automatically after a system reboot:

   sudo systemctl enable elasticsearch
   

3. Optional: If the Elasticsearch service was started automatically before configuring it, 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 Elasticsearch service by running:

   sudo systemctl daemon-reload
   sudo service elasticsearch start
   

2. Enable the Elasticsearch service to restart automatically after a system reboot:

   sudo systemctl enable elasticsearch
   

---

File storage

For standalone production and test servers, use the local filesystem. However, if you are planning to build a cluster with TheHive, several solutions are available, including NFS or S3 services. For more details and an example using MinIO servers, refer to Setting up a Cluster.

Local filesystemS3 with MinIO

To use 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 MinIO can be found in the Setting up a Cluster topic.

---

TheHive installation and configuration

This section provides detailed instructions for installing and configuring TheHive.

Installation

TheHive packages are distributed as RPM and DEB files, as well as ZIP binary packages, all available for direct download via tools like Wget or cURL, with installation performed manually.

All packages are hosted on an HTTPS-secured website and come with a SHA256 checksum and a GPG signature for verification.

Prerequisites

Before starting this procedure, check that you have installed the following tools:

• Wget or cURL to download package files
• GPG to verify the package’s GPG signature
• sha256sum to check the SHA256 checksum of the downloaded package

DEBRPMZIP binary packages

Destination path

The commands below use /tmp/ as the download path. Replace it with the full local directory path where you want to save the files.

1. Download the installation package along with its SHA256 checksum and signature files.

   • Using Wget:

     wget -O /tmp/thehive_5.5.7-1_all.deb https://thehive.download.strangebee.com/5.5/deb/thehive_5.5.7-1_all.deb
     wget -O /tmp/thehive_5.5.7-1_all.deb.sha256 https://thehive.download.strangebee.com/5.5/sha256/thehive_5.5.7-1_all.deb.sha256
     wget -O /tmp/thehive_5.5.7-1_all.deb.asc https://thehive.download.strangebee.com/5.5/asc/thehive_5.5.7-1_all.deb.asc
     

     To download a specific version instead of the latest, use the following format:

     wget -O /tmp/<file_name>.deb https://thehive.download.strangebee.com/<major.minor_version>/deb/<file_name>.deb
     wget -O /tmp/<file_name>.deb.sha256 https://thehive.download.strangebee.com/<major.minor_version>/sha256/<file_name>.deb.sha256
     wget -O /tmp/<file_name>.deb.asc https://thehive.download.strangebee.com/<major.minor_version>/asc/<file_name>.deb.asc
     

     • Replace <file_name> with the full name of the versioned file you want to install. For example, use thehive_5.4.10-1_all.
     • Replace <major.minor_version> with the corresponding version directory. For example, use 5.4.

   • Using cURL:

     curl -o /tmp/thehive_5.5.7-1_all.deb https://thehive.download.strangebee.com/5.5/deb/thehive_5.5.7-1_all.deb
     curl -o /tmp/thehive_5.5.7-1_all.deb.sha256 https://thehive.download.strangebee.com/5.5/sha256/thehive_5.5.7-1_all.deb.sha256
     curl -o /tmp/thehive_5.5.7-1_all.deb.asc https://thehive.download.strangebee.com/5.5/asc/thehive_5.5.7-1_all.deb.asc
     

     To download a specific version instead of the latest, use the following format:

     curl -o /tmp/<file_name>.deb https://thehive.download.strangebee.com/<major.minor_version>/deb/<file_name>.deb
     curl -o /tmp/<file_name>.deb.sha256 https://thehive.download.strangebee.com/<major.minor_version>/sha256/<file_name>.deb.sha256
     curl -o /tmp/<file_name>.deb.asc https://thehive.download.strangebee.com/<major.minor_version>/asc/<file_name>.deb.asc
     

     • Replace <file_name> with the full name of the versioned file you want to install. For example, use thehive_5.4.10-1_all.
     • Replace <major.minor_version> with the corresponding version directory. For example, use 5.4.

2. Verify the integrity of the downloaded package.

   • Check the SHA256 checksum by comparing it with the provided value.

     a. Generate the SHA256 checksum of your downloaded package.

     sha256sum /tmp/thehive_5.5.7-1_all.deb
     

     b. Compare the output hash with the official SHA256 value listed in the .sha256 file.

     c. If both hashes match exactly, the file integrity is verified. If not, the file may be corrupted or tampered with—don't proceed with installation, and contact the StrangeBee Security Team.

   • Verify the GPG signature using the public key.

     a. Download the public key at keys.download.strangebee.com using Wget or cURL.

     wget -O /tmp/strangebee.gpg https://keys.download.strangebee.com/latest/gpg/strangebee.gpg
     

     curl -o /tmp/strangebee.gpg https://keys.download.strangebee.com/latest/gpg/strangebee.gpg
     

     b. Import the key into your GPG keyring.

     gpg --import /tmp/strangebee.gpg
     

     c. Verify the downloaded package signature.

     gpg --verify /tmp/thehive_5.5.7-1_all.deb.asc /tmp/thehive_5.5.7-1_all.deb
     

     d. You should see a message stating indicating that the signature is valid and the package is authentic. If you see warnings or errors, don't install the package as its integrity or authenticity can't be confirmed. Report the issue to the StrangeBee Security Team.

3. Install the package.

   • Using apt-get to manage dependencies automatically:

     sudo apt-get install /tmp/thehive_5.5.7-1_all.deb
     

   • Using dpkg:

     sudo dpkg -i /tmp/thehive_5.5.7-1_all.deb
     

     Missing dependencies

     While using dpkg, you might encounter warnings about missing dependencies during installation. To resolve this, run the commands described in the Dependencies section of the installation guide.

4. When switching from the previous repository-based installation, remove the old repository to avoid stale configurations.

   Why you should remove the old repository

   Keeping the old repository configuration can cause your system to download outdated or conflicting packages during updates, potentially breaking your installation or causing unexpected behavior.

   sudo rm /etc/apt/sources.list.d/strangebee.list
   sudo apt-get update
   

Destination path

The commands below use /tmp/ as the download path. Replace it with the full local directory path where you want to save the files.

1. Download the installation package along with its SHA256 checksum and signature files.

   • Using Wget:

     wget -O /tmp/thehive-5.5.7-1.noarch.rpm https://thehive.download.strangebee.com/5.5/rpm/thehive-5.5.7-1.noarch.rpm
     wget -O /tmp/thehive-5.5.7-1.noarch.rpm.sha256 https://thehive.download.strangebee.com/5.5/sha256/thehive-5.5.7-1.noarch.rpm.sha256
     wget -O /tmp/thehive-5.5.7-1.noarch.rpm.asc https://thehive.download.strangebee.com/5.5/asc/thehive-5.5.7-1.noarch.rpm.asc
     

     To download a specific version instead of the latest, use the following format:

     wget -O /tmp/<file_name>.noarch.rpm https://thehive.download.strangebee.com/<major.minor_version>/rpm/<file_name>.noarch.rpm
     wget -O /tmp/<file_name>.noarch.rpm.sha256 https://thehive.download.strangebee.com/<major.minor_version>/sha256/<file_name>.noarch.rpm.sha256
     wget -O /tmp/<file_name>.noarch.rpm.asc https://thehive.download.strangebee.com/<major.minor_version>/asc/<file_name>.noarch.rpm.asc
     

     • Replace <file_name> with the full name of the versioned file you want to install. For example, use thehive-5.4.10-1.
     • Replace <major.minor_version> with the corresponding version directory. For example, use 5.4.

   • Using cURL:

     curl -o /tmp/thehive-5.5.7-1.noarch.rpm https://thehive.download.strangebee.com/5.5/rpm/thehive-5.5.7-1.noarch.rpm
     curl -o /tmp/thehive-5.5.7-1.noarch.rpm.sha256 https://thehive.download.strangebee.com/5.5/sha256/thehive-5.5.7-1.noarch.rpm.sha256
     curl -o /tmp/thehive-5.5.7-1.noarch.rpm.asc https://thehive.download.strangebee.com/5.5/asc/thehive-5.5.7-1.noarch.rpm.asc
     

     To download a specific version instead of the latest, use the following format:

     curl -o /tmp/<file_name>.noarch.rpm https://thehive.download.strangebee.com/<major.minor_version>/rpm/<file_name>.noarch.rpm
     curl -o /tmp/<file_name>.noarch.rpm.sha256 https://thehive.download.strangebee.com/<major.minor_version>/sha256/<file_name>.noarch.rpm.sha256
     curl -o /tmp/<file_name>.noarch.rpm.asc https://thehive.download.strangebee.com/<major.minor_version>/asc/<file_name>.noarch.rpm.asc
     

     • Replace <file_name> with the full name of the versioned file you want to install. For example, use thehive-5.4.10-1.
     • Replace <major.minor_version> with the corresponding version directory. For example, use 5.4.

2. Verify the integrity of the downloaded package.

   • Check the SHA256 checksum by comparing it with the provided value.

     a. Generate the SHA256 checksum of your downloaded package.

     sha256sum /tmp/thehive-5.5.7-1.noarch.rpm
     

     b. Compare the output hash with the official SHA256 value listed in the .sha256 file.

     c. If both hashes match exactly, the file integrity is verified. If not, the file may be corrupted or tampered with—don't proceed with installation, and contact the StrangeBee Security Team

   • Verify the GPG signature using the public key.

     a. Download the public key at keys.download.strangebee.com using Wget or cURL.

     wget -O /tmp/strangebee.gpg https://keys.download.strangebee.com/latest/gpg/strangebee.gpg
     

     curl -o /tmp/strangebee.gpg https://keys.download.strangebee.com/latest/gpg/strangebee.gpg
     

     b. Import the key into your GPG keyring.

     gpg --import /tmp/strangebee.gpg
     

     c. Verify the downloaded package signature.

     gpg --verify /tmp/thehive-5.5.7-1.noarch.rpm.asc /tmp/thehive-5.5.7-1.noarch.rpm
     

     d. You should see a message stating indicating that the signature is valid and the package is authentic. If you see warnings or errors, don't install the package as its integrity or authenticity can't be confirmed. Report the issue to the StrangeBee Security Team.

3. Install the package.

   • Using yum to manage dependencies automatically:

     sudo yum install /tmp/thehive-5.5.7-1.noarch.rpm
     

   • Using dnf to manage dependencies automatically:

     sudo dnf install /tmp/thehive-5.5.7-1.noarch.rpm
     

   • Using rpm:

     sudo rpm -ivh /tmp/thehive-5.5.7-1.noarch.rpm
     

     Missing dependencies

     While using rpm, you might encounter warnings about missing dependencies during installation. To resolve this, run the commands described in the Dependencies section of the installation guide.

4. When switching from the previous repository-based installation, deactivate the old repository to avoid stale configurations.

   Why you should deactivate the old repository

   Keeping the old repository configuration can cause your system to download outdated or conflicting packages during updates, potentially breaking your installation or causing unexpected behavior.

   a. Deactivate the repository.

   ```bash
   sudo yum-config-manager --disable strangebee
   ```
   

   b. Optional: Remove the repository file.

   ```bash
   sudo rm /etc/yum.repos.d/strangebee.repo
   sudo yum clean all
   ```
   

If you prefer more control over where TheHive is installed, need to use it in environments without package managers, or want to avoid dependency issues, you can install TheHive by downloading a ZIP binary package.

Destination path

The commands below use /opt/ as the download path. Replace it with the full local directory path where you want to save the files.

1. Download the binary package along with its SHA256 checksum and signature files. You can install TheHive anywhere on your filesystem.

   • Using Wget

     wget -O /opt/thehive-5.5.7-1.zip https://thehive.download.strangebee.com/5.5/zip/thehive-5.5.7-1.zip
     wget -O /opt/thehive-5.5.7-1.zip.sha256 https://thehive.download.strangebee.com/5.5/sha256/thehive-5.5.7-1.zip.sha256
     wget -O /opt/thehive-5.5.7-1.zip.asc https://thehive.download.strangebee.com/5.5/asc/thehive-5.5.7-1.zip.asc
     

     To download a specific version instead of the latest, use the following format:

     wget -O /opt/<file_name>.zip thehive.download.strangebee.com/<major.minor_version>/zip/<file_name>.zip
     wget -O /opt/<file_name>.zip.sha256 thehive.download.strangebee.com/<major.minor_version>/sha256/<file_name>.zip.sha256
     wget -O /opt/<file_name>.zip.asc thehive.download.strangebee.com/<major.minor_version>/asc/<file_name>.zip.asc
     

     • Replace <file_name> with the full name of the versioned file you want to install. For example, use thehive-5.4.10-1.
     • Replace <major.minor_version> with the corresponding version directory. For example, use 5.4.

   • Using cURL

     curl -o /opt/thehive-5.5.7-1.zip https://thehive.download.strangebee.com/5.5/zip/thehive-5.5.7-1.zip
     curl -o /opt/thehive-5.5.7-1.zip.sha256 https://thehive.download.strangebee.com/5.5/sha256/thehive-5.5.7-1.zip.sha256
     curl -o /opt/thehive-5.5.7-1.zip.asc https://thehive.download.strangebee.com/5.5/asc/thehive-5.5.7-1.zip.asc
     

     To download a specific version instead of the latest, use the following format:

     curl -o /opt/<file_name>.zip thehive.download.strangebee.com/<major.minor_version>/zip/<file_name>.zip
     curl -o /opt/<file_name>.zip.sha256 thehive.download.strangebee.com/<major.minor_version>/sha256/<file_name>.zip.sha256
     curl -o /opt/<file_name>.zip.asc thehive.download.strangebee.com/<major.minor_version>/asc/<file_name>.zip.asc
     

     • Replace <file_name> with the full name of the versioned file you want to install. For example, use thehive-5.4.10-1.
     • Replace <major.minor_version> with the corresponding version directory. For example, use 5.4.

2. Verify the integrity of the downloaded package.

   • Check the SHA256 checksum by comparing it with the provided value.

     a. Generate the SHA256 checksum of your downloaded package.

     sha256sum /opt/thehive-5.5.7-1.zip
     

     b. Compare the output hash with the official SHA256 value listed in the .sha256 file.

     c. If both hashes match exactly, the file integrity is verified. If not, the file may be corrupted or tampered with—don't proceed with unzipping or installation, and contact the StrangeBee Security Team.

   • Verify the GPG signature using the public key.

     a. Download the public key at keys.download.strangebee.com using Wget or cURL.

     wget -O /opt/strangebee.gpg https://keys.download.strangebee.com/latest/gpg/strangebee.gpg
     

     curl -o /opt/strangebee.gpg https://keys.download.strangebee.com/latest/gpg/strangebee.gpg
     

     b. Import the key into your GPG keyring.

     gpg --import /opt/strangebee.gpg
     

     c. Verify the downloaded package signature.

     gpg --verify /opt/thehive-5.5.7-1.zip.asc /opt/thehive-5.5.7-1.zip
     

     d. You should see a message stating indicating that the signature is valid and the package is authentic. If you see warnings or errors, don't unzip or install the package as its integrity or authenticity can't be confirmed. Report the issue to the StrangeBee Security Team.

3. Unzip the package.

   Unzip paths

   • Replace /opt/thehive-5.5.7-1.zip with the full path to the ZIP file you downloaded.
   • Replace /opt/ after -d with the directory where you want to extract the contents of the archive.

   unzip /opt/thehive-5.5.7-1.zip -d /opt/
   sudo ln -s /opt/thehive-5.5.7-1 /opt/thehive
   

4. Prepare the system by creating a dedicated, non-privileged user account to run TheHive. Ensure this user has permission to 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
   

5. Copy the systemd script into /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:

Configuring baseURL

Correct baseURL configuration is essential for TheHive. Make sure the baseURL exactly matches the URL users use to access TheHive, including the protocol and any path segments.

Incorrect configuration causes Single Sign-On (SSO) to fail.

/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

DEBRPMOther

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 and index

By default, TheHive configures 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.

Local filesystemS3

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 and 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.

Cortex support

5.5 Cortex 3.1.5 and earlier are no longer supported since version 5.5.

/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
# commenting 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

Service startup delay

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's strongly advised to change the default password after logging in.

---

Advanced configuration

For further customization options, please consult the Configuration and Operations sections.

To configure HTTPS, follow the instructions on SSL Configuration.

Next steps

• Database and Index Configuration
• File Storage Configuration
• TheHive Connectors
• Akka Configuration
• Pekko Configuration (TheHive 5.4+)
• Logs Configuration
• Proxy Settings
• Secret Configuration File
• SSL Configuration
• Service Configuration
• GDPR Compliance in TheHive 5.x