Usage Instructions for the Official TheHive 5 AMI#
Use the AMI to set up a new TheHive 5 installation, or to launch an instance with existing data and configuration to upgrade, migrate, or restore TheHive.
Introduction#
- Scripts included in the image initialize a new instance or restore a previous TheHive 5 instance.
- Data is stored on three dedicated volumes: one for the Cassandra database at
/var/lib/cassandra, one for storage attachments at/opt/thp_data/files, and one for indexes at/opt/thp_data/index. - The AMI is based on the official Ubuntu 24.04 LTS AMI from Canonical.
- The AMI is updated with each new TheHive release. To upgrade, launch a new instance from the latest AMI, as you would with a container.
- Migration from TheHive 3 is a manual operation. See Migration from TheHive 3.x.
- Upgrading from a TheHive 4 AMI isn't automated or documented yet. For the general upgrade process, see Upgrade from TheHive 4.x.
Run context#
- TheHive runs as an unprivileged user named thehive and listens on HTTP port 9000. This port uses HTTP, not HTTPS. Never open it outside your VPC. Use a public-facing load balancer or reverse proxy to handle TLS sessions with end users. The AMI doesn't include a load balancer or reverse proxy. Many TheHive users also run Cortex and Malware Information Sharing Platform & Threat Sharing (MISP) instances alongside it and already have one they prefer.
- TheHive uses secure cookies by default, so connecting to the UI over HTTP fails. To allow HTTP connections, set
play.http.session.secure = falsein/etc/thehive/application.conf, then restart thethehiveservice. - The default sudoer user is ubuntu, and the SSH service listens on port 22.
- A cron job for the thehive user runs every night with the
@dailyschedule. It backs up the application configuration to the data volume at/var/lib/cassandra/thehive/. To restore the configuration when launching a new instance from existing data, this job must have run at least once after the initial installation.
Launching an instance for a new TheHive installation#
- Launch an instance from the AMI.
- SSH into the instance with the ubuntu user.
- Initialize and format the additional EBS volumes:
/dev/sdh,/dev/sdi, and/dev/sdj. On Nitro-based instances,/dev/sdhmight appear under a name such as/dev/nvme1n1. For more information, see Amazon EBS and NVMe on Linux instances. - Launch the application initialization script with the block device names of the EBS data volumes as arguments. With a default AMI setup, these are
/dev/sdh,/dev/sdi, and/dev/sdj. On Nitro-based instances, don't use the NVMe names such as/dev/nvme0n1. Example:/opt/thehive/ops/scripts/ops-thehive-init.sh /dev/sdh /dev/sdi /dev/sdj - TheHive is now available on port 9000. The default admin account is
admin@thehive.localwith passwordsecret. Change the password after the first login.
Alternatively, perform steps 3 and 4 by providing cloud-init user data to the AMI at launch. In the following example, which uses a Nitro-based m5 instance, the user data:
- Runs a script that exposes the external volumes, which the instance sees as
/dev/nvme1n1and/dev/nvme2n1, under their block device mapping names,/dev/sdhand/dev/sdi - Partitions and formats the EBS volumes using their block device mapping names
- Launches the initialization script with the EBS block mapping names as arguments:
/dev/sdh,/dev/sdi, and/dev/sdj
#cloud-config
bootcmd:
- [ /usr/sbin/nvme-to-block-mapping ]
fs_setup:
- filesystem: ext4
device: '/dev/sdh'
partition: auto
overwrite: false
- filesystem: ext4
device: '/dev/sdi'
partition: auto
overwrite: false
- filesystem: ext4
device: '/dev/sdj'
partition: auto
overwrite: false
runcmd:
- [ /opt/thehive/ops/scripts/ops-thehive-init.sh, /dev/sdh, /dev/sdi, /dev/sdj ]
You can also provision TheHive using Terraform. The StrangeBee cloud-distrib-resources repository on GitHub provides detailed sample code.
Launching an instance with existing data to upgrade, migrate, or restore TheHive#
- Launch an instance from the AMI. Base the additional EBS volumes on existing TheHive EBS volume snapshots:
/dev/sdhfor the Cassandra database,/dev/sdifor the storage attachments, and/dev/sdjfor the database index. These are the default device names. - SSH into the instance with the ubuntu user.
- Launch the restore script with the block device names of the EBS data volumes as arguments. With a default AMI setup, these are
/dev/sdh,/dev/sdi, and/dev/sdj. On Nitro-based instances, don't use the NVMe names such as/dev/nvme1n1. Example:/opt/thehive/ops/scripts/ops-thehive-restore.sh /dev/sdh /dev/sdi /dev/sdj - TheHive is now available on port 9000, or on the custom port you configured, with all your existing configuration, users, and data.
Alternatively, perform step 3 by providing cloud-init user data to the AMI at launch. The following example, which uses a Nitro-based m5 instance, launches the restore script with the EBS block mapping names as arguments: /dev/sdh, /dev/sdi, and /dev/sdj.
#cloud-config
runcmd:
- [ /opt/thehive/ops/scripts/ops-thehive-restore.sh, /dev/sdh, /dev/sdi, /dev/sdj ]
You can also provision TheHive using Terraform. The StrangeBee cloud-distrib-resources repository on GitHub provides detailed sample code.