Cert Spotter

When writing a hook script to filter out legitimate certificates, avoid using fingerprints, serial numbers, Subject Key Identifiers (SKI), or Issuer fields, as these can be spoofed or vary between precertificates and certificates.

Instead, use one of these two methods:

1. Compare TBS Hash: Compare the $TBS_SHA256 value against a list of authorized TBS hashes. The TBS hash is computed over the DER encoding of the TBSCertificate with any SCT extension removed. You can compute this using certspotter-authorize(8) -printhash.

2. Compare Public Key Hash: Compare the $PUBKEY_SHA256 value against a list of authorized public key hashes. You can compute a public key hash manually using:

openssl x509 -pubkey -noout | openssl pkey -pubin -outform DER | openssl sha256

The watchlist defines the domain names that Certspotter will monitor in the CT logs.

• File-based: Use the -watchlist <path> flag to point to a file. If no flag is provided, it defaults to ~/.certspotter/watchlist.
• Stdin-based: Use -watchlist - to read the list of domains from standard input.
• Requirement: A watchlist must be provided; if it is empty or not found, the program will exit with code 2.

# Using a file
./certspotter -watchlist my_domains.txt

# Using stdin
cat my_domains.txt | ./certspotter -watchlist -

A certspotter-script is a program executed by certspotter(8) to notify you of events (like discovering a certificate for a watched domain).

To use hooks, you can either:

1. Place scripts in the $CERTSPOTTER_CONFIG_DIR/hooks.d directory (defaults to ~/.certspotter/hooks.d).
2. Specify a script explicitly using the -script command-line argument.

When a hook is triggered, certspotter sets several environment variables that your script can use to process the event.

# Example of specifying a script via CLI
certspotter -script /path/to/your/script.sh

To prevent false alarms, you can use certspotter-authorize to tell Cert Spotter about legitimate certificates issued by your certificate authority. Once authorized, Cert Spotter will not notify you when it discovers these certificates (or their corresponding precertificates) in Certificate Transparency logs.

Installation

go install software.sslmate.com/src/certspotter/cmd/certspotter-authorize@latest

Usage

Run the command against your certificate PEM file:

certspotter-authorize /path/to/cert.pem

Certspotter requires at least one way to notify you when a matching certificate is found. You can configure these via CLI flags or configuration files:

1. Email:
   • Use the -email <address> flag (can be used multiple times).
   • Or, place email addresses (one per line) in the email_recipients file located in your configuration directory.
2. Scripts:
   • Use the -script <path> flag to execute a specific program.
   • Or, place executable scripts in the hooks.d directory within your configuration directory.
3. Stdout:
   • Use the -stdout flag to print matching certificates directly to the standard output.

Cert Spotter monitors DNS names provided in a watchlist file.

• Format: One DNS name per line.
• Wildcard/Namespace monitoring: To monitor a domain and all its sub-domains, prefix the name with a dot (e.g., .example.com).
• Single name monitoring: To monitor only a specific DNS name, do not use a prefix (e.g., example.com).
• Input methods:
  • Use the -watchlist PATH flag to specify a file.
  • Use - to read the watchlist from stdin.
  • By default, it reads from $CERTSPOTTER_CONFIG_DIR/watchlist (defaults to ~/.certspotter/watchlist).

Note: The watchlist is only read at startup. You must restart certspotter to apply changes.

# Example watchlist file content
.example.com
api.example.com
standalone.com

The certspotter-authorize utility must use the same state directory as the main certspotter(8) process to function correctly. You can specify this directory in two ways:

1. Environment Variable: Set CERTSPOTTER_STATE_DIR to the desired path.
2. CLI Flag: Use the -state_dir flag to override the environment variable.

If neither is provided, it defaults to ~/.certspotter.

# Using the environment variable
export CERTSPOTTER_STATE_DIR=/var/lib/certspotter
certspotter-authorize cert.pem

# Using the CLI flag (overrides environment variable)
certspotter-authorize -state_dir /var/lib/certspotter cert.pem

Certspotter uses several directories for state, configuration, and caching. You can override the default locations using the following environment variables: