ansible-thehive

Description

This tool sets up and configures TheHive, a great open-source incident response platform. It installs TheHive using RPM and can also set up the ElasticSearch index automatically, which helps avoid some tedious manual setup steps.

You'll need to install ElasticSearch on your own. This tool has been tested with the Elastic's official Ansible role. The documentation includes example configurations.

This should work for most TheHive applications, but contributions and improvement suggestions are encouraged.

Requirements

• Ansible version 2.0 or higher
• CentOS 7
• ElasticSearch version 5.x

Usage

It's best to install this on a dedicated server, though you can safely run ElasticSearch and Cortex alongside TheHive. There’s an optional Nginx proxy enabled by default, and it supports Vouch and LDAP for authentication. If you use delegated authentication, ensure you set a seed user to log in.

Make sure ElasticSearch is already installed and running. This tool has been tested with the ansible-elasticsearch role, which you can get from Ansible Galaxy.

Here are some recommended settings:

es_instance_name: "thehive"
es_version: 5.6.14
es_major_version: 5.x
es_data_dirs:
  - "/data/es"
es_config:
  node.name: "thehive"
  cluster.name: "thehive"
  node.data: true
  node.master: true
  script.inline: on
  thread_pool.index.queue_size: 100000
  thread_pool.search.queue_size: 100000
  thread_pool.bulk.queue_size: 100000
es_scripts: true
es_templates: false
es_version_lock: false
es_heap_size: 1g
es_xpack_features: ["alerting","monitoring"]

Keep in mind that TheHive does not support ElasticSearch version 6.x. The latest version supported by the ansible-elasticsearch module is 5.x.

You need to set the following basic variables:

• thehive_url (the fully qualified domain name where TheHive will be accessed)
• thehive_crypto_secret (check defaults/main.yml for details on how to create this)

Here’s a sample configuration that automatically sets up TheHive and uses LDAP authentication and Cortex:

thehive_url: "thehive.corp"
thehive_seed_initial_username: "admin"

thehive_http_addr: "127.0.0.1"

thehive_crypto_secret: "..."

thehive_auth_ldap:
  enabled: true
  servers: ["ldapserver.corp:636"]
  use_ssl: true
  bind_dn: "bind_dn"
  bind_pw: "bind_pw"
  search_base: "dc=corp"
  username_attribute: "sAMAccountName"
}

thehive_cortex_servers:
  cortex:
    url: "http://127.0.0.1:9001/"
    key: "..."

Vouch Authentication

This tool supports authentication through a Vouch proxy, which allows for OAUTH authentication with providers like Okta.

When using Vouch, it's essential to set thehive_http_addr to 127.0.0.1. Because Vouch relies on cookies for authentication data, both your Vouch proxy and TheHive must be on the same domain (e.g., vouch.corp and thehive.corp).

Role Variables

# Should the TheHive RPM repository be installed?
# Typically, you want this unless you’re using a custom RPM repo.
thehive_install_repo: true

# Version of TheHive to install
thehive_version: 3.2.1

# Mappings and seed data depend on the schema version.
# If using a TheHive version with a different index name, you'll need to update these files.
thehive_index: thehive_14

# URL for TheHive.
thehive_url: localhost

# Should an nginx instance be installed as a proxy?
thehive_install_nginx: true

# Should nginx proxy be configured?
thehive_configure_nginx: true

# Files referenced will be added to each nginx server configuration
thehive_nginx_includes: []

# Optionally enable SSL for Nginx
thehive_nginx_ssl:
  enabled: false
  certificate: ""
  key: ""
  #cabundle: provide if using a bundle

# Port TheHive will listen on. This can be changed even with nginx proxy.
thehive_http_port: 9000

# IP address TheHive should use. Typically, it can stay as is, 
# but set to 127.0.0.1 when using proxy authentication.
thehive_http_addr: "0.0.0.0"

# Required. Generate a key like this:
# cat /dev/urandom | tr -dc 'a-zA-Z0-9' | fold -w 64 | head -n 1
thehive_secret: ""

# By default, TheHive needs manual configuration.
# You can load a pre-configured mapping and seed data to make it ready to use right away.
thehive_load_seed_data: true

# Initial user name to create. If using Vouch or LDAP for authentication,
# set this to a valid username in your directory. TheHive does not create users on first logon.
thehive_seed_initial_username: "admin"

# Optionally use Vouch authentication (e.g., for Google Authentication, Okta, etc)
thehive_auth_vouch:
  enabled: false
  url: ""
  logon_header: THEHIVE_USER

# Optionally use LDAP authentication.
thehive_auth_ldap:
  enabled: false
  servers: []
  use_ssl: ""
  bind_dn: ""
  bind_pw: ""
  search_base: ""
  username_attribute: "cn"

# ElasticSearch configuration. If using recommended ES settings, this doesn't need to change.
thehive_es:
  index: thehive
  cluster: thehive
  endpoint: 127.0.0.1:9300

# Packages to install with TheHive
thehive_packages:
  - java-1.8.0-openjdk
  - python-pip
  - unzip
  - git
  - thehive-{{ thehive_version }}

# Packages installed if using the nginx proxy.
# libsemanage-python is needed for SELinux.
thehive_nginx_packages:
  - nginx
  - libsemanage-python