depot/third_party/nixpkgs/nixos/modules/services/monitoring/certspotter.md

Cert Spotter

Cert Spotter is a tool for monitoring Certificate Transparency logs.

Service Configuration

A basic config that notifies you of all certificate changes for your domain would look as follows:

{
  services.certspotter = {
    enable = true;
    # replace example.org with your domain name
    watchlist = [ ".example.org" ];
    emailRecipients = [ "webmaster@example.org" ];
  };

  # Configure an SMTP client
  programs.msmtp.enable = true;
  # Or you can use any other module that provides sendmail, like
  # services.nullmailer, services.opensmtpd, services.postfix
}

In this case, the leading dot in ".example.org" means that Cert Spotter should monitor not only example.org, but also all of its subdomains.

Operation

By default, NixOS configures Cert Spotter to skip all certificates issued before its first launch, because checking the entire Certificate Transparency logs requires downloading tens of terabytes of data. If you want to check the entire logs for previously issued certificates, you have to set services.certspotter.startAtEnd to false and remove all previously saved log state in /var/lib/certspotter/logs. The downloaded logs aren't saved, so if you add a new domain to the watchlist and want Cert Spotter to go through the logs again, you will have to remove /var/lib/certspotter/logs again.

After catching up with the logs, Cert Spotter will start monitoring live logs. As of October 2023, it uses around 20 Mbps of traffic on average.

Hooks

Cert Spotter supports running custom hooks instead of (or in addition to) sending emails. Hooks are shell scripts that will be passed certain environment variables.

To see hook documentation, see Cert Spotter's man pages:

nix-shell -p certspotter --run 'man 8 certspotter-script'

For example, you can remove emailRecipients and send email notifications manually using the following hook:

{
  services.certspotter.hooks = [
    (pkgs.writeShellScript "certspotter-hook" ''
      function print_email() {
        echo "Subject: [certspotter] $SUMMARY"
        echo "Mime-Version: 1.0"
        echo "Content-Type: text/plain; charset=US-ASCII"
        echo
        cat "$TEXT_FILENAME"
      }
      print_email | ${config.services.certspotter.sendmailPath} -i webmaster@example.org
    '')
  ];
}