The Hive (Security Incident Response Platform)

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

Java Virtual Machine

apt-get install -y openjdk-8-jre-headless
echo JAVA_HOME="/usr/lib/jvm/java-8-openjdk-amd64" >> /etc/environment
export JAVA_HOME="/usr/lib/jvm/java-8-openjdk-amd64"

Note

TheHive can be loaded by Java 11, but not the stable version of Cassandra, which still requires Java 8. If you set up a cluster for the database distinct from TheHive servers:

• Cassandra nodes can be loaded by Java 8
• TheHive nodes can be loaded by Java 11

For standalone servers, with TheHive and Cassandra on the same OS, we recommend having only Java 8 installed for both applications.

Cassandra database

Apache Cassandra is a scalable and high available database. TheHive supports the latest stable version 3.11.x of Cassandra.

Install from repository

Add Apache repository references

curl -fsSL https://www.apache.org/dist/cassandra/KEYS | sudo apt-key add -
echo "deb http://www.apache.org/dist/cassandra/debian 311x main" | sudo tee -a /etc/apt/sources.list.d/cassandra.sources.list

Install the package

sudo apt update
sudo apt install cassandra

By default, data is stored in /var/lib/cassandra.

Configuration

Start by changing the cluster_name with thp. Run the command cqlsh:

cqlsh localhost 9042

cqlsh> UPDATE system.local SET cluster_name = 'thp' where key='local';

Exit and then run:

nodetool flush

Configure Cassandra by editing /etc/cassandra/cassandra.yaml file.

# content from /etc/cassandra/cassandra.yaml

cluster_name: 'thp'
listen_address: 'xx.xx.xx.xx' # address for nodes
rpc_address: 'xx.xx.xx.xx' # address for clients
seed_provider:
    - class_name: org.apache.cassandra.locator.SimpleSeedProvider
      parameters:
          # Ex: "<ip1>,<ip2>,<ip3>"
          - seeds: 'xx.xx.xx.xx' # self for the first node
data_file_directories:
  - '/var/lib/cassandra/data'
commitlog_directory: '/var/lib/cassandra/commitlog'
saved_caches_directory: '/var/lib/cassandra/saved_caches'
hints_directory: 
  - '/var/lib/cassandra/hints'

Then restart the service:

service cassandra restart

By default Cassandra listens on 7000/tcp (inter-node), 9042/tcp (client).

File storage

Files uploaded in TheHive (in task logs or in observables) can be stores in localsystem, in a Hadoop filesystem (recommended) or in the graph database.

For standalone production and test servers , we recommends using local filesystem. If you think about building a cluster with TheHive, you have several possible solutions: using Hadoop or S3 services .

This option is perfect for standalone servers. If you intend to build a cluster for your instance of TheHive 4 we recommend:

• using a NFS share, common to all nodes
• having a look at storage solutions implementing S3 or HDFS.

To store files on the local filesystem, start by choosing the dedicated folder:

mkdir -p /opt/thp/thehive/files

This path will be used in the configuration of the applicaction.

Later, after having installed TheHive, ensure the user thehive owns the path chosen for storing files:

chown -R thehive:thehive /opt/thp/thehive/files

TheHive

This part contains instructions to install The Hive and then configure it.

TheHive4 can’t be installed on the same server than older versions. We recommend installing it on a new server, especially if a migration is foreseen

Installation

All packages are published on our packages repository. . Its fingerprint is 0CD5 AC59 DE5C 5A8E 0EE1 3849 3D99 BB18 562C BC1C.

curl https://raw.githubusercontent.com/TheHive-Project/TheHive/master/PGP-PUBLIC-KEY | sudo apt-key add -

The hive also release stable and beta version of the applications.

Stable versions

echo 'deb https://deb.thehive-project.org release main' | sudo tee -a /etc/apt/sources.list.d/thehive-project.list
sudo apt-get update
sudo apt-get install thehive4

Beta versions

echo 'deb https://deb.thehive-project.org beta main' | sudo tee -a /etc/apt/sources.list.d/thehive-project.list
sudo apt-get update
sudo apt-get install thehive4

We recommend using or playing with Beta version for testing purpose only.

Configuration

Following configurations are required to start the app successfully:

• Secret key configuration
• Database configuration
• File storage configuration

Secret key configuration

The secret key is automatically generated and stored in /etc/thehive/secret.conf by package installation script.

Database

To use Cassandra database, TheHive configuration file (/etc/thehive/application.conf) has to be edited and updated with following lines:

db {
  provider: janusgraph
  janusgraph {
    storage {
      backend: cql
      hostname: ["127.0.0.1"] # seed node ip addresses
      #username: "<cassandra_username>"       # login to connect to database (if configured in Cassandra)
      #password: "<cassandra_passowrd"
      cql {
        cluster-name: thp       # cluster name
        keyspace: thehive           # name of the keyspace
        local-datacenter: datacenter1   # name of the datacenter where TheHive runs (relevant only on multi datacenter setup)
        # replication-factor: 2 # number of replica
        read-consistency-level: ONE
        write-consistency-level: ONE
      }
    }
  }
}

Filesystem

1:If you chose to store files on the local filesystem:

Ensure permission of the folder


chown -R thehive:thehive /opt/thp/thehive/files
2: add following lines to TheHive configuration file (/etc/thehive/application.conf)


## Storage configuration
storage {
provider = localfs
localfs.location = /opt/thp/thehive/files
}

Run

Save configuration file and run the service:

service thehive start

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:9000/.

Application website