Welcome to parsedmarc’s documentation!¶

pasedmarc is a Python module and CLI utility for parsing aggregate DMARC reports.

Features¶

Parses draft and 1.0 standard aggregate reports
Transparently handles gzip or zip compressed reports
Consistent data structures
Simple JSON or CSV output
Python 2 and 3 support

CLI help¶

usage: parsedmarc.py [-h] [-f FORMAT] [-o OUTPUT]
                     [-n NAMESERVER [NAMESERVER ...]] [-t TIMEOUT] [-v]
                     file_path [file_path ...]

Parses aggregate DMARC reports

positional arguments:
  file_path             one or more paths of aggregate report files
                        (compressed or uncompressed)

optional arguments:
  -h, --help            show this help message and exit
  -f FORMAT, --format FORMAT
                        specify JSON or CSV output format
  -o OUTPUT, --output OUTPUT
                        output to a file path rather than printing to the
                        screen
  -n NAMESERVER [NAMESERVER ...], --nameserver NAMESERVER [NAMESERVER ...]
                        nameservers to query
  -t TIMEOUT, --timeout TIMEOUT
                        number of seconds to wait for an answer from DNS
                        (default 6.0)
  -v, --version         show program's version number and exit

Sample output¶

Here are the results from parsing the example report from the dmarc.org wiki. It’s actually an older draft of the the 1.0 report schema standardized in RFC 7480 Appendix C. This draft schema is still in wide use.

parsedmarc produces consistent, normalized output, regardless of the report schema.

JSON¶

{
  "xml_schema": "draft",
  "report_metadata": {
    "org_name": "acme.com",
    "org_email": "noreply-dmarc-support@acme.com",
    "org_extra_contact_info": "http://acme.com/dmarc/support",
    "report_id": "9391651994964116463",
    "begin_date": "2012-04-27 20:00:00",
    "end_date": "2012-04-28 19:59:59",
    "errors": []
  },
  "policy_published": {
    "domain": "example.com",
    "adkim": "r",
    "aspf": "r",
    "p": "none",
    "sp": "none",
    "pct": "100",
    "fo": "0"
  },
  "records": [
    {
      "source": {
        "ip_address": "72.150.241.94",
        "country": "US",
        "reverse_dns": "adsl-72-150-241-94.shv.bellsouth.net",
        "base_domain": "bellsouth.net"
      },
      "count": 2,
      "policy_evaluated": {
        "disposition": "none",
        "dkim": "fail",
        "spf": "pass",
        "policy_override_reasons": []
      },
      "identifiers": {
        "header_from": "example.com",
        "envelope_from": "example.com",
        "envelope_to": null
      },
      "auth_results": {
        "dkim": [
          {
            "domain": "example.com",
            "selector": "none",
            "result": "fail"
          }
        ],
        "spf": [
          {
            "domain": "example.com",
            "scope": "mfrom",
            "result": "pass"
          }
        ]
      }
    }
  ]
}

CSV¶

xml_schema,org_name,org_email,org_extra_contact_info,report_id,begin_date,end_date,errors,domain,adkim,aspf,p,sp,pct,fo,source_ip_address,source_country,source_reverse_dns,source_base_domain,count,disposition,dkim_alignment,spf_alignment,policy_override_reasons,policy_override_comments,envelope_from,header_from,envelope_to,dkim_domains,dkim_selectors,dkim_results,spf_domains,spf_scopes,spf_results
draft,acme.com,noreply-dmarc-support@acme.com,http://acme.com/dmarc/support,9391651994964116463,2012-04-27 20:00:00,2012-04-28 19:59:59,[],example.com,r,r,none,none,100,0,72.150.241.94,US,adsl-72-150-241-94.shv.bellsouth.net,bellsouth.net,2,none,fail,pass,,,example.com,example.com,,example.com,none,fail,example.com,mfrom,pass

What about forensic DMARC reports?¶

Forensic DMARC reports are emails with an attached email sample that failed a DMARC check. You can parse them with any email message parser, such as mail-parser.

Very few recipients send forensic reports, and even those who do will only provide the message headers, and not the message’s content, for privacy reasons.

Bug reports¶

Please report bugs on the GitHub issue tracker

https://github.com/domainaware/parsedmarc/issues

API¶

A Python module and CLI for parsing aggregate DMARC reports

exception parsedmarc.InvalidAggregateReport[source]¶: Raised when an invalid DMARC aggregate report is encountered

parsedmarc.parse_aggregate_report_file(_input, nameservers=None, timeout=6.0)[source]¶

Parses a file at the given path, a file-like object. or bytes as a aggregate DMARC report

Parameters:	_input – A path to a file, a file like object, or bytes nameservers (list) – A list of one or more nameservers to use timeout (float) – Sets the DNS timeout in seconds
Returns:	The parsed DMARC aggregate report
Return type:	OrderedDict

parsedmarc.parse_aggregate_report_xml(xml, nameservers=None, timeout=6.0)[source]¶

Parses a DMARC XML report string and returns a consistent OrderedDict

Parameters:	xml (str) – A string of DMARC aggregate report XML nameservers (list) – A list of one or more nameservers to use timeout (float) – Sets the DNS timeout in seconds
Returns:	The parsed aggregate DMARC report
Return type:	OrderedDict

parsedmarc.parsed_aggregate_report_to_csv(_input)[source]¶

Converts one or more parsed aggregate reports to flat CSV format, including headers

Parameters:	_input – A parsed aggregate report or list of parsed aggregate reports
Returns:	Parsed aggregate report data in flat CSV format, including headers
Return type:	str