diff --git a/README.md b/README.md index 6eb49a0..40a3798 100644 --- a/README.md +++ b/README.md @@ -32,34 +32,27 @@ Cert Spotter requires Go version 1.19 or higher. go install software.sslmate.com/src/certspotter/cmd/certspotter@latest ``` -2. Create a watch list file containing the DNS names you want to monitor, +2. Create a watch list file `$HOME/.certspotter/watchlist` containing the DNS names you want to monitor, one per line. To monitor an entire domain tree (including the domain itself and all sub-domains) prefix the domain name with a dot (e.g. `.example.com`). To monitor a single DNS name only, do not prefix the name with a dot. -3. Configure your system to run `certspotter` as a daemon. You should specify - the following command line options: +3. Place one or more email addresses in the `$HOME/.certspotter/email_recipients` + file (one per line), and/or place one or more executable scripts in the + `$HOME/.certspotter/hooks.d` directory. certspotter will email the listed + addresses (requires your system to have a working sendmail command) and + execute the provided scripts when it detects a domain on your watch list. - * `-watchlist PATH` to specify the path to your watch list file. - - * `-email ADDRESS` to specify an email address which certspotter will contact - when it detects a domain on your watch list. (Your system must have a - working sendmail command.) - - * (Optional) `-start_at_end` to tell certspotter to start monitoring logs at the end - instead of the beginning. This saves significant bandwidth, but you won't be - notified about certificates which were logged before you started using certspotter. - - For example: - - ``` - certspotter -watchlist /etc/certspotter.watchlist -email pki@certspotteruser.example -start_at_end - ``` +4. Configure your system to run `certspotter` as a daemon. You may want to specify + the `-start_at_end` command line option to tell certspotter to start monitoring + logs at the end instead of the beginning. This saves significant bandwidth, but + you won't be notified about certificates which were logged before you started + using certspotter. ## Documentation * Command line options and operational details: [certspotter(8) man page](man/certspotter.md) -* The `-script` interface: [certspotter-script(8) man page](man/certspotter-script.md) +* The script interface: [certspotter-script(8) man page](man/certspotter-script.md) * [Change Log](CHANGELOG.md) ## What certificates are detected by Cert Spotter? diff --git a/man/certspotter-script.md b/man/certspotter-script.md index 56c2e0d..82b4c83 100644 --- a/man/certspotter-script.md +++ b/man/certspotter-script.md @@ -4,9 +4,13 @@ # DESCRIPTION -**certspotter-script** is *any* program that is called using **certspotter(8)**'s -*-script* argument. **certspotter** executes this program when it needs to notify -you about an event, such as detecting a certificate for a domain on your watch list. +**certspotter-script** is *any* program that is executed by **certspotter(8)** +when it needs to notify you about an event, such as detecting a certificate for +a domain on your watch list. + +Scripts are placed in the `$CERTSPOTTER_CONFIG_DIR/hooks.d` directory +(`~/.certspotter/hooks.d` by default), or specified on the command line +using the `-script` argument. # ENVIRONMENT diff --git a/man/certspotter.md b/man/certspotter.md index 17aefec..728d09e 100644 --- a/man/certspotter.md +++ b/man/certspotter.md @@ -41,6 +41,12 @@ You can use Cert Spotter to detect: an error occurs. You can specify this option more than once to email multiple addresses. Your system must have a working sendmail(1) command. + Regardless of the `-email` option, certspotter also emails any address listed + in `$CERTSPOTTER_CONFIG_DIR/email_recipients` file + (`~/.certspotter/email_recipients` by default). (One address per line, + blank lines are ignored.) This file is read only at startup, so you + must restart certspotter if you change it. + -healthcheck *INTERVAL* : Perform a health check at the given interval (default: "24h") as described @@ -64,6 +70,10 @@ You can use Cert Spotter to detect: : Command to execute when a matching certificate is found or an error occurs. See certspotter-script(8) for information about the interface to scripts. + Regardless of the `-script` option, certspotter also executes any executable + file in the `$CERTSPOTTER_CONFIG_DIR/hooks.d` directory + (`~/.certspotter/hooks.d` by default). + -start\_at\_end : Start monitoring logs from the end rather than the beginning. @@ -103,14 +113,36 @@ You can use Cert Spotter to detect: certspotter reads the watch list only when starting up, so you must restart certspotter if you change it. +# NOTIFICATIONS + +When certspotter detects a certificate matching your watchlist, or encounters +an error that is preventing it from discovering certificates, it notifies you +as follows: + +* Emails any address specified by the `-email` command line flag. + +* Emails any address listed in the `$CERTSPOTTER_CONFIG_DIR/email_recipients` + file (`~/.certspotter/email_recipients` by default). (One address per line, + blank lines are ignored.) This file is read only at startup, so you + must restart certspotter if you change it. + +* Executes the script specified by the `-script` command line flag. + +* Executes every executable file in the `$CERTSPOTTER_CONFIG_DIR/hooks.d` + directory (`~/.certspotter/hooks.d` by default). + +* Writes the notification to standard out if the `-stdout` flag was specified. + +Sending email requires a working sendmail(1) command. For details about +the script interface, see certspotter-script(8). + # OPERATION 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 (if `-email` is specified), executes a script (if `-script` -is specified), and/or writes a report to standard out (if `-stdout` -is specified). +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) @@ -156,9 +188,8 @@ following health checks: since the previous health check. * Ensure that certspotter is not falling behind monitoring any logs. -If any health check fails, certspotter notifies you by email (if `-email` -is specified), script (if `-script` is specified), and/or standard out -(if `-stdout` is specified). +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