# prometheus-tlsrpt-exporter

Prometheus exporter for MTA-STS TLS report metrics.


## Description

When using [MTA-STS][mtasts] to enforce TLS transport encryption for e-mail traffic, regular automated reports can be requested from supporting servers. These JSON-formatted TLSRPT reports contain information regarding the success rate of TLS connections.

This piece of software exposes an HTTP endpoint where such reports can be submitted, and a Prometheus metrics endpoint where aggregated statistics are exposed.


## Endpoints

By default, this exporter binds to `localhost:9123`.  It is intended to be used behind a TLS-terminating reverse proxy.  There are the following endpoints:

- `/reports`: This is where the TLSRPT reports are submitted to.  This endpoint must be world-accessable, and the POST-method must be permitted.
- `/metrics`: This is the Prometheus metrics endpoint.  Access should be restricted to your prometheus server.
- `/ui`: At this endpoint a (very simple) user interface is presented where the recently received reports can be viewed.  Access should be restricted to your mail administrators.


## Metrics

The following metrics are exposed, each labelled with the domain for which a report was received:

```metrics
# TYPE tlsrpt_successful counter
# HELP tlsrpt_successful Number of successful sessions
# TYPE tlsrpt_failed counter
# HELP tlsrpt_failed Number of failed sessions
# TYPE tlsrpt_count counter
# HELP tlsrpt_count Number of reports
```


## Setup

1. Install the `prometheus-tlsrpt-exporter`.
  - I recommend installing the [Debian package][deb].
1. Set up a TLS-terminating reverse proxy that forwards e.g. `https://mail.example.org/report` to the `/report` endpoint.
1. Publish a DNS record `_smtp._tls.example.org. TXT "v=TLSRPTv1; rua=https://mail.example.org/report"`, where `example.org` is your mail domain.
  - The same TLSRPT endpoint can be used for multiple mail domains.


[mtasts]: https://en.wikipedia.org/wiki/Simple_Mail_Transfer_Protocol#SMTP_MTA_Strict_Transport_Security
[deb]: https://git.kabelsalat.ch/s3lph/-/packages/debian/prometheus-tlsrpt-exporter