parsedmarc 🔗

A Python package for parsing DMARC reports

email_results 🔗

email_results(
    results: SortedReportContainer,
    host: str,
    mail_from: str,
    mail_to: list[str],
    mail_cc: list[str] | None = None,
    mail_bcc: list[str] | None = None,
    port: int = 0,
    require_encryption: bool = False,
    verify: bool = True,
    username: str | None = None,
    password: str | None = None,
    subject: str | None = None,
    attachment_filename: str | None = None,
    message: str | None = None,
) -> None

Emails parsing results as a zip file

PARAMETER	DESCRIPTION
`results`	Parsing results TYPE: `SortedReportContainer`
`host`	Mail server hostname or IP address TYPE: `str`
`mail_from`	The value of the message from header TYPE: `str`
`mail_to`	A list of addresses to mail to TYPE: `list[str]`
`mail_cc`	A list of addresses to CC TYPE: `list[str] \| None` DEFAULT: `None`
`mail_bcc`	A list addresses to BCC TYPE: `list[str] \| None` DEFAULT: `None`
`port`	Port to use TYPE: `int` DEFAULT: `0`
`require_encryption`	Require a secure connection from the start TYPE: `bool` DEFAULT: `False`
`verify`	verify the SSL/TLS certificate TYPE: `bool` DEFAULT: `True`
`username`	An optional username TYPE: `str \| None` DEFAULT: `None`
`password`	An optional password TYPE: `str \| None` DEFAULT: `None`
`subject`	Overrides the default message subject TYPE: `str \| None` DEFAULT: `None`
`attachment_filename`	Override the default attachment filename TYPE: `str \| None` DEFAULT: `None`
`message`	Override the default plain text body TYPE: `str \| None` DEFAULT: `None`

get_dmarc_reports_from_mailbox 🔗

get_dmarc_reports_from_mailbox(
    connection: MailboxConnection,
    reports_folder: str = "INBOX",
    archive_folder: str = "Archive",
    delete: bool = False,
    test: bool = False,
    ip_db_path: str | None = None,
    offline: bool = False,
    nameservers: list[str] | None = None,
    dns_timeout: float = 6.0,
    strip_attachment_payloads: bool = False,
    results: SortedReportContainer | None = None,
    batch_size: int = 10,
    create_folders: bool = True,
) -> SortedReportContainer

Fetches and parses DMARC reports from a mailbox

PARAMETER	DESCRIPTION
`connection`	A Mailbox connection object TYPE: `MailboxConnection`
`reports_folder`	The folder where reports can be found TYPE: `str` DEFAULT: `'INBOX'`
`archive_folder`	The folder to move processed mail to TYPE: `str` DEFAULT: `'Archive'`
`delete`	Delete messages after processing them TYPE: `bool` DEFAULT: `False`
`test`	Do not move or delete messages after processing them TYPE: `bool` DEFAULT: `False`
`ip_db_path`	Path to a MMDB file from MaxMind or DBIP TYPE: `str \| None` DEFAULT: `None`
`offline`	Do not query online for geolocation or DNS TYPE: `bool` DEFAULT: `False`
`nameservers`	A list of DNS nameservers to query TYPE: `list[str] \| None` DEFAULT: `None`
`dns_timeout`	Set the DNS query timeout TYPE: `float` DEFAULT: `6.0`
`strip_attachment_payloads`	Remove attachment payloads from forensic report results TYPE: `bool` DEFAULT: `False`
`results`	Results from the previous run TYPE: `SortedReportContainer \| None` DEFAULT: `None`
`batch_size`	Number of messages to read and process before saving (use 0 for no limit) TYPE: `int` DEFAULT: `10`
`create_folders`	Whether to create the destination folders (not used in watch) TYPE: `bool` DEFAULT: `True`

RETURNS	DESCRIPTION
`SortedReportContainer`	collected reported

get_dmarc_reports_from_mbox 🔗

get_dmarc_reports_from_mbox(
    source: str,
    nameservers: list[str] | None = None,
    dns_timeout: float = 2.0,
    strip_attachment_payloads: bool = False,
    ip_db_path: str | None = None,
    offline: bool = False,
) -> SortedReportContainer

Parses a mailbox in mbox format containing e-mails with attached DMARC reports

PARAMETER	DESCRIPTION
`source`	A path to a mbox file TYPE: `str`
`nameservers`	A list of one or more nameservers to use (Cloudflare's public DNS resolvers by default) TYPE: `list[str] \| None` DEFAULT: `None`
`dns_timeout`	Sets the DNS timeout in seconds TYPE: `float` DEFAULT: `2.0`
`strip_attachment_payloads`	Remove attachment payloads from forensic report results TYPE: `bool` DEFAULT: `False`
`ip_db_path`	Path to a MMDB file from MaxMind or DBIP TYPE: `str \| None` DEFAULT: `None`
`offline`	Do not make online queries for geolocation or DNS TYPE: `bool` DEFAULT: `False`

RETURNS	DESCRIPTION
`SortedReportContainer`	container of reports

get_report_zip 🔗

get_report_zip(results: SortedReportContainer) -> bytes

Creates a zip file of parsed report output

PARAMETER	DESCRIPTION
`results`	The parsed results TYPE: `SortedReportContainer`

RETURNS	DESCRIPTION
`bytes`	raw zip file

parse_aggregate_report_file 🔗

parse_aggregate_report_file(
    source: bytes | str | BinaryIO,
    offline: bool = False,
    ip_db_path: str | None = None,
    nameservers: list[str] | None = None,
    dns_timeout: float = 2.0,
    keep_alive: Callable | None = None,
) -> AggregateReport

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

PARAMETER	DESCRIPTION
`source`	A path to a file, a file like object, or bytes TYPE: `bytes \| str \| BinaryIO`
`offline`	Do not query online for geolocation or DNS TYPE: `bool` DEFAULT: `False`
`ip_db_path`	Path to a MMDB file from MaxMind or DBIP TYPE: `str \| None` DEFAULT: `None`
`nameservers`	A list of one or more nameservers to use (Cloudflare's public DNS resolvers by default) TYPE: `list[str] \| None` DEFAULT: `None`
`dns_timeout`	Sets the DNS timeout in seconds TYPE: `float` DEFAULT: `2.0`
`keep_alive`	Keep alive function TYPE: `Callable \| None` DEFAULT: `None`

RETURNS	DESCRIPTION
`AggregateReport`	The parsed DMARC aggregate report

parse_aggregate_report_xml 🔗

parse_aggregate_report_xml(
    xml: str,
    ip_db_path: str | None = None,
    offline: bool = False,
    nameservers: list[str] | None = None,
    timeout: float = 2.0,
    keep_alive: Callable | None = None,
) -> AggregateReport

Parses a DMARC XML report string and returns an AggregateReport

PARAMETER	DESCRIPTION
`xml`	A string of DMARC aggregate report XML TYPE: `str`
`ip_db_path`	Path to a MMDB file from MaxMind or DBIP TYPE: `str \| None` DEFAULT: `None`
`offline`	Do not query online for geolocation or DNS TYPE: `bool` DEFAULT: `False`
`nameservers`	A list of one or more nameservers to use (Cloudflare's public DNS resolvers by default) TYPE: `list[str] \| None` DEFAULT: `None`
`timeout`	Sets the DNS timeout in seconds TYPE: `float` DEFAULT: `2.0`
`keep_alive`	Keep alive function TYPE: `Callable \| None` DEFAULT: `None`

RETURNS	DESCRIPTION
`AggregateReport`	The parsed aggregate DMARC report

parse_forensic_report 🔗

parse_forensic_report(
    feedback_report: str,
    sample: str,
    msg_date: datetime,
    offline: bool = False,
    ip_db_path: str | None = None,
    nameservers: list[str] | None = None,
    dns_timeout: float = 2.0,
    strip_attachment_payloads: bool = False,
) -> ForensicReport

Converts a DMARC forensic report and sample to a ForensicReport

PARAMETER	DESCRIPTION
`feedback_report`	A message's feedback report as a string TYPE: `str`
`sample`	The RFC 822 headers or RFC 822 message sample TYPE: `str`
`msg_date`	The message's date header TYPE: `datetime`
`offline`	Do not query online for geolocation or DNS TYPE: `bool` DEFAULT: `False`
`ip_db_path`	Path to a MMDB file from MaxMind or DBIP TYPE: `str \| None` DEFAULT: `None`
`nameservers`	A list of one or more nameservers to use (Cloudflare's public DNS resolvers by default) TYPE: `list` DEFAULT: `None`
`dns_timeout`	Sets the DNS timeout in seconds TYPE: `float` DEFAULT: `2.0`
`strip_attachment_payloads`	Remove attachment payloads from forensic report results TYPE: `bool` DEFAULT: `False`

RETURNS	DESCRIPTION
`ForensicReport`	A parsed report and sample

parse_report_email 🔗

parse_report_email(
    source: bytes | str,
    offline: bool = False,
    ip_db_path: str | None = None,
    nameservers: list[str] | None = None,
    dns_timeout: float = 2.0,
    strip_attachment_payloads: bool = False,
    keep_alive: Callable | None = None,
) -> Report

Parse a DMARC report from an email

PARAMETER	DESCRIPTION
`source`	An emailed DMARC report in RFC 822 format, as bytes or a string TYPE: `bytes \| str`
`offline`	Do not query online for geolocation on DNS TYPE: `bool` DEFAULT: `False`
`ip_db_path`	Path to a MMDB file from MaxMind or DBIP TYPE: `str \| None` DEFAULT: `None`
`nameservers`	A list of one or more nameservers to use TYPE: `list[str] \| None` DEFAULT: `None`
`dns_timeout`	Sets the DNS timeout in seconds TYPE: `float` DEFAULT: `2.0`
`strip_attachment_payloads`	Remove attachment payloads from forensic report results TYPE: `bool` DEFAULT: `False`
`keep_alive`	keep alive function TYPE: `Callable \| None` DEFAULT: `None`

RETURNS	DESCRIPTION
`Report`	report container

parse_report_file 🔗

parse_report_file(
    source: str | bytes | BinaryIO,
    nameservers: list[str] | None = None,
    dns_timeout: float = 2.0,
    strip_attachment_payloads: bool = False,
    ip_db_path: str | None = None,
    offline: bool = False,
    keep_alive: Callable | None = None,
) -> Report

Parse a DMARC aggregate or forensic file at the given path, a file-like object. or bytes

PARAMETER	DESCRIPTION
`source`	A path to a file, a file like object, or bytes TYPE: `str \| bytes \| BinaryIO`
`nameservers`	A list of one or more nameservers to use (Cloudflare's public DNS resolvers by default) TYPE: `list[str] \| None` DEFAULT: `None`
`dns_timeout`	Sets the DNS timeout in seconds TYPE: `float` DEFAULT: `2.0`
`strip_attachment_payloads`	Remove attachment payloads from forensic report results TYPE: `bool` DEFAULT: `False`
`ip_db_path`	Path to a MMDB file from MaxMind or DBIP TYPE: `str \| None` DEFAULT: `None`
`offline`	Do not make online queries for geolocation or DNS TYPE: `bool` DEFAULT: `False`
`keep_alive`	Keep alive function TYPE: `Callable \| None` DEFAULT: `None`

RETURNS	DESCRIPTION
`Report`	The parsed DMARC report

parsed_aggregate_reports_to_csv 🔗

parsed_aggregate_reports_to_csv(
    reports: AggregateReport | list[AggregateReport],
) -> str

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

PARAMETER	DESCRIPTION
`reports`	A parsed aggregate report or list of parsed aggregate reports TYPE: `AggregateReport \| list[AggregateReport]`

RETURNS	DESCRIPTION
`str`	Parsed aggregate report data in flat CSV format, including headers

parsed_aggregate_reports_to_csv_rows 🔗

parsed_aggregate_reports_to_csv_rows(
    reports: AggregateReport | list[AggregateReport],
) -> list[dict[str, str | int | bool]]

Convert one or more parsed aggregate reports to list of dicts in flat CSV format

PARAMETER	DESCRIPTION
`reports`	A parsed aggregate report or list of parsed aggregate reports TYPE: `AggregateReport \| list[AggregateReport]`

RETURNS	DESCRIPTION
`list[dict[str, str \| int \| bool]]`	Parsed aggregate report data as a list of dicts in flat CSV format

parsed_forensic_reports_to_csv 🔗

parsed_forensic_reports_to_csv(
    reports: ForensicReport | list[ForensicReport],
) -> str

Convert one or more parsed forensic reports to flat CSV format, including headers

PARAMETER	DESCRIPTION
`reports`	A parsed forensic report or list of parsed forensic reports TYPE: `ForensicReport \| list[ForensicReport]`

RETURNS	DESCRIPTION
`str`	Parsed forensic report data in flat CSV format, including headers

parsed_forensic_reports_to_csv_rows 🔗

parsed_forensic_reports_to_csv_rows(
    reports: ForensicReport | list[ForensicReport],
) -> list[dict[str, Any]]

Convert one or more parsed forensic reports to a list of dicts in flat CSV format

PARAMETER	DESCRIPTION
`reports`	A parsed forensic report or list of parsed forensic reports TYPE: `ForensicReport \| list[ForensicReport]`

RETURNS	DESCRIPTION
`list[dict[str, Any]]`	Parsed forensic report data as a list of dicts in flat CSV format

save_output 🔗

save_output(
    results: SortedReportContainer,
    output_directory: str = "output",
    aggregate_json_filename: str = "aggregate.json",
    forensic_json_filename: str = "forensic.json",
    aggregate_csv_filename: str = "aggregate.csv",
    forensic_csv_filename: str = "forensic.csv",
) -> None

Save report data in the given directory

PARAMETER	DESCRIPTION
`results`	Parsing results TYPE: `SortedReportContainer`
`output_directory`	The path to the directory to save in TYPE: `str` DEFAULT: `'output'`
`aggregate_json_filename`	Filename for the aggregate JSON file TYPE: `str` DEFAULT: `'aggregate.json'`
`forensic_json_filename`	Filename for the forensic JSON file TYPE: `str` DEFAULT: `'forensic.json'`
`aggregate_csv_filename`	Filename for the aggregate CSV file TYPE: `str` DEFAULT: `'aggregate.csv'`
`forensic_csv_filename`	Filename for the forensic CSV file TYPE: `str` DEFAULT: `'forensic.csv'`

watch_inbox 🔗

watch_inbox(
    mailbox_connection: MailboxConnection,
    callback: Callable,
    reports_folder: str = "INBOX",
    archive_folder: str = "Archive",
    delete: bool = False,
    test: bool = False,
    check_timeout: int = 30,
    ip_db_path: str | None = None,
    offline: bool = False,
    nameservers: list[str] | None = None,
    dns_timeout: float = 6.0,
    strip_attachment_payloads: bool = False,
    batch_size: int | None = None,
) -> None

Watches a mailbox for new messages and sends the results to a callback function

PARAMETER	DESCRIPTION
`mailbox_connection`	The mailbox connection object TYPE: `MailboxConnection`
`callback`	The callback function to receive the parsing results TYPE: `Callable`
`reports_folder`	The IMAP folder where reports can be found TYPE: `str` DEFAULT: `'INBOX'`
`archive_folder`	The folder to move processed mail to TYPE: `str` DEFAULT: `'Archive'`
`delete`	Delete messages after processing them TYPE: `bool` DEFAULT: `False`
`test`	Do not move or delete messages after processing them TYPE: `bool` DEFAULT: `False`
`check_timeout`	Number of seconds to wait for a IMAP IDLE response or the next mail check TYPE: `int` DEFAULT: `30`
`ip_db_path`	Path to a MMDB file from MaxMind or DBIP TYPE: `str \| None` DEFAULT: `None`
`offline`	Do not query online for geolocation or DNS TYPE: `bool` DEFAULT: `False`
`nameservers`	A list of one or more nameservers to use (Cloudflare's public DNS resolvers by default) TYPE: `list[str] \| None` DEFAULT: `None`
`dns_timeout`	Set the DNS query timeout TYPE: `float` DEFAULT: `6.0`
`strip_attachment_payloads`	Replace attachment payloads in forensic report samples with None TYPE: `bool` DEFAULT: `False`
`batch_size`	Number of messages to read and process before saving TYPE: `int \| None` DEFAULT: `None`