Skip to content

Upgrade Cortex to Version 4.1#

In this tutorial, you'll upgrade Cortex from version 3.1.x+ to 4.1.x.

Because Cortex can't support multiple major versions of Elasticsearch simultaneously, this upgrade requires moving from Elasticsearch 7.x to 8.x.

By the end, you'll have successfully upgraded both Elasticsearch to 8.x and Cortex to 4.1.x, with all services running and connected.

Shared Elasticsearch instance

If you share the same Elasticsearch instance between Cortex and TheHive, ensure that your TheHive version also supports Elasticsearch 8.x. If you're running TheHive 5.2.16 or earlier, upgrade TheHive at the same time as Cortex.

Maintenance window required

This procedure involves restarting services. Schedule a maintenance window to prevent service disruption.

Back up before upgrading

Before upgrading Cortex, create a complete backup of your data and configurations. See Back Up and Restore Data for detailed guidance.

This tutorial applies to single-node Elasticsearch instances.

Step 1: Stop Cortex service#

Before upgrading Elasticsearch, stop the Cortex service to prevent index writes during the process.

Service commands

For stop/restart commands depending on your installation method, refer back to the relevant installation guide.

Stop TheHive if sharing Elasticsearch

If you share your Elasticsearch instance with TheHive, stop TheHive as well before upgrading Elasticsearch to prevent data inconsistencies.

Step 2: Check the Elasticsearch version#

You can't upgrade directly from Elasticsearch versions earlier than 7.17.x to 8.x. Before continuing, confirm that your deployment is running Elasticsearch 7.17.x.

  1. Check your current Elasticsearch version:

    curl -X GET "localhost:9200"

    Look for the version.number field in the response.

  2. If your Elasticsearch version is earlier than 7.17.x, continue to the next step. If you're already on 7.17.x, skip to Step 4.

(Optional) Step 3: Upgrade Elasticsearch to 7.17.x#

If your current version is below 7.17.x, upgrade to the latest 7.17.x release before moving forward.

Follow the official Elasticsearch 7.17 upgrade guide to complete this upgrade.

Step 4: Prepare for Elasticsearch 8.x upgrade#

Now that you're running Elasticsearch 7.17.x, verify that all features and indexes are ready for migration to 8.x.

  1. Check upgrade compatibility using the Elasticsearch feature upgrade API.

    curl -X GET "localhost:9200/_migration/system_features"

  2. Review the response to ensure all features and indexes report as ready for upgrade.

    If any elements require action, follow the recommendations in the API response before proceeding.

Step 5: Upgrade Elasticsearch to 8.x#

With compatibility verified, you're ready to upgrade Elasticsearch to version 8.x.

  1. Follow the official Elasticsearch upgrade documentation to complete the upgrade.

    Automatic restart

    If you're using package-based or containerized installations, Elasticsearch restarts are handled automatically during the upgrade.

  2. Verify that Elasticsearch 8.x is running successfully.

    curl -X GET "localhost:9200"

    You should see version 8.x in the response.

Step 6: Upgrade Cortex to version 4.1.x#

With Elasticsearch 8.x running, you can now upgrade Cortex itself.

Download RPM, DEB, and ZIP packages directly with tools like wget or curl and install them manually. For Docker, redeploy with the StrangeBee Docker Compose profiles or pull an updated image tag.

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

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/cortex_4.1.0-1_all.deb https://cortex.download.strangebee.com/4.1/deb/cortex_4.1.0-1_all.deb
wget -O /tmp/cortex_4.1.0-1_all.deb.sha256 https://cortex.download.strangebee.com/4.1/sha256/cortex_4.1.0-1_all.deb.sha256
wget -O /tmp/cortex_4.1.0-1_all.deb.asc https://cortex.download.strangebee.com/4.1/asc/cortex_4.1.0-1_all.deb.asc

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

      wget -O /tmp/<file_name>.deb https://cortex.download.strangebee.com/<major.minor_version>/deb/<file_name>.deb
wget -O /tmp/<file_name>.deb.sha256 https://cortex.download.strangebee.com/<major.minor_version>/sha256/<file_name>.deb.sha256
wget -O /tmp/<file_name>.deb.asc https://cortex.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 cortex_3.2.1-2_all.
      • Replace <major.minor_version> with the corresponding version directory. For example, use 3.2.

      Package repository

      For details on package organization and naming conventions, see Cortex Package Repository.

    • Using curl:

      curl -o /tmp/cortex_4.1.0-1_all.deb https://cortex.download.strangebee.com/4.1/deb/cortex_4.1.0-1_all.deb
curl -o /tmp/cortex_4.1.0-1_all.deb.sha256 https://cortex.download.strangebee.com/4.1/sha256/cortex_4.1.0-1_all.deb.sha256
curl -o /tmp/cortex_4.1.0-1_all.deb.asc https://cortex.download.strangebee.com/4.1/asc/cortex_4.1.0-1_all.deb.asc

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

      curl -o /tmp/<file_name>.deb https://cortex.download.strangebee.com/<major.minor_version>/deb/<file_name>.deb
curl -o /tmp/<file_name>.deb.sha256 https://cortex.download.strangebee.com/<major.minor_version>/sha256/<file_name>.deb.sha256
curl -o /tmp/<file_name>.deb.asc https://cortex.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 cortex_3.2.1-2_all.
      • Replace <major.minor_version> with the corresponding version directory. For example, use 3.2.

      Package repository

      For details on package organization and naming conventions, see Cortex Package Repository.

  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/cortex_4.1.0-1_all.deb

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

      cat /tmp/cortex_4.1.0-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/cortex_4.1.0-1_all.deb.asc /tmp/cortex_4.1.0-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/cortex_4.1.0-1_all.deb

    • Using dpkg:

      sudo dpkg -i /tmp/cortex_4.1.0-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/cortex-4.1.0-1.noarch.rpm https://cortex.download.strangebee.com/4.1/rpm/cortex-4.1.0-1.noarch.rpm
wget -O /tmp/cortex-4.1.0-1.noarch.rpm.sha256 https://cortex.download.strangebee.com/4.1/sha256/cortex-4.1.0-1.noarch.rpm.sha256
wget -O /tmp/cortex-4.1.0-1.noarch.rpm.asc https://cortex.download.strangebee.com/4.1/asc/cortex-4.1.0-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://cortex.download.strangebee.com/<major.minor_version>/rpm/<file_name>.noarch.rpm
wget -O /tmp/<file_name>.noarch.rpm.sha256 https://cortex.download.strangebee.com/<major.minor_version>/sha256/<file_name>.noarch.rpm.sha256
wget -O /tmp/<file_name>.noarch.rpm.asc https://cortex.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 cortex-3.2.1-1.
      • Replace <major.minor_version> with the corresponding version directory. For example, use 3.2.

      Package repository

      For details on package organization and naming conventions, see Cortex Package Repository.

    • Using curl:

      curl -o /tmp/cortex-4.1.0-1.noarch.rpm https://cortex.download.strangebee.com/4.1/rpm/cortex-4.1.0-1.noarch.rpm
curl -o /tmp/cortex-4.1.0-1.noarch.rpm.sha256 https://cortex.download.strangebee.com/4.1/sha256/cortex-4.1.0-1.noarch.rpm.sha256
curl -o /tmp/cortex-4.1.0-1.noarch.rpm.asc https://cortex.download.strangebee.com/4.1/asc/cortex-4.1.0-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://cortex.download.strangebee.com/<major.minor_version>/rpm/<file_name>.noarch.rpm
curl -o /tmp/<file_name>.noarch.rpm.sha256 https://cortex.download.strangebee.com/<major.minor_version>/sha256/<file_name>.noarch.rpm.sha256
curl -o /tmp/<file_name>.noarch.rpm.asc https://cortex.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 cortex-3.2.1-1.
      • Replace <major.minor_version> with the corresponding version directory. For example, use 3.2.

      Package repository

      For details on package organization and naming conventions, see Cortex Package Repository.

  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/cortex-4.1.0-1.noarch.rpm

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

      cat /tmp/cortex-4.1.0-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/cortex-4.1.0-1.noarch.rpm.asc /tmp/cortex-4.1.0-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/cortex-4.1.0-1.noarch.rpm

    • Using dnf to manage dependencies automatically:

      sudo dnf install /tmp/cortex-4.1.0-1.noarch.rpm

    • Using rpm:

      sudo rpm -Uvh /tmp/cortex-4.1.0-1.noarch.rpm

If you prefer more control over where Cortex is installed, need to use it in environments without package managers, or want to avoid dependency issues, you can install Cortex 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 Cortex anywhere on your filesystem.

    • Using wget

      wget -O /opt/cortex/cortex-4.1.0-1.zip https://cortex.download.strangebee.com/4.1/zip/cortex-4.1.0-1.zip
wget -O /opt/cortex/cortex-4.1.0-1.zip.sha256 https://cortex.download.strangebee.com/4.1/sha256/cortex-4.1.0-1.zip.sha256
wget -O /opt/cortex/cortex-4.1.0-1.zip.asc https://cortex.download.strangebee.com/4.1/asc/cortex-4.1.0-1.zip.asc

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

      wget -O /opt/<file_name>.zip cortex.download.strangebee.com/<major.minor_version>/zip/<file_name>.zip
wget -O /opt/<file_name>.zip.sha256 cortex.download.strangebee.com/<major.minor_version>/sha256/<file_name>.zip.sha256
wget -O /opt/<file_name>.zip.asc cortex.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 cortex-3.2.1-2.
      • Replace <major.minor_version> with the corresponding version directory. For example, use 3.2.

      Package repository

      For details on package organization and naming conventions, see Cortex Package Repository.

    • Using curl

      curl -o /opt/cortex/cortex-4.1.0-1.zip https://cortex.download.strangebee.com/4.1/zip/cortex-4.1.0-1.zip
curl -o /opt/cortex/cortex-4.1.0-1.zip.sha256 https://cortex.download.strangebee.com/4.1/sha256/cortex-4.1.0-1.zip.sha256
curl -o /opt/cortex/cortex-4.1.0-1.zip.asc https://cortex.download.strangebee.com/4.1/asc/cortex-4.1.0-1.zip.asc

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

      curl -o /opt/<file_name>.zip cortex.download.strangebee.com/<major.minor_version>/zip/<file_name>.zip
curl -o /opt/<file_name>.zip.sha256 cortex.download.strangebee.com/<major.minor_version>/sha256/<file_name>.zip.sha256
curl -o /opt/<file_name>.zip.asc cortex.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 cortex-3.2.1-2.
      • Replace <major.minor_version> with the corresponding version directory. For example, use 3.2.

      Package repository

      For details on package organization and naming conventions, see Cortex Package Repository.

  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/cortex-4.1.0-1.zip

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

      cat /opt/cortex-4.1.0-1.zip.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 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/cortex-4.1.0-1.zip.asc /opt/cortex-4.1.0-1.zip

      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. Unzip the package.

    Unzip paths

    • Replace /opt/cortex-4.1.0-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/cortex-4.1.0-1.zip -d /opt/
sudo ln -s /opt/cortex-4.1.0-1 /opt/cortex

  4. Make the Cortex binary executable.

    cd /opt/
chmod +x cortex

If you deployed using the StrangeBee Docker Compose profiles, pull the latest version of the repository before redeploying. The docker-compose.yml, configuration templates, and helper scripts may have changed between versions. The version is set in the versions.env file at the root of the repository, with the cortex_image_version variable.

If you used the public image directly, update the image tag to thehiveproject/cortex:4.1, or to a specific version if you don't want the latest.

Step 7: Restart Cortex and verify connectivity#

You're now ready to bring Cortex back online and ensure everything connects properly.

  1. Restart the Cortex service.

  2. Verify that Cortex connects successfully to the upgraded Elasticsearch instance.

    Check the Cortex logs for successful connection messages and confirm that the application is available.

  3. Optional: Restart TheHive if you share the Elasticsearch instance.

    This restores full connectivity between TheHive and the upgraded Elasticsearch instance.

  4. Verify that both Cortex (and TheHive, if applicable) are functioning normally.

You've successfully upgraded Cortex to version 4.1.x with Elasticsearch 8.x. Your system is now running the latest versions and ready for use.

Next steps