certspotter/man/certspotter.md

201 lines
7.2 KiB
Markdown
Raw Normal View History

2023-02-05 16:55:10 +01:00
# NAME
**certspotter** - Certificate Transparency Log Monitor
# SYNOPSIS
2023-02-05 16:58:05 +01:00
**certspotter** [`-start_at_end`] [`-watchlist` *FILENAME*] [`-email` *ADDRESS*] `...`
2023-02-05 16:55:10 +01:00
# DESCRIPTION
**Cert Spotter** is a Certificate Transparency log monitor from SSLMate that
2023-02-05 16:58:05 +01:00
alerts you when a SSL/TLS certificate is issued for one of your domains.
Cert Spotter is easier to use than other open source CT monitors, since it does not require
2023-02-05 16:55:10 +01:00
a database. It's also more robust, since it uses a special certificate parser
that ensures it won't miss certificates.
Cert Spotter is also available as a hosted service by SSLMate,
<https://sslmate.com/certspotter>.
You can use Cert Spotter to detect:
* Certificates issued to attackers who have compromised your DNS and
are redirecting your visitors to their malicious site.
* Certificates issued to attackers who have taken over an abandoned
sub-domain in order to serve malware under your name.
* Certificates issued to attackers who have compromised a certificate
authority and want to impersonate your site.
* Certificates issued in violation of your corporate policy
or outside of your centralized certificate procurement process.
# OPTIONS
2023-02-05 16:58:05 +01:00
-batch_size *NUMBER*
2023-02-05 16:55:10 +01:00
2023-02-05 16:58:05 +01:00
: Maximum number of entries to request per call to get-entries.
You should not generally need to change this. Defaults to 1000.
2023-02-05 16:55:10 +01:00
2023-02-05 16:58:05 +01:00
-email *ADDRESS*
2023-02-06 17:21:01 +01:00
: Email address to contact when a matching certificate is discovered, or
an error occurs. You can specify this option more than once to email
multiple addresses. Your system must have a working sendmail(1) command.
-healthcheck *INTERVAL*
: Perform a health check at the given interval (default: "24h") as described
below. *INTERVAL* must be a decimal number followed by "h" for hours or
"m" for minutes.
2023-02-05 16:58:05 +01:00
-logs *ADDRESS*
: Filename or HTTPS URL of a v2 or v3 JSON log list containing logs to monitor.
The schema for this file can be found at <https://www.gstatic.com/ct/log_list/v3/log_list_schema.json>.
2023-02-05 16:55:10 +01:00
Defaults to <https://loglist.certspotter.org/monitor.json>, which includes
2023-02-05 16:58:05 +01:00
the union of active logs recognized by Chrome and Apple. certspotter periodically
reloads the log list in case it has changed.
2023-02-06 17:22:48 +01:00
-no\_save
2023-02-05 16:55:10 +01:00
: Do not save a copy of matching certificates.
2023-02-05 16:58:05 +01:00
-script *COMMAND*
2023-02-05 16:55:10 +01:00
2023-02-06 17:21:01 +01:00
: Command to execute when a matching certificate is found or an error occurs. See
2023-02-05 16:58:05 +01:00
certspotter-script(8) for information about the interface to scripts.
2023-02-06 17:22:48 +01:00
-start\_at\_end
2023-02-05 16:55:10 +01:00
: Start monitoring logs from the end rather than the beginning.
**WARNING**: monitoring from the beginning guarantees detection of all
certificates, but requires downloading hundreds of millions of
certificates, which takes days.
2023-02-06 17:22:48 +01:00
-state\_dir *PATH*
2023-02-05 16:55:10 +01:00
2023-02-05 16:58:05 +01:00
: Directory for storing state. Defaults to `$CERTSPOTTER_STATE_DIR`, which is
"~/.certspotter" by default.
2023-02-05 16:55:10 +01:00
2023-02-05 16:58:05 +01:00
-stdout
2023-02-05 16:55:10 +01:00
2023-02-06 17:21:01 +01:00
: Write matching certificates and errors to stdout.
2023-02-05 16:55:10 +01:00
2023-02-05 16:58:05 +01:00
-verbose
2023-02-05 16:55:10 +01:00
2023-02-05 16:58:05 +01:00
: Be verbose.
2023-02-05 16:55:10 +01:00
2023-02-05 16:58:05 +01:00
-version
2023-02-05 16:55:10 +01:00
2023-02-05 16:58:05 +01:00
: Print version and exit.
2023-02-05 16:55:10 +01:00
2023-02-05 16:58:05 +01:00
-watchlist *PATH*
: File containing DNS names to monitor, one per line. To monitor an entire
domain namespace (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.
Defaults to `$CERTSPOTTER_CONFIG_DIR/watchlist`, which is
"~/.certspotter/watchlist" by default.
Specify `-` to read the watch list from stdin.
certspotter reads the watch list only when starting up, so you must restart
certspotter if you change it.
# 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).
certspotter also saves a copy of matching certificates in
`$CERTSPOTTER_STATE_DIR/certs` ("~/.certspotter/certs" by default)
unless you specify the `-no_save` option.
When certspotter has not previously monitored a log, it can either start
2023-02-05 16:55:10 +01:00
monitoring the log from the beginning, or seek to the end of the log and
start monitoring from there. Monitoring from the beginning guarantees
detection of all certificates, but requires downloading hundreds of
millions of certificates, which takes days. The default behavior is to
monitor from the beginning. To start monitoring new logs from the end,
2023-02-05 16:58:05 +01:00
specify the `-start_at_end` option.
If certspotter has previously monitored a log, it resumes monitoring
the log from the previous position. This means that if you add
a domain to your watch list, certspotter will not detect any certificates
that were logged prior to the addition. To detect such certificates,
you must delete `$CERTSPOTTER_STATE_DIR/logs`, which will cause certspotter
to restart monitoring from the very beginning of each log (provided
`-start_at_end` is not specified). This will cause certspotter to download
hundreds of millions of certificates, which takes days. To find preexisting
certificates, it's faster to use the Cert Spotter service
<https://sslmate.com/certspotter>, SSLMate's Certificate Transparency Search
API <https://sslmate.com/ct_search_api>, or a CT search engine such as
<https://crt.sh>.
2023-02-05 16:55:10 +01:00
2023-02-06 17:21:01 +01:00
# ERROR HANDLING
When certspotter encounters a problem with the local system (e.g. failure
to write a file or execute a script), it prints a message to stderr and
exits with a non-zero status.
When certspotter encounters a problem monitoring a log, it prints a message
to stderr and continues running. It will try monitoring the log again later;
most log errors are transient.
Every 24 hours (unless overridden by `-healthcheck`), certspotter performs the
following health checks:
* Ensure that the log list has been successfully retrieved at least once
since the previous health check.
* Ensure that every log has been successfully contacted at least once
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).
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
of CT log misbehavior. Consult certspotter's stderr output for details, and if
you need help, file an issue at <https://github.com/SSLMate/certspotter>.
2023-02-05 16:55:10 +01:00
# EXIT STATUS
2023-02-05 16:58:05 +01:00
certspotter exits 0 when it receives `SIGTERM` or `SIGINT`,
and non-zero when a serious error occurs.
2023-02-05 16:55:10 +01:00
# ENVIRONMENT
2023-02-05 16:58:05 +01:00
`CERTSPOTTER_STATE_DIR`
: Directory for storing state. Overridden by `-state_dir`. Defaults to
2023-02-05 16:55:10 +01:00
`~/.certspotter`.
2023-02-05 16:58:05 +01:00
`CERTSPOTTER_CONFIG_DIR`
: Directory from which any configuration, such as the watch list, is read.
2023-02-05 16:55:10 +01:00
Defaults to `~/.certspotter`.
2023-02-05 16:58:05 +01:00
`HTTPS_PROXY`
: URL of proxy server for making HTTPS requests. `http://`, `https://`, and
`socks5://` URLs are supported. By default, no proxy server is used.
2023-02-05 16:55:10 +01:00
# SEE ALSO
2023-02-05 16:58:05 +01:00
certspotter-script(8)
2023-02-05 16:55:10 +01:00
# COPYRIGHT
2023-02-05 16:58:05 +01:00
Copyright (c) 2016-2023 Opsmate, Inc.
2023-02-05 16:55:10 +01:00
# BUGS
2023-02-05 16:58:05 +01:00
Report bugs to <https://github.com/SSLMate/certspotter>.