NAME

       certspotter - Certificate Transparency Log Monitor

SYNOPSIS

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

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 to use 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

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

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

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

       -no_save
          Do not save a copy of matching certificates.

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

       -verbose
          Be verbose.

       -version
          Print version and exit.

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

NOTIFICATIONS

       When certspotter detects a certificate matching your watchlist, or encounters an error that is preventing
       it from discovering certificates, it notifies you as follows:

       •  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.

       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.

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.

       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.

       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.

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

       certspotter-script(8)

COPYRIGHT

       Copyright © 2016-2023 Opsmate, Inc.

BUGS

       Report bugs to https://github.com/SSLMate/certspotter.

                                                   2023-11-17                                     certspotter(8)