pyrox.dev
1# Cert Spotter {#module-services-certspotter}
2
3Cert Spotter is a tool for monitoring [Certificate Transparency](https://en.wikipedia.org/wiki/Certificate_Transparency)
4logs.
5
6## Service Configuration {#modules-services-certspotter-service-configuration}
7
8A basic config that notifies you of all certificate changes for your
9domain would look as follows:
10
11```nix
12services.certspotter = {
13 enable = true;
14 # replace example.org with your domain name
15 watchlist = [ ".example.org" ];
16 emailRecipients = [ "webmaster@example.org" ];
17};
18
19# Configure an SMTP client
20programs.msmtp.enable = true;
21# Or you can use any other module that provides sendmail, like
22# services.nullmailer, services.opensmtpd, services.postfix
23```
24
25In this case, the leading dot in `".example.org"` means that Cert
26Spotter should monitor not only `example.org`, but also all of its
27subdomains.
28
29## Operation {#modules-services-certspotter-operation}
30
31**By default, NixOS configures Cert Spotter to skip all certificates
32issued before its first launch**, because checking the entire
33Certificate Transparency logs requires downloading tens of terabytes of
34data. If you want to check the *entire* logs for previously issued
35certificates, you have to set `services.certspotter.startAtEnd` to
36`false` and remove all previously saved log state in
37`/var/lib/certspotter/logs`. The downloaded logs aren't saved, so if you
38add a new domain to the watchlist and want Cert Spotter to go through
39the logs again, you will have to remove `/var/lib/certspotter/logs`
40again.
41
42After catching up with the logs, Cert Spotter will start monitoring live
43logs. As of October 2023, it uses around **20 Mbps** of traffic on
44average.
45
46## Hooks {#modules-services-certspotter-hooks}
47
48Cert Spotter supports running custom hooks instead of (or in addition
49to) sending emails. Hooks are shell scripts that will be passed certain
50environment variables.
51
52To see hook documentation, see Cert Spotter's man pages:
53
54```ShellSession
55nix-shell -p certspotter --run 'man 8 certspotter-script'
56```
57
58For example, you can remove `emailRecipients` and send email
59notifications manually using the following hook:
60
61```nix
62services.certspotter.hooks = [
63 (pkgs.writeShellScript "certspotter-hook" ''
64 function print_email() {
65 echo "Subject: [certspotter] $SUMMARY"
66 echo "Mime-Version: 1.0"
67 echo "Content-Type: text/plain; charset=US-ASCII"
68 echo
69 cat "$TEXT_FILENAME"
70 }
71 print_email | ${config.services.certspotter.sendmailPath} -i webmaster@example.org
72 '')
73];
74```