Skip to content

Upgrade from TheHive 5.x#

Important: Starting with version 5.4, our web framework has been upgraded to Play3/Pekko. Depending on your TheHive installation and configuration, certain updates may be required in your configuration files. Refer to the configuration guide for details.

Cortex support

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

Important considerations#

Before proceeding with the upgrade, please keep the following points in mind:

  1. Database Backup: We strongly recommend performing a full database backup before upgrading. For detailed instructions on how to perform a backup, please refer to the backup instructions.

  2. Downgrade Limitation: Once upgraded to TheHive 5.5, your instance can't be downgraded. This means reverting to a previous version of TheHive 5 will require restoring your data from the backup.

  3. When upgrading an existing TheHive 5.x instance, the first application launch will trigger a database evolution, including schema and data updates. This operation may take some time depending on your database size.

  4. Since version 5.1, TheHive no longer supports the Lucene backend as the index engine. Lucene was an option for handling data indexing with TheHive 4.1.x. To migrate your index to Elasticsearch, please follow the provided guide.

Overview#

This guide provides step-by-step instructions for upgrading an existing TheHive 5.x instance to TheHive 5.5.x.

Upgrade instructions#

TheHive packages are distributed as RPM and DEB files 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.

Alternatively, you can deploy TheHive using Docker images.

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.8-1_all.deb https://thehive.download.strangebee.com/5.5/deb/thehive_5.5.8-1_all.deb
wget -O /tmp/thehive_5.5.8-1_all.deb.sha256 https://thehive.download.strangebee.com/5.5/sha256/thehive_5.5.8-1_all.deb.sha256
wget -O /tmp/thehive_5.5.8-1_all.deb.asc https://thehive.download.strangebee.com/5.5/asc/thehive_5.5.8-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.8-1_all.deb https://thehive.download.strangebee.com/5.5/deb/thehive_5.5.8-1_all.deb
curl -o /tmp/thehive_5.5.8-1_all.deb.sha256 https://thehive.download.strangebee.com/5.5/sha256/thehive_5.5.8-1_all.deb.sha256
curl -o /tmp/thehive_5.5.8-1_all.deb.asc https://thehive.download.strangebee.com/5.5/asc/thehive_5.5.8-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.8-1_all.deb

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

      cat /tmp/thehive_5.5.8-1_all.deb.sha256

      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.8-1_all.deb.asc /tmp/thehive_5.5.8-1_all.deb

      d. Expected result.

      You should see output similar to:

      gpg: Good signature from "TheHive Project (TheHive release key) <support@thehive-project.org>"

      The key fingerprint must match: 0CD5 AC59 DE5C 5A8E 0EE1 3849 3D99 BB18 562C BC1C

      Expected GPG warning

      gpg: WARNING: This key is not certified with a trusted signature!
gpg:          There is no indication that the signature belongs to the owner.
      This warning is expected. It means the package is signed with the official TheHive release key, but you haven't marked this key as trusted in your local GPG setup. As long as you see Good signature and the fingerprint matches, the verification is successful. Don't mark our key as globally trusted—the warning is a normal safety reminder and should remain visible.

      If you don't see Good signature, if the fingerprint differs, or if the signature is reported as BAD, don't install the package. This indicates the integrity or authenticity of the file 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.8-1_all.deb

    • Using dpkg:

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

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.8-1.noarch.rpm https://thehive.download.strangebee.com/5.5/rpm/thehive-5.5.8-1.noarch.rpm
wget -O /tmp/thehive-5.5.8-1.noarch.rpm.sha256 https://thehive.download.strangebee.com/5.5/sha256/thehive-5.5.8-1.noarch.rpm.sha256
wget -O /tmp/thehive-5.5.8-1.noarch.rpm.asc https://thehive.download.strangebee.com/5.5/asc/thehive-5.5.8-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.8-1.noarch.rpm https://thehive.download.strangebee.com/5.5/rpm/thehive-5.5.8-1.noarch.rpm
curl -o /tmp/thehive-5.5.8-1.noarch.rpm.sha256 https://thehive.download.strangebee.com/5.5/sha256/thehive-5.5.8-1.noarch.rpm.sha256
curl -o /tmp/thehive-5.5.8-1.noarch.rpm.asc https://thehive.download.strangebee.com/5.5/asc/thehive-5.5.8-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.8-1.noarch.rpm

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

      cat /tmp/thehive-5.5.8-1.noarch.rpm.sha256

      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.8-1.noarch.rpm.asc /tmp/thehive-5.5.8-1.noarch.rpm

      d. Expected result.

      You should see output similar to:

      gpg: Good signature from "TheHive Project (TheHive release key) <support@thehive-project.org>"

      The key fingerprint must match: 0CD5 AC59 DE5C 5A8E 0EE1 3849 3D99 BB18 562C BC1C

      Expected GPG warning

      gpg: WARNING: This key is not certified with a trusted signature!
gpg:          There is no indication that the signature belongs to the owner.
      This warning is expected. It means the package is signed with the official TheHive release key, but you haven't marked this key as trusted in your local GPG setup. As long as you see Good signature and the fingerprint matches, the verification is successful. Don't mark our key as globally trusted—the warning is a normal safety reminder and should remain visible.

      If you don't see Good signature, if the fingerprint differs, or if the signature is reported as BAD, don't install the package. This indicates the integrity or authenticity of the file 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.8-1.noarch.rpm

    • Using dnf to manage dependencies automatically:

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

    • Using rpm:

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

Update your existing TheHive 5.x Docker stack (docker-compose file or similar) using the image named strangebee/thehive:5.5

Important note

Ensure that you update your Docker tags accordingly. The strangebee/thehive:latest tag is deprecated and remains associated with TheHive 5.0.x versions. A new strangebee/thehive:5.5 tag is now available and associated with the latest 5.5.x version.

Health checks#

If you have health checks on the application HTTP interface, they should be disabled during the upgrade process. Otherwise, the orchestrator may kill TheHive during the update process.