Installation guide
This guide describes the installation of TheHive from binaries. A docker installation guide is also available. You can also build TheHive's source code.
The wiki contains a lot of information about minimum requirements, installation, administration, and many other guides for users and administrators.
Install a minimal Ubuntu 16.04 server system with the following software:
- OpenSSH server
Make sure your system is up-to-date:
sudo apt-get update
sudo apt-get upgrade
Install the following packages:
sudo apt-get install unzip python python-pip
You can install either Oracle Java or OpenJDK.
echo 'deb http://ppa.launchpad.net/webupd8team/java/ubuntu trusty main' | sudo tee -a /etc/apt/sources.list.d/java.list
sudo apt-key adv --keyserver hkp://keyserver.ubuntu.com:80 --recv-key EEA14886
sudo apt-get update
sudo apt-get install oracle-java8-installer
Once Oracle Java is installed, go directly to section 3. Install and Prepare your Database.
sudo add-apt-repository ppa:openjdk-r/ppa
sudo apt-get update
sudo apt-get install openjdk-8-jre-headless
Install the ElasticSearch package provided by Elastic:
sudo apt-key adv --keyserver hkp://keyserver.ubuntu.com:80 --recv-key D88E42B4
echo "deb https://packages.elastic.co/elasticsearch/2.x/debian stable main" | sudo tee -a /etc/apt/sources.list.d/elasticsearch-2.x.list
sudo apt-get update && sudo apt-get install elasticsearch
The Debian package does not start up the service by default. The reason for this is to prevent the instance from accidentally joining a cluster, without being configured appropriately.
If you prefer using ElasticSearch inside a docker, see 3.4. 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), 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=on.
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: on
cluster.name: hive
threadpool.index.queue_size: 100000
threadpool.search.queue_size: 100000
threadpool.bulk.queue_size: 1000
Now that ElasticSearch is configured, start it as a service:
sudo systemctl enable elasticsearch.service
sudo service elasticsearch start
Note that by default, the database is stored in /var/lib/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 \
--publish 127.0.0.1:9200:9200 \
--publish 127.0.0.1:9300:9300 \
--volume /absolute/path/to/persistent/data/:/usr/share/elasticsearch/data \
--rm \
elasticsearch:2.3 \
-Des.script.inline=on \
-Des.cluster.name=hive \
-Des.threadpool.index.queue_size=100000 \
-Des.threadpool.search.queue_size=100000 \
-Des.threadpool.bulk.queue_size=1000
Binaries must be downloaded from https://dl.bintray.com/cert-bdf/thehive/thehive-latest.zip. The archive includes the back-end and the front-end.
You can install TheHive wherever you want on the filesystem. In this guide, we decided to set it in /opt.
cd /opt
wget https://dl.bintray.com/cert-bdf/thehive/thehive-latest.zip
unzip thehive-latest.zip
mv thehive-latest thehive
The default configuration is sufficient to run TheHive and start using it. The only required parameter is the key of the server (play.crypto.secret). This key is used to authenticate cookies that contain data, and not only a session id. If TheHive runs in cluster mode, all instance must share the same key.
You should generate a random key using the following command line:
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.crypto.secret="$(cat /dev/urandom | tr -dc 'a-zA-Z0-9' | fold -w 64 | head -n 1)"
_EOF_
) | sudo tee -a /etc/thehive/application.conf
sudo chgrp thehive /etc/thehive/application.conf
sudo chmod 640 /etc/thehive/application.conf
For advanced configuration, see section 5. Advanced Configuration.
Change your current directory to TheHive installation directory, then execute (/opt in this guide):
cd /opt/thehive
bin/thehive -Dconfig.file=/etc/thehive/application.conf
It is recommended to use a dedicated non-privilege user to start TheHive. If so, make sure that your user can create log file in `/opt/thehive/conf̀
This command starts an HTTP service on port 9000/tcp. You can change the port by adding "http.port=8080" in the configuration file or add the "-Dhttp.port=8080" parameter to the command line. If you run TheHive using a non-privileged user, you can't bind a port under 1024.
If you'd rather start the application as a service, do the following:
sudo addgroup thehive
sudo adduser --system thehive
sudo cp /opt/thehive/install/thehive.service /usr/lib/systemd/system
sudo chown -R thehive:thehive /opt/thehive
sudo systemctl enable thehive
sudo service thehive start
Please note that the service may take some time to start.
Then open your browser and connect to http://YOUR_SERVER_ADDRESS:9000/
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 Admin account.
Once created, you should be redirected to the login page.
Warning: at this stage, if you missed the creation of the admin user, you will not be able to do it unless you delete the index in ElasticSearch. In the case you made a mistake, just delete the index with the following command (beware, it deletes everything in the database)
curl -X DELETE http://127.0.0.1:9200/the_hive_7
And reload the page or restart TheHive.
Some features might need custom configuration like Active Directory or LDAP authentication, MISP connector, or using the Metrics module.
All configuration parameters should go in the /etc/thehive/application.conf file. This file use the HOCON format. All default values can be found in reference.conf files for each module:
The advanced configuration of the Admininistrator's guide provides more details.
TheHive comes with few analyzers by default. Some python modules are required to run them successfully :
sudo pip install requests olefile
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/cert-bdf/thehive/thehive-latest.zip
unzip thehive-latest.zip
rm /opt/thehive && ln -s thehive-2.9.1 thehive
chown -R thehive:thehive /opt/thehive /opt/thehive-2.9.1
service thehive start