Skip to content

Install Cortex with Packages#

Welcome to the step-by-step guide for installing and configuring Cortex with packages!

This guide is designed for users who are comfortable with Linux system administration, but you don't need to be an infrastructure expert to follow along.

By the end, you'll have a fully functional instance of Cortex up and running.

Guide scope

This guide covers setting up a new instance of Cortex with packages, with all components hosted on the same server. This guide is illustrated with examples for Debian and RPM packages based systems and for installation from ZIP binary packages.

It doesn't cover:

Before you begin

To ensure a smooth installation process, make sure you have:

Step 1: Install required dependencies#

Start by installing the necessary dependencies for Cortex.

Run the following commands:

sudo apt update
sudo apt install wget curl gnupg coreutils apt-transport-https git ca-certificates ca-certificates-java software-properties-common python3-pip lsb-release unzip

Run the following commands:

sudo yum update
sudo yum install wget curl gnupg2 coreutils chkconfig python3-pip git unzip

Step 2: Set up the Java virtual machine (JVM)#

Cortex requires Java to run its application server and to manage various processes.

Manual installation required

Starting with Cortex 3.2, the Java virtual machine (JVM) is no longer installed automatically. You must manually install it before running Cortex.

Java support

  • For security and long-term support, use Amazon Corretto, which provides OpenJDK builds maintained by Amazon.
  • Corretto 11 or higher is required to install Cortex.

  1. Run 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"

  2. Verify the installation.

    java -version

    You should see output similar to the following:

    openjdk version "11.0.28" 2025-07-15
OpenJDK Runtime Environment Corretto-11.0.28.6.1 (build 11.0.28+6-LTS)
OpenJDK 64-Bit Server VM Corretto-11.0.28.6.1 (build 11.0.28+6-LTS, mixed mode)

    If a different Java version appears, set Java 11 as the default using sudo update-alternatives --config java.

  1. Run 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
sudo yum install -y 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"

    Adjusting for your distribution

    The exact commands may vary depending on your Linux distribution. Refer to your distribution documentation for the recommended way to install Java and adjust the steps accordingly.

  2. Verify the installation.

    java -version

    You should see output similar to the following:

    openjdk version "11.0.28" 2025-07-15
OpenJDK Runtime Environment Corretto-11.0.28.6.1 (build 11.0.28+6-LTS)
OpenJDK 64-Bit Server VM Corretto-11.0.28.6.1 (build 11.0.28+6-LTS, mixed mode)

    If a different Java version appears, set Java 11 as the default using sudo alternatives --config java.

If you're using a system other than DEB or RPM, refer to your system documentation for instructions on installing Java 11.

Step 3: Install and configure Elasticsearch#

Elasticsearch is a data indexing and search engine that's used in Cortex to store and manage all its data.

Single node configuration

In this guide, you will configure Elasticsearch as a single node on your server, which is fine for running Cortex.

Elasticsearch supported versions

Cortex

Cortex version Elasticsearch
4.x 8.x
3.2.1 and earlier 7.x

TheHive

TheHive version Elasticsearch
5.5.10 - 5.7.6 7.11.x - 9.1.x
5.5.0 - 5.5.9 7.11.x - 8.x
5.3.0 - 5.4.11 7.10.x - 8.x
5.0.0 - 5.2.16 7.2.x - 7.17.x

Sharing a single Elasticsearch instance between TheHive and Cortex isn't recommended. If you must do it, ensure the Elasticsearch version is compatible with both applications.

Step 3.1: Install Elasticsearch#

  1. Add Elasticsearch repository references.

    a. Download Elasticsearch repository keys.

    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

    b. Check if the /etc/apt/sources.list.d/elastic-8.x.list file exists. If it doesn't, create it.

    c. Add the repository to your system by appending the following line to the /etc/apt/sources.list.d/elastic-8.x.list file.

    echo "deb [signed-by=/usr/share/keyrings/elasticsearch-keyring.gpg] https://artifacts.elastic.co/packages/8.x/apt stable main" |  sudo tee /etc/apt/sources.list.d/elastic-8.x.list

  2. Update your package index and install Elasticsearch using the following commands:

    sudo apt update
sudo apt install elasticsearch

Refer to the official Elasticsearch documentation website for the most up-to-date instructions.

  1. Add Elasticsearch repository references.

    a. Download Elasticsearch repository keys.

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

    b. Check if the /etc/yum.repos.d/elasticsearch.repo file exists. If it doesn't, create it.

    c. Add the repository to your system by appending the following line to the /etc/yum.repos.d/elasticsearch.repo file.

    echo "[elasticsearch]
name=Elasticsearch repository for 8.x packages
baseurl=https://artifacts.elastic.co/packages/8.x/yum
gpgcheck=1
gpgkey=https://artifacts.elastic.co/GPG-KEY-elasticsearch
enabled=0" | sudo tee /etc/yum.repos.d/elasticsearch.repo

  2. Update your package index and install Elasticsearch using the following commands:

    sudo yum -y update
sudo yum install --enablerepo=elasticsearch elasticsearch

Refer to the official Elasticsearch documentation website for the most up-to-date instructions.

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

Step 3.2: Configure Elasticsearch#

Configure the /etc/elasticsearch/elasticsearch.yml file#

  1. Open the /etc/elasticsearch/elasticsearch.yml file using a text editor.

  2. In the elasticsearch.yml file, set the cluster.name parameter to the desired name. This name will help identify your Elasticsearch cluster.

    Replace my-application with your new cluster name.

    Default commented line

    This line is commented out by default. Uncomment it to ensure your new value is applied.

  3. In the elasticsearch.yml file, set the thread_pool.search.queue_size to the desired number. This parameter controls how many search requests Elasticsearch can queue at the same time. If the queue is full, new requests will wait or be rejected.

    Add the following line (or edit it if it already exists):

    thread_pool.search.queue_size: <requests_limit>

    Replace <requests_limit> with the number of requests you want to allow in the queue. For example, you can use 100000 for a single-node setup.

  4. Optional: In the elasticsearch.yml file, change the default directory path values for the path.data and path.logs parameters. That tells Elasticsearch where to store its data and logs.

    Parameter Default directory path value
    path.data /var/lib/elasticsearch
    path.logs /var/log/elasticsearch

  5. Recommended: Activate X-Pack security. It controls authentication, encryption, and other security features in Elasticsearch.

    In the elasticsearch.yml file, add the desired security parameters from the official Elasticsearch security settings documentation.

    At minimum add the following line (or edit it if it already exists):

    xpack.security.enabled: true

    Deactivating X-Pack security

    You can deactivate X-Pack security by setting xpack.security.enabled: false, but this is strongly discouraged—especially in production environments. Doing so leaves your Elasticsearch instance unprotected against unauthorized access and compromises the security of your entire Cortex deployment.

  6. Optional: In the elasticsearch.yml file, set the script.allowed_types parameter. This controls what types of scripts Elasticsearch is allowed to run for calculations, aggregations, or custom logic on your data.

    By default, Elasticsearch allows both inline and stored scripts. For a standard single-node setup, you usually don't need to change this.

    You can restrict this if you want to allow only one type—or none by adding the following line (or edit it if it already exists):

    script.allowed_types: <allowed_type>

    Replace <allowed_type> with the type you want to allow: inline, stored, or none.

  7. Save your modifications in the elasticsearch.yml file.

Example of a elasticsearch.yml file configuration

# content from /etc/elasticsearch/elasticsearch.yml
[..]
cluster.name: cortex
thread_pool.search.queue_size: 100000
path.logs: "/var/log/elasticsearch"
path.data: "/var/lib/elasticsearch"
xpack.security.enabled: true
script.allowed_types: "inline,stored"
[..]

Configure JVM options for Elasticsearch#

The Java virtual machine (JVM) is what runs Elasticsearch. The JVM options control how much memory Elasticsearch can use, how it manages that memory, and other performance-related settings. By default, Java determines heap size automatically, which isn't recommended for production environments and may cause memory contention or out-of-memory errors.

  1. Check if the /etc/elasticsearch/jvm.options.d/jvm.options exists. If it doesn't, create it.

  2. Open the /etc/elasticsearch/jvm.options.d/jvm.options file using a text editor.

  3. In the jvm.options file, set the JVM options.

    Heap size guidelines for Elasticsearch

    Heap allocation must not exceed 50% of the available RAM. Available RAM refers to the memory remaining after accounting for the operating system and other services running on the same host.

    -Dlog4j2.formatMsgNoLookups=true
-Xms<heap_size>
-Xmx<heap_size>

    Replace <heap_size> with the desired heap size. Xms sets the initial heap size, and Xmx the maximum heap size.

    Set initial and maximum heap to the same value

    Set -Xms and -Xmx to the same value to prevent heap resizing at runtime and reduce CPU overhead.

    Deactivate memory swapping

    Memory swapping on the host running Elasticsearch degrades performance: garbage collection and cluster communication then depend on disk speed instead of RAM. Deactivate swap entirely, or set bootstrap.memory_lock: true in elasticsearch.yml to lock the JVM heap in RAM. See Disable swapping in the official Elasticsearch documentation.

  4. Save your modifications in the jvm.options file.

Step 3.3: Start the Elasticsearch service#

  1. Check whether the Elasticsearch service started automatically before configuring it.

    sudo systemctl status elasticsearch

    If it's running, stop it and remove existing data.

    sudo systemctl stop elasticsearch
sudo rm -rf /var/lib/elasticsearch/*

  2. Start the Elasticsearch service.

    sudo systemctl start elasticsearch

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

    sudo systemctl enable elasticsearch

  4. Verify that Elasticsearch is running.

    sudo systemctl status elasticsearch

    If Elasticsearch is running, you should see an active status in green.

  1. Check whether the Elasticsearch service started automatically before configuring it.

    sudo systemctl status elasticsearch

    If it's running, stop it and remove existing data.

    sudo systemctl stop elasticsearch
sudo rm -rf /var/lib/elasticsearch/*

  2. Start the Elasticsearch service by running the following commands:

    sudo systemctl daemon-reload
sudo systemctl start elasticsearch

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

    sudo systemctl enable elasticsearch

  4. Verify that Elasticsearch is running.

    sudo systemctl status elasticsearch

    If Elasticsearch is running, you should see an active status in green.

Troubleshooting Elasticsearch

  • Service not starting → Check /var/log/elasticsearch/ for JVM errors or heap misconfiguration.
  • Memory issues → Ensure heap (Xms/Xmx) is no more than 50% of system RAM.

Step 3.4: Set a user with the right permissions#

If you enabled X-Pack security in Step 3.2, and Elasticsearch is running, set up a user with the right permissions for Cortex.

  1. Create a cortex user.

    sudo /usr/share/elasticsearch/bin/elasticsearch-users useradd cortex -p <cortex_user_password> -r superuser

    Replace <cortex_user_password> with a secure password you choose for your Cortex user.

    Note this password

    Keep this password secure. You will need to enter it later in the Cortex configuration file so the application can connect to Elasticsearch.

  2. Optional: Set a password for the elastic user.

    sudo /usr/share/elasticsearch/bin/elasticsearch-setup-passwords interactive

    sudo /usr/share/elasticsearch/bin/elasticsearch-reset-password

    Skip this step if the password is already set.

  3. Create or update a role with the privileges needed for Cortex.

    Elasticsearch permission requirements

    The cortex_role role needs the create_index, write, and read indices privileges on cortex_* indices:

    • Creating an index and its mapping at initialization requires the create_index privilege.
    • Creating and deleting documents in the index requires the write privilege.
    • Searching documents in the index requires the read privilege.

    If you're using an existing Elasticsearch instance, confirm it can grant these privileges before connecting it to Cortex.

    • Create a role:
    curl -u elastic:<elastic_user_password> -X POST "http://localhost:9200/_security/role/cortex_role" -H "Content-Type: application/json" -d '
{
  "indices": [
    {
      "names": ["cortex_*"],
      "privileges": ["create_index", "write", "read"]
    }
  ]
}'

    Replace <elastic_user_password> with the password you set for the elastic user.

    If successful, the command should return: {"role":{"created":true}}.

    For more details, refer to the official Elasticsearch API documentation for role creation.

    • Update a role:
    curl -u elastic:<elastic_user_password> -X PUT "http://localhost:9200/_security/role/<role>" -H "Content-Type: application/json" -d '
{
  "indices": [
    {
      "names": ["cortex_*"],
      "privileges": ["create_index", "write", "read"]
    }
  ]
}'

    Replace <role> with the actual role name you want to update.

    Replace <elastic_user_password> with the password you set for the elastic user.

    For more details, refer to the official Elasticsearch API documentation for updating roles.

  4. Assign the role to the user you'll use for Cortex.

    curl -u elastic:<elastic_user_password> -X PUT "http://localhost:9200/_security/user/cortex" \
-H "Content-Type: application/json" \
-d '{
    "password" : "<cortex_user_password>",
    "roles" : ["cortex_role"]
}'

    Replace <cortex_user_password> with the password you set for the cortex user.

    Replace <elastic_user_password> with the password you set for the elastic user.

    Replace cortex_role with actual role name if different.

    If successful, the command should return: {"created":true}.

    For more details, refer to the official Elasticsearch API documentation for updating users.

(Optional) Step 4: Install Docker#

If you plan to run analyzers and responders as Docker images—the recommended option—install the Docker engine on the operating system running Cortex.

. /etc/os-release
curl -fsSL https://download.docker.com/linux/${ID}/gpg | sudo gpg --dearmor -o /usr/share/keyrings/docker-archive-keyring.gpg
echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/docker-archive-keyring.gpg] https://download.docker.com/linux/${ID} ${VERSION_CODENAME:-$UBUNTU_CODENAME} stable" | sudo tee /etc/apt/sources.list.d/docker.list
sudo apt update
sudo apt install docker-ce

. /etc/os-release
sudo yum remove -yq docker \
          docker-client \
          docker-client-latest \
          docker-common \
          docker-latest \
          docker-latest-logrotate \
          docker-logrotate \
          docker-engine
sudo dnf -yq install dnf-plugins-core
sudo dnf config-manager --add-repo https://download.docker.com/linux/${ID}/docker-ce.repo
sudo dnf install -yq docker-ce docker-ce-cli containerd.io docker-compose-plugin

If you'd rather store and run analyzers and responders directly on the host instead of using Docker, see Store & run programs on the host.

Step 5: Install and configure Cortex#

Step 5.1: Install Cortex#

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

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 -ivh /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

Step 5.2: Configure Cortex#

Configure the secret key#

Cortex uses a secret key to sign session cookies and ensure secure user authentication.

  1. Generate and configure a secret key.

    cat > /etc/cortex/secret.conf << _EOF_
play.http.secret.key="$(cat /dev/urandom | tr -dc 'a-zA-Z0-9' | fold -w 64 | head -n 1)"
_EOF_

  2. In the /etc/cortex/application.conf file, replace the line including play.http.secret.key= with:

    /etc/cortex/application.conf
    [..]
include "/etc/cortex/secret.conf"
[..]

    Security requirements

    Never share or commit your secret key to version control. Use different keys for each environment (development, staging, production).

For more details, see Secret key configuration.

Configure the database and index#

In the application.conf file, configure Cortex to connect to Elasticsearch.

Example of database and index configuration with authentication

/etc/cortex/application.conf
[..]
search {
  index = cortex
  uri = "http://127.0.0.1:9200"
  user = "cortex"
  password = "<cortex_user_password>"
}
[..]

Replace <cortex_user_password> with the password set in Step 3.4.

You can remove the user and password lines if you didn't enable X-Pack security for Elasticsearch.

For all available options, see Database configuration.

Configure analyzers and responders#

Tell Cortex where to find analyzers and responders, and whether they run as Docker images or directly on the host.

For detailed instructions and configuration examples, see Analyzers & Responders.

If you plan to run analyzers and responders as Docker images, ensure the cortex service account has appropriate permissions to interact with Docker:

sudo usermod -a -G docker cortex

Step 5.3: Verify installation#

After installation, you can check if Cortex is properly installed by running:

cortex --version

This should return the installed version of Cortex.

Step 5.4: Start Cortex service#

Warning

Before starting the service, ensure you have configured the application accordingly. At minimum, set up the secret key and the database and index configuration.

  1. Start Cortex service and enable it at boot.

    sudo systemctl start cortex
sudo systemctl enable cortex

  2. Verify that Cortex is running.

    sudo systemctl status cortex

    If Cortex is running, you should see an active status in green.

    Service startup delay

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

    Troubleshooting Cortex

    Check the Cortex logs in /var/log/cortex/application.log for configuration or startup errors.

  3. Open your web browser and navigate to http://<server_address>:9001/.

Step 5.5: Perform the initial setup#

Follow the instructions in the First start guide to complete the initial setup of Cortex.

Advanced configuration#

For additional customization, see:

Backup#

All persistent data is stored in Elasticsearch. See Backup and Restore Data for detailed steps.

Next steps