# silent-ct

An implementation of a silent Certificate Transparency (CT) monitor.

## How it works

Each node that issues TLS certificates submit them to a self-hosted monitor.
This is what makes it possible for silent-ct to be _silent_: alerts are only
generated if a certificate found in the logs were not requested by the nodes.

An overview is shown in the figure below.

    XXX: ASCII figure.

To establish a secure connection to the monitor, a Tor onion service is assumed.
This means that all nodes and the monitor need to have Tor installed locally.

The use of a Tor onion service also allows for NAT punching.  In other words, it
is possible to run the monitor without a publicly reachable IP address.

For the monitor to authenticate each node, HTTP Basic Authentication is used.

## Setting and threat model

  1. It is not always possible for nodes to reach the monitor.  For example, the
     monitor may be running on a workstation only powered on during work hours.
  2. An administrator notices alerts that `silent-ctmoon` outputs on stdout.
     The integration with email, dashboards, or similar is out of scope.
  3. The platform running the monitor is not compromised by the attacker.
  4. The platforms hosting TLS sites start in good states but may be compromised
     by the attacker sometime in the future.  Detection of certificate
     mis-issuance is then out of scope for the domains the compromised node
     issued certificates for.  It is in-scope to not let such a compromise
     affect detection of mis-issued certificates with other nodes' domains.
  5. Mis-issued certificates will only be used for MitM attacks against users
     that connect from a set of fixed IP addresses.  It is assumed that the
     party who can detect certificate mis-issuance will never be targeted.  This
     is why each node needs to establish a secure channel with the monitor.

## Install

Install Tor on all platforms.  On Debian:

    # apt install tor

Install the silent-ct software using Go's toolchain:

    $ go install rgdd.se/silent-ct/cmd/silent-ctnode@latest
    $ go install rgdd.se/silent-ct/cmd/silent-ctmoon@latest

`silent-ctnode` is only used on nodes that issue TLS certificates.

`silent-ctmoon` is only used on the system that runs the monitor.

## Node setup

What makes `silent-ctmoon` _silent_ is that all nodes report legitimately issued
certificates over a secure channel.  For each such legitimate certificate, run:

    $ torify silent-ctnode -n NODE_NAME -s NODE_SECRET -o ONION_ADDR -c CHAIN_PATH

`NODE_NAME` is an arbitrary node name used for authentication.

`NODE_SECRET` is an arbitrary node secret used for authentication.

`ONION_ADDR` is the onion address where `silent-ctmoon` listens for requests.

`CHAIN_PATH` is the path to a certificate chain that was issued legitimately.
It is safe to repeatedly submit the same certificate chain to `silent-ctmoon`.

You will need to add a cron job (or similar) that periodically submits the
issued certificates to `silent-ctmoon`.  See example that works for `certbot`
issuing certificates with Let's Encrypt in the [contrib/](./contrib) directory.

## Configure the monitor

Create a configuration file specifying which nodes can issue what certificates.

Example:

    $ cat config
    NODE_A aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa example.org www.example.org
    NODE_B bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb git.example.org

The first column specifies an arbitrary node name.

The second column specifies a node secret used for mutual authentication.

The following columns specify domain names the node issues certificates for.

## Start the monitor

[Configure an onion service][] that routes through the below UNIX socket.

Start the monitor:

    $ silent-ctmoon -c config -s state.db -l silent-ctmoon.sock

Stop gracefully by sending the SIGINT signal. 

[Configure an onion service]: xxx

## Read monitoring alerts

All output is formatted as follows:

    <keyword>: <description>

Only two keywords are expected by default: `alert` and `recovered`.

## Contact

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