certspotter(8) | System Manager's Manual | certspotter(8) |
certspotter - Certificate Transparency Log Monitor
certspotter [-start_at_end] [-watchlist FILENAME] [-email ADDRESS] ...
Cert Spotter is a Certificate Transparency log monitor from SSLMate that alerts you when a SSL/TLS certificate is issued for one of your domains. Cert Spotter is easier to use than other open source CT monitors, since it does not require a database. It’s also more robust, since it uses a special certificate parser that ensures it won’t miss certificates.
Cert Spotter is also available as a hosted service by SSLMate, https://sslmate.com/certspotter.
You can use Cert Spotter to detect:
-batch_size NUMBER
-email ADDRESS
-healthcheck INTERVAL
-logs ADDRESS
-no_save
-script COMMAND
-start_at_end
-state_dir PATH
-stdout
-verbose
-version
-watchlist PATH
When certspotter detects a certificate matching your watchlist, or encounters an error that is preventing it from discovering certificates, it notifies you as follows:
Sending email requires a working sendmail(1) command. For details about the script interface, see certspotter-script(8).
certspotter continuously monitors all browser-recognized Certificate Transparency logs looking for certificates which are valid for any domain on your watch list. When certspotter detects a matching certificate, it emails you, executes a script, and/or writes a report to standard out, as described above.
certspotter also saves a copy of matching certificates in $CERTSPOTTER_STATE_DIR/certs (“~/.certspotter/certs” by default) unless you specify the -no_save option.
When certspotter has not previously monitored a log, it can either start monitoring the log from the beginning, or seek to the end of the log and start monitoring from there. Monitoring from the beginning guarantees detection of all certificates, but requires downloading hundreds of millions of certificates, which takes days. The default behavior is to monitor from the beginning. To start monitoring new logs from the end, specify the -start_at_end option.
If certspotter has previously monitored a log, it resumes monitoring the log from the previous position. This means that if you add a domain to your watch list, certspotter will not detect any certificates that were logged prior to the addition. To detect such certificates, you must delete $CERTSPOTTER_STATE_DIR/logs, which will cause certspotter to restart monitoring from the very beginning of each log (provided -start_at_end is not specified). This will cause certspotter to download hundreds of millions of certificates, which takes days. To find preexisting certificates, it’s faster to use the Cert Spotter service https://sslmate.com/certspotter, SSLMate’s Certificate Transparency Search API https://sslmate.com/ct_search_api, or a CT search engine such as https://crt.sh.
When certspotter encounters a problem with the local system (e.g. failure to write a file or execute a script), it prints a message to stderr and exits with a non-zero status.
When certspotter encounters a problem monitoring a log, it prints a message to stderr and continues running. It will try monitoring the log again later; most log errors are transient.
Every 24 hours (unless overridden by -healthcheck), certspotter performs the following health checks:
If any health check fails, certspotter notifies you by email, script, and/or standard out, as described above.
Health check failures should be rare, and you should take them seriously because it means certspotter might not detect all certificates. It might also be an indication of CT log misbehavior. Consult certspotter’s stderr output for details, and if you need help, file an issue at https://github.com/SSLMate/certspotter.
certspotter exits 0 when it receives SIGTERM or SIGINT, and non-zero when a serious error occurs.
CERTSPOTTER_STATE_DIR
CERTSPOTTER_CONFIG_DIR
HTTPS_PROXY
Copyright © 2016-2023 Opsmate, Inc.
Report bugs to https://github.com/SSLMate/certspotter.
2023-02-25 |