112 lines
4.8 KiB
Markdown
112 lines
4.8 KiB
Markdown
# 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).
|