95.1.40. pepsi-stage-dmarc-report

read the DMARC aggregate reports other receivers send about us

Manual section:

1

95.1.40.1.1. Name

pepsi-stage-dmarc-report - the DMARC aggregate-report stage of the Pepsi pipeline.

95.1.40.1.2. Synopsis

pepsi-stage-dmarc-report [GLOBAL-OPTIONS] worker

95.1.40.1.3. Description

pepsi-stage-dmarc-report is a stage program run by pepsi-dispatch(1) as a persistent worker reading message ids on standard input.

A domain’s DMARC record (RFC 7489) names, in rua=, where receivers send their aggregate reports: once a day, per receiving organisation, which addresses sent mail with the domain in From:, how many messages, and whether DKIM and SPF passed in alignment with that domain. Those reports are the only way to learn whether p=reject refuses a legitimate sender, such as a newsletter service or a ticket system: before it does so, and while it does. This stage reads them into the database (pepsi.dmarc_report and pepsi.dmarc_report_record); pepsi-status(1), the administrative console (Logs, DMARC reports) and pepsi-setup check (see pepsi-setup(1)) report from there.

Place it on the inbound path ahead of the whitelist, challenge and payment gates: a receiver’s report robot passes none of them. It acts only on mail to LOCAL_PART at one of the served domains; everything else advances to NEXT_STAGE untouched, and in the unified binary it does so on the message’s metadata alone, without loading the body. pepsi-setup --wizard places it right after decryption on every installation that receives mail, and pepsi-setup run then suggests a DMARC record whose rua= is mailto:dmarc-reports@<domain>.

95.1.40.1.4. What happens to report mail

  • A message to the report address carrying a readable report (a gzip, zip or plain XML attachment, as RFC 7489 §7.2.1 describes) about a served domain (the domain itself, a subdomain, or the organisational domain of a served subdomain) is stored and consumed. The same report (same organisation, report id, domain and authentication) is not stored twice.

  • A report about a domain this host does not serve is consumed and ignored.

  • Mail to the report address that is not a readable report is consumed and dropped (logged at info). Anybody can write to a published rua= address, and passing such mail on to a mailbox that does not exist would turn it into bounces to forged senders.

  • With DELIVER = yes the message is passed on to NEXT_STAGE as well, for a site that keeps a mailbox at the address.

  • Any other recipient of the same message keeps its copy, with its own DSN parameters; only the report address is taken off the envelope.

95.1.40.1.5. What a report proves

A report proves nothing about who wrote it. The stage records what ingress could vouch for about the mail that carried it: the From: domain when DMARC passed, else the envelope sender’s domain when SPF passed. A report with neither is stored as unauthenticated (logged at warn). Only authenticated reports count towards a verdict: a forged report can neither make p=reject look safe nor invent a source that it would refuse. dkim=pass alone does not authenticate a report; it says that some signature verified, not whose. A forged copy of a report never shadows the authenticated one, since the two are stored apart.

95.1.40.1.6. Hostile input

A report is a compressed file from the Internet:

  • Decompression stops at MAX_REPORT_SIZE (default 16 MiB): a gzip or zip bomb ends at the cap, and a zip entry that declares a larger size is refused before it is read. Only the deflate method is understood.

  • The XML reader expands the five predefined entities and character references only, never an entity a document declares, so an entity-expansion (“billion laughs”) report stays the size it arrived at.

  • At most 20 000 records of one report are stored; the rest are counted (records_dropped).

95.1.40.1.7. Configuration

[stage-<name>] with PROGRAM = pepsi-stage-dmarc-report:

NEXT_STAGE (required)

Where every message that is not a report goes, which is nearly all of them. pepsi-setup(1) checks that the target resolves.

LOCAL_PART (default dmarc-reports)

The local part that the reports arrive at, on every LOCAL_DOMAINS domain, after the sub-address is stripped (RECIPIENT_DELIMITER). The recipient check at RCPT accepts it at every served domain.

DELIVER (default no)

Also pass the report mail on to NEXT_STAGE.

MAX_REPORT_SIZE (default 16M)

Cap on a decompressed report, as a byte size (K/M/G suffixes). none is refused: the cap is what stops a bomb.

LOCAL_DOMAINS, RECIPIENT_DELIMITER

Which domains are served (default [pepsi-ingress] ACCEPTED_DOMAINS) and the sub-address delimiter (default [pepsi] RECIPIENT_DELIMITER, else +).

[pepsi-dmarc-reports] (read by this stage’s start-up check, by pepsi-status(1), pepsi-queue(1) gc, the console and pepsi-setup(1)):

RETAIN_DAYS (default 90)

Days a report is kept after the end of the period it covers; pepsi-queue gc deletes older ones (with their records).

WINDOW_DAYS (default 7)

How many days back the summaries and the pepsi-setup check verdict look, counted by the end of each report’s period; at most RETAIN_DAYS.

There is no BOUNCE_STAGE: the stage never bounces. A database error while storing a report is retried like any stage error. The base configuration is checked when the worker starts: a broken one makes it refuse to start (exit 78).

95.1.40.1.8. Message data

The stage loads the whole message (Load::Full), but in the unified binary every message without a recipient at the report address fuses through on its metadata, so ordinary mail never loads its body here. The stage never rewrites a message it passes on; a split message keeps its state (state.dsn sliced to the remaining recipients). Telemetry key dmarc-report: one count per stored report.

95.1.40.1.9. Commands

worker

Read message ids on standard input and process each. The only run mode; the dispatcher starts and stops these workers.

95.1.40.1.10. Global Options

-c FILE, –config FILE

Read the configuration from FILE instead of searching the default locations. Must come before the subcommand.

-L LOGLEVEL, –log LOGLEVEL

Set the logging verbosity (default [pepsi] LOG, else info).

-v, –verbose

Show log messages from all sources.

-h, –help; -V, –version

Print a usage summary / the version and exit.

95.1.40.1.11. Exit Status

0

The worker exited cleanly.

1

An error occurred (a malformed configuration file, an unresolvable stage section, or a failed database connection). The reason is written to the log.

78

The worker refused to start: its section or [pepsi-dmarc-reports] does not parse.

95.1.40.1.12. Examples

Read the reports right after decryption:

[stage-decrypt]
PROGRAM = pepsi-stage-decrypt
NEXT_STAGE = dmarc-reports

[stage-dmarc-reports]
PROGRAM = pepsi-stage-dmarc-report
NEXT_STAGE = check-whitelist

and publish, for each served domain:

_dmarc.example.org. IN TXT "v=DMARC1; p=reject; adkim=s; rua=mailto:dmarc-reports@example.org"

Process one message by hand:

echo 4711 | pepsi-stage-dmarc-report -c /etc/pepsi/pepsi.conf worker

95.1.40.1.13. See Also

pepsi-status(1), pepsi-setup(1), pepsi-queue(1), pepsi-httpd(1), pepsi-dispatch(1), pepsi.conf(5), pepsi.state(7)

RFC 7489, Domain-based Message Authentication, Reporting, and Conformance (DMARC), §7.2 (aggregate reports) and Appendix C (their XML schema).

95.1.40.1.14. Bugs

Report bugs to the Pepsi issue tracker.