security-onion-letsencrypt.md

Automate LetsEncrypt certificate deployment in SecurityOnion

Prerequisites

• A domain name
• A DNS provider that works with Certbot. I'm using Cloudflare.
• An API token for the DNS provider that is scoped to allow TXT record creation.
• SecurityOnion 2.4 with sudo privileges and SSH access.

Turn on user certs in Security Onion (do this only once)

1. Administration -> Configuration
2. Options -> Show all configurable settings, including advanced settings
3. Filter "cert"
4. nginx -> ssl -> Replace Default Cert (ssl/tls in SO <= 2.4.80)
5. Replace deafult cert: set to True
6. Don't replace the key files yet - we're going to automate this!

Setup LetsEncrypt

Note: some of these commands may seem unnecessary, e.g. the symlinks. Don't skip them. SecurityOnion 2.4 is based on Oracle Linux, which has some quirks.

1. Log in as your admin user and su to root.

   sudo su

2. Install snapd.

   yum install epel-release
   yum install -y snapd
   ln -s /var/lib/snapd/snap /snap

   Check to ensure that the snapd service is running.

   sudo systemctl status snapd

   If it is not running, start the service.

   sudo systemctl start snapd

3. Install certbot.

   snap install --classic certbot
   ln -s /snap/bin/certbot /usr/bin/certbot

4. Install certbot Cloudflare DNS plugin.

   snap set certbot trust-plugin-with-root=ok
   snap install certbot-dns-cloudflare

5. Initialize the /etc/letsencrypt directory by running certbot without any arguments. Ignore the errors.

   certbot

6. Add Cloudflare DNS API token.

   TOKEN={enter your Cloudflare API token here}
   echo dns_cloudflare_api_token=$TOKEN > /etc/letsencrypt/cloudflare.ini
   chmod 400 /etc/letsencrypt/cloudflare.ini

7. Request the certificate. Replace your.fqdn.xyz with the FQDN of your SecurityOnion server.

   FQDN=your.fqdn.xyz
   certbot certonly --dns-cloudflare --dns-cloudflare-credentials /etc/letsencrypt/cloudflare.ini -d $FQDN

8. Copy the cert and key to SecurityOnion's nginx salt config.

   cp -f /etc/letsencrypt/live/$FQDN/privkey.pem /opt/so/saltstack/local/salt/nginx/ssl/ssl.key
   chmod 644 /opt/so/saltstack/local/salt/nginx/ssl/ssl.key
   cp -f /etc/letsencrypt/live/$FQDN/fullchain.pem /opt/so/saltstack/local/salt/nginx/ssl/ssl.crt
   chmod 640 /opt/so/saltstack/local/salt/nginx/ssl/ssl.crt

9. Restart nginx.

   so-nginx-restart

   Clear your browser cache (or use an incognito window) and visit your SO admin page to ensure that the new certificate is presented.

10. Create a post-hook to perform this each time certs are renewed.

    cat <<EOF > /etc/letsencrypt/copy_to_nginx.sh
    cp -f /etc/letsencrypt/live/$FQDN/privkey.pem /opt/so/saltstack/local/salt/nginx/ssl/ssl.key
    chmod 644 /opt/so/saltstack/local/salt/nginx/ssl/ssl.key
    cp -f /etc/letsencrypt/live/$FQDN/fullchain.pem /opt/so/saltstack/local/salt/nginx/ssl/ssl.crt
    chmod 640 /opt/so/saltstack/local/salt/nginx/ssl/ssl.crt
    so-nginx-restart
    EOF
    
    chmod +x /etc/letsencrypt/copy_to_nginx.sh

11. Test certbot renew, and create a cron job for it.

    certbot renew --dry-run --post-hook /etc/letsencrypt/copy_to_nginx.sh
    crontab -e

12. Place the following at the TOP of the file and save:

    # check certs once a week
    10 4 * * 0 certbot renew --post-hook /etc/letsencrypt/copy_to_nginx.sh

Maintenance

If the steps above succeeded, there is no special maintenance required. The cron job will renew the certs automatically before they expire.

Use SecurityOnion's built-in soup utility to maintain your SecurityOnion stack.

Follow up on this- I noticed that my cert had expired and found the cause is that the Cloudflare plugin needs to be updated. Here is the error-

The following plugins are using an outdated python version and must be updated to be compatible with Certbot 3.0. Please see https://community.letsencrypt.org/t/certbot-3-0-could-have-potential-third-party-snap-breakages/226940 for more information:
  * certbot-dns-cloudflare

Removing and re installing the Certbot snap doesn't work because that doesn't delete the old plugin.
After a bunch of trial and error I found this could be done with

# snap list | grep certbot-dns
certbot-dns-cloudflare  2.11.0              3451   latest/stable  certbot-eff**  -
# sudo snap remove certbot-dns-cloudflare

Once you've removed the old Cloudflare plugin, you can install a new one with

# snap install certbot-dns-cloudflare

There might be easier ways to simply update it, but this cost me a lot of time so worth documenting...

That's interesting. snapd automatically upgraded the Cloudflare plugin to 3.0.1 for me. 🤔

I looked extensively but couldn't find a method to update the plugin, I probably missed

sudo snap refresh certbot-dns-cloudflare

If anyone can verify this works- then I don't mind looking a bit dumb if it helps others...