Configure Database and Index Authentication#

In this tutorial, you'll secure your TheHive installation by configuring authentication for both Cassandra and Elasticsearch. By the end, you'll have password-protected access to your database and index back ends.

Maintenance window required

This procedure involves changing configuration files and restarting services. Schedule a maintenance window to prevent service disruption.

Configure authentication for Cassandra#

Step 1: Stop your services#

First, stop your running services in the following order to avoid data corruption:

Stop TheHive service
Stop Cassandra service

Service commands

Stop and restart commands depend on your installation method and the specific service. Refer to the official documentation for the appropriate commands.

Package installation: Depending on your distribution and the service, use systemctl or service. See the systemctl documentation and the service documentation for details.
Docker Compose deployment: Refer to the official Docker Compose documentation.
Kubernetes deployment: Refer to the kubectl scale documentation or the kubectl rollout restart documentation.

Step 2: Update Cassandra configuration#

Now you'll modify the Cassandra configuration to require authentication.

Locate the cassandra.yaml file.
Open the cassandra.yaml file using a text editor.
In the cassandra.yaml file, enable authentication.

Set the following parameters with these exact values:
```
authenticator: PasswordAuthenticator
authorizer: CassandraAuthorizer 
```
Save your modifications in the cassandra.yaml file.
Restart Cassandra service.

Step 3: Set a secure password for authentication#

Python compatibility for cqlsh

cqlsh requires Python 3.10 to 3.14. If your Linux distribution provides an older Python version by default, you must install a compatible version alongside it and explicitly use it to create the cqlsh virtual environment: /path/to/python3.12 -m venv "${VENV_PATH}".

By default, Cassandra uses the cassandra username and the password cassandra. For security reasons, especially in production environments, you must change this password immediately after setup.

To do this, you'll use CQL, the Cassandra Query Language, which is similar in purpose to SQL.

Install cqlsh.

Install cqlsh from PyPI in a Python virtual environment:
```
VENV_PATH=$HOME/.venv
sudo apt update
sudo apt install python3-venv
python3 -m venv "${VENV_PATH}"
"${VENV_PATH}/bin/pip" install cqlsh
```
On RPM-based distributions, skip the two apt commands. The venv module is included with Python.

Activate the virtual environment so that the cqlsh command runs from it, then verify the installation:
```
source "${VENV_PATH}/bin/activate"
cqlsh --version
```

Connect to Cassandra using default credentials.

cqlsh -u cassandra -p cassandra

If the connection is successful, you'll see output similar to:

Connected to xxx at xx.xx.xx.xx:xxxx
[cqlsh 6.2.0 | Cassandra 4.1.9 | CQL spec 3.4.6 | Native protocol v5]

Change the default password.
```
ALTER USER cassandra WITH PASSWORD '<authentication_cassandra_password>';
```
Replace <authentication_cassandra_password> with the password you intend to use for the cassandra superuser account.
Disconnect from the session.

Press Ctrl+D to exit the cqlsh shell.
Reconnect using your new password.
```
cqlsh -u cassandra
```

Step 4: Create a new administrator role for authentication#

To avoid relying on the default cassandra superuser account, create a new administrator role and then deactivate or delete the default user.

Create the admin role.
```
CREATE ROLE admin WITH PASSWORD = '<authentication_admin_password>' AND LOGIN = true AND SUPERUSER = true;
```
Replace <authentication_admin_password> with the password you intend to use for the admin superuser account.
Disconnect from the session.

Press Ctrl+D to exit the cqlsh shell.
Reconnect as the new admin.
```
cqlsh -u admin
```
Deactivate the default cassandra user.
```
ALTER ROLE cassandra WITH SUPERUSER = false AND LOGIN = false;
```
If your security policy requires deleting default accounts, delete the role instead:
```
DROP ROLE cassandra;
```

Step 5: Create a role for TheHive#

Create a dedicated role that TheHive will use to connect to Cassandra.

Create a dedicated role for TheHive.
```
CREATE ROLE thehive WITH LOGIN = true AND PASSWORD = '<thehive_role_password>';
```
Replace <thehive_role_password> with the password you intend to use for the thehive role.

Note this password

Keep this password secure. You will need to enter it later in TheHive configuration file so the application can connect to the Cassandra database.

Grant access to the keyspace.

GRANT ALL PERMISSIONS ON KEYSPACE thehive TO 'thehive';

Step 6: Update TheHive configuration#

Now you'll configure TheHive to use the credentials you just created.

Open the application.conf file using a text editor.

In the application.conf file, update the database configuration.

Example of database configuration with authentication

[..]
# Database and index configuration
db.janusgraph {
    storage {
        [..]
        # Cassandra authentication
        username = "thehive"
        password = "<thehive_role_password>"
        cql {
            keyspace = thehive
        }
    }
    index.search {
        [..]
    }
}
[..]

Replace <thehive_role_password> with the password set in Step 5.

To set up SSL for Cassandra connections, see Configure Database and Index SSL.

For additional connection parameters and advanced options, see TheHive Database and Index Connection Settings.

Save your modifications in the application.conf file.
Restart TheHive service.

At this point, your Cassandra database is secured with authentication.

Configure authentication for Elasticsearch#

Step 1: Stop services#

First, stop your running services in the following order to avoid data corruption:

Stop TheHive service
Stop Elasticsearch service

Service commands

Stop and restart commands depend on your installation method and the specific service. Refer to the official documentation for the appropriate commands.

Package installation: Depending on your distribution and the service, use systemctl or service. See the systemctl documentation and the service documentation for details.
Docker Compose deployment: Refer to the official Docker Compose documentation.
Kubernetes deployment: Refer to the kubectl scale documentation or the kubectl rollout restart documentation.

Step 2: Update Elasticsearch configuration#

Now you'll modify the Elasticsearch configuration to require authentication.

Open the /etc/elasticsearch/elasticsearch.yml file using a text editor.
In the elasticsearch.yml file, add the desired security parameters from the official Elasticsearch security settings documentation.

At minimum add the following line (or edit it if it already exists):
```
xpack.security.enabled: true
```
Restart Elasticsearch service.

Step 3: Set a user with the right permissions for TheHive#

Create a thehive user.
```
sudo /usr/share/elasticsearch/bin/elasticsearch-users useradd thehive -p <thehive_user_password> -r superuser
```
Replace <thehive_user_password> with a secure password you choose for your TheHive user.

Note this password

Keep this password secure. You will need to enter it later in TheHive configuration file so the application can connect to Elasticsearch.

Optional: Set a password for the elastic user.

For Elasticsearch 7.x:

sudo /usr/share/elasticsearch/bin/elasticsearch-setup-passwords interactive

For Elasticsearch 8.0:

sudo /usr/share/elasticsearch/bin/elasticsearch-reset-password

Skip this step if the password is already set.

Create or update a role with the privileges needed for TheHive.
- Create a role:
```
curl -u elastic:<elastic_user_password> -X POST "http://<elasticsearch_host>/_security/role/thehive_role" -H "Content-Type: application/json" -d '
{
  "cluster": ["manage"],
  "indices": [
    {
      "names": ["thehive*"],
      "privileges": ["all"]
    }
  ]
}'
```
Replace <elasticsearch_host> with localhost:9200 if you're running a standalone server deployment, or with the IP address or hostname of any one of your Elasticsearch nodes if you're running a cluster deployment. The security configuration is automatically replicated across all nodes.

Replace <elastic_user_password> with the password you set for the elastic user.

If successful, the command should return: {"role":{"created":true}}.

For more details, refer to the official Elasticsearch API documentation for role creation.
- Update a role:
```
curl -u elastic:<elastic_user_password> -X PUT "http://<elasticsearch_host>/_security/role/<role>" -H "Content-Type: application/json" -d '
{
  "cluster": ["manage"],
  "indices": [
    {
      "names": ["thehive*"],
      "privileges": ["all"]
    }
  ]
}'
```
Replace <elasticsearch_host> with localhost:9200 if you're running a standalone server deployment, or with the IP address or hostname of any one of your Elasticsearch nodes if you're running a cluster deployment. The security configuration is automatically replicated across all nodes.

Replace <role> with the actual role name you want to update.

Replace <elastic_user_password> with the password you set for the elastic user.

For more details, refer to the official Elasticsearch API documentation for updating roles.
Assign the role to the user you'll use for TheHive.
```
curl -u elastic:<elastic_user_password> -X PUT "http://<elasticsearch_host>/_security/user/thehive" \
-H "Content-Type: application/json" \
-d '{
    "password" : "<thehive_user_password>",
    "roles" : ["thehive_role"]
}'
```
Replace <elasticsearch_host> with localhost:9200 if you're running a standalone server deployment, or with the IP address or hostname of any one of your Elasticsearch nodes if you're running a cluster deployment. The security configuration is automatically replicated across all nodes.

Replace <thehive_user_password> with the password you set for the thehive user.

Replace <elastic_user_password> with the password you set for the elastic user.

Replace thehive_role with actual role name if different.

If successful, the command should return: {"created":true}.

For more details, refer to the official Elasticsearch API documentation for updating users.

Step 4: Update TheHive configuration#

Now you'll configure TheHive to use the credentials you just created.

Open the application.conf file using a text editor.

In the application.conf file, update the index configuration.

Example of index configuration with authentication

[..]
# Database and index configuration
db.janusgraph {
    storage {
        [..]
    }
    index.search {
        [..]
        # Elasticsearch authentication
        elasticsearch {
            http {
                auth {
                    type = basic
                    basic {
                        username = "thehive"
                        password = "<thehive_user_password>"
                    }
                }
            }
        }
    }
}
[..]

Replace <thehive_user_password> with the password set in Step 3.

To set up SSL for Elasticsearch connections, see Configure Database and Index SSL.

For additional connection parameters and advanced options, see TheHive Database and Index Connection Settings.

Save your modifications in the application.conf file.
Restart TheHive service.

At this point, Elasticsearch is secured and requires valid credentials for access.

Next steps

Configure Database and Index SSL