Skip to content

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:

  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#

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

  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#

  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#

  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#

  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.

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.

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

    Destination path

    Replace /path/to/ with the full local directory path where you want to save the downloaded files.

    • Using Wget:

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

      Example:

      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.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
      
    • Using cURL:

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

      Example:

      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
      
  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 /path/to/<file_name>.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 /path/to/strangebee.gpg https://keys.download.strangebee.com/latest/gpg/strangebee.gpg
      
      curl -o /path/to/strangebee.gpg https://keys.download.strangebee.com/latest/gpg/strangebee.gpg
      

      b. Import the key into your GPG keyring.

      gpg --import /path/to/strangebee.gpg
      

      c. Verify the downloaded package signature.

      gpg --verify /path/to/<file_name>.deb.asc /path/to/<file_name>.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 /path/to/<file_name>.deb
      
    • Using dpkg:

      sudo dpkg -i /path/to/<file_name>.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
    
  1. Download the package along with its SHA256 checksum and signature files.

    Destination path

    Replace /path/to/ with the full local directory path where you want to save the downloaded files.

    • Using Wget:

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

      Example:

      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
      
    • Using cURL:

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

      Example:

      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
      
  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 /path/to/<file_name>.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 /path/to/strangebee.gpg https://keys.download.strangebee.com/latest/gpg/strangebee.gpg
      
      curl -o /path/to/strangebee.gpg https://keys.download.strangebee.com/latest/gpg/strangebee.gpg
      

      b. Import the key into your GPG keyring.

      gpg --import /path/to/strangebee.gpg
      

      c. Verify the downloaded package signature.

      gpg --verify /path/to/<file_name>.rpm.asc /path/to/<file_name>.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 /path/to/<file_name>.rpm
      
    • Using dnf to manage dependencies automatically:

      sudo dnf install /path/to/<file_name>.rpm
      
    • Using rpm:

      sudo rpm -ivh /path/to/<file_name>.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.

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

    Destination path

    Replace /path/to/ with the full local directory path where you want to save the downloaded files.

    • Using Wget

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

      Example:

      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
      
    • Using cURL

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

      Example:

      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
      
  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 /path/to/<file_name>.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 /path/to/strangebee.gpg https://keys.download.strangebee.com/latest/gpg/strangebee.gpg
      
      curl -o /path/to/strangebee.gpg https://keys.download.strangebee.com/latest/gpg/strangebee.gpg
      

      b. Import the key into your GPG keyring.

      gpg --import /path/to/strangebee.gpg
      

      c. Verify the downloaded package signature.

      gpg --verify /path/to/<file_name>.zip.asc /path/to/<file_name>.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 /path/to/<file_name>.zip with the full path to the ZIP file you downloaded.
    • Replace /path/to/ after -d with the directory where you want to extract the contents of the archive.
    unzip /path/to/<file_name>.zip -d /path/to/
    sudo ln -s /path/to/<file_name> /path/to/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 /path/to/thehive/logs.

    sudo addgroup thehive
    sudo adduser --system thehive
    sudo chown -R thehive:thehive /path/to/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#

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.

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