Update documentation

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?

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
 

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