Before installing TheHive, you need to choose the installation option which suits your environment as described below. Once you have a chosen an option and installed the software, read the Configuration Guide. We also advise reading the Administration Guide.
TheHive is available as:
- an RPM package
- a DEB package
- a Docker image
- a binary package
In addition, TheHive can be also be built from the source code.
RPM packages are published on a Bintray repository. All packages are signed using our GPG key 562CBC1C. Its fingerprint is:
0CD5 AC59 DE5C 5A8E 0EE1 3849 3D99 BB18 562C BC1C
First install the RPM release package:
yum install https://dl.bintray.com/thehive-project/rpm-stable/thehive-project-release-1.1.0-2.noarch.rpmThis will install TheHive Project's repository in /etc/yum.repos.d/thehive-rpm.repo and the corresponding GPG public key in
/etc/pki/rpm-gpg/GPG-TheHive-Project.
Then you will able to install the package using yum:
yum install thehiveOnce the package is installed, proceed to the configuration using the Configuration Guide. For additional configuration options, please refer to the Administration Guide.
The RPM release package installs two repositories: thehive-project-stable and thehive-project-beta. The latter contains pre-release, beta versions and is disabled by default. If you want to install them and help us find bugs to the benefit of the whole community, you can enable it by editing /etc/yum.repos.d/thehive-rpm.repo and set enable value to 1 for thehive-project-beta repository.
Debian packages are published on a Bintray repository. All packages are signed using our GPG key 562CBC1C. Its fingerprint is:
0CD5 AC59 DE5C 5A8E 0EE1 3849 3D99 BB18 562C BC1C
To install the x Debian package, use the following commands:
echo 'deb https://dl.bintray.com/thehive-project/debian-stable any main' | sudo tee -a /etc/apt/sources.list.d/thehive-project.list
sudo apt-key adv --keyserver hkp://pgp.mit.edu --recv-key 562CBC1C
sudo apt-get update
sudo apt-get install thehiveSome environments may block access to the pgp.mit.edu key server. As a result, the command sudo apt-key adv --keyserver hkp://pgp.mit.edu --recv-key 562CBC1C will fail. In that case, you can run the following command instead:
curl https://raw.githubusercontent.com/TheHive-Project/TheHive/master/PGP-PUBLIC-KEY | sudo apt-key add -
Once the package is installed, proceed to the configuration using the Configuration Guide. For additional configuration options, please refer to the Administration Guide.
If you want to install pre-release, beta versions of TheHive packages and help us find bugs to the benefit of the whole community, you can add the pre-release repository with the command:
echo 'deb https://dl.bintray.com/thehive-project/debian-beta any main' | sudo tee -a /etc/apt/sources.list.d/thehive-project.listTo use the Docker image, you must use Docker (courtesy of Captain Obvious).
TheHive requires Elasticsearch to run. You can use docker-compose to start them together in Docker or install and configure Elasticsearch manually.
Docker-compose can start multiple dockers and link them together.
The following docker-compose.yml file starts Elasticsearch and TheHive:
version: "2"
services:
elasticsearch:
image: elasticsearch:6.8.8
environment:
- http.host=0.0.0.0
- discovery.type=single-node
ulimits:
nofile:
soft: 65536
hard: 65536
cortex:
image: thehiveproject/cortex:latest
depends_on:
- elasticsearch
ports:
- "0.0.0.0:9001:9001"
thehive:
image: thehiveproject/thehive:latest
depends_on:
- elasticsearch
- cortex
ports:
- "0.0.0.0:9000:9000"
command: --cortex-port 9001
Put this file in an empty folder and run docker-compose up. TheHive is exposed on 9000/tcp port and Cortex on 9001/tcp. These ports can be changed by modifying the docker-compose file.
You can specify a custom TheHive configuration file (application.conf) by adding the following lines in the thehive section of your docker-compose file:
volumes:
- /path/to/application.conf:/etc/thehive/application.conf
To take effect, be sure that:
- '/path/to/application.conf' is readable for the user who runs the docker daemon (typically 644)
- you specified
command: --no-configin yourdocker-compose.ymlfile
You should define where the data (i.e. the Elasticsearch database) will be located on your operating system by adding the following lines in the elasticsearch section of your docker-compose file:
volumes:
- /path/to/data:/usr/share/elasticsearch/data
Running ElasticSearch in production mode requires a minimum vm.max_map_count of 262144. ElasticSearch documentation provides instructions on how to query and change this value.
If you want to make Cortex be available on TheHive, you must create an account on Cortex, define an API key for it and provide that key to TheHive container using parameter --cortex-key or environment TH_CORTEX_KEY.
Elasticsearch can be installed on the same server as TheHive or on a different one. You can then configure TheHive according to the documentation and run TheHive docker as follow:
docker run --volume /path/to/thehive/application.conf:/etc/thehive/application.conf thehiveproject/thehive:latest --no-configYou can add the --publish docker option to expose TheHive HTTP service.
By default, the TheHive Docker image has minimal configuration:
- choose a random secret (
play.http.secret.key) - search for the Elasticsearch instance (host named
elasticsearch) and add it to configuration - search for a Cortex instance (host named
cortex) and add it to configuration
This behavior can be disabled by adding --no-config to the Docker command line:
docker run thehiveproject/thehive:latest --no-config
Or by adding the line command: --no-config in the thehive section of
docker-compose file.
It is possible to start database migration at startup with the parameter --auto-migration.
If the initial administrator doesn't exist yet, you can request its creation with --create-admin followed by the user login and its password.
You can also create a normal user with --create-user followed by the user login and its roles and its password.
The image accepts more options. All options are available using environment variables.
For boolean variable, 1 means true and other value means false. For multivalued variables, values are separated by coma. This is possible only with --create-admin.
| Option | Env variable | Description |
|---|---|---|
--no-config |
TH_NO_CONFIG | Do not try to configure TheHive (add the secret and Elasticsearch) |
--no-config-secret |
TH_NO_CONFIG_SECRET | Do not add the random secret to the configuration |
--secret <secret> |
TH_SECRET | Cryptographic secret needed to secure sessions |
--show-secret |
TH_SHOW_SECRET | Show the generated secret |
--no-config-es |
TH_NO_CONFIG_ES | Do not add the Elasticsearch hosts to configuration |
--es-uri <uri> |
TH_CONFIG_ES | Use this string to configure elasticsearch hosts (format: http(s)://host:port,host:port(/prefix)?querystring) |
--es-hostname <host> |
TH_ES_HOSTNAME | Resolve this hostname to find Elasticsearch instances |
--no-config-cortex |
TH_NO_CONFIG_CORTEX | Do not add Cortex configuration |
--cortex-proto <proto> |
TH_CORTEX_PROTO | Define the protocol to connect to Cortex (default: http) |
--cortex-port <port> |
TH_CORTEX_PORT | Define the port to connect to Cortex (default: 9001) |
--cortex-url <url> |
TH_CORTEX_URL | Add the Cortex connection |
--cortex-hostname <host> |
TH_CORTEX_HOSTNAME | Resolve this hostname to find the Cortex instance |
--cortex-key <key> |
TH_CORTEX_KEY | Define Cortex key |
--auto-migration |
TH_AUTO_MIGRATION | Migrate the database, if needed |
--create-admin <user> <password |
TH_CREATE_ADMIN_LOGIN TH_CREATE_ADMIN_PASSWORD | Create the first admin user, if not exist yet |
--create-user <user> <role> <password> |
TH_CREATE_USER_LOGIN TH_CREATE_USER_ROLE TH_CREATE_USER_PASSWORD | Create a user, only in conjunction with admin creation |
Note: please remember that you must install and configure Elasticsearch.
Once the Docker image is up and running, proceed to the configuration using the Configuration Guide. For additional configuration options, please refer to the Administration Guide.
If you would like to use pre-release, beta versions of our Docker images and help us find bugs to the benefit of the whole community, please use thehiveproject/thehive:version-RCx. For example thehiveproject/thehive:3.1.0-RC1.
The following section contains the instructions to manually install TheHive using binaries on Ubuntu 18.04 LTS.
Install a minimal Ubuntu 18.04 system with the following software:
- Java runtime environment 1.8+ (JRE)
- Elasticsearch 5.x
Make sure your system is up-to-date:
sudo apt-get update
sudo apt-get upgradeYou can install either Oracle Java or OpenJDK. The latter is recommended.
sudo apt-get install openjdk-11-jre-headless
To install Elasticsearch, please read the Elasticsearch Installation section below.
Binary packages can be downloaded from Bintray. The latest version is called thehive-latest.zip.
Download and unzip the chosen binary package. TheHive files can be installed wherever you want on the filesystem. In this guide, we assume you have chosen to install them under /opt.
cd /opt
wget https://dl.bintray.com/thehive-project/binary/thehive-latest.zip
unzip thehive-latest.zip
ln -s thehive-x.x.x thehiveNote: if you would like to use pre-release, beta versions of and help us find bugs to the benefit of the whole community, please download https://dl.bintray.com/thehive-project/binary/thehive-version-RCx.zip. For example https://dl.bintray.com/thehive-project/binary/thehive-3.1.0-RC1.zip.
It is recommended to use a dedicated, non-privileged user account to start TheHive. If so, make sure that the chosen account can create log files in /opt/thehive/logs.
If you'd rather start the application as a service, use the following commands:
sudo addgroup thehive
sudo adduser --system thehive
sudo cp /opt/thehive/package/thehive.service /usr/lib/systemd/system
sudo chown -R thehive:thehive /opt/thehive
sudo chgrp thehive /etc/thehive/application.conf
sudo chmod 640 /etc/thehive/application.conf
sudo systemctl enable thehive
sudo service thehive startThe only required parameter in order to start TheHive is the key of the server (play.http.secret.key). This key is used
to authenticate cookies that contain data. If TheHive runs in cluster mode, all instances must share the same key.
You can generate the minimal configuration with the following commands (they assume that you have created a
dedicated user for TheHive, named thehive):
sudo mkdir /etc/thehive
(cat << _EOF_
# Secret key
# ~~~~~
# The secret key is used to secure cryptographics functions.
# If you deploy your application to several instances be sure to use the same key!
play.http.secret.key="$(cat /dev/urandom | tr -dc 'a-zA-Z0-9' | fold -w 64 | head -n 1)"
_EOF_
) | sudo tee -a /etc/thehive/application.confNow you can start TheHive. To do so, change your current directory to the TheHive installation directory (/opt/thehive in this guide), then execute:
bin/thehive -Dconfig.file=/etc/thehive/application.confPlease 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:9000/.
Please note that the service may take some time to start.
The first time you connect you will have to create the database schema. Click "Migrate database" to create the DB schema.
Once done, you should be redirected to the page for creating the administrator's account.
Once created, you should be redirected to the login page.
Warning: at this stage, if you missed the creation of the admin account, you will not be able to do it unless you delete TheHive's index from Elasticsearch. In the case you made a mistake, first find out what is the current index of TheHive by running the following command on a host where the Elasticsearch DB used by TheHive is located:
$ curl http://127.0.0.1:9200/_cat/indices?vThe indexes that TheHive uses always start withthe_hive_ following by a number. Let's assume that the output of the command is:
health status index uuid pri rep docs.count docs.deleted store.size pri.store.size
yellow open cortex_1 PC_pLFGBS5G2TNQYr4ajgw 5 1 609 6 2.1mb 2.1mb
yellow open the_hive_13 ft7GGTfhTr-4lSzZw5r1DQ 5 1 180131 3 51.3mb 51.3mbThe index used by TheHive is the_hive_13. To delete it, run the following command:
$ curl -X DELETE http://127.0.0.1:9200/the_hive_13Then reload the page or restart TheHive.
To update TheHive from binaries, just stop the service, download the latest package, rebuild the link /opt/thehive and
restart the service.
service thehive stop
cd /opt
wget https://dl.bintray.com/thehive-project/binary/thehive-latest.zip
unzip thehive-latest.zip
rm /opt/thehive && ln -s thehive-x.x.x thehive
chown -R thehive:thehive /opt/thehive /opt/thehive-x.x.x
service thehive startTo configure TheHive, read the Configuration Guide. For additional configuration options, please refer to the Administration Guide.
The following section contains a step-by-step guide to build TheHive from its sources.
The following software are required to download and build TheHive:
- Java Development Kit 11 (JDK)
- git: use the system package or download it
- Node.js with its package manager (NPM)
- Grunt: after installing Node.js, run
sudo npm install -g grunt-cli - Bower: after installing Node.js, run
sudo npm install -g bower - Elasticsearch 5.6
To install the requirements and build TheHive from sources, please follow the instructions below depending on your operating system.
Packages
sudo yum -y install git bzip2Installation of OpenJDK
sudo yum -y install java-11-openjdk-develInstallation of Node.js
Install the EPEL repository. You should have the extras repository enabled, then:
sudo yum -y install epel-releaseThen, you can install Node.js, Grunt, and Bower:
sudo yum -y install nodejs
sudo npm install -g grunt-cli bowerInstallation of Elasticsearch
To install Elasticsearch, please read the Elasticsearch Installation section below.
Packages
sudo apt-get install git wgetInstallation of Oracle JDK
sudo apt install openjdk-11-jdk-headlessInstallation of Node.js, Grunt and Bower
sudo apt-get install curl
curl -sL https://deb.nodesource.com/setup_11.x | sudo -E bash -
sudo apt-get install -y nodejs
sudo npm install -g grunt-cli bowerInstallation of Elasticsearch
To install Elasticsearch, please read the Elasticsearch Installation section below.
Download The Source
git clone https://github.com/TheHive-Project/TheHive.git
Build the Project
cd TheHive
./sbt clean stage
This operation may take some time to complete as it will download all dependencies then build the back-end.
This command cleans previous build files and creates an autonomous package in the target/universal/stage directory. This packages contains TheHive binaries with required libraries (/lib), configuration files (/conf) and startup scripts (/bin).
Binaries are built and stored in TheHive/target/universal/stage/. You can install them in /opt/thehive for example.
sudo cp -r TheHive/target/universal/stage /opt/thehive
Configure TheHive, read the Configuration Guide. For additional configuration options, please refer to the Administration Guide.
Edit /etc/elasticsearch/elasticsearch.yml and add the following lines:
network.host: 127.0.0.1
script.inline: true
cluster.name: hive
thread_pool.index.queue_size: 100000
thread_pool.search.queue_size: 100000
thread_pool.bulk.queue_size: 1000
Start the service:
service elasticsearch restart
Follow the first start section of the binary installation method above to start using TheHive.
Building the back-end builds also the front-end, so you don't need to build it separately. This section is useful only for troubleshooting or for installing the front-end on a reverse proxy.
Go to the front-end directory:
cd TheHive/ui
Install Node.js libraries, which are required by this step, bower libraries (JavaScript libraries downloaded by the browser). Then build the front-end :
npm install
bower install
grunt build
This step generates static files (HTML, JavaScript and related resources) in the dist directory. They can be readily imported on a HTTP server.
If, for some reason, you need to install Elasticsearch, it can be installed using a system package or a Docker image. Version 5.X must be used. From version 6, Elasticsearch drops mapping type.
Install the Elasticsearch package provided by Elastic
# PGP key installation
sudo apt-key adv --keyserver hkp://keyserver.ubuntu.com:80 --recv-key D88E42B4
# Alternative PGP key installation
# wget -qO - https://artifacts.elastic.co/GPG-KEY-elasticsearch | sudo apt-key add -
# Debian repository configuration
echo "deb https://artifacts.elastic.co/packages/5.x/apt stable main" | sudo tee -a /etc/apt/sources.list.d/elastic-5.x.list
# Install https support for apt
sudo apt install apt-transport-https
# Elasticsearch installation
sudo apt update && sudo apt install elasticsearch
The Debian package does not start up the service by default, to prevent the instance from accidentally joining a cluster, without being configured appropriately.
# PGP key installation
sudo rpm --import https://artifacts.elastic.co/GPG-KEY-elasticsearch
Create the file elasticsearch.repo in /etc/yum/repos.d/ for RedHat and CentOS, or in /etc/zypp/repos.d/ for OpenSuSE distributions, and add the following lines:
[elasticsearch-5.x]
name=Elasticsearch repository for 5.x packages
baseurl=https://artifacts.elastic.co/packages/5.x/yum
gpgcheck=1
gpgkey=https://artifacts.elastic.co/GPG-KEY-elasticsearch
enabled=1
autorefresh=1
type=rpm-md
Then, you can use the following command:
# On CentOS and older Red Hat based distributions.
sudo yum install elasticsearch
# On Fedora and other newer Red Hat distributions.
sudo dnf install elasticsearch
# On OpenSUSE based distributions.
sudo zypper install elasticsearch
If you prefer using Elasticsearch inside a docker, see Elasticsearch inside a Docker.
It is highly recommended to avoid exposing this service to an untrusted zone.
If Elasticsearch and TheHive run on the same host (and not in a docker), edit /etc/elasticsearch/elasticsearch.yml and
set network.host parameter with 127.0.0.1. TheHive use dynamic scripts to make partial updates. Hence, they must be activated using script.inline: true.
The cluster name must also be set (hive for example). Threadpool queue size must be set with a high value (100000). The default size will get the queue easily overloaded.
Edit /etc/elasticsearch/elasticsearch.yml and add the following lines:
network.host: 127.0.0.1
script.inline: true
cluster.name: hive
thread_pool.index.queue_size: 100000
thread_pool.search.queue_size: 100000
thread_pool.bulk.queue_size: 100000
Now that Elasticsearch is configured, start it as a service and check whether it's running:
sudo systemctl enable elasticsearch.service
sudo systemctl start elasticsearch.service
sudo systemctl status elasticsearch.service
The status should be active (running). If it's not running, you can check for the reason in the logs:
sudo journalctl -u elasticsearch.service
Note that by default, the database is stored in /var/lib/elasticsearch and the logs in /var/log/elasticsearch
You can also start Elasticsearch inside a docker. Use the following command and do not forget to specify the absolute path for persistent data on your host :
docker run \
--name elasticsearch \
--hostname elasticsearch \
--rm \
--publish 127.0.0.1:9200:9200 \
--publish 127.0.0.1:9300:9300 \
--volume ***DATA_DIR***:/usr/share/elasticsearch/data \
-e "http.host=0.0.0.0" \
-e "transport.host=0.0.0.0" \
-e "xpack.security.enabled=false" \
-e "cluster.name=hive" \
-e "script.inline=true" \
-e "thread_pool.index.queue_size=100000" \
-e "thread_pool.search.queue_size=100000" \
-e "thread_pool.bulk.queue_size=100000" \
docker.elastic.co/elasticsearch/elasticsearch:5.6.0