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
+3. Place one or more email addresses in the `$HOME/.certspotter/email_recipients`
-   the following command line options:
+   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.
+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
-   * `-email ADDRESS` to specify an email address which certspotter will contact
+   logs at the end instead of the beginning.  This saves significant bandwidth, but
-     when it detects a domain on your watch list.  (Your system must have a
+   you won't be notified about certificates which were logged before you started
-     working sendmail command.)
+   using certspotter.
-
-   * (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
-   ```
 
 ## 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
+**certspotter-script** is *any* program that is executed by **certspotter(8)**
-*-script* argument. **certspotter** executes this program when it needs to notify
+when it needs to notify you about an event, such as detecting a certificate for
-you about an event, such as detecting a certificate for a domain on your watch list.
+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`
+emails you, executes a script, and/or writes a report to standard out,
-is specified), and/or writes a report to standard out (if `-stdout`
+as described above.
-is specified).
 
 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`
+If any health check fails, certspotter notifies you by email, script, and/or
-is specified), script (if `-script` is specified), and/or standard out
+standard out, as described above.
-(if `-stdout` is specified).
 
 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