silentct

An implementation of a silent Certificate Transparency monitor.

Status

Drafty prototype, please do not use for anything too serious yet.

How it works

A monitor downloads all certificates from Certificate Transparency logs. This provides a concise view of which certificates have been issued for what domains.

The monitor is configured to pull certificates from trusted systems that legitimately request certificates. The legitimately issued certificates are typically made available on HTTP(S) URLs that are polled periodically.

To convince the monitor that the file of legitimately issued certificates is authentic, it is integrity protected using a message authentication code. So, the monitor and its trusted systems need to be configured with shared secrets.

What makes this setup "silent" is that the monitor can compute the difference between any downloaded and legitimately issued certificates. If a certificate is found that no trusted system made available, only then an alert is emitted.

See the silentct design for a lengthier introduction.

Quickstart

Setup a trusted system

Install the silentct-mac tool.

$ go install rgdd.se/silentct/cmd/silentct-mac@latest

Mark all certificates that have yet to expire as legitimately issued. The below specifies one certificate chain, but it is possible to list multiple ones.

$ silentct-mac -n example.org -s sikritpassword /etc/letsencrypt/live/example.org/fullchain.pem

-n sets an arbitrary name of the trusted system.

-s sets a secret that will be shared with the monitor.

The output includes the name, a message authentication code, and the list of certificate chains that was specified. Record the output as a file the monitor can pull, e.g., by saving it in a web root or transferring it to one. Ensure that this file gets updated each time a new certificate is legitimately issued. Below is an example that keeps the file up-to-date with crontab and certbot.

# crontab -l
35 3 * * * certbot renew --post-hook "silentct-mac -n example.org -s sikritpassword -o /var/www/example.org/silentct/allowlist /etc/letsencrypt/live/example.org/fullchain.pem"

Note: the --post-hook option can be specified per site in the [renewalparams] section of /etc/letsencrypt/renewal/example.org.conf.

Setup the monitor

Install the silentct-mon tool:

$ go install rgdd.se/silentct/cmd/silentct-mon@latest

Create a configuration file.

$ cat config.json
{
  "monitor": [
    {
      "bootstrap_at": "2024-01-01T00:00:00Z",
      "suffix": "example.org",
      "excludes": [
        "test"
      ]
    }
  ],
  "certificate_requesters": [
    {
      "name": "example.org",
      "secret": "sikritpassword",
      "location": "https://www.example.org/silentct/allowlist",
      "requests": [
        "example.org",
        "www.example.org"
      ]
    }
  ]
}

bootstrap_at is the time the monitor started looking for certificates that match suffix. The monitor considers a certificate to match iff (i) it expired after the bootstrap time, and (ii) at least one subject alternative name ends with the specified suffix without a longer match being available when taking the optional excludes list of subdomains into account. For example, the above configuration matches www.example.org but not foo.test.example.org.

Each entry in the "certificate-requesters" list corresponds to a trusted system and the domains it requests certificates for. Set name, secret, location (filename or URL to pull from), and requests to match the configuration of each trusted system. The monitor will refuse to mark a certificate as legitimate unless the trusted system that requested it had permission to do so. This adds a layer of separation between trusted systems.

Start the monitor

Start the monitor:

$ silentct-mon -c config.json -d ~/.local/lib/silentct

Use the --bootstrap flag when running the monitor for the first time.

Noteworthy events will be printed on stdout using the NOTICE level. If you prefer to get the monitor's output in a file, use the -o option.

Stop the monitor

Stop the monitor gracefully by sending the SIGINT or SIGTERM signals. Nothing bad will happen on an ungraceful exit (just redundant work on next startup).

Contact

Room #certificate-transparency at OFTC.net
Room #certificate-transparency at matrix.org