65. pepsi-stage-dmarc-report

Read the DMARC aggregate reports other receivers send about the served domains.

65.1. 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, 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: pepsi-stage-dmarc-report(1).

65.2. 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; The 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@<domain> 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.

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

65.4. 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 DMARC aggregate reports.

65.5. Configuration

[stage-<name>]: 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).

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

65.7. See also

pepsi-status, pepsi-setup, pepsi-queue, Security model, pepsi-stage-dmarc-report(1).