Secure Configuration Guide#
Overview#
This page outlines a number of steps that can be taken in order to configure the Squirro environment in a more secure manner than out of the box. This includes Squirro-specific steps, such as encrypting configuration files or enabling single sign-on (SSO), but also shows how the operating systems and some of the shipped services can be configured in a more restrictive way.
Pre-Requisites#
Linux instance to be setup according to third party standards and protocols.
Familiarity with Squirro services and setup procedures.
Linux & Networking#
Firewall Settings#
Squirro Ports#
Incoming traffic to Squirro servers are open on a number of TCP ports. The individual ports and the required access level are documented below.
Storage Nodes#
On Squirro storage nodes all port except the following can be blocked.
TCP Port |
Usage |
Open for |
9200 |
Elasticsearch access |
All storage and Squirro nodes |
9300 |
Elasticsearch replication |
All storage nodes |
Squirro Nodes#
On Squirro cluster nodes all ports except the following can be blocked.
TCP Port |
Usage |
Open for |
443 |
Web and API access (SSL-protected) |
|
2181 |
Zookeeper |
|
2888 |
Zookeeper node discovery |
|
3306 |
MariaDB |
|
3888 |
Zookeeper node discovery |
|
6379 |
Redis (storage) |
|
6380 |
Redis (cache) |
|
For more information on configuring ports, see Installing Squirro on Linux.
Nginx#
Squirro ships with an Nginx web server which terminates web connections and then forwards them internally on the machine to the services.
SSL certificate#
For the HTTPS connection to the Squirro cluster node, a self-signed SSL certificate is generated by default. That certificate will trigger warnings for users and is not trusted by the Squirro Toolbox either. For security reasons, an SSL certificate should be issued by the respective body.
For more information on configuring SSL certificates, see SSL Certificates.
Limit TLS protocols#
As a compromise to security and compatibility, Squirro’s default configuration of Nginx allows TLS 1.0, 1.1 and 1.2. This can be reduced to only allow TLS 1.2 if the environment (users and clients connecting) allows that restriction.
To change, edit /etc/nginx/conf.d/ssl.inc
. Look for the ssl_protocols
and change it to:
ssl_protocols TLSv1.2;
The Red Hat Enterprise Linux 7 version of nginx does not yet support TLS 1.3.
Remove non-secure ports#
The default configuration listens on port 80 and 81 for HTTP and 443 for HTTPS. The ports 80 and 81 can be removed to avoid these connections (requiring further changes in the Squirro configuration below).
Edit /etc/nginx/conf.d/00-default.conf
and remove the following two lines:
listen 80;
listen 81;
MariaDB#
SSL certificate#
MariaDB can be configured to encrypt connections with TLS. For this, an SSL certificate needs to be provided at /etc/my.cnf.d/certificates/
. To create self-signed certificates, the official documentation for Certificate Creation with OpenSSL can be followed.
The files can then be provided to MariaDB by putting the following configuration into /etc/my.cnf.d/security.cnf
:
[server]
ssl_cert = /etc/my.cnf.d/certificates/server-cert.pem
ssl_key = /etc/my.cnf.d/certificates/server-key.pem
ssl_ca = /etc/my.cnf.d/certificates/ca.pem
Enabling SSL#
You must edit /etc/squirro/common.ini
and add the line ssl=true
in the db
section as follow:
[db]
mysql_transaction_isolation=READ COMMITTED
ssl=true
ssl_ca=<PATH_TO_SSL_CERTIFICATE>
Changing User Passwords#
Each Squirro service with a database has a dedicated MariaDB user. Squirro recommends the default passwords of these users are changed. This can be achieved using the following commands per service:
$ mysql -u root -p
USE mysql;
UPDATE user SET password=PASSWORD('YourPasswordHere') WHERE User='<service_user_name>';
FLUSH PRIVILEGES;
The service database users for which to do this are:
configuration
cluster (will only exist on multi-node installations)
datasource
emailsender
filtering
fingerprint
machinelearning
plumber
scheduler
topic
trends
user
The password can be different for each user.
Redis#
There are two Redis instances, one for queueing and more persistent metadata, and one for caching. Their respective configuration files are:
Storage:
/etc/redis/redis.conf
Cache:
/etc/redis/cache.conf
SSL certificate#
The Redis version shipped with Squirro does not currently allow SSL encryption. Later in 2020 Squirro aims to include Redis 6, which provides TLS encryption.
Changing Redis Passwords#
Squirro recommends the default passwords of the Redis instances be changed. In both configuration files, the password can be set on the lines:
masterauth <password>
…
requirepass <password>
The password for the two Redis instances should be the same.
Elasticsearch#
Note
Starting from Release 3.7.4, Squirro storage nodes use fully secured Elasticsearch out-of-the-box with a SSL and a default password. For that reason, there is no need to perform manual configuration.
SSL certificate#
Elasticsearch allows the encryption of communication with TLS.
For this the certificate files can be put into /etc/elasticsearch/certs
as:
servername.key
servername.crt
ca.crt
They are then referenced in /etc/elasticsearch/elasticsearch.yml
by adding the following lines:
xpack.ssl.key: certs/servername.key
xpack.ssl.certificate: certs/servername.crt
xpack.ssl.certificate_authorities: certs/ca.crt
xpack.security.transport.ssl.enabled: true
xpack.security.http.ssl.enabled: true
Full documentation is available in the Elasticsearch manual at Encrypting Communications.
Password#
A password can be defined to access Elasticsearch. For this the following line needs to be added to /etc/elasticsearch/elasticsearch.yml
:
xpack.security.enabled: true
The password can then be defined by calling the command:
/usr/share/elasticsearch/bin/elasticsearch-setup-passwords interactive
After you set your password, you are required to add this parameter to squirro, you must edit /etc/squirro/common.ini
and add the following lines (under [index]):
es_auth_user = elastic # or the user you selected
es_auth_password = YOUR_PASSWORD
NB: you can also generate a random password by calling:
/usr/share/elasticsearch/bin/bin/elasticsearch-setup-passwords auto -b
Important: On ES version < 7.7.1 you must first install x-pack and then the commands change as follow:
/usr/share/elasticsearch/bin/bin/x-pack/elasticsearch-setup-passwords auto -b
/usr/share/elasticsearch/bin/x-pack/setup-passwords interactive
See Cluster References for more information.
Accessing Elasticsearch#
Edit /etc/squirro/common.ini
and ensure the following lines point to your relevant Elasticsearch host(s):
[index]
es_index_servers = https://localhost:9200
If your Elasticsearch is on a remote host, the correct setting is as follows:
[index]
es_index_servers = https://hostname.yourdomain.tld:9200
If you use multiple hosts, the correct setting is as follows:
[index]
es_index_servers = https://hostname1.yourdomain.tld:9200, https://hostname2.yourdomain.tld:9200, https://hostname3.yourdomain.tld:9200
If you use self-signed certificates that the operating system cannot trust, you can provide your custom certificates as follows:
[index]
es_index_servers = https://hostname.yourdomain.tld:9200
es_pem_path = /path/to/your/ca.pem
Note: Ensure that the ca
file is readable by the squirro group (gid).
While not recommended in production, you can disable the SSL certificate verification as follows:
[index]
es_verify_certs = False
Example#
The following is a combined reference for example purposes:
[index]
auto_refresh = False
es_index_servers = https://hostname1.yourdomain.tld:9200, https://hostname2.yourdomain.tld:9200, https://hostname3.yourdomain.tld:9200
es_auth_user = elastic
es_auth_password = your-password
es_pem_path = /path/to/your/ca.pem
es_verify_certs = True
Caution
If you make any changes to /etc/squirro/common.ini
, you must restart the Squirro services for the changes to take effect using the command squirro_restart
.
Squirro#
SSO#
Squirro supports the use of Single Sign-On with multiple SAML protocols. Squirro recommends that is enabled for secure server setups.
For user guides on how to enable Single Sign-On for various providers, see SAML SSO for Squirro.
Change Session Secret#
To ensure the session cookies are hashed uniquely, you should add a custom secret key to the configuration file.
This must be set to the same value on all servers of a cluster.
See Session Secret Key for how to set this value.
Reducing Session Lifetime#
Note
The following section describes the behavior of a new sessions mode introduced with Squirro Release 3.8.6 LTS. This needs to be enabled in the Configuration Service with the security.expiring-sessions
settings.
Squirro user sessions expire based on the following two separate timeouts:
Session timeout, which logs a user out if they have not been active during that time window.
Maximum session duration, which can never be exceeded, independent of user activity.
These two default values are 12 hours and 7 days respectively. (This means a user’s session can be valid for up to 7 days, as long as they are active at least once every 12 hours.)
Depending on your security considerations, these values can be adjusted. To do so, edit /etc/squirro/frontend.ini
and add the following settings:
[frontend]
# Session timeout. This is calculated on every request and the cookie is
# extended correspondingly. (default: 12 hours)
session_timeout_seconds = 43200
# Maximum session lifetime that can not be exceeded. If the user is active in
# every `session_timeout_seconds` window between the session being created and
# `session_max_duration_seconds` the session will still be closed. (default: 7 days)
session_max_duration_seconds = 604800
Reference: For different recommendations for these values, refer to Session Expiration in the OWASP Session Management Cheat Sheet or NIST 800-63B.
Restoring Permanent Sessions#
Caution
Previous versions of this guide had recommended switching to session cookies. This is no longer recommended as some browsers, most notably Google Chrome, tend to persist session cookies indefinitely.
If you have followed previous versions of the guide, ensure that the corresponding setting is turned back on:
[frontend]
session_permanent = true
Restart the frontend service to activate both of these configuration file changes:
systemctl restart sqfrontendd
Changing database passwords#
The changed Redis and MariaDB passwords need to be updated in the configuration files. Where a Vault is used (see “Encrypting Configuration Files” section), the passwords can instead be set in the corresponding values there.
Filename |
INI file section |
INI file key |
Value |
Redis |
|||
|
redis |
password |
Redis password |
|
redis |
password |
Redis password |
|
redis_content |
password |
Redis password |
|
redis_cache |
password |
Redis password |
|
redis_http_cache |
password |
Redis password |
|
redis_provider_deduplication |
password |
Redis password |
|
redis_bloom |
password |
Redis password |
|
redis_studio |
password |
Redis password |
|
redis_studio_cache |
password |
Redis password |
|
queues_local |
redis_password |
Redis password |
|
redis_key_value_cache_provider |
redis_password |
Redis password |
|
redis_key_value_store_provider |
redis_password |
Redis password |
|
redis_email_history |
password |
Redis password |
|
redis_item_batching |
password |
Redis password |
|
redis_studio |
password |
Redis password |
|
redis_studio_cache |
password |
Redis password |
|
queues_local |
redis_password |
Redis password |
|
redis_duplicate |
password |
Redis password |
|
redis_nearduplicate |
password |
Redis password |
MariaDB |
|||
|
configuration |
db |
MariaDB password for user |
|
configuration |
db |
MariaDB password for user |
|
datasource |
db |
MariaDB password for user |
|
emailsender |
db |
MariaDB password for user |
|
filtering |
db |
MariaDB password for user |
|
filtering |
db |
MariaDB password for user |
|
machinelearning |
db |
MariaDB password for user |
|
plumber |
db |
MariaDB password for user |
|
scheduler |
db |
MariaDB password for user |
|
topic |
db |
MariaDB password for user |
|
topicproxy |
db |
MariaDB password for user |
|
trends |
db |
MariaDB password for user |
|
user |
db |
MariaDB password for user |
|
userproxy |
db |
MariaDB password for user |
Changing Endpoints for APIs#
If the HTTP ports have been disabled, Squirro needs to be changed to use the HTTPS endpoints. For this, edit /etc/squirro/common.ini
and change any occurrence of http://127.0.0.1:81/
to https://127.0.0.1/.
This can be achieved with the following command:
sed -i'' -e 's@http://127.0.0.1:81@https://127.0.0.1@' /etc/squirro/common.ini
Changing MariaDB connection to TLS#
SSL can be enabled for MariaDB connections by setting the following configuration value in /etc/squirro/common.ini
:
[db]
ssl=true
The [db]
section will already exist in the config file, thus the full section will then look something like this:
[db]
mysql_transaction_isolation=READ COMMITTED
ssl=true
Changing Default Session Passwords#
Squirro recommends that the below session passwords stored in /etc/squirro/frontend.ini
be changed from the default values:
[frontend]
# key used to create secure HMAC tokens from passwords
password_key = …
[flask_app]
secret_key = …
Random values can be generated for these.
Encrypting Configuration Files#
By default passwords (e.g. the passwords for Redis or MariaDB) are configured in plain text in the configuration files. However, Squirro can provide a mechanism so that this sensitive information is encrypted. There are three different ways to encrypt Squirro configuration files:
Encryption key in a Unix environment variable
Encryption key stored in a file
A custom command for encrypting and decrypting
For more information on the different types of encryption, see Securing Configuration Files.
Should there be some form of the vault where credentials are stored, Squirro can provide the necessary decryption tools in order to decrypt values.
Content Security Policy (CSP)#
The Content Security Policy for Squirro content can be defined in the server configurations. If for instance image resources that are references from within Squirro items are not loading, you can adapt the CSP accordingly to enable those cross-site references. For more information see below links.
Relevant Links: