Tandem/certspotter
2
0
Fork 0
mirror of https://github.com/SSLMate/certspotter.git synced 2025-07-03 10:47:17 +02:00
Code Issues Packages Projects Releases Wiki Activity

Update documentation

Browse Source
This commit is contained in:
Andrew Ayer 2023-02-20 10:35:44 -05:00
parent cd1b7a80ca
commit 838fc988cc
3 changed files with 56 additions and 28 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

31
README.md
View File

@ -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?

10
man/certspotter-script.md
View File

@ -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

43
man/certspotter.md
View File

@ -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