Update documentation
This commit is contained in:
Andrew Ayer
parent
cd1b7a80ca
commit
838fc988cc
31
README.md
31
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?
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
Loading…
Reference in New Issue