- Features
- CLI help -
- Sample output
-
+
- Sample aggregate report output -
- What about forensic DMARC reports? +
- Sample forensic report output
- Bug reports -
- Installation +
- Installation +
- API
- Indices and tables
Welcome to parsedmarc’s documentation!¶
-
+pasedmarcis a Python module and CLI utility for parsing aggregate DMARC reports.pasedmarcis a Python module and CLI utility for parsing DMARC reports.Features¶
- Parses draft and 1.0 standard aggregate reports +
- Parses forensic reports +
- Can parse reports from an inbox over IMAP
- Transparently handles gzip or zip compressed reports
- Consistent data structures -
- Simple JSON or CSV output -
- Python 2 and 3 support +
- Simple JSON and/or CSV output
CLI help¶
--usage: parsedmarc.py [-h] [-f FORMAT] [-o OUTPUT] - [-n NAMESERVER [NAMESERVER ...]] [-t TIMEOUT] [-v] - file_path [file_path ...] +
usage: parsedmarc [-h] [-o OUTPUT] [-n NAMESERVERS [NAMESERVERS ...]] + [-t TIMEOUT] [-H HOST] [-U USERNAME] [-p PASSWORD] + [-a ARCHIVE_FOLDER] [-d] [-i] [-T] [-v] + [file_path [file_path ...]] -Parses aggregate DMARC reports +Parses DMARC reports positional arguments: file_path one or more paths of aggregate report files @@ -196,28 +201,38 @@ 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 ...] + Write output files to the given directory + -n NAMESERVERS [NAMESERVERS ...], --nameservers NAMESERVERS [NAMESERVERS ...] nameservers to query -t TIMEOUT, --timeout TIMEOUT number of seconds to wait for an answer from DNS (default 6.0) + -H HOST, --host HOST IMAP hostname or IP address + -U USERNAME, --username USERNAME + IMAP username + -p PASSWORD, --password PASSWORD + IMAP password + -a ARCHIVE_FOLDER, --archive-folder ARCHIVE_FOLDER + Specifies the IMAP folder to move messages to after + processing them (default: Archive) + -d, --delete Delete the reports after processing them + -i, --idle Use an IMAP IDLE connection to process reports as they + arrive in the inbox + -T, --test Do not move or delete IMAP messages -v, --version show program's version number and exit
-Sample output¶
++Sample aggregate report 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.
-
+parsedmarcproduces consistent, normalized output, regardless of the report schema.parsedmarcproduces consistent, normalized output, regardless of the report +schema.-JSON¶
{ @@ -290,14 +305,10 @@ This draft schema is still in wide use.-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 often -provide only the message headers, and not the message’s content, for privacy -reasons.
++Sample forensic report output¶
+I don’t have a sample I can share for privacy reasons. If you have a sample +forensic report that you can share publicly, please contact me!
Bug reports¶
@@ -311,8 +322,10 @@ reasons.-$ sudo apt-get install python3-pip
Python 3 installers for Windows and macOS can be found at https://www.python.org/downloads/
-To install or upgrade to the latest stable release of
+parsedmarcon macOS or Linux, runPython 3 installers for Windows and macOS can be found at +https://www.python.org/downloads/
+To install or upgrade to the latest stable release of
parsedmarcon +macOS or Linux, run@@ -323,28 +336,62 @@ reasons.$ sudo -H pip3 install -U checkdmarc
+Note
On Windows,
+substitutepip3ispip, even with Python 3. So on Windows, simply -substitutepipas an administrator in place ofsudo pip3, in the above commands.pipas an administrator in place ofsudo pip3, in the +above commands. ++Optional dependencies¶
+If you would like to be able to parse emails saved from Microsoft Outlook +(i.e. OLE .msg files), install
+msgconvert:On Debian or Ubuntu systems, run:
++$ sudo apt-get install libemail-outlook-message-perl +
@@ -490,7 +694,7 @@ headers @@ -64,7 +64,7 @@API¶
-A Python module and CLI for parsing aggregate DMARC reports
+A Python module and CLI for parsing DMARC reports
+ +-
exception
parsedmarc.InvalidAggregateReport[source]¶ Raised when an invalid DMARC aggregate report is encountered
-
+
-
+exception
parsedmarc.InvalidDMARCReport[source]¶
+ Raised when an invalid DMARC report is encountered
+
-
+
-
+exception
parsedmarc.InvalidForensicReport[source]¶
+ Raised when an invalid DMARC forensic report is encountered
+
-
-
parsedmarc.extract_xml(_input)[source]¶
+ Extracts xml from a zip or gzip file at the given path, file-like object, or bytes.
- Parameters: _input – A path to a file, a file like object, or bytes +Parameters: input – A path to a file, a file like object, or bytes Returns: The extracted XML
parsedmarc.extract_xml(input_)[source]¶-
+
-
+
parsedmarc.get_dmarc_reports_from_inbox(host, username, password, archive_folder='Archive', delete=False, test=False, nameservers=None, dns_timeout=6.0)[source]¶
+ Fetches and parses DMARC reports from sn inbox
++
++ + + Parameters: -
+
- host – The mail server hostname or IP address +
- username – The mail server username +
- password – The mail server password +
- archive_folder – The folder to move processed mail to +
- delete (bool) – Delete messages after processing them +
- test (bool) – Do not move or delete messages after processing them +
- nameservers (list) – A list of DNS nameservers to query +
- dns_timeout (float) – Set the DNS query timeout +
Returns: Lists of
+aggregate_reportsandforensic_reportsReturn type: OrderedDict
+
-
parsedmarc.human_timestamp_to_datetime(human_timestamp)[source]¶
@@ -423,6 +500,88 @@ aggregate DMARC report
-
+
-
+
parsedmarc.parse_forensic_report(feedback_report, sample, sample_headers_only, nameservers=None, timeout=6.0)[source]¶
+ Converts a DMARC forensic report and sample to a
+OrderedDict+
++ + + Parameters: -
+
- feedback_report – A message’s feedback report as a string +
- sample – The RFC 822 headers or RFC 822 message sample +
- sample_headers_only (bool) – Set true if the sample is only headers +
- nameservers (list) – A list of one or more nameservers to use +
- timeout (float) – Sets the DNS timeout in seconds +
Returns: An parsed report and sample
+Return type: OrderedDict
+
-
+
-
+
parsedmarc.parse_report_email(input_, nameservers=None, timeout=6.0)[source]¶
+ Parses a DMARC report from an email
++
++ + + Parameters: -
+
- input – An emailed DMARC report in RFC 822 format, as bytes or a string +
- nameservers (list) – A list of one or more nameservers to use +
- timeout (float) – Sets the DNS timeout in seconds +
Returns: -
+
report_type:aggregateorforensic
+report: The parsed report
+
Return type: OrderedDict
+
-
+
-
+
parsedmarc.parse_report_file(input_, nameservers=None, timeout=6.0)[source]¶
+ Parses a DMARC aggregate or forensic file at the given path, a +file-like object. or bytes
++
++ + + 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 report
+Return type: OrderedDict
+
-
+
-
+
parsedmarc.save_output(results, output_directory='output')[source]¶
+ Save report data in the given directory
++
++ + + Parameters: -
+
- results (OrderedDict) – Parsing results +
- output_directory – The patch to the directory to save in +
-
+
-
+
parsedmarc.watch_inbox(host, username, password, callback, archive_folder='Archive', delete=False, test=False, wait=30, nameservers=None, dns_timeout=6.0)[source]¶
+ Use an IDLE IMAP connection to parse incoming emails, and pass the results +to a callback function
++
++ + + Parameters: -
+
- host – The mail server hostname or IP address +
- username – The mail server username +
- password – The mail server password +
- callback – The callback function to receive the parsing results +
- archive_folder – The folder to move processed mail to +
- delete (bool) – Delete messages after processing them +
- test (bool) – Do not move or delete messages after processing them +
- wait (int) – Number of seconds to wait for a IMAP IDLE response +
- nameservers (list) – A list of DNS nameservers to query +
- dns_timeout (float) – Set the DNS query timeout +
- 1.1.0 + 2.0.0@@ -195,7 +195,7 @@