diff --git a/man/.gitignore b/man/.gitignore new file mode 100644 index 0000000..8703c5c --- /dev/null +++ b/man/.gitignore @@ -0,0 +1 @@ +*.8 diff --git a/man/Makefile b/man/Makefile new file mode 100644 index 0000000..b99e9f2 --- /dev/null +++ b/man/Makefile @@ -0,0 +1,9 @@ +all: certspotter-script.8 certspotter.8 + +%.8: %.md + lowdown -s -Tman \ + -M title:$(basename $(notdir $@)) \ + -M section:$(subst .,,$(suffix $@)) \ + -M date:$(if $(SOURCE_DATE_EPOCH),$(shell date -I -u -d "@$(SOURCE_DATE_EPOCH)"),$(shell date -I -u)) \ + -o $@ $< + diff --git a/man/certspotter-script.md b/man/certspotter-script.md new file mode 100644 index 0000000..081a7ac --- /dev/null +++ b/man/certspotter-script.md @@ -0,0 +1,105 @@ +# NAME + +**certspotter-script** - Certificate Transparency Log Monitor (hook script) + +# SYNOPSIS + +**certspotter-script** + +# DESCRIPTION + +**certspotter-script** is *any* program that is called from **certspotter**'s +*-script* argument. **certspotter** executes this script when a file from the +CT log matches against the watchlist. + +# ENVIRONMENT + +The script will have the following variables defined in its environment: + +## Log entry information + +**CERT\_FILENAME** +: The path of the saved certificate on the local filesystem, if one exists. + +**CERT\_TYPE** +: The certificate's type (*cert* or *precert*). + +**FINGERPRINT** +: The certificate's fingerprint. + +**LOG\_URI** +: The URI of the log the certificate was found on. + +**ENTRY\_INDEX** +: The entry's index in the log. + +**CERT\_PARSEABLE** +: Whether the certificate could be parsed. + +## Identifiers + +**DNS\_NAMES** +: A comma-separated list of the certificate's dnsNames. + +**IP\_ADDRESSES** +: A comma-separated list of the certificate's IP addresses. + +## Certificate information + +**PUBKEY\_HASH** +: The certificate public key's hash. + +**SERIAL** +: The certificate's serial. + +**NOT\_BEFORE**, **NOT\_AFTER** +: The certificate's validity information, as a string. + +**NOT\_BEFORE\_UNIXTIME**, **NOT\_AFTER\_UNIXTIME** +: The certificate's validity information, as UNIX time. + +**SUBJECT\_DN** +: The certificate's subject distinguished name (DN). + +**ISSUER\_DN** +: the certificate issuer distinguished name (DN). + +## Errors + +**PARSE\_ERROR** +: Set to the error that occurred when attempting to extract information about + the certificate. In this case, **CERT\_PARSEABLE** will also be set to "no" + and information such as **PUBKEY\_HASH**, **SERIAL**, as well as validity + and subject, will not be present. + +**SERIAL\_PARSE\_ERROR** +: Set to the error that occurred when attempting to extract the certificate's + serial. Emitted instead of **SERIAL**. + +**IDENTIFIERS\_PARSE\_ERROR** +: Set to the error that occurred when attempting to extract the certificate's + identifiers. Emitted instead of **DNS\_NAMES**, **IP\_ADDRESSES**. + +**VALIDITY\_PARSE\_ERROR** +: Set to the error that occurred when attempting to extract the certificate's + validity information. Emitted instead of **NOT\_BEFORE**, **NOT\_AFTER**. + +**SUBJECT\_PARSE\_ERROR** +: Set to the error that occurred when attempting to extract the certificate's + subject information. Emitted instead of **SUBJECT\_DN**. + +**ISSUER\_PARSE\_ERROR** +: Set to the error that occurred when attempting to extract the certificate's + issuer information. Emitted instead of **ISSUER\_DN**. + +# SEE ALSO + +**certspotter**(8), **x509**(1) + +# COPYRIGHT + +Copyright (c) 2016-2022 Opsmate, Inc. + +# BUGS + +Report bugs to . diff --git a/man/certspotter.md b/man/certspotter.md new file mode 100644 index 0000000..3c39a3e --- /dev/null +++ b/man/certspotter.md @@ -0,0 +1,192 @@ +# NAME + +**certspotter** - Certificate Transparency Log Monitor + +# SYNOPSIS + +**certspotter** [**-verbose**] [**-start\_at\_end**] [**-watchlist** _file_] `...` + +# DESCRIPTION + +**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, +. + +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. + +# OPTIONS + +**-all_time** +: Scan certs from all time, not just those logged since the previous run of + Cert Spotter. + +**-batch_size** _int_ +: Max number of entries to request at per call to get-entries. This is + advanced option. Defaults to 1000. + +**-logs** _string_ +: Filename or HTTPS URL of a JSON file containing logs to monitor, in the + format documented at . + Defaults to , which includes + the union of active logs recognized by Chrome and Apple. + +**-no\_save** +: Do not save a copy of matching certificates. + +**-num\_workers** _int_ +: Number of concurrent matchers. Default 2. + +**-script** _string_ +: Script to execute when a matching certificate is found. See + **certspotter-script**(8) for information about the interface to scripts. + +**-start\_at\_end** +: Start monitoring logs from the end rather than the beginning. + + **WARNING**: monitoring from the beginning guarantees detection of all + certificates, but requires downloading hundreds of millions of + certificates, which takes days. + +**-state\_dir** _string_ +: Directory for storing state. Defaults to `~/.certspotter`. + +**-verbose** +: Be verbose. + +**-version** +: Print version and exit. + +**-watchlist** _string_ +: File containing identifiers to watch. Use `-` for stdin. + Defaults to `~/.certspotter/watchlist`. + +# NOTES + +## Method of operation + +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. + +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 . + +## Coverage + +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. + +## Bygone certificates + +Cert Spotter can also notify users of bygone SSL certificates, which are SSL +certificates that outlived their prior domain owner's registration into the +next owners registration. To detect these certificates add a **valid\_at** +argument to each domain in the watchlist followed by the date the domain was +registered in the following format YYYY-MM-DD. For example: + +``` +example.com valid_at:2014-05-02 +``` + +## Security considerations + +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. + +# EXIT STATUS + +certspotter exits 0 on success, 1 on any error. + +# ENVIRONMENT + +**CERTSPOTTER\_STATE\_DIR** +: Directory for storing state. Overridden by **-state\_dir**. Defaults to + `~/.certspotter`. + +**CERTSPOTTER\_CONFIG\_DIR** +: Directory from which any configuration, such as the watchlist, is read. + Defaults to `~/.certspotter`. + +# SEE ALSO + +**certspotter-script**(8) + +# COPYRIGHT + +Copyright (c) 2016-2022 Opsmate, Inc. + +# BUGS + +Report bugs to .