DMARCTS Handbook
DMARCTS is a small and simple web application for viewing DMARC aggregate reports. This handbook explains how DMARCTS works and how to interpret the results.
Quick Start
- Set up a DMARC DNS record and collect aggregate reports in an IMAP mailbox.
- Install dmarcts-report-parser and dmarcts-report-viewer.
- Filter “Report Status” for “At least one failed result” and review the reports every few days.
- Check for potential SPF or DKIM configuration errors.
Aggregate Report
A DMARC aggregate report is sent by a mail receiver (aka the reporter) to a mail domain owner. One aggregate report covers a period of one day for one domain. The report comprises information about the DMARC policy as seen by the reporter and aggregate data about the SPF and DKIM verification result of emails received. The aggregate data is spread over multiple records (or rows). See the article about understanding DMARC reports to learn more about the data format of reports.
Installation
Install dmarcts-report-parser in order to load DMARC aggregate reports from an IMAP mailbox into an SQL database. The parser is a perl script and can be run from cron.
Then install dmarcts-report-viewer to view the data from the database. The viewer is a PHP application. It does not provide authentication, therefore either run it on an internal webserver or set up .htaccess for access control.
DMARCTS User Interface
Figure 1: Screenshot of DMARCTS.
DMARCTS consists of three panels, from top to bottom:
There is no aggregated statistic about the number of reports or the comprised DMARC results. If you need a visual dashboard presentation, consider using parsedmarc with Kibana or Splunk. The advantage of DMARCTS over parsedmarc is the detail view of individual reports.
Option Bar
The Option Bar at the top offers a couple of options to filter the view.
Figure 2: Option Bar.
The option “Hostname” turns the DNS reverse lookup on or off for the IP addresses listed in the reports. The reverse lookup happens at viewing time and the resulting hostname is not saved in the database. This may lead to a significant delay if the report is very long or if the DNS lookup is impaired. If the user interface feels unresponsive, consider turning the option off.
The option “DMARC Result” allows to filter for reports, in which all rows comprise either a DMARC pass (i.e., success) or fail, or in which the rows have mixed results. This option is of less importance.
The option “Report Status” allows to filter for reports, in which SPF, DKIM and DMARC have either all passed or failed. The most useful filter condition is “At least one failed result”, as it allows a review of all reports, where something went wrong. “Other condition” allows a review of all reports, in which the SPF or DKIM result is neither pass nor fail, but some kind of other error. This usually results in a SPF or DKIM fail and thus will be also shown when filtering for “At least one failed result”.
The option “Month” is self-explanatory.
The option “Domain(s)” allows to filter for reports about specific sender domains. If one of your domains is missing, it has not received a DMARC report yet.
The option “Reporter(s)” allows to filter for reports from specific mail receivers (aka reporters). This is usually an organization, not a destination domain. Even if an organizational domain is given, the report may comprise all mail domains used by the organization (as is the case for google.com for example). However, some reporters send individual reports from each mail server, which are distinguishable by the server hostname.
The right-most button “≡” allows to tweak the user interface and switch to a dark theme.
Report List
Each aggregate report received is shown in the Report List in the center panel.
Figure 3: Report List. The red and orange circles on the left indicate email authentication problems.
The colored circle on the left indicates the overall result. A green circle does not require any action, as the SPF/DKIM/DMARC verification was successful. Any non-green circles should be reviewed for potential configuration errors. Clicking a report item will show its details in the bottom panel.
Report Details
The bottom panel shows the details from a selected DMARC report. The “Policies” text field at the top shows the DMARC policy as interpreted by the reporter. This may differ from your intended policy in corner cases or syntax errors in the DMARC DNS record. The “XML” button allows you to view the raw XML data from the report.
Figure 4: Detail view of an aggregate report with a successful result.
An easy-to-read representation of the XML data is shown in the colored table. Note that DMARCTS displays the data as received by the reporter. It does not evaluate whether the data is actually reasonable. The table comprises the following columns.
“IP” is the server address from which the reporter received emails in the name of your mail domain. This is not necessarily the actual origin of an email; in case of email forwarding or mailing lists, the IP address will point to the last hop that delivered the email to the reporter.
“Host Name” is the reverse lookup of the IP address. It is determined by DMARCTS at runtime, but not persisted in the database. The host name is not submitted by the reporter.
“Message Count” is the number of emails received by the reporter that yielded the same result as shown in the table row.
“Disposition” states whether the reporter quarantined or rejected the email due to the DMARC result. The disposition depends on the overall result of the DMARC check, the policy of your mail domain, and also the local policy of the mail receiver. A disposition result of “none” indicates that the email has not been disposed by the DMARC check. However, the email may still be disposed due to other reasons, e.g., by the spam filter.
“Reason” is an optional field to indicate that the reporter has overriden the DMARC policy. It may used when the reporter applied a local policy and thus to explain why the disposition does not match the DMARC policy of the domain owner. An example for a local policy would be a testing phase, during which the mail receiver does not adhere to the DMARC policy yet, or the detection of a known, trusted email forwarder.
Figure 5: Multiple DKIM authentication results. The DKIM selector is only shown in the XML view.
“DKIM Domain” shows the domain parameter of the DKIM authentication result (d= in the DKIM-Signature header). If the message had multiple DKIM signatures, there may be multiple DKIM authentication results, which will by shown by DMARCTS as a list of DKIM domains (Figure 5). This however depends on whether the reporter includes multiple DKIM authentication results or just the first successful one.
A reporter may optionally include the DKIM selector, but DMARCTS does not show it. It can be viewed in the raw XML report, though (Figure 5).
“DKIM Auth” is the DKIM authentication result before applying the DMARC alignment check (some people call this the “raw DKIM result”). A limitation of DMARCTS is that it shows only the first DKIM authentication result, even if there is more than one (indicated by multiple DKIM domains). The other ones can be viewed in the raw XML report (Figure 5).
Figure 6: Multiple SPF authentication results. The SPF Scope is only shown in the XML view.
“SPF Domain” shows the domain used in the SPF check. This corresponds either to the SMTP envelope-from (RFC 5321) or the HELO/EHLO name. A reporter may include both, which will be shown by DMARCTS as a list of two SPF Domains (Figure 6).
A reporter may optionally indicate the SPF scope (“mfrom” = envelope-from domain, “helo” = HELO/EHLO domain), but DMARCTS does not show it. It can be viewed in the raw XML report, though (Figure 6).
“SPF Auth” is the SPF authentication result before applying the DMARC alignment check (some people call this the “raw SPF result”). A limitation of DMARCTS is that is shows only the first SPF authentication result, even if there is more than one (indicated by multiple SPF domains). The other ones can be viewed in the raw XML report (Figure 6).
“DKIM Align” and “SPF Align” are the DKIM and SPF authentication results after applying the DMARC alignment check. DMARC requires alignment of the DKIM domain and SPF domain with the header-from domain (RFC 5322). An email that passes the raw DKIM or SPF check but fails the DMARC alignment is considered as not authenticated by DMARC. The DKIM and SPF “Align” fields are thus more significant than their corresponding “Auth” fields.
“DMARC” is the overall DMARC result. It will be “Pass” if at least one of “DKIM Align” or “SPF Align” is a pass. If both have failed, the email will be disposed according to the DMARC policy of the domain owner and optionally the local policy of the mail receiver.
Example Scenarios
The following examples show common scenarios, in which some kind of authentication error has occurred.
DMARC Pass
DMARC requires at least one of the two authentication methods, SPF or DKIM, to succed. If one fails, the other one suffices for a successful DMARC validation.
Figure 7: DMARC validation passes, though DKIM is unused.
In the example in Figure 7 the email had no DKIM signature. This is indicated by “DKIM Auth=unknown”. Without a DKIM signature the “DKIM Align” check has failed. However, the SPF authentication and alignment check was successful, therefore the DMARC overall result is “Pass”. It is recommended to check whether DKIM signing is set up correctly.
Figure 8: DMARC validation passes, though SPF is unused.
Figure 8 shows two different results: in the first row (swznet.de), both SPF and DKIM succeeded. In the second row (mailroute.net), “SPF Auth=none” indicates that SPF is not configured for the envelope-from domain (“SPF Domain=srs.mailroute.net”). Therefore, the “SPF Align” check has failed. However, the DKIM result indicates that the email is authentic and that the DMARC result is “Pass”. This is a typical scenario of server-based email forwarding. The recipient server receives the email from a different IP address and thus SPF inevitably fails. As long as DKIM succeeds, the email is authentic and there is no action necessary.
Figure 9: DMARC validation passes, though SPF has failed.
Figure 9 is similar to the previous example, but with “SPF Auth=fail”. This happens because the sender IP address is not authorized in the SPF record of the envelope-from domain (“SPF Domain=wander.science”). Again, this is typical for server-based email forwarding. However, it may also occur if the sender IP address is missing in the SPF record of the envelope-from domain. It is therefore recommended to check whether the server IP address shown in the DMARC report is supposed to be an authorized sender.
DMARC Fail
The following are various examples of spoofed emails. Once an active DMARC policy of “p=quarantine” or “p=reject” is being used, reports about spoofed emails do not require an action. However, it is recommended to check whether these are actually cases of spoofing or whether legitimate emails fail DMARC validation. DMARC reports help to identify corner cases of SPF/DKIM/DMARC misconfigurations, which may go unnoticed otherwise.
Figure 10: No DKIM or SPF.
In the example in Figure 10 both DKIM and SPF have failed. The message had no DKIM signature (“DKIM Auth=none”) and the envelope-from domain (“SPF Domain”) has no SPF record. The sender is not authorized to send emails for the header-from domain (shown at the top of Figure 10: Report from google.com for swznet.de). The DMARC validation result is “Fail” and the email has been rejected (“Disposition=reject”) according to the DMARC policy.
Figure 11: SPF misaligned.
The example in Figure 11 is similar to the previous one, except for “SPF Auth=pass”. This indicates that the envelope-from domain (“SPF Domain=eigbox.net”) has an SPF record, which authorizes the sender IP address. However, the envelope-from domain eigbox.net is misaligned with the header-from domain swznet.de. Thus the “SPF Align” check has failed. There is also no DKIM signature, thus overall this is a “DMARC=Fail”.
Figure 12: DKIM misaligned.
The example in Figure 12 shows “DKIM Auth=pass”, which indicates a DKIM signatures that verified correctly. However, the DKIM signature is for “DKIM Domain=evastores.com”, which is misaligned with the header-from domain swznet.de that the report is about. Hence, the “DKIM Align” check has failed. The envelope-from domain (“SPF Domain=swznet.de”) claims to be aligned with the header-from domain, but fails the SPF authentication (“SPF Auth=fail”). Without SPF authentication, the “SPF Align” check cannot pass and is considered to have failed, too. The overall result is “DMARC=Fail”.