.. This file is part of PEPSI. Copyright (C) 2026 GNUnet e.V. PEPSI is free software; you can redistribute it and/or modify it under the terms of the GNU Affero General Public License as published by the Free Software Foundation; either version 3, or (at your option) any later version. ======================== pepsi-stage-dmarc-report ======================== *Read the DMARC aggregate reports other receivers send about the served domains.* Role ==== The DMARC record that Pepsi suggests asks receivers to refuse mail that fails alignment (``p=reject``). Pepsi's own mail always aligns, but another service sending as the domain may not. The only way to find out before receivers refuse such mail is to read the *aggregate reports* (RFC 7489 ยง7.2) that they mail to the record's ``rua=`` address once a day. A report says which addresses sent mail under the domain, how many messages they sent, and whether DKIM and SPF aligned. This stage reads those reports into ``pepsi.dmarc_report``. From them, :doc:`pepsi-status`, the console (*Logs*, *DMARC reports*, and ``GET /api/v1/dmarc-reports``) and ``pepsi-setup check`` say, per domain, either that every source of the last ``WINDOW_DAYS`` aligned, so that ``p=reject`` is safe, or which sources would be refused. Reference: :manpage:`pepsi-stage-dmarc-report(1)`. Placement and address ===================== The stage acts only on mail to ``LOCAL_PART`` (default ``dmarc-reports``) at a served domain; everything else advances to ``NEXT_STAGE`` untouched, and in the unified binary without its body being loaded, so the stage costs ordinary mail nothing. It belongs on the inbound path ahead of the whitelist, challenge and payment gates, which a receiver's report robot would never pass; :doc:`../wizard` places it right after decryption on every installation that receives mail. The recipient check at ``RCPT`` accepts the address at every served domain, and ``pepsi-setup run`` puts ``rua=mailto:dmarc-reports@`` into the DMARC record it suggests (and notes a live record whose ``rua=`` leaves that address out). The report mail is consumed: stored when it carries a readable report about a served domain, dropped and logged when it does not (passing it on to a mailbox that does not exist would bounce it to whoever forged it). ``DELIVER = yes`` passes it on as well. Another recipient of the same message keeps its copy. What a report proves ==================== A report proves nothing about who wrote it. The stage therefore records what ingress vouched for: the ``From:`` domain on a DMARC pass, or else the envelope domain on an SPF pass. **Only an authenticated report counts towards a verdict.** An unauthenticated one is stored, shown marked, and logged at ``warn``; it can neither make ``p=reject`` look safe nor name a source it would refuse, and it cannot shadow the authenticated copy of the same report. Hostile input ============= Decompression stops at ``MAX_REPORT_SIZE`` (16 MiB), so a gzip or zip bomb ends at the cap; the XML reader never expands an entity a document declares; at most 20 000 records of a report are stored. See :ref:`sec-dmarc-reports`. Configuration ============= ``[stage-]``: ``PROGRAM = pepsi-stage-dmarc-report``, ``NEXT_STAGE`` (**required**), ``LOCAL_PART`` (``dmarc-reports``), ``DELIVER`` (``no``), ``MAX_REPORT_SIZE`` (``16M``), ``LOCAL_DOMAINS`` and ``RECIPIENT_DELIMITER``. ``[pepsi-dmarc-reports]``: ``RETAIN_DAYS`` (90; ``pepsi-queue gc``, hourly, deletes older reports) and ``WINDOW_DAYS`` (7; what the summaries and the verdict read). State ===== * **Inputs:** ``state.auth.dmarc`` / ``state.auth.spf``, the ``From:`` and envelope sender, the message body (report mail only). * **Outputs:** none in ``state``. A split message keeps its ``state``, with ``state.dsn`` sliced to the recipients that remain. Telemetry key ``dmarc-report``. See also ======== :doc:`pepsi-status`, :doc:`pepsi-setup`, :doc:`pepsi-queue`, :doc:`../security`, :manpage:`pepsi-stage-dmarc-report(1)`.