95.1.55. pepsi-tlsrpt

SMTP TLS Reporting (RFC 8460) daily reports

Handbuchabschnitt:

1

95.1.55.1.1. Name

pepsi-tlsrpt - tägliche Sammelberichte für SMTP TLS Reporting (RFC 8460).

95.1.55.1.2. Übersicht

pepsi-tlsrpt [GLOBAL-OPTIONS] report [–date YYYY-MM-DD] [–dry-run]

pepsi-tlsrpt [GLOBAL-OPTIONS] prune [–older-than DAYS]

95.1.55.1.3. Beschreibung

pepsi-tlsrpt ist die Absenderseite von SMTP TLS Reporting (RFC 8460). Während Pepsi ausgehende Mail zustellt, halten die Relay-Stages (pepsi-stage-relay-to-internet(1) und pepsi-stage-relay-to-smarthost(1)) das Ergebnis jeder TLS-Sitzung als Aggregat-Zähler in der Tabelle pepsi.tls_session fest. Das Ergebnis ist ein Erfolg oder ein klassifizierter Fehler (starttls-not-supported, certificate-host-mismatch, certificate-expired, certificate-not-trusted, validation-failure, tlsa-invalid, sts-policy-invalid, sts-policy-fetch-error, sts-webpki-invalid). Die Zähler sind nach UTC-Tag, Richtliniendomain, angewandtem Richtlinientyp (tlsa/sts/no-policy-found), MX-Host und Ergebnis geschlüsselt.

Eine Sitzung ist ein Erfolg, wenn TLS ausgehandelt wurde, gleich was der SMTP-Austausch darüber dann ergab (eine SMTP-Ablehnung nach dem Handshake ist kein TLS-Fehler), außer unter einer DANE-Richtlinie: Ein Zertifikat, das zu keinem der TLSA-Einträge passte, ist tlsa-invalid (RFC 8460 Abschnitt 4.3.2.1), ob DANE = strict die Sitzung abgelehnt oder DANE = warn sie bei der Ausweichprüfung durchgelassen hat. Eine im Klartext zugestellte Nachricht ist keine TLS-Sitzung: Ohne Richtlinie (ein Smarthost mit MODE = plain oder ein MX, der kein STARTTLS anbietet) wird sie nicht festgehalten, und wo MTA-STS oder DANE TLS verlangten, wird sie als starttls-not-supported festgehalten. Ein Fehler, der sich nicht als TLS- oder Richtlinienproblem klassifizieren lässt (ein einfacher Verbindungsfehler), wird überhaupt nicht festgehalten.

Eine Domain kann eine MTA-STS-Richtlinie ankündigen, die pepsi-stage-relay-to-internet(1) nicht abrufen kann, ohne dass eine Richtlinie aus einem früheren Abruf gespeichert ist. Mail an eine solche Domain wird zugestellt, als hätte die Domain keine Richtlinie (RFC 8461), und der fehlgeschlagene Abruf wird als eine sts-Sitzung mit dem Ergebnis sts-policy-fetch-error festgehalten (sts-webpki-invalid, wenn sich das Zertifikat des Richtlinien-Hosts nicht validieren ließ; RFC 8460 Abschnitt 4.3.2.2). Dieser Eintrag hat keinen MX-Host und keine Richtlinien-Zeichenkette, und er wird höchstens einmal pro Domain und Worker alle fünf Minuten angelegt. Der Bericht führt diesen Fehler dann ohne receiving-mta-hostname auf und die Richtlinie ohne mx-host oder policy-string.

Die Richtliniendomain ist bei pepsi-stage-relay-to-internet(1) die Empfängerdomain. Die Smarthost-Stage hält unter dem eigenen Hostnamen des Smarthosts fest, denn dieser Host, nicht die Domain des Empfängers, ist die Gegenstelle, deren TLS beobachtet wurde. [pepsi-tlsrpt] SEND_REPORTS (standardmäßig aus) schaltet dieses Festhalten ein. Für eine Berichtsnachricht selbst wird es übersprungen (der Schleifenschutz state.tlsrpt), sodass ein Bericht, der auf einen TLS-Fehler stößt, nie einen Bericht über einen Bericht erzeugt.

Einmal täglich per Cron ausgeführt, stellt pepsi-tlsrpt report die Zähler eines Tages zu einem RFC-8460-Sammelbericht pro Richtliniendomain zusammen, schlägt die angekündigte Berichtsadresse dieser Domain nach (das rua-Feld ihres _smtp._tls-TXT-Eintrags) und verschickt den gzip-komprimierten JSON-Bericht dorthin. Ein mailto:-Ziel erhält ihn per E-Mail: Der Bericht wird bei REPORT_STAGE in die Pipeline injiziert, damit er DKIM-signiert und wie jede andere Nachricht weitergeleitet wird; ist REPORT_STAGE nicht gesetzt, wird das Ziel protokolliert und übersprungen. Ein https:-Ziel erhält ihn per HTTPS-POST (mit Content-Type: application/tlsrpt+gzip). Eine Bericht-E-Mail trägt REPORT_FROM sowohl als Umschlagabsender als auch als From:. RFC 8460 §5.3 verlangt, dass ein Bericht per DKIM/DMARC ausrichtbar ist, er hat daher bewusst keinen Null-Absender; es ist das Flag state.tlsrpt statt des Null-Absenders, das die Rekursion stoppt. Sobald der Bericht einer Domain verschickt ist, werden die Zähler dieses Tages für sie gelöscht, sodass ein erneuter Lauf für denselben Tag sicher ist.

Beide Zielformen werden vor der Verwendung validiert, denn beide stammen aus einem DNS-Eintrag, den die Domain veröffentlicht, über die berichtet wird. Ein mailto:-Ziel muss eine einzelne schlichte Addr-Spec local@domain sein, sodass es weder Header noch zusätzliche Empfänger in die Berichtsnachricht einschleusen kann. An ein https:-Ziel wird über denselben gehärteten Client gesendet, den die Schlüsselentdeckung verwendet. Der Client verifiziert den Server gegen die System-CA-Wurzeln ([pepsi-keydiscovery] TLS_CA_BUNDLE gilt hier nicht), und eine schlichte http:-URL wird abgelehnt. Der Hostname wird aufgelöst und jede Kandidatenadresse geprüft, sodass ein rua, das auf eine Loopback-, private, Link-Local- oder CGNAT-Adresse zeigt, abgelehnt wird, statt aus dem Netz des Mailservers heraus angesprochen zu werden. Ein POST folgt keiner Umleitung, sodass eine öffentliche URL den Bericht nicht anderswohin lenken kann. Ein Ziel, das eine der beiden Prüfungen nicht besteht, wird protokolliert und übersprungen; die Zähler des Tages bleiben erhalten, sodass nichts verloren geht.

Nur die ersten fünf rua-Ziele einer Domain werden verwendet, in veröffentlichter Reihenfolge; der Rest wird protokolliert und ignoriert. Die Länge der Liste wählt der Veröffentlichende, und ohne Obergrenze würde ein Eintrag, der Hunderte von Adressen bei einem Dritten nennt, jeden berichtenden Server diesen Dritten einmal pro Adresse und Tag anmailen lassen.

Es verbindet sich über den Abschnitt [pepsi-postgres] mit der gemeinsamen Datenbank und wird durch [pepsi-tlsrpt] konfiguriert (siehe pepsi.conf(5)). Es ist keine Stage. Als Cron-Job wird es normalerweise als root gestartet und läuft dann als Dienstkonto pepsi weiter; siehe Ausführung als root.

Die ankündigende Hälfte erledigt pepsi-setup(1), das unseren eigenen _smtp._tls-TXT-Eintrag aus [pepsi-tlsrpt] RUA ausgibt. Sobald dieser Eintrag veröffentlicht ist, melden andere Absender ihre TLS-Ergebnisse zu unseren Domains an uns.

95.1.55.1.4. Befehle

report [–date YYYY-MM-DD] [–dry-run]

Stellt die Berichte für einen UTC-Tag zusammen und verschickt sie, standardmäßig für gestern.

–date YYYY-MM-DD

Berichtet über diesen UTC-Tag statt über gestern.

–dry-run

Gibt das JSON jedes Berichts auf die Standardausgabe aus, statt ihn zu senden, und behält die Zähler (nichts wird gelöscht). Nützlich zur Inspektion.

prune [–older-than DAYS]

Löscht pepsi.tls_session-Zähler, die älter als das Aufbewahrungsfenster sind. Ohne Flag ist das Fenster [pepsi-tlsrpt] RETAIN_DAYS (Standardwert 7). Berichtete Tage werden bereits von report geleert; dies räumt nur Tage ab, über die nie berichtet wurde (z. B. eine Domain, die kein rua ankündigt). Der mitgelieferte pepsi-tlsrpt-prune.timer führt es täglich aus, unabhängig von report. Zähler sammeln sich an, ob jemals Berichte gesendet werden oder nicht, daher darf die Aufbewahrung nicht davon abhängen, dass der Berichtsjob eingerichtet ist.

–older-than DAYS

Überschreibt das Aufbewahrungsfenster für diesen Lauf.

95.1.55.1.5. Konfiguration

Der Abschnitt [pepsi-tlsrpt] (siehe pepsi.conf(5)) wird als Ganzes gelesen: Er gilt nur dann als konfiguriert, wenn er entweder ein RUA ankündigt oder SEND_REPORTS setzt, und report verweigert andernfalls die Ausführung (prune, das nur Datensätze löscht, benötigt ihn nicht).

RUA

Die Berichts-URI(s), die wir in unserem eigenen _smtp._tls-TXT-Eintrag ankündigen, wörtlich (z. B. mailto:tls@example.org oder eine kommagetrennte mailto:-/https:-Liste). Nur pepsi-setup(1) liest sie, um den Eintrag auszugeben; beim Senden spielen sie keine Rolle. Nicht gesetzt bedeutet, dass wir nichts ankündigen.

SEND_REPORTS

Ob die Relay-Stages ausgehende TLS-Sitzungen überhaupt in pepsi.tls_session festhalten. Standardwert no.

REPORT_FROM

Umschlagabsender und From: ausgehender Bericht-E-Mails; seine Domain ist der Einreicher des Berichts (und Teil jeder report-id). Von report benötigt.

REPORT_STAGE

Die Pipeline-Stage, bei der Bericht-E-Mails injiziert werden, damit sie wie jede andere Nachricht signiert und weitergeleitet werden. Ohne sie kann ein mailto:-Ziel nicht verwendet werden. pepsi-setup(1) prüft, dass sie eine vorhandene Stage benennt.

ORGANIZATION

organization-name in ausgegebenen Berichten. Standardwert ist die Domain von REPORT_FROM.

CONTACT

contact-info (eine E-Mail-Adresse) in ausgegebenen Berichten. Nicht gesetzt, wird es im Bericht weggelassen.

RETAIN_DAYS

Wie viele Tage an pepsi.tls_session-Zählern prune behält (Standardwert 7), sofern --older-than es nicht für einen Lauf überschreibt.

95.1.55.1.6. Ausführung als root

Pepsi gibt jeder Komponente ihre eigene PostgreSQL-Rolle, die über den lokalen Socket durch das Betriebssystemkonto authentifiziert wird, unter dem sie läuft, und root gehört bewusst nicht dazu. Das fällt hier ins Gewicht, weil der tägliche Auftrag normalerweise aus der Crontab von root läuft. Statt den Verbindungsaufbau scheitern zu lassen, erkennt das Werkzeug, dass es als root gestartet wurde, und wird zum unprivilegierten Dienstkonto pepsi, bevor es sich verbindet. Diesem Konto gehört pepsi.tls_session, und es darf die Berichtsnachrichten injizieren. Ein Crontab-Eintrag braucht daher kein sudo -u pepsi.

Die Konfigurationsdatei (und jedes von ihr referenzierte @inline-secret@-Fragment) wird vor dem Wechsel gelesen, sodass eine nur für root lesbare Konfiguration weiterhin normal geladen wird.

Existiert das Konto pepsi nicht (in einem nicht installierten Quellbaum oder einem Testaufbau), bleibt die Identität unangetastet, es wird eine Warnung protokolliert und die Verbindung als aufrufender Benutzer versucht, sodass eine Installation, in der root die Datenbank erreichen kann, weiterhin funktioniert.

95.1.55.1.7. Globale Optionen

Diese globalen Optionen stehen vor dem Unterbefehl (ein nachgestelltes Flag wird abgelehnt).

-c FILE, –config FILE

Liest die Konfiguration aus FILE, statt die Standardorte zu durchsuchen.

-L LOGLEVEL, –log LOGLEVEL

Setzt die Log-Ausführlichkeit. LOGLEVEL ist eines von error, warn, info, debug oder trace. Fehlt die Option, gilt die globale Option [pepsi] LOG, und ohne diese info.

-v, –verbose

Zeigt Log-Meldungen aus allen Quellen, einschließlich Drittanbieter-Bibliotheken.

-h, –help

Gibt eine Verwendungsübersicht aus und beendet sich.

-V, –version

Gibt die Version aus und beendet sich.

95.1.55.1.8. Exit-Status

0

Erfolgreicher Abschluss. Zustellprobleme je Domain (ein Abfragefehler, ein unerreichbarer HTTPS-Endpunkt) werden protokolliert und der Lauf fährt fort; die Zähler des betroffenen Tages werden für den nächsten Lauf aufbewahrt.

1

Ein Fehler ist aufgetreten: eine fehlerhafte Konfiguration, ein [pepsi-tlsrpt]-Abschnitt, der weder ein RUA ankündigt noch SEND_REPORTS setzt (es gibt nichts zu berichten), eine fehlende erforderliche Option (REPORT_FROM), ein nicht parsebares --date oder eine fehlgeschlagene Datenbankverbindung oder -abfrage.

78

Das Datenbankschema passt nicht zu diesem Build (nicht installiert, älter, neuer oder verändert); führen Sie zuerst pepsi-setup(1) schema aus.

95.1.55.1.9. Beispiele

Die Berichte von gestern senden (typischer Cron-Aufruf):

pepsi-tlsrpt -c /etc/pepsi/pepsi.conf report

Inspizieren, was für einen bestimmten Tag gesendet würde, ohne zu senden:

pepsi-tlsrpt -c /etc/pepsi/pepsi.conf report --date 2026-06-14 --dry-run

Zähler entfernen, die älter als 30 Tage sind:

pepsi-tlsrpt -c /etc/pepsi/pepsi.conf prune --older-than 30

Ein täglicher Crontab-Eintrag (nach Mitternacht UTC, der über den gerade beendeten Tag berichtet; das Aufräumen ist bereits durch pepsi-tlsrpt-prune.timer eingeplant):

17 1 * * *  pepsi  pepsi-tlsrpt -c /etc/pepsi/pepsi.conf report

95.1.55.1.10. Siehe auch

pepsi-setup(1), pepsi.conf(5), pepsi-stage-relay-to-internet(1), pepsi-stage-relay-to-smarthost(1), pepsi-config(1)

„Key-discovery SSRF“ im Sicherheitskapitel des Pepsi-Handbuchs (die Adressprüfung, die das Berichts-POST teilt), und der Eintrag zur Aufbewahrung von TLS-Berichten in der Verfügbarkeitstabelle seines Bedrohungsmodells.

95.1.55.1.11. Fehler

Melden Sie Fehler an den Pepsi-Issue-Tracker.