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