Update README, and reformat as Markdown
This commit is contained in:
Andrew Ayer
parent
61e3d80f57
commit
d4cf32f9b3
151
README
151
README
|
|
@ -1,151 +0,0 @@
|
||||||
Cert Spotter is a Certificate Transparency log monitor from SSLMate that
|
|
||||||
alerts you when a SSL/TLS certificate is issued for one of your domains.
|
|
||||||
Cert Spotter is easier than other open source CT monitors, since it does
|
|
||||||
not require 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 that
|
|
||||||
requires zero setup and provides an easy web dashboard to centrally
|
|
||||||
manage your certificates. Visit <https://sslmate.com/certspotter>
|
|
||||||
to sign up.
|
|
||||||
|
|
||||||
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.
|
|
||||||
|
|
||||||
|
|
||||||
USING CERT SPOTTER
|
|
||||||
|
|
||||||
The easiest way to use Cert Spotter is to sign up for an account at
|
|
||||||
<https://sslmate.com/certspotter>. If you want to run Cert Spotter on
|
|
||||||
your own server, follow these instructions.
|
|
||||||
|
|
||||||
Cert Spotter requires Go version 1.17 or higher.
|
|
||||||
|
|
||||||
1. Install Cert Spotter using the `go` command:
|
|
||||||
|
|
||||||
go install software.sslmate.com/src/certspotter/cmd/certspotter@latest
|
|
||||||
|
|
||||||
2. Create a file called ~/.certspotter/watchlist listing 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. Create a cron job to periodically run `certspotter`. See below for
|
|
||||||
command line options.
|
|
||||||
|
|
||||||
Every time you run Cert Spotter, it scans all browser-recognized
|
|
||||||
Certificate Transparency logs for certificates matching domains on
|
|
||||||
your watch list. When Cert Spotter detects a matching certificate, it
|
|
||||||
writes a report to standard out, which the Cron daemon emails to you.
|
|
||||||
Make sure you are able to receive emails sent by Cron.
|
|
||||||
|
|
||||||
Cert Spotter also saves a copy of matching certificates in
|
|
||||||
~/.certspotter/certs (unless you specify the -no_save option).
|
|
||||||
|
|
||||||
When Cert Spotter has previously monitored a log, it scans the log
|
|
||||||
from the previous position, to avoid downloading the same log entry
|
|
||||||
more than once. (To override this behavior and scan all logs from the
|
|
||||||
beginning, specify the -all_time option.)
|
|
||||||
|
|
||||||
When Cert Spotter has not previously monitored a log, it can either start
|
|
||||||
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,
|
|
||||||
specify the -start_at_end option.
|
|
||||||
|
|
||||||
You can add and remove domains on your watchlist at any time. However,
|
|
||||||
the certspotter command only notifies you of certificates that were
|
|
||||||
logged since adding a domain to the watchlist, unless you specify the
|
|
||||||
-all_time option, which requires scanning the entirety of every log
|
|
||||||
and takes many days to complete with a fast Internet connection.
|
|
||||||
To examine preexisting certificates, it's better to use the Cert
|
|
||||||
Spotter service <https://sslmate.com/certspotter>, the Cert Spotter
|
|
||||||
API <https://sslmate.com/certspotter/api>, or a CT search engine such
|
|
||||||
as <https://crt.sh>.
|
|
||||||
|
|
||||||
|
|
||||||
COMMAND LINE FLAGS
|
|
||||||
|
|
||||||
-watchlist FILENAME
|
|
||||||
File containing identifiers to watch, one per line, as described
|
|
||||||
above (use - to read from stdin). Default: ~/.certspotter/watchlist
|
|
||||||
-no_save
|
|
||||||
Do not save a copy of matching certificates.
|
|
||||||
-start_at_end
|
|
||||||
Start monitoring logs from the end, rather than the beginning.
|
|
||||||
This significantly reduces the time to run Cert Spotter, but
|
|
||||||
you will miss certificates that were added to a log before Cert
|
|
||||||
Spotter started monitoring it.
|
|
||||||
-all_time
|
|
||||||
Scan for certificates from all time, not just those logged since
|
|
||||||
the previous run of Cert Spotter.
|
|
||||||
-logs FILENAME_OR_URL
|
|
||||||
Filename of HTTPS URL of a JSON file containing logs to monitor, in the format
|
|
||||||
documented at <https://www.certificate-transparency.org/known-logs>.
|
|
||||||
Default: https://loglist.certspotter.org/monitor.json which includes the union
|
|
||||||
of active logs recognized by Chrome and Apple.
|
|
||||||
-state_dir PATH
|
|
||||||
Directory for storing state. Default: ~/.certspotter
|
|
||||||
-verbose
|
|
||||||
Be verbose.
|
|
||||||
|
|
||||||
|
|
||||||
WHAT CERTIFICATES ARE DETECTED BY CERT SPOTTER?
|
|
||||||
|
|
||||||
Any certificate that is logged to a Certificate Transparency log trusted
|
|
||||||
by Chromium will be detected by Cert Spotter. All certificates issued
|
|
||||||
after April 30, 2018 must be logged to such a log to be trusted by Chromium.
|
|
||||||
|
|
||||||
Generally, certificate authorities will automatically submit certificates
|
|
||||||
to logs so that they will work in Chromium. In addition, certificates
|
|
||||||
that are discovered during Internet-wide scans are submitted to Certificate
|
|
||||||
Transparency logs.
|
|
||||||
|
|
||||||
|
|
||||||
SECURITY
|
|
||||||
|
|
||||||
Cert Spotter assumes an adversarial model in which an attacker produces
|
|
||||||
a certificate that is accepted by at least some clients but goes
|
|
||||||
undetected because of an encoding error that prevents CT monitors from
|
|
||||||
understanding it. To defend against this attack, Cert Spotter uses a
|
|
||||||
special certificate parser that keeps the certificate unparsed except
|
|
||||||
for the identifiers. If one of the identifiers matches a domain on your
|
|
||||||
watchlist, you will be notified, even if other parts of the certificate
|
|
||||||
are unparsable.
|
|
||||||
|
|
||||||
Cert Spotter takes special precautions to ensure identifiers are parsed
|
|
||||||
correctly, and implements defenses against identifier-based attacks.
|
|
||||||
For instance, if a DNS identifier contains a null byte, Cert Spotter
|
|
||||||
interprets it as two identifiers: the complete identifier, and the
|
|
||||||
identifier formed by truncating at the first null byte. For example, a
|
|
||||||
certificate for example.org\0.example.com will alert the owners of both
|
|
||||||
example.org and example.com. This defends against null prefix attacks
|
|
||||||
<http://www.thoughtcrime.org/papers/null-prefix-attacks.pdf>.
|
|
||||||
|
|
||||||
SSLMate continuously monitors CT logs to make sure every certificate's
|
|
||||||
identifiers can be successfully parsed, and will release updates to
|
|
||||||
Cert Spotter as necessary to fix parsing failures.
|
|
||||||
|
|
||||||
Cert Spotter understands wildcard and redacted DNS names, and will alert
|
|
||||||
you if a wildcard or redacted certificate might match an identifier on
|
|
||||||
your watchlist. For example, a watchlist entry for sub.example.com would
|
|
||||||
match certificates for *.example.com or ?.example.com.
|
|
||||||
|
|
||||||
Cert Spotter is not just a log monitor, but also a log auditor which
|
|
||||||
checks that the log is obeying its append-only property. A future
|
|
||||||
release of Cert Spotter will support gossiping with other log monitors
|
|
||||||
to ensure the log is presenting a single view.
|
|
||||||
|
|
@ -0,0 +1,111 @@
|
||||||
|
# Cert Spotter - Certificate Transparency Monitor
|
||||||
|
|
||||||
|
**Cert Spotter** is a Certificate Transparency log monitor from SSLMate that
|
||||||
|
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
|
||||||
|
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 that
|
||||||
|
requires zero setup and provides an easy web dashboard to centrally
|
||||||
|
manage your certificates. Visit <https://sslmate.com/certspotter>
|
||||||
|
to sign up.
|
||||||
|
|
||||||
|
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.
|
||||||
|
|
||||||
|
## Quickstart
|
||||||
|
|
||||||
|
Cert Spotter requires Go version 1.19 or higher.
|
||||||
|
|
||||||
|
1. Install the certspotter command using the `go` command:
|
||||||
|
|
||||||
|
```
|
||||||
|
go install software.sslmate.com/src/certspotter/cmd/certspotter@latest
|
||||||
|
```
|
||||||
|
|
||||||
|
2. Create a watch list file 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:
|
||||||
|
|
||||||
|
* `-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
|
||||||
|
```
|
||||||
|
|
||||||
|
## 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)
|
||||||
|
* [Change Log](CHANGELOG.md)
|
||||||
|
|
||||||
|
## What certificates are detected by Cert Spotter?
|
||||||
|
|
||||||
|
In the default configuration, any certificate that is logged to a Certificate
|
||||||
|
Transparency log recognized by Google Chrome or Apple will be detected by
|
||||||
|
Cert Spotter. By default, Google Chrome and Apple only accept certificates that
|
||||||
|
are logged, so any certificate that works in Chrome or Safari will be detected
|
||||||
|
by Cert Spotter.
|
||||||
|
|
||||||
|
## Security
|
||||||
|
|
||||||
|
Cert Spotter assumes an adversarial model in which an attacker produces
|
||||||
|
a certificate that is accepted by at least some clients but goes
|
||||||
|
undetected because of an encoding error that prevents CT monitors from
|
||||||
|
understanding it. To defend against this attack, Cert Spotter uses a
|
||||||
|
special certificate parser that keeps the certificate unparsed except
|
||||||
|
for the identifiers. If one of the identifiers matches a domain on your
|
||||||
|
watchlist, you will be notified, even if other parts of the certificate
|
||||||
|
are unparsable.
|
||||||
|
|
||||||
|
Cert Spotter takes special precautions to ensure identifiers are parsed
|
||||||
|
correctly, and implements defenses against identifier-based attacks.
|
||||||
|
For instance, if a DNS identifier contains a null byte, Cert Spotter
|
||||||
|
interprets it as two identifiers: the complete identifier, and the
|
||||||
|
identifier formed by truncating at the first null byte. For example, a
|
||||||
|
certificate for `example.org\0.example.com` will alert the owners of both
|
||||||
|
`example.org` and `example.com`. This defends against [null prefix attacks]
|
||||||
|
(http://www.thoughtcrime.org/papers/null-prefix-attacks.pdf).
|
||||||
|
|
||||||
|
SSLMate continuously monitors CT logs to make sure every certificate's
|
||||||
|
identifiers can be successfully parsed, and will release updates to
|
||||||
|
Cert Spotter as necessary to fix parsing failures.
|
||||||
|
|
||||||
|
Cert Spotter understands wildcard DNS names, and will alert
|
||||||
|
you if a wildcard certificate might match an identifier on
|
||||||
|
your watchlist. For example, a watchlist entry for `sub.example.com` would
|
||||||
|
match certificates for `*.example.com`.
|
||||||
|
|
||||||
|
Cert Spotter is not just a log monitor, but also a log auditor which
|
||||||
|
checks that the log is obeying its append-only property. A future
|
||||||
|
release of Cert Spotter will support gossiping with other log monitors
|
||||||
|
to ensure the log is presenting a single view.
|
||||||
|
|
||||||
|
## Copyright
|
||||||
|
|
||||||
|
Copyright © 2016-2023 Opsmate, Inc.
|
||||||
|
|
||||||
|
Licensed under the [Mozilla Public License Version 2.0](LICENSE).
|
||||||
Loading…
Reference in New Issue