prometheus-tlsrpt-exporter/README.md

prometheus-tlsrpt-exporter

Prometheus exporter for MTA-STS TLS report metrics.

Description

When using MTA-STS 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:

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

1. Set up a TLS-terminating reverse proxy that forwards e.g. https://mail.example.org/report to the /report endpoint.
2. 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.