diff --git a/README b/README deleted file mode 100644 index 4f947bc..0000000 --- a/README +++ /dev/null @@ -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 -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 -. 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 , the Cert Spotter -API , or a CT search engine such -as . - - -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 . - 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 -. - -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. diff --git a/README.md b/README.md new file mode 100644 index 0000000..99cacf6 --- /dev/null +++ b/README.md @@ -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 +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).