Using NGINX for targeted access to the Sensu Core 1.4 API

This is a first in a series of posts under the banner “Jef Practices” — short, technical how-to articles focused on sharing useful tips to help make better use of Sensu. Think of these posts as conversation starters for approaches to common challenges you’ll run into as your Sensu usage grows in complexity.

Summary

NGINX can be used as a proxy to provide authenticated access to specific endpoints for any RESTful service API — including the Sensu API. Below I provide an NGINX configuration to grant external service provides narrow access to only create check results in the Sensu 1.4 API external service providers. But first, here’s some backstory of how I got here.

Backstory

I was working on integrating my Sensu 1.x install with Particle.io a couple of weeks ago — I’ll write that up in more detail soon. I’m just getting started with Particle IoT devices, but I have an interesting personal project in mind for an IoT network that involves driving data into the Sensu event pipeline.

I find IoT networks quite fascinating: they’re really making it possible to cost effectively instrument much of our physical environment. If you want to be inspired, take a look at this article about how Particle devices are being used to monitor the deadly volcanic emissions in Hawaii.

While working on driving a check result into Sensu from my Particle device, I found I needed to expose the Sensu 1.4 results API to the particle service to make use of Particle.io’s webhook integration. Particle.io is an external service outside of my control, so I don’t want to trust it with access beyond what is absolutely necessary. Here’s a rundown of security precautions I’m looking to enforce:

• Only allow Particle.io webhook access to the Sensu 1.4 API /results POST endpoint.
• Make sure the Particle.io webhook has its own user/password separate from other API access so I can revoke Particle.io access without retooling other integrations.
• Use encrypted communication across the public network from Particle.io to my Sensu API service.

To accomplish all this, I set up a little NGINX reverse proxy to provide very narrow access that I could use to post check results — and that’s all. I thought it was useful enough config to share with everyone, as this is a pattern that can be used for any external service integration. Below you’ll find the cut-down server directive used in my nginx.conf.

A narrow-minded NGINX proxy config

server {

  listen    8080 default_server;
  listen    [::]:8080 default_server;
  server_name _;
  root      /usr/share/nginx/html;

  # Enable SSL using certs obtained via certbot
  # Checkout ‘Getting Started’ guide using letsencrypt.org 
  # You'll need to adjust the cert paths accordingly.
  ssl on;
  ssl_certificate /etc/letsencrypt/live/a.com/fullchain.pem;
  ssl_certificate_key /etc/letsencrypt/live/a.com/privkey.pem;
  ssl_session_cache shared:SSL:10m;

  # Match results endpoint exactly
  location = /results {

    # Only allow POST to the /results endpoint 
    limit_except POST {
      deny all;
    }

    # Setup basic http auth
    auth_basic "Restricted Access!";
    auth_basic_user_file /etc/nginx/conf.d/.htpasswd;

    # setup as a proxy for the actual Sensu API service
    proxy_pass http://127.0.0.1:4567;
    proxy_set_header Host $host;

    # needed if using Sensu 1.x config has http auth enabled
    # string is base64 encoded “user:password”
    #proxy_set_header Authorization "Basic dXNlckBwYXNzd29yZAo=";

  }
}

The referenced .htpasswd file contains whatever user/password combinations I want to require. I generate a different authentication for each external service I’d like to create check results to isolate service authentication.

This NGINX configuration example uses a Sensu 1.4 API process running on localhost with auth disabled, and relies on firewall rules to hide the Sensu API from the external network, treating all localhost access as trusted. If you want to proxy a Sensu 1.x API service with auth enabled, you can uncomment the proxy_set_header Authorization line and replace the base64 encoded string representing the Sensu API user and password.

With Sensu 2.0 — now in beta — none of this is necessary. The role-based access control baked into Sensu 2.0 makes it possible for me to define a specific role with its own password that has narrow access to create events — I’ll cover that in more detail in the afore-promised Particle.io integration blog post. In the meantime, stay tuned for more “Jef Practices” on the Sensu blog.