Making Sense of DMARC Reports with a CLI Tool

• Introduction
• Why DMARC Exists
• How to Configure DMARC Reports
  • 1. Publish a DMARC Record
  • 2. Create a Mailbox for Reports
  • 3. (Optional) Publish a DNS Delegation Record
  • 4. Collect and Process Reports
• What a DMARC Report Looks Like
• The Challenge: XML Fatigue
• The DMARC Report Viewer CLI
  • Features
  • Example Output
• Lessons Learned
• Conclusion

Introduction

If you own a domain and use it for email, you might want to receive DMARC aggregate reports. These reports are sent by receiving mail servers to let you know who is sending mail claiming to be from your domain, whether legitimate or not.

The problem: DMARC reports arrive as bulky XML files, often compressed into .gz or .zip archives. They are detailed but hard to read by hand.

To make sense of them, I built a CLI tool that parses DMARC reports and turns them into human-friendly tables right in the terminal. This post explains the basics of DMARC, why the reports matter, and how this CLI can make them much easier to work with.

👉 Check it out here: DMARC Report Viewer

Why DMARC Exists

Email was not originally designed with authentication in mind, which makes it easy for attackers to send emails that look like they came from your domain. This is called spoofing.

To fight this, three mechanisms are commonly used together:

• SPF (Sender Policy Framework): Defines which mail servers are authorized to send email for your domain.
• DKIM (DomainKeys Identified Mail): Cryptographically signs messages to prove they have not been altered and were sent by an authorized server.
• DMARC (Domain-based Message Authentication, Reporting, and Conformance): Ties SPF and DKIM together, and tells receiving mail servers what to do when a message fails (ignore, quarantine, reject).

With DMARC, you can also request aggregate reports (via the rua tag) so you know exactly who is trying to send as you.

How to Configure DMARC Reports

To receive DMARC aggregate reports, you need to:

1. Publish a DMARC Record

Add a TXT record in DNS at:

_dmarc.<your-domain>

Example:

v=DMARC1; p=reject; rua=mailto:dmarc-reports@your-domain.com; ruf=mailto:dmarc-failures@your-domain.com; adkim=r; aspf=r

Key tags:

• v=DMARC1: Version
• p=reject: Policy (none, quarantine, or reject)
• rua=: Where aggregate reports are sent (daily XML summaries)
• ruf=: Where failure (forensic) reports are sent (less common, optional)
• adkim / aspf: Alignment modes (r = relaxed, s = strict)

2. Create a Mailbox for Reports

Set up a dedicated address such as dmarc-reports@your-domain.com.

• It just needs to handle attachments (.xml.gz or .xml.zip).
• Reports are often daily per provider (Google, Microsoft, Yahoo, etc.).
• Expect volume to grow with your email traffic. The more mail you send, the more reports you will receive.

3. (Optional) Publish a DNS Delegation Record

If reports are sent to a different domain (e.g. a third-party service), you may need to publish a DNS delegation record to prove that domain is authorized to receive reports.

4. Collect and Process Reports

At this point, you’ll start receiving compressed XML reports with information about:

• Source IPs sending as your domain
• SPF/DKIM pass/fail results
• The receiver’s disposition (none, quarantine, reject)

What a DMARC Report Looks Like

Here is an example DMARC Report:

<?xml version="1.0" encoding="UTF-8"?>
<feedback>
  <report_metadata>
    <org_name>ExampleOrg</org_name>
    <email>dmarc-reports@example.com</email>
    <report_id>123456789</report_id>
    <date_range>
      <begin>1622505600</begin>
      <end>1622592000</end>
    </date_range>
  </report_metadata>
  <policy_published>
    <domain>your-domain.com</domain>
    <p>reject</p>
    <sp>reject</sp>
    <adkim>r</adkim>
    <aspf>r</aspf>
  </policy_published>
  <record>
    <row>
      <source_ip>192.0.2.1</source_ip>
      <count>1</count>
      <policy_evaluated>
        <disposition>none</disposition>
        <dkim>pass</dkim>
        <spf>pass</spf>
      </policy_evaluated>
    </row>
    <identifiers>
      <header_from>your-domain.com</header_from>
    </identifiers>
    <auth_results>
      <spf>
        <domain>your-domain.com</domain>
        <result>pass</result>
      </spf>
      <dkim>
        <domain>your-domain.com</domain>
        <result>pass</result>
      </dkim>
    </auth_results>
  </record>
</feedback>

This means:

• An email claiming to be from your-domain.com came from IP 192.0.2.1.
• Both SPF and DKIM passed and aligned.
• Even though the policy is reject, aligned authentication means the message is delivered normally, so the disposition is none.

This is what a legitimate, correctly configured email looks like in a DMARC report.

The Challenge: XML Fatigue

Reading one of these XML files by hand is manageable. Reading dozens quickly becomes overwhelming.

That is why it makes sense to build tooling that can:

• Decompress .gz or .zip
• Parse the XML
• Display results in a human-friendly way

The DMARC Report Viewer CLI

The DMARC Report Viewer is a small CLI written in Node.js + TypeScript.

Features

• Supports .xml, .gz, and .zip
• Lets you select reports from the current directory
• Displays results as a table in the terminal

Example Output

┌─────────┬─────────────┬───────┬────────┬────────┬─────────────┬───────────────────┬────────────┬─────────────┬────────────────┐
│ (index) │ IP          │ Count │ SPF    │ DKIM   │ Disposition │ From              │ SPF Result │ DKIM Result │ Status         │
├─────────┼─────────────┼───────┼────────┼────────┼─────────────┼───────────────────┼────────────┼─────────────┼────────────────┤
│ 0       │ '192.0.2.1' │ '1'   │ 'pass' │ 'pass' │ 'none'      │ 'your-domain.com' │ 'pass'     │ 'pass'      │ '✅ Delivered' │
└─────────┴─────────────┴───────┴────────┴────────┴─────────────┴───────────────────┴────────────┴─────────────┴────────────────┘

👉 Source: GitHub - DMARC Report Viewer

Lessons Learned

• Spoofing attempts are normal. You can not stop people from trying, but you can stop their emails from being delivered.
• SPF, DKIM, and DMARC work best together.
• DMARC aggregate reports give you real-world visibility into how your domain is being used.
• With the right tooling, even daily XML dumps can be turned into something easy to read.

Conclusion

DMARC reports may look intimidating at first, but once you configure DNS correctly and have a way to parse them, they become a powerful tool for protecting your domain.

That is why I built the DMARC Report Viewer. A simple CLI to help make sense of those reports.

👉 Try it here: DMARC Report Viewer on GitHub

Do not ignore your DMARC reports. They are your window into the health and safety of your domain’s email ecosystem.