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