Skip to content

Step-by-Step Guide#

This page is a step by step installation and configuration guide to get a Cortex instance up and running. This guide is illustrated with examples for Debian and RPM packages based systems and for installation from ZIP binary packages.

Required packages#

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

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

Java Virtual Machine#

Manual installation required

Starting with Cortex 3.2, the Java Virtual Machine is no longer installed automatically. You must manually install it before running Cortex.

Install Java

For enhanced security and long-term support, use Amazon Corretto, an OpenJDK build provided and maintained by Amazon. Corretto 11 or higher is required to install Cortex.

  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)

The installation requires Java 11, so refer to your system documentation to install it.

Elasticsearch#

wget -qO - https://artifacts.elastic.co/GPG-KEY-elasticsearch |  sudo gpg --dearmor -o /usr/share/keyrings/elasticsearch-keyring.gpg
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 
sudo apt install elasticsearch
/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

sudo yum install --enablerepo=elasticsearch elasticsearch

Configuration#

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

Adjust this file according to the amount of RAM available on your server:

/etc/elasticsearch/jvm.options.d/jvm.options
-Dlog4j2.formatMsgNoLookups=true
-Xms4g
-Xmx4g

Docker#

If using Docker images of analyzers and responders, Docker engine is required on the operating system:

curl -fsSL https://download.docker.com/linux/debian/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/ubuntu \
$(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list
apt install docker-ce

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/fedora/docker-ce.repo
sudo dnf install -yq docker-ce docker-ce-cli containerd.io docker-compose-plugin

Cortex installation and configuration#

This section provides step-by-step instructions to install Cortex and configure it properly.

Installation#

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

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

    • Using cURL:

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

  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_3.2.1-2_all.deb

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

      cat /tmp/cortex_3.2.1-2_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_3.2.1-2_all.deb.asc /tmp/cortex_3.2.1-2_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_3.2.1-2_all.deb

    • Using dpkg:

      sudo dpkg -i /tmp/cortex_3.2.1-2_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-3.2.1-2.noarch.rpm https://cortex.download.strangebee.com/3.2/rpm/cortex-3.2.1-2.noarch.rpm
wget -O /tmp/cortex-3.2.1-2.noarch.rpm.sha256 https://cortex.download.strangebee.com/3.2/sha256/cortex-3.2.1-2.noarch.rpm.sha256
wget -O /tmp/cortex-3.2.1-2.noarch.rpm.asc https://cortex.download.strangebee.com/3.2/asc/cortex-3.2.1-2.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.1.8-1.
      • Replace <major.minor_version> with the corresponding version directory. For example, use 3.1.

    • Using cURL:

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

  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-3.2.1-2.noarch.rpm

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

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

    • Using dnf to manage dependencies automatically:

      sudo dnf install /tmp/cortex-3.2.1-2.noarch.rpm

    • Using rpm:

      sudo rpm -ivh /tmp/cortex-3.2.1-2.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-3.2.1-2.zip https://cortex.download.strangebee.com/3.2/zip/cortex-3.2.1-2.zip
wget -O /opt/cortex/cortex-3.2.1-2.zip.sha256 https://cortex.download.strangebee.com/3.2/sha256/cortex-3.2.1-2.zip.sha256
wget -O /opt/cortex/cortex-3.2.1-2.zip.asc https://cortex.download.strangebee.com/3.2/asc/cortex-3.2.1-2.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.1.8-1.
      • Replace <major.minor_version> with the corresponding version directory. For example, use 3.1.

    • Using cURL

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

  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-3.2.1-2.zip

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

      cat /opt/cortex-3.2.1-2.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-3.2.1-2.zip.asc /opt/cortex-3.2.1-2.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-3.2.1-2.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-3.2.1-2.zip -d /opt/
sudo ln -s /opt/cortex-3.2.1-2 /opt/cortex

  4. Make the Cortex binary executable.

    cd /opt/
chmod +x cortex

Post-installation configuration#

Running analyzers & responders with Docker#

If you plan to use Cortex with Analyzers & Responders running in Docker, ensure the cortex service account has appropriate permissions to interact with Docker:

sudo usermod -a -G docker cortex

Verify installation#

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

cortex --version

This should return the installed version of Cortex.

Configuration#

Following settings are required to start Cortex successfully:

Advanced configuration settings might be added to run the application successfully:

Start Cortex service#

Warning

Before starting the service, ensure to have configured accordingly the application. Start by setting up the secret key.

Save configuration file and run the service:

systemctl start cortex

Please note that the service may take some time to start. Once it is started, you may launch your browser and connect to http://YOUR_SERVER_ADDRESS:9001/.

First start#

Refer to the First start guide for the next steps.