certspotter(8)

📦
version 0.18.0 · 5 versions
, in ubuntu resolute, ubuntu stonking

💅 certspotter — like, the manual page, but make it make sense

okay bestie, sit down, hydrate, because we're about to talk about certspotter(8) — that's section 8 of your system manager's manual, and yes she's iconic. This is the Certificate Transparency Log Monitor from SSLMate, and she is very good at her job. 🌸

✨ NAME ✨

certspotter — Certificate Transparency Log Monitor. that's it, that's the name, and honestly? she ate. 👑

🦋 SYNOPSIS 🦋

certspotter [-start_at_end] [-watchlist FILENAME] [-email ADDRESS] ...

notice the ... at the end, bestie, because there are so many more flags and we're gonna go through every single one. no skips. 🎀

💖 DESCRIPTION 💖

okay so Cert Spotter is a Certificate Transparency log monitor from SSLMate, and her whole vibe is: she alerts you the moment an SSL/TLS certificate gets issued for one of your domains. like she's watching, she's always watching, and she will tell you. 📣

why is she the bestie of choice over other open source CT monitors? because she does not require a database — obsessed, honestly, no setup drama. she's also more robust, since she uses a special certificate parser that ensures she won't miss certificates. not one. not ever. periodt. 💅

Cert Spotter is also available as a hosted service by SSLMate, https://sslmate.com/certspotter. yes, hosted, so if you don't feel like running her yourself, that's an option, live your life. ✨

so what can you actually use Cert Spotter to detect?? let me count the ways:

  • 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. yeah, the "who approved this" situation. 🙈

✨ OPTIONS ✨

here's the full menu, bestie. every flag, no gatekeeping:

  • -batch_size NUMBER — Maximum number of entries to request per call to get-entries. You should not generally need to change this. Defaults to 1000. like, she picked a good number, leave her alone. 🧚
  • -email ADDRESS — Email address to contact when a matching certificate is discovered, or an error occurs. You can specify this option more than once to email multiple addresses. Your system must have a working sendmail(1) command.

Regardless of the -email option, certspotter also emails any address listed in $CERTSPOTTER_CONFIG_DIR/email_recipients file (~/.certspotter/email_recipients by default). (One address per line, blank lines are ignored.) This file is read only at startup, so you must restart certspotter if you change it. 👀

  • -healthcheck INTERVAL — Perform a health check at the given interval (default: “24h”) as described below. INTERVAL must be a decimal number followed by “h” for hours or “m” for minutes. yes you literally have to write the h or the m. she's not psychic. 🌈
  • -logs ADDRESS — Filename or HTTPS URL of a v2 or v3 JSON log list containing logs to monitor. The schema for this file can be found at https://www.gstatic.com/ct/log_list/v3/log_list_schema.json. Defaults to https://loglist.certspotter.org/monitor.json, which includes the union of active logs recognized by Chrome and Apple. certspotter periodically reloads the log list in case it has changed. keeping it fresh, always. 🍓
  • -no_save — Do not save a copy of matching certificates. that's it, that's the whole flag.
  • -script COMMAND — Command to execute when a matching certificate is found or an error occurs. See certspotter-script(8) for information about the interface to scripts.

Regardless of the -script option, certspotter also executes any executable file in the $CERTSPOTTER_CONFIG_DIR/hooks.d directory (~/.certspotter/hooks.d by default). 🫶

  • -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 PATH — Directory for storing state. Defaults to $CERTSPOTTER_STATE_DIR, which is “~/.certspotter” by default. 💜
  • -stdout — Write matching certificates and errors to stdout. loud and proud.
  • -verbose — Be verbose. she's talking, listen. 🗣️
  • -version — Print version and exit. quick lil flex.
  • -watchlist PATH — File containing DNS names to monitor, one per line. To monitor an entire domain namespace (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.

Defaults to $CERTSPOTTER_CONFIG_DIR/watchlist, which is “~/.certspotter/watchlist” by default. Specify - to read the watch list from stdin.

certspotter reads the watch list only when starting up, so you must restart certspotter if you change it. no hot reloading, bestie, restart her. 🔄

🌸 NOTIFICATIONS 🌸

when certspotter detects a certificate matching your watchlist, or encounters an error that is preventing it from discovering certificates, she notifies you like this:

  • Emails any address specified by the -email command line flag. 📧
  • Emails any address listed in the $CERTSPOTTER_CONFIG_DIR/email_recipients file (~/.certspotter/email_recipients by default). (One address per line, blank lines are ignored.) This file is read only at startup, so you must restart certspotter if you change it.
  • Executes the script specified by the -script command line flag. ⚙️
  • Executes every executable file in the $CERTSPOTTER_CONFIG_DIR/hooks.d directory (~/.certspotter/hooks.d by default). 🪝
  • Writes the notification to standard out if the -stdout flag was specified. 📺

Sending email requires a working sendmail(1) command. For details about the script interface, see certspotter-script(8). 🫡

👑 OPERATION 👑

certspotter continuously monitors all browser-recognized Certificate Transparency logs looking for certificates which are valid for any domain on your watch list. When certspotter detects a matching certificate, it emails you, executes a script, and/or writes a report to standard out, as described above. she's got range. 💅

certspotter also saves a copy of matching certificates in $CERTSPOTTER_STATE_DIR/certs (“~/.certspotter/certs” by default) unless you specify the -no_save option.

When certspotter 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.

If certspotter has previously monitored a log, it resumes monitoring the log from the previous position. This means that if you add a domain to your watch list, certspotter will not detect any certificates that were logged prior to the addition. 😭 To detect such certificates, you must delete $CERTSPOTTER_STATE_DIR/logs, which will cause certspotter to restart monitoring from the very beginning of each log (provided -start_at_end is not specified). This will cause certspotter to download hundreds of millions of certificates, which takes days. ⏳

To find preexisting certificates, it's faster to use the Cert Spotter service https://sslmate.com/certspotter, SSLMate's Certificate Transparency Search API https://sslmate.com/ct_search_api, or a CT search engine such as https://crt.sh. saving you the whole download situation. 🙏

🚨 ERROR HANDLING 🚨

When certspotter encounters a problem with the local system (e.g. failure to write a file or execute a script), it prints a message to stderr and exits with a non-zero status. 💀 local problems = she's out.

When certspotter encounters a problem monitoring a log, it prints a message to stderr and continues running. It will try monitoring the log again later; most log errors are transient. so she keeps going, resilient queen. 💪

Every 24 hours (unless overridden by -healthcheck), certspotter performs the following health checks:

  • Ensure that the log list has been successfully retrieved at least once since the previous health check.
  • Ensure that every log has been successfully contacted at least once since the previous health check.
  • Ensure that certspotter is not falling behind monitoring any logs.

If any health check fails, certspotter notifies you by email, script, and/or standard out, as described above. 📬

Health check failures should be rare, and you should take them seriously because it means certspotter might not detect all certificates. It might also be an indication of CT log misbehavior. Consult certspotter's stderr output for details, and if you need help, file an issue at https://github.com/SSLMate/certspotter. 🫂

⭐ EXIT STATUS ⭐

certspotter exits 0 when it receives SIGTERM or SIGINT, and non-zero when a serious error occurs. clean exit = happy exit. ✌️

🌈 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 watch list, is read. Defaults to ~/.certspotter.
  • HTTPS_PROXY — URL of proxy server for making HTTPS requests. http://, https://, and socks5:// URLs are supported. By default, no proxy server is used.
  • SENDMAIL_PATH — Path to the sendmail binary used for sending emails. Defaults to /usr/sbin/sendmail.

🎀 SEE ALSO 🎀

Copyright © 2016-2023 Opsmate, Inc. protect the intellectual property, periodt.

🐛 BUGS 🐛

Report bugs to https://github.com/SSLMate/certspotter. found a glitch? tell the devs, they're nice about it. 🫶

okay and that's the whole page, bestie!! 🩷 source and version vibes go out to the System Manager's Manual — certspotter(8), dated 2026-01-14. go protect your domains, you're doing amazing, mwah 💋✨

📦 where this page comes from