Add man pages

Closes: #11

man/.gitignore

@@ -0,0 +1 @@
+*.8

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 $@ $<
+

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 <https://github.com/SSLmate/certspotter>.

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,
+<https://sslmate.com/certspotter>.
+
+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 <https://www.certificate-transparency.org/known-logs>.
+    Defaults to <https://loglist.certspotter.org/monitor.json>, 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 <https://sslmate.com/certspotter>, the Cert Spotter
+API <https://sslmate.com/certspotter/api>, or a CT search engine such
+as <https://crt.sh>.
+
+## 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
+<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.
+
+# 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 <https://github.com/SSLmate/certspotter>.