Secure Sensu

As with any piece of software, it is critical to minimize any attack surface the software exposes. Sensu is no different. This guide describes the components you need to secure to make Sensu production-ready.

Before you can use this guide, you must have generated the certificates you will need to secure Sensu.

Secure etcd peer communication

You can secure etcd peer communication via the configuration at /etc/sensu/backend.yml. Here are the parameters you’ll need to configure:

##
# backend store configuration
##
etcd-listen-client-urls: "https://localhost:2379"
etcd-listen-peer-urls: "https://localhost:2380"
etcd-initial-advertise-peer-urls: "https://localhost:2380"
etcd-cert-file: "/path/to/your/cert"
etcd-key-file: "/path/to/your/key"
etcd-trusted-ca-file: "/path/to/your/ca/file"
etcd-peer-cert-file: "/path/to/your/peer/cert"
etcd-peer-key-file: "/path/to/your/peer/key"
etcd-peer-client-cert-auth: "true"
etcd-peer-trusted-ca-file: "/path/to/your/peer/ca/file"

Secure the API and web UI

The Sensu Go Agent API, HTTP API, and web UI use a common stanza in /etc/sensu/backend.yml to provide the certificate, key, and CA file needed to provide secure communication. Here are the attributes you’ll need to configure.

##
# backend ssl configuration
##
cert-file: "/path/to/ssl/cert.pem"
key-file: "/path/to/ssl/key.pem"
trusted-ca-file: "/path/to/trusted-certificate-authorities.pem"
insecure-skip-tls-verify: false

Providing these cert-file and key-file parameters will cause the Agent Websocket API and HTTP API to serve requests over SSL/TLS (https). As a result, you will also need to specify https:// schema for the api-url parameter:

##
# backend api configuration
##
api-url: "https://localhost:8080"

You can also specify a certificate and key for the web UI separately from the API using the dashboard-cert-file and dashboard-key-file parameters:

##
# backend ssl configuration
##
cert-file: "/path/to/ssl/cert.pem"
key-file: "/path/to/ssl/key.pem"
trusted-ca-file: "/path/to/trusted-certificate-authorities.pem"
insecure-skip-tls-verify: false
dashboard-cert-file: "/path/to/ssl/cert.pem"
dashboard-key-file: "/path/to/ssl/key.pem"

In this example, we provide the path to the cert, key, and CA file. After you restart the sensu-backend service, the parameters will load and you will able to access the web UI at https://localhost:3000. Configuring these attributes will also ensure that agents can communicate securely.

Secure Sensu agent-to-server communication

By default, an agent uses the insecure ws:// transport. Here’s an example from /etc/sensu/agent.yml:

---
##
# agent configuration
##
backend-url:
  - "ws://127.0.0.1:8081"

To use WebSocket over SSL/TLS (wss), change the backend-url value to the wss:// schema:

---
##
# agent configuration
##
backend-url:
  - "wss://127.0.0.1:8081"

The agent will connect to Sensu backends over wss. Remember, if you change the configuration to wss, plaintext communication will not be possible.

You can also provide a trusted CA as part of the agent configuration by passing --trusted-ca-file if you are starting the agent via sensu-agent start. You may include it as part of the agent configuration in /etc/sensu/agent.yml:

trusted-ca-file: "/path/to/trusted-certificate-authorities.pem"

Sensu agent mTLS authentication

COMMERCIAL FEATURE: Access client mutual transport layer security (mTLS) authentication in the packaged Sensu Go distribution. For more information, see Get started with commercial features.

By default, Sensu agents require username and password authentication to communicate with Sensu backends. For Sensu’s default user credentials and details about configuring Sensu role-based access control, see the RBAC reference and Create a read-only user.

Sensu can also use mutual transport layer security (mTLS) authentication for connecting agents to backends. When agent mTLS authentication is enabled, agents do not need to send password credentials to backends when they connect. To use secrets management, Sensu agents must be secured with mTLS. In addition, when using mTLS authentication, agents do not require an explicit user in Sensu. They will default to using the system:agents group.

You can still bind agents to a specific user when the system:agents group is problematic. For this use case, create a user that matches the Common Name (CN) of the agent’s certificate.

To view a certificate’s CN with openssl:

$ openssl x509 -in client.pem -text -noout
Certificate:
    Data:
        Version: 3 (0x2)
        Serial Number:
            37:57:7b:04:1d:67:63:7b:ff:ae:39:19:5b:55:57:80:41:3c:ec:ff
        Signature Algorithm: sha256WithRSAEncryption
        Issuer: CN = CA
        Validity
            Not Before: Sep 26 18:58:00 2019 GMT
            Not After : Sep 24 18:58:00 2024 GMT
        Subject: CN = client
...

The Subject: field indicates the certificate’s CN is client, so to bind the agent to a particular user in Sensu, create a user called client.

To enable agent mTLS authentication, create and distribute new certificates and keys according to the Generate certificates guide. Once the TLS certificate and key are in place, update the agent configuration using cert-file and key-file security configuration flags.

After you create backend and agent certificates, modfiy the backend and agent configuration:

##
# backend configuration
##
agent-auth-cert-file: "/path/to/backend-1.pem"
agent-auth-key-file: "/path/to/backend-1-key.pem"
agent-auth-trusted-ca-file: "/path/to/ca.pem"

##
# agent configuration
##
cert-file: "/path/to/agent-1.pem"
key-file: "/path/to/agent-1-key.pem"
trusted-ca-file: "/path/to/ca.pem"

You can use use certificates for authentication that are distinct from other communication channels used by Sensu, like etcd or the API. However, deployments can also use the same certificates and keys for etcd peer and client communication, the HTTP API, and agent authentication without issues.

Next step: Run a Sensu cluster

Well done! Your Sensu installation should now be secured with TLS. The last step before you deploy Sensu is to set up a Sensu cluster.