From 38b9c920eb3dcd034c4a4f517cca7c173bf3a603 Mon Sep 17 00:00:00 2001 From: Andrew Ayer Date: Wed, 27 Jul 2016 14:17:53 -0700 Subject: [PATCH] Add README --- README | 141 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 141 insertions(+) create mode 100644 README diff --git a/README b/README new file mode 100644 index 0000000..3476cf4 --- /dev/null +++ b/README @@ -0,0 +1,141 @@ +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 a certificate + authority and want to impersonate your site. + +* Certificates issued to attackers who are using your infrastructure + to serve malware. + +* Certificates issued in violation of your corporate policy + or outside of your centralized certificate procurement process. + +* Certificates issued to your infrastructure providers without your + consent. + + +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.5 or higher. + +1. Install Cert Spotter using go get: + + go get software.sslmate.com/src/certspotter/cmd/certspotter + +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 + + When Cert Spotter detects a certificate for a name on your watchlist, + 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. + +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 several hours 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. + -all_time + Scan certs from all time, not just since last scan. + -logs FILENAME + JSON file containing logs to scan, in the format documented at + . + Default: use the logs trusted by Chromium. + -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. Currently, the following +certificates are logged: + +* EV certificates + +* All certificates issued by the following CAs: + + * Let's Encrypt + * StartCom + * Symantec + * WoSign + +* Certificates that are detected when crawling web pages and doing + Internet-wide scans. + +In the coming years more certificates will be logged as more CAs +participate and as browsers begin requiring certificate transparency +for all certificates. + + +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.