79 lines
2.5 KiB
Markdown
79 lines
2.5 KiB
Markdown
|
# Cert Spotter {#module-services-certspotter}
|
||
|
|
|
||
|
|
Cert Spotter is a tool for monitoring [Certificate Transparency](https://en.wikipedia.org/wiki/Certificate_Transparency)
|
||
|
|
logs.
|
||
|
|
|
||
|
|
## Service Configuration {#modules-services-certspotter-service-configuration}
|
||
|
|
|
||
|
|
A basic config that notifies you of all certificate changes for your
|
||
|
|
domain would look as follows:
|
||
|
|
|
||
|
|
```nix
|
||
|
|
{
|
||
|
|
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 {#modules-services-certspotter-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 {#modules-services-certspotter-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:
|
||
|
|
|
||
|
|
```ShellSession
|
||
|
|
nix-shell -p certspotter --run 'man 8 certspotter-script'
|
||
|
|
```
|
||
|
|
|
||
|
|
For example, you can remove `emailRecipients` and send email
|
||
|
|
notifications manually using the following hook:
|
||
|
|
|
||
|
|
```nix
|
||
|
|
{
|
||
|
|
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
|
||
|
|
'')
|
||
|
|
];
|
||
|
|
}
|
||
|
|
```
|