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 publishedrua=address, and passing such mail on to a mailbox that does not exist would turn it into bounces to forged senders.With
DELIVER = yesthe message is passed on toNEXT_STAGEas 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_DOMAINSdomain, after the sub-address is stripped (RECIPIENT_DELIMITER). The recipient check atRCPTaccepts 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/Gsuffixes).noneis 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 gcdeletes older ones (with their records).- WINDOW_DAYS (default 7)
How many days back the summaries and the
pepsi-setup checkverdict look, counted by the end of each report’s period; at mostRETAIN_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, elseinfo).- -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.