API

checkdmarc

Validates and parses email-related DNS records

checkdmarc.check_domains(domains: list[str], *, parked: bool = False, approved_nameservers: list[str] = None, approved_mx_hostnames: bool = None, skip_tls: bool = False, bimi_selector: str = 'default', include_tag_descriptions: bool = False, nameservers: list[str] = None, resolver: Resolver = None, timeout: float = 2.0, timeout_retries: int = 2, wait: float = 0.0) → OrderedDict | list[OrderedDict][source]

Check the given domains for SPF and DMARC records, parse them, and return them

Parameters:

  • domains (list) – A list of domains to check

  • parked (bool) – Indicates that the domains are parked

  • approved_nameservers (list) – A list of approved nameservers

  • approved_mx_hostnames (list) – A list of approved MX hostname

  • skip_tls (bool) – Skip STARTTLS testing

  • bimi_selector (str) – The BIMI selector to test

  • include_tag_descriptions (bool) – Include descriptions of tags and/or tag values in the results

  • nameservers (list) – A list of nameservers to query

  • resolver (dns.resolver.Resolver) – A resolver object to use for DNS requests

  • timeout (float) – number of seconds to wait for an answer from DNS

  • timeout_retries (int) – The number of times to reattempt a query after a timeout

  • wait (float) – number of seconds to wait between processing domains

Returns:

An OrderedDict or list of OrderedDict with the following keys

checkdmarc.check_ns(domain: str, *, approved_nameservers: list[str] = None, nameservers: list[str] = None, resolver: Resolver = None, timeout: float = 2.0, timeout_retries: int = 2) → OrderedDict[source]

Returns a dictionary of nameservers and warnings or a dictionary with an empty list and an error.

Parameters:

  • domain (str) – A domain name

  • approved_nameservers (list) – A list of approved nameserver substrings

  • nameservers (list) – A list of nameservers to query

  • resolver (dns.resolver.Resolver) – A resolver object to use for DNS requests

  • timeout (float) – number of seconds to wait for a record from DNS

Returns:

A dictionary with the following keys:

  • hostnames - A list of nameserver hostnames

  • warnings - A list of warnings

If a DNS error occurs, the dictionary will have the following keys:

  • hostnames - An empty list

  • error - An error message

Return type:

OrderedDict

checkdmarc.output_to_file(path: str, content: str)[source]

Write given content to the given path

Parameters:

  • path (str) – A file path

  • content (str) – JSON or CSV text

checkdmarc.results_to_csv(results: dict) → str[source]

Converts a dictionary of results to CSV

Parameters:

results (dict) – A dictionary of results

Returns:

A CSV of results

Return type:

str

checkdmarc.results_to_csv_rows(results: dict | list[dict]) → list[dict][source]

Converts a results dictionary or list of dictionaries and returns a list of CSV row dictionaries

Parameters:

results (dict) – A dictionary of results

Returns:

A list of CSV row dictionaries

Return type:

list

checkdmarc.results_to_json(results: dict | list[dict]) → str[source]

Converts a dictionary of results or list of results to a JSON string

Parameters:

results (dict) – A dictionary of results

Returns:

Results in JSON format

Return type:

str

checkdmarc.bimi

Brand Indicators for Message Identification (BIMI) record validation

exception checkdmarc.bimi.BIMIError(msg: str, data: dict = None)[source]
Parameters:

  • msg (str) – The error message

  • data (dict) – A dictionary of data to include in the results

exception checkdmarc.bimi.BIMIRecordInWrongLocation(msg: str, data: dict = None)[source]
Parameters:

  • msg (str) – The error message

  • data (dict) – A dictionary of data to include in the results

exception checkdmarc.bimi.BIMIRecordNotFound(error)[source]
Parameters:

  • msg (str) – The error message

  • data (dict) – A dictionary of data to include in the results

exception checkdmarc.bimi.BIMISyntaxError(msg: str, data: dict = None)[source]
Parameters:

  • msg (str) – The error message

  • data (dict) – A dictionary of data to include in the results

exception checkdmarc.bimi.InvalidBIMIIndicatorURI(msg: str, data: dict = None)[source]
Parameters:

  • msg (str) – The error message

  • data (dict) – A dictionary of data to include in the results

exception checkdmarc.bimi.InvalidBIMITag(msg: str, data: dict = None)[source]
Parameters:

  • msg (str) – The error message

  • data (dict) – A dictionary of data to include in the results

exception checkdmarc.bimi.InvalidBIMITagValue(msg: str, data: dict = None)[source]
Parameters:

  • msg (str) – The error message

  • data (dict) – A dictionary of data to include in the results

exception checkdmarc.bimi.MultipleBIMIRecords(msg: str, data: dict = None)[source]
Parameters:

  • msg (str) – The error message

  • data (dict) – A dictionary of data to include in the results

exception checkdmarc.bimi.SPFRecordFoundWhereBIMIRecordShouldBe(msg: str, data: dict = None)[source]
Parameters:

  • msg (str) – The error message

  • data (dict) – A dictionary of data to include in the results

exception checkdmarc.bimi.UnrelatedTXTRecordFoundAtBIMI(msg: str, data: dict = None)[source]
Parameters:

  • msg (str) – The error message

  • data (dict) – A dictionary of data to include in the results

checkdmarc.bimi.check_bimi(domain: str, *, selector: str = 'default', parsed_dmarc_record: dict = None, include_tag_descriptions: bool = False, nameservers: list[str] = None, resolver: Resolver = None, timeout: float = 2.0, timeout_retries: int = 2) → OrderedDict[source]

Returns a dictionary with a parsed BIMI record or an error.

Note

This will attempt to download the files at the URLs provided in the BIMI record and will include a warning if the downloads fail, but the file content is not currently analyzed.

Parameters:

  • domain (str) – A domain name

  • selector (str) – The BIMI selector

  • parsed_dmarc_record (dict) – A parsed DMARC record

  • include_tag_descriptions (bool) – Include descriptions in parsed results

  • nameservers (list) – A list of nameservers to query

  • resolver (dns.resolver.Resolver) – A resolver object to use for DNS requests

  • timeout (float) – number of seconds to wait for an answer from DNS

  • timeout_retries (int) – The number of times to reattempt a query after a timeout

Returns:

An OrderedDict with the following keys:

  • record - The BIMI record string

  • parsed - The parsed BIMI record

  • valid - True

  • warnings - A list of warnings

If a DNS error occurs, the dictionary will have the following keys:

  • error - Tne error message

  • valid - False

Return type:

OrderedDict

checkdmarc.bimi.get_certificate_metadata(pem_crt: bytes, *, domain=None) → OrderedDict[source]

Get metadata about a Verified Mark Certificate (VMC)

checkdmarc.bimi.parse_bimi_record(record: str, *, domain: str = None, parsed_dmarc_record: dict = None, include_tag_descriptions: bool = False, syntax_error_marker: str = '➞', http_timeout: float = 2.0) → OrderedDict[source]

Parses a BIMI record

Parameters:

  • record (str) – A BIMI record

  • domain (str) – The domain where the BIMI record was located

  • parsed_dmarc_record (dict) – A parsed DMARC record

  • include_tag_descriptions (bool) – Include descriptions in parsed results

  • syntax_error_marker (str) – The maker for pointing out syntax errors

  • http_timeout (float) – HTTP timeout in seconds

Returns:

An OrderedDict with the following keys:

  • tags - An OrderedDict of BIMI tags

    • value - The BIMI tag value

    • description - A description of the tag/value

  • image - SVG image metadata, if any

  • certificate - Verified Mark Certificate (VMC metadata), if any

  • warnings - A list of warnings

Note

This will attempt to download the files at the URLs provided in the BIMI record and will include a warning if the downloads fail, but the file content is not currently analyzed.

Note

description is only included if include_tag_descriptions is set to True

Return type:

OrderedDict

Raises:
checkdmarc.bimi.query_bimi_record(domain: str, *, selector: str = 'default', nameservers: list[str] = None, resolver: Resolver = None, timeout: float = 2.0, timeout_retries: int = 2) → OrderedDict[source]

Queries DNS for a BIMI record

Parameters:

  • domain (str) – A domain name

  • selector (str) – The BMI selector

  • nameservers (list) – A list of nameservers to query

  • resolver (dns.resolver.Resolver) – A resolver object to use for DNS requests

  • timeout (float) – number of seconds to wait for a record from DNS

  • timeout_retries (int) – The number of times to reattempt a query after a timeout

Returns:

An OrderedDict with the following keys:

  • record - the unparsed BIMI record string

  • location - the domain where the record was found

  • warnings - warning conditions found

Return type:

OrderedDict

Raises:

checkdmarc.dmarc

DMARC record validation

exception checkdmarc.dmarc.DMARCError(msg: str, data: dict = None)[source]
Parameters:

  • msg (str) – The error message

  • data (dict) – A dictionary of data to include in the results

exception checkdmarc.dmarc.DMARCRecordInWrongLocation(msg: str, data: dict = None)[source]
Parameters:

  • msg (str) – The error message

  • data (dict) – A dictionary of data to include in the results

exception checkdmarc.dmarc.DMARCRecordNotFound(error)[source]

Raised when a DMARC record could not be found

exception checkdmarc.dmarc.DMARCRecordStartsWithWhitespace(msg: str, data: dict = None)[source]
Parameters:

  • msg (str) – The error message

  • data (dict) – A dictionary of data to include in the results

exception checkdmarc.dmarc.DMARCReportEmailAddressMissingMXRecords[source]

Raised when an email address in a DMARC report URI is missing MX records

exception checkdmarc.dmarc.DMARCSyntaxError(msg: str, data: dict = None)[source]
Parameters:

  • msg (str) – The error message

  • data (dict) – A dictionary of data to include in the results

exception checkdmarc.dmarc.InvalidDMARCReportURI(msg: str, data: dict = None)[source]
Parameters:

  • msg (str) – The error message

  • data (dict) – A dictionary of data to include in the results

exception checkdmarc.dmarc.InvalidDMARCTag(msg: str, data: dict = None)[source]
Parameters:

  • msg (str) – The error message

  • data (dict) – A dictionary of data to include in the results

exception checkdmarc.dmarc.InvalidDMARCTagValue(msg: str, data: dict = None)[source]
Parameters:

  • msg (str) – The error message

  • data (dict) – A dictionary of data to include in the results

exception checkdmarc.dmarc.MultipleDMARCRecords(msg: str, data: dict = None)[source]
Parameters:

  • msg (str) – The error message

  • data (dict) – A dictionary of data to include in the results

exception checkdmarc.dmarc.SPFRecordFoundWhereDMARCRecordShouldBe(msg: str, data: dict = None)[source]
Parameters:

  • msg (str) – The error message

  • data (dict) – A dictionary of data to include in the results

exception checkdmarc.dmarc.UnrelatedTXTRecordFoundAtDMARC(msg: str, data: dict = None)[source]
Parameters:

  • msg (str) – The error message

  • data (dict) – A dictionary of data to include in the results

exception checkdmarc.dmarc.UnverifiedDMARCURIDestination[source]

Raised when the destination of a DMARC report URI does not indicate that it accepts reports for the domain

checkdmarc.dmarc.check_dmarc(domain: str, *, parked: bool = False, include_dmarc_tag_descriptions: bool = False, ignore_unrelated_records: bool = False, nameservers: list[str] = None, resolver: Resolver = None, timeout: float = 2.0, timeout_retries: int = 2) → OrderedDict[source]

Returns a dictionary with a parsed DMARC record or an error

Parameters:

  • domain (str) – A domain name

  • parked (bool) – The domain is parked

  • include_dmarc_tag_descriptions (bool) – Include tag descriptions

  • ignore_unrelated_records (bool) – Ignore unrelated TXT records

  • nameservers (list) – A list of nameservers to query

  • resolver (dns.resolver.Resolver) – A resolver object to use for DNS requests

  • timeout (float) – number of seconds to wait for a record from DNS

  • timeout_retries (int) – The number of times to reattempt a query after a timeout

Returns:

An OrderedDict with the following keys:

  • record - the unparsed DMARC record string

  • location - the domain where the record was found

  • warnings - warning conditions found

If a DNS error occurs, the dictionary will have the following keys:

  • error - An error message

  • valid - False

Return type:

OrderedDict

checkdmarc.dmarc.check_wildcard_dmarc_report_authorization(domain: str, *, nameservers: list[str] = None, ignore_unrelated_records: bool = False, resolver: Resolver = None, timeout: float = 2.0, timeout_retries: int = 2) → bool[source]

Checks for a wildcard DMARC report authorization record, e.g.:

*._report.example.com IN TXT "v=DMARC1"
Parameters:

  • domain (str) – The domain to check

  • nameservers (list) – A list of nameservers to query

  • ignore_unrelated_records (bool) – Ignore unrelated TXT records

  • resolver (dns.resolver.Resolver) – A resolver object to use for DNS requests

  • timeout (float) – number of seconds to wait for an answer from DNS

  • timeout_retries (int) – The number of times to reattempt a query after a timeout

Returns:

An indicator of the existence of a valid wildcard DMARC report authorization record

Return type:

bool

checkdmarc.dmarc.get_dmarc_record(domain: str, *, include_tag_descriptions: bool = False, nameservers: list[str] = None, resolver: Resolver = None, timeout: float = 2.0, timeout_retries: int = 2) → OrderedDict[source]

Retrieves a DMARC record for a domain and parses it

Parameters:

  • domain (str) – A domain name

  • include_tag_descriptions (bool) – Include descriptions in parsed results

  • nameservers (list) – A list of nameservers to query

  • resolver (dns.resolver.Resolver) – A resolver object to use for DNS requests

  • timeout (float) – number of seconds to wait for an answer from DNS

  • timeout_retries (int) – The number of times to reattempt a query after a timeout

Returns:

An OrderedDict with the following keys:

  • record - The DMARC record string

  • location - Where the DMARC was found

  • parsed - See checkdmarc.parse_dmarc_record()

Return type:

OrderedDict

Raises:
checkdmarc.dmarc.get_dmarc_tag_description(tag: str, value: str | list[str] = None) → OrderedDict[source]

Get the name, default value, and description for a DMARC tag, amd/or a description for a tag value

Parameters:

  • tag (str) – A DMARC tag

  • value – An optional value

Returns:

An OrderedDict with the following keys:

  • name - the tag name

  • default- the tag’s default value

  • description - A description of the tag or value

Return type:

OrderedDict

checkdmarc.dmarc.parse_dmarc_record(record: str, domain: str, *, parked: bool = False, include_tag_descriptions: bool = False, nameservers: list[str] = None, ignore_unrelated_records: bool = False, resolver: Resolver = None, timeout: float = 2.0, timeout_retries: int = 2, syntax_error_marker: str = '➞') → OrderedDict[source]

Parses a DMARC record

Parameters:

  • record (str) – A DMARC record

  • domain (str) – The domain where the record is found

  • parked (bool) – Indicates if a domain is parked

  • include_tag_descriptions (bool) – Include descriptions in parsed results

  • nameservers (list) – A list of nameservers to query

  • ignore_unrelated_records (bool) – Ignore unrelated TXT records

  • resolver (dns.resolver.Resolver) – A resolver object to use for DNS requests

  • timeout (float) – number of seconds to wait for an answer from DNS

  • timeout_retries (int) – The number of times to reattempt a query after a timeout

  • syntax_error_marker (str) – The maker for pointing out syntax errors

Returns:

An OrderedDict with the following keys:

  • tags - An OrderedDict of DMARC tags

    • value - The DMARC tag value

    • explicit - bool: A value is explicitly set

    • default - The tag’s default value

    • description - A description of the tag/value

  • warnings - A list of warnings

Note

default and description are only included if include_tag_descriptions is set to True

Return type:

OrderedDict

Raises:
checkdmarc.dmarc.parse_dmarc_report_uri(uri: str) → OrderedDict[source]

Parses a DMARC Reporting (i.e. rua/ruf) URI

Note

mailto is the only reporting URI scheme supported in DMARC1

Parameters:

uri – A DMARC URI

Returns:

An OrderedDict of the URI’s components:

  • scheme

  • address

  • size_limit

Return type:

OrderedDict

Raises:

checkdmarc.dmarc.InvalidDMARCReportURI –

checkdmarc.dmarc.query_dmarc_record(domain: str, *, nameservers: list[str] = None, resolver: Resolver = None, timeout: float = 2.0, timeout_retries: int = 2, ignore_unrelated_records: bool = False) → OrderedDict[source]

Queries DNS for a DMARC record

Parameters:

  • domain (str) – A domain name

  • nameservers (list) – A list of nameservers to query

  • resolver (dns.resolver.Resolver) – A resolver object to use for DNS requests

  • timeout (float) – number of seconds to wait for a record from DNS

  • timeout_retries (int) – The number of times to reattempt a query after a timeout

  • ignore_unrelated_records (bool) – Ignore unrelated TXT records

Returns:

An OrderedDict with the following keys:

  • record - the unparsed DMARC record string

  • location - the domain where the record was found

  • warnings - warning conditions found

Return type:

OrderedDict

Raises:

checkdmarc.dmarc.DMARCRecordNotFound checkdmarc.dmarc.DMARCRecordInWrongLocation checkdmarc.dmarc.MultipleDMARCRecords checkdmarc.dmarc.SPFRecordFoundWhereDMARCRecordShouldBe

checkdmarc.dmarc.verify_dmarc_report_destination(source_domain: str, destination_domain: str, *, nameservers: list[str] = None, ignore_unrelated_records: bool = False, resolver: Resolver = None, timeout: float = 2.0, timeout_retries: int = 2) → None[source]

Checks if the report destination accepts reports for the source domain per RFC 7489, § 7.1. Raises checkdmarc.dmarc.UnverifiedDMARCURIDestination if it doesn’t accept.

Parameters:

  • source_domain (str) – The source domain

  • destination_domain (str) – The destination domain

  • nameservers (list) – A list of nameservers to query

  • ignore_unrelated_records (bool) – Ignore unrelated TXT records

  • resolver (dns.resolver.Resolver) – A resolver object to use for DNS requests

  • timeout (float) – number of seconds to wait for an answer from DNS

  • timeout_retries (int) – The number of times to reattempt a query after a timeout

Raises:

checkdmarc.dnssec

DNSSEC tests

checkdmarc.dnssec.get_dnskey(domain: str, *, nameservers: list[str] = None, timeout: float = 2.0, cache: ExpiringDict = None)[source]

Get a DNSKEY RRSet on the given domain

Parameters:

  • domain (str) – The domain to check

  • nameservers (list) – A list of nameservers to query

  • timeout (float) – Timeout in seconds

  • cache (ExpiringDict) – A cache

Returns:

A DNSKEY dictionary

checkdmarc.dnssec.get_tlsa_records(hostname: str, *, nameservers: list[str] = None, timeout: float = 2.0, port: int = 25, protocol: str = 'tcp', cache: ExpiringDict = None) → list[str][source]

Checks for TLSA records on the given hostname

Parameters:

  • hostname (str) – The domain to check

  • nameservers (list) – A list of nameservers to query

  • timeout (float) – Timeout in seconds

  • port (int) – The port

  • protocol (str) – The protocol

  • cache (ExpiringDict) – A cache

Returns:

A list of TLSA records

Return type:

list

checkdmarc.dnssec.test_dnssec(domain: str, *, nameservers: list[str] = None, timeout: float = 2.0, cache: ExpiringDict = None) → bool[source]

Check for DNSSEC on the given domain

Parameters:

  • domain (str) – The domain to check

  • nameservers (list) – A list of nameservers to query

  • timeout (float) – Timeout in seconds

  • cache (ExpiringDict) – Cache

Returns:

DNSSEC status

Return type:

bool

checkdmarc.mta_sts

SMTP MTA Strict Transport Security (MTA-STS) validation

exception checkdmarc.mta_sts.InvalidMTASTSTag(msg: str, data: dict = None)[source]
Parameters:

  • msg (str) – The error message

  • data (dict) – A dictionary of data to include in the results

exception checkdmarc.mta_sts.InvalidSTSTagValue(msg: str, data: dict = None)[source]
Parameters:

  • msg (str) – The error message

  • data (dict) – A dictionary of data to include in the results

exception checkdmarc.mta_sts.MTASTSError(msg: str, data: dict = None)[source]
Parameters:

  • msg (str) – The error message

  • data (dict) – A dictionary of data to include in the results

exception checkdmarc.mta_sts.MTASTSPolicyDownloadError(msg: str, data: dict = None)[source]
Parameters:

  • msg (str) – The error message

  • data (dict) – A dictionary of data to include in the results

exception checkdmarc.mta_sts.MTASTSPolicyError(msg: str, data: dict = None)[source]
Parameters:

  • msg (str) – The error message

  • data (dict) – A dictionary of data to include in the results

exception checkdmarc.mta_sts.MTASTSPolicySyntaxError(msg: str, data: dict = None)[source]
Parameters:

  • msg (str) – The error message

  • data (dict) – A dictionary of data to include in the results

exception checkdmarc.mta_sts.MTASTSRecordInWrongLocation(msg: str, data: dict = None)[source]
Parameters:

  • msg (str) – The error message

  • data (dict) – A dictionary of data to include in the results

exception checkdmarc.mta_sts.MTASTSRecordNotFound(error)[source]
Parameters:

  • msg (str) – The error message

  • data (dict) – A dictionary of data to include in the results

exception checkdmarc.mta_sts.MTASTSRecordSyntaxError(msg: str, data: dict = None)[source]
Parameters:

  • msg (str) – The error message

  • data (dict) – A dictionary of data to include in the results

exception checkdmarc.mta_sts.MultipleMTASTSRecords(msg: str, data: dict = None)[source]
Parameters:

  • msg (str) – The error message

  • data (dict) – A dictionary of data to include in the results

exception checkdmarc.mta_sts.SPFRecordFoundWhereMTASTSRecordShouldBe(msg: str, data: dict = None)[source]
Parameters:

  • msg (str) – The error message

  • data (dict) – A dictionary of data to include in the results

exception checkdmarc.mta_sts.UnrelatedTXTRecordFoundAtMTASTS(msg: str, data: dict = None)[source]
Parameters:

  • msg (str) – The error message

  • data (dict) – A dictionary of data to include in the results

checkdmarc.mta_sts.check_mta_sts(domain: str, *, nameservers: list[str] = None, resolver: Resolver = None, timeout: float = 2.0, timeout_retries: int = 2) → OrderedDict[source]

Returns a dictionary with a parsed MTA-STS policy or an error.

Parameters:

  • domain (str) – A domain name

  • nameservers (list) – A list of nameservers to query

  • resolver (dns.resolver.Resolver) – A resolver object to use for DNS requests

  • timeout (float) – number of seconds to wait for an answer from DNS

  • timeout_retries (int) – The number of times to reattempt a query after a timeout

Returns:

An OrderedDict with the following keys:

  • id - The SIS-MTA DNS record ID

  • policy - The parsed MTA-STS policy

  • valid - True

  • warnings - A list of warnings

If an error occurs, the dictionary will have the following keys:

  • error - Tne error message

  • valid - False

Return type:

OrderedDict

checkdmarc.mta_sts.download_mta_sts_policy(domain: str, *, http_timeout: float = 2.0) → OrderedDict[source]

Downloads a domains MTA-HTS policy

Parameters:

  • domain (str) – A domain name

  • http_timeout (float) – HTTP timeout in seconds

Returns:

An OrderedDict with the following keys:

  • policy - The unparsed policy string

  • warnings - A list of any warning conditions found

Return type:

OrderedDict

Raises:

checkdmarc.mta_sts.MTASTSPolicyDownloadError –

checkdmarc.mta_sts.mx_in_mta_sts_patterns(mx_hostname: str, mta_sts_mx_patterns: list[str]) → bool[source]

Tests is a given MX hostname is covered by a given list of MX patterns from an MTA-STS policy:

Parameters:

  • mx_hostname (str) – The MX hostname to test

  • mta_sts_mx_patterns (str) – The list of MTA-STS MX patterns

Returns: True if the MX hostname is included, false if not

checkdmarc.mta_sts.parse_mta_sts_policy(policy: str) → OrderedDict[source]

Parses an MTA-STS policy

Parameters:

policy – The policy

Raises:

checkdmarc.mta_sts.MTASTSPolicySyntaxError –

checkdmarc.mta_sts.parse_mta_sts_record(record: str, *, include_tag_descriptions: bool = False, syntax_error_marker: str = '➞') → OrderedDict[source]

Parses an MTA-STS record

Parameters:

  • record (str) – A MTA-STS record

  • include_tag_descriptions (bool) – Include descriptions in parsed results

  • syntax_error_marker (str) – The maker for pointing out syntax errors

Returns:

An OrderedDict with the following keys:

  • tags - An OrderedDict of MTA-STS tags

    • value - The MTA-STS tag value

    • description - A description of the tag/value

  • warnings - A list of warnings

Note

description is only included if include_tag_descriptions is set to True

Return type:

OrderedDict

Raises:
checkdmarc.mta_sts.query_mta_sts_record(domain: str, *, nameservers: list[str] = None, resolver: Resolver = None, timeout: float = 2.0, timeout_retries: int = 2) → OrderedDict[source]

Queries DNS for an MTA-STS record

Parameters:

  • domain (str) – A domain name

  • nameservers (list) – A list of nameservers to query

  • resolver (dns.resolver.Resolver) – A resolver object to use for DNS requests

  • timeout (float) – number of seconds to wait for a record from DNS

  • timeout_retries (int) – The number of times to reattempt a query after a timeout

Returns:

An OrderedDict with the following keys:

  • record - the unparsed MTA-STS record string

  • warnings - warning conditions found

Return type:

OrderedDict

Raises:

checkdmarc.smtp_tls_reporting

SMTP TLS Reporting

exception checkdmarc.smtp_tls_reporting.InvalidSMTPTLSReportingTag(msg: str, data: dict = None)[source]
Parameters:

  • msg (str) – The error message

  • data (dict) – A dictionary of data to include in the results

exception checkdmarc.smtp_tls_reporting.InvalidSMTPTLSReportingTagValue(msg: str, data: dict = None)[source]
Parameters:

  • msg (str) – The error message

  • data (dict) – A dictionary of data to include in the results

exception checkdmarc.smtp_tls_reporting.MultipleSMTPTLSReportingRecords(msg: str, data: dict = None)[source]
Parameters:

  • msg (str) – The error message

  • data (dict) – A dictionary of data to include in the results

exception checkdmarc.smtp_tls_reporting.SMTPTLSReportingError(msg: str, data: dict = None)[source]
Parameters:

  • msg (str) – The error message

  • data (dict) – A dictionary of data to include in the results

exception checkdmarc.smtp_tls_reporting.SMTPTLSReportingRecordInWrongLocation(msg: str, data: dict = None)[source]
Parameters:

  • msg (str) – The error message

  • data (dict) – A dictionary of data to include in the results

exception checkdmarc.smtp_tls_reporting.SMTPTLSReportingRecordNotFound(error)[source]
Parameters:

  • msg (str) – The error message

  • data (dict) – A dictionary of data to include in the results

exception checkdmarc.smtp_tls_reporting.SMTPTLSReportingSyntaxError(msg: str, data: dict = None)[source]
Parameters:

  • msg (str) – The error message

  • data (dict) – A dictionary of data to include in the results

exception checkdmarc.smtp_tls_reporting.SPFRecordFoundWhereTLSRPTShouldBe(msg: str, data: dict = None)[source]
Parameters:

  • msg (str) – The error message

  • data (dict) – A dictionary of data to include in the results

exception checkdmarc.smtp_tls_reporting.UnrelatedTXTRecordFoundAtTLSRPT(msg: str, data: dict = None)[source]
Parameters:

  • msg (str) – The error message

  • data (dict) – A dictionary of data to include in the results

checkdmarc.smtp_tls_reporting.check_smtp_tls_reporting(domain: str, *, nameservers: list[str] = None, resolver: Resolver = None, timeout: float = 2.0, timeout_retries: int = 2) → OrderedDict[source]

Returns a dictionary with a parsed SMTP-TLS Reporting policy or an error.

Parameters:

  • domain (str) – A domain name

  • nameservers (list) – A list of nameservers to query

  • resolver (dns.resolver.Resolver) – A resolver object to use for DNS requests

  • timeout (float) – number of seconds to wait for an answer from DNS

  • timeout_retries (int) – The number of times to reattempt a query after a timeout

Returns:

An OrderedDict with the following keys:

  • valid - True tags - A dictionary of tags and values

  • warnings - A list of warnings

If an error occurs, the dictionary will have the following keys:

  • error - Tne error message

  • valid - False

Return type:

OrderedDict

checkdmarc.smtp_tls_reporting.parse_smtp_tls_reporting_record(record: str, *, include_tag_descriptions: bool = False, syntax_error_marker: str = '➞') → OrderedDict[source]

Parses an SMTP TLS Reporting record

Parameters:

  • record (str) – A SMTP TLS Reporting record

  • include_tag_descriptions (bool) – Include descriptions in parsed results

  • syntax_error_marker (str) – The maker for pointing out syntax errors

Returns:

An OrderedDict with the following keys:

  • tags - An OrderedDict of SMTP TLS Reporting tags

    • value - The SMTP TLS Reporting tag value

    • description - A description of the tag/value

  • warnings - A list of warnings

Note

description is only included if include_tag_descriptions is set to True

Return type:

OrderedDict

Raises:
checkdmarc.smtp_tls_reporting.query_smtp_tls_reporting_record(domain: str, *, nameservers: list[str] = None, resolver: Resolver = None, timeout: float = 2.0, timeout_retries: int = 2) → OrderedDict[source]

Queries DNS for an SMTP TLS Reporting record

Parameters:

  • domain (str) – A domain name

  • nameservers (list) – A list of nameservers to query

  • resolver (dns.resolver.Resolver) – A resolver object to use for DNS requests

  • timeout (float) – number of seconds to wait for a record from DNS

  • timeout_retries (int) – The number of times to reattempt a query after a timeout

Returns:

An OrderedDict with the following keys:

  • record - the unparsed SMTP TLS Reporting record

  • warnings - warning conditions found

Return type:

OrderedDict

Raises:

checkdmarc.smtp

SMTP tests

exception checkdmarc.smtp.SMTPError[source]

Raised when SMTP error occurs

checkdmarc.smtp.check_mx(domain: str, *, approved_mx_hostnames: list[str] = None, mta_sts_mx_patterns: list[str] = None, skip_tls: bool = False, nameservers: list[str] = None, resolver: Resolver = None, timeout: float = 2.0, timeout_retries: int = 2) → OrderedDict[source]

Gets MX hostname and their addresses, or an empty list of hosts and an error if a DNS error occurs

Parameters:

  • domain (str) – A domain name

  • skip_tls (bool) – Skip STARTTLS testing

  • approved_mx_hostnames (list) – A list of approved MX hostname substrings

  • mta_sts_mx_patterns (list) – A list of MX patterns from MTA-STS

  • nameservers (list) – A list of nameservers to query

  • resolver (dns.resolver.Resolver) – A resolver object to use for DNS requests

  • timeout (float) – number of seconds to wait for a record from DNS

  • timeout_retries (int) – The number of times to reattempt a query after a timeout

Returns:

An OrderedDict with the following keys:

  • hosts - A list of OrderedDict with keys of

    • hostname - A hostname

    • addresses - A list of IP addresses

  • warnings - A list of MX resolution warnings

If a DNS error occurs, the dictionary will have the following keys:

  • hosts - An empty list

  • error - An error message

Return type:

OrderedDict

checkdmarc.smtp.get_mx_hosts(domain: str, *, skip_tls: bool = False, approved_hostnames: list[str] = None, mta_sts_mx_patterns: list[str] = None, parked: bool = False, nameservers: list[str] = None, resolver: Resolver = None, timeout: float = 2.0, timeout_retries: int = 2)[source]

Gets MX hostname and their addresses

Parameters:

  • domain (str) – A domain name

  • skip_tls (bool) – Skip STARTTLS testing

  • approved_hostnames (list) – A list of approved MX hostname substrings

  • mta_sts_mx_patterns (list) – A list of MX patterns from MTA-STS

  • parked (bool) – Indicates that the domains are parked

  • nameservers (list) – A list of nameservers to query

  • resolver (dns.resolver.Resolver) – A resolver object to use for DNS requests

  • timeout (float) – number of seconds to wait for a record from DNS

Returns:

An OrderedDict with the following keys:

  • hosts - A list of OrderedDict with keys of

    • hostname - A hostname

    • dnssec - DNSSEC status

    • addresses - A list of IP addresses

    • tlsa - A list of TLSA records, if they exist

  • warnings - A list of MX resolution warnings

Return type:

OrderedDict

checkdmarc.smtp.test_starttls(hostname: str, *, ssl_context: SSLContext = None, cache: ExpiringDict = None) → bool[source]

Attempt to connect to an SMTP server and validate STARTTLS support

Parameters:

  • hostname (str) – The hostname

  • cache (ExpiringDict) – Cache storage

  • ssl_context – A SSL context

Returns:

True if STARTTLS supported

Return type:

bool

Raises:

checkdmarc.smtp.SMTPError – SMTP connection failed

checkdmarc.smtp.test_tls(hostname: str, *, ssl_context: SSLContext = None, cache: ExpiringDict = None) → bool[source]

Attempt to connect to an SMTP server port 465 and validate TLS/SSL support

Parameters:

  • hostname (str) – The hostname

  • cache (ExpiringDict) – Cache storage

  • ssl_context (SSLContext) – A SSL context

Returns:

True if TLS supported

Return type:

bool

Raises:

checkdmarc.smtp.SMTPError – SMTP connection failed

checkdmarc.soa

checkdmarc.soa.check_soa(domain: str, *, nameservers: List[str] = None, resolver: Resolver = None, timeout: float = 2.0, timeout_retries: int = 2) → OrderedDict[source]

Returns a dictionary of a domain’s SOA record and a parsed version of the record or a dictionary with an the record and an error.

Parameters:

  • domain (str) – A domain name

  • nameservers (list) – A list of nameservers to query

  • resolver (dns.resolver.Resolver) – A resolver object to use for DNS requests

  • timeout (float) – number of seconds to wait for a record from DNS

  • timeout_retries (int) – The number of times to reattempt a query after a timeout

Returns:

A dictionary with the following keys:

  • record - The SOA record as a string

  • values - A parsed version of the SOA record

If a parsing error occurs, the dictionary will have the following keys:

  • record - the SOA record

  • error - An error message

Return type:

OrderedDict

checkdmarc.soa.parse_soa_string(rr: str) → OrderedDict[source]

Parses a raw SOA record string and returns an OrderedDict with validated fields.

checkdmarc.soa.soa_rname_to_email(rname: str) → str[source]

Converts a SOA RNAME domain-style name into an RFC 822 email address.

checkdmarc.spf

Sender Policy framework (SPF) record validation

exception checkdmarc.spf.MultipleSPFRTXTRecords(msg: str, data: dict = None)[source]
Parameters:

  • msg (str) – The error message

  • data (dict) – A dictionary of data to include in the output

exception checkdmarc.spf.SPFError(msg: str, data: dict = None)[source]
Parameters:

  • msg (str) – The error message

  • data (dict) – A dictionary of data to include in the output

exception checkdmarc.spf.SPFIncludeLoop(msg: str, data: dict = None)[source]
Parameters:

  • msg (str) – The error message

  • data (dict) – A dictionary of data to include in the output

exception checkdmarc.spf.SPFRecordNotFound(error, domain)[source]
Parameters:

  • msg (str) – The error message

  • data (dict) – A dictionary of data to include in the output

exception checkdmarc.spf.SPFRedirectLoop(msg: str, data: dict = None)[source]
Parameters:

  • msg (str) – The error message

  • data (dict) – A dictionary of data to include in the output

exception checkdmarc.spf.SPFSyntaxError(msg: str, data: dict = None)[source]
Parameters:

  • msg (str) – The error message

  • data (dict) – A dictionary of data to include in the output

exception checkdmarc.spf.SPFTooManyDNSLookups(*args, **kwargs)[source]
Parameters:

  • msg (str) – The error message

  • data (dict) – A dictionary of data to include in the output

exception checkdmarc.spf.SPFTooManyVoidDNSLookups(*args, **kwargs)[source]
Parameters:

  • msg (str) – The error message

  • data (dict) – A dictionary of data to include in the output

exception checkdmarc.spf.UndecodableCharactersInTXTRecord[source]

Raised when a TXT record contains one or more undecodable characters

checkdmarc.spf.check_spf(domain: str, *, parked: bool = False, nameservers: list[str] = None, resolver: Resolver = None, timeout: float = 2.0, timeout_retries: int = 2) → OrderedDict[source]

Returns a dictionary with a parsed SPF record or an error.

Parameters:

  • domain (str) – A domain name

  • parked (bool) – The domain is parked

  • nameservers (list) – A list of nameservers to query

  • resolver (dns.resolver.Resolver) – A resolver object to use for DNS requests

  • timeout (float) – number of seconds to wait for an answer from DNS

  • timeout_retries (int) – The number of times to reattempt a query after a timeout

Returns:

An OrderedDict with the following keys:

  • record - The SPF record string

  • parsed - The parsed SPF record

  • dns_lookups - The number of DNS lookups

  • void_dns_lookups - The number of void DNS lookups

  • valid - True

  • warnings - A list of warnings

If a DNS error occurs, the dictionary will have the following keys:

  • error - Tne error message

  • valid - False

Return type:

OrderedDict

checkdmarc.spf.get_spf_record(domain: str, *, nameservers: list[str] = None, resolver: Resolver = None, timeout: float = 2.0, timeout_retries: int = 2) → OrderedDict[source]

Retrieves and parses an SPF record

Parameters:

  • domain (str) – A domain name

  • nameservers (list) – A list of nameservers to query

  • resolver (dns.resolver.Resolver) – A resolver object to use for DNS requests

  • timeout (float) – Number of seconds to wait for an answer from DNS

  • timeout_retries (int) – The number of times to reattempt a query after a timeout

Returns:

An SPF record parsed by result

Return type:

OrderedDict

Raises:
checkdmarc.spf.parse_spf_record(record: str, domain: str, *, ignore_too_many_lookups: bool = False, parked: bool = False, seen: bool = None, nameservers: list[str] = None, resolver: Resolver = None, recursion: OrderedDict = None, timeout: float = 2.0, timeout_retries: int = 2, syntax_error_marker: str = '➞') → OrderedDict[source]

Parses an SPF record, including resolving a, mx, and include mechanisms

Parameters:

  • record (str) – An SPF record

  • domain (str) – The domain that the SPF record came from

  • parked (bool) – indicated if a domain has been parked

  • ignore_too_many_lookups (bool) – Do not raise an exception for too many lookups

  • seen (list) – A list of domains seen in past loops

  • nameservers (list) – A list of nameservers to query

  • resolver (dns.resolver.Resolver) – A resolver object to use for DNS requests

  • recursion (OrderedDict) – Results from a previous call

  • timeout (float) – number of seconds to wait for an answer from DNS

  • timeout_retries (int) – The number of times to reattempt a query after a timeout

  • syntax_error_marker (str) – The maker for pointing out syntax errors

Returns:

An OrderedDict with the following keys:

  • dns_lookups - Number of DNS lookups required by the record

  • parsed - An OrderedDict of a parsed SPF record values

  • warnings - A list of warnings

Return type:

OrderedDict

Raises:
checkdmarc.spf.query_spf_record(domain: str, *, nameservers: list[str] = None, quoted_txt_segments: bool = False, resolver: Resolver = None, timeout: float = 2.0, timeout_retries: int = 2) → OrderedDict[source]

Queries DNS for an SPF record

Parameters:

  • domain (str) – A domain name

  • quoted_txt_segments (bool) – Retain quotes around TXT segments

  • nameservers (list) – A list of nameservers to query

  • resolver (dns.resolver.Resolver) – A resolver object to use for DNS requests

  • timeout (float) – number of seconds to wait for an answer from DNS

  • timeout_retries (int) – The number of times to reattempt a query after a timeout

Returns:

An OrderedDict with the following keys:

  • record - The SPF record string

  • warnings - A list of warnings

Return type:

OrderedDict

Raises:

checkdmarc.SPFRecordNotFound –

checkdmarc.utils

DNS utility functions

exception checkdmarc.utils.DNSException(error)[source]

Raised when a general DNS error occurs

exception checkdmarc.utils.DNSExceptionNXDOMAIN(error)[source]

Raised when a NXDOMAIN DNS error (RCODE:3) occurs

checkdmarc.utils.get_a_records(domain: str, *, nameservers: list[str] = None, resolver: Resolver = None, timeout: float = 2.0, timeout_retries: int = 2) → list[str][source]

Queries DNS for A and AAAA records

Parameters:

  • domain (str) – A domain name

  • nameservers (list) – A list of nameservers to query

  • resolver (dns.resolver.Resolver) – A resolver object to use for DNS requests

  • timeout (float) – number of seconds to wait for an answer from DNS

Returns:

A sorted list of IPv4 and IPv6 addresses

Return type:

list

Raises:

checkdmarc.DNSException –

checkdmarc.utils.get_base_domain(domain: str) → str[source]

Gets the base domain name for the given domain

Note

Results are based on a list of public domain suffixes at https://publicsuffix.org/list/public_suffix_list.dat.

Parameters:

domain (str) – A domain or subdomain

Returns:

The base domain of the given domain

Return type:

str

checkdmarc.utils.get_mx_records(domain: str, *, nameservers: list[str] = None, resolver: Resolver = None, timeout: float = 2.0, timeout_retries: int = 2) → list[OrderedDict][source]

Queries DNS for a list of Mail Exchange hosts

Parameters:

  • domain (str) – A domain name

  • nameservers (list) – A list of nameservers to query

  • resolver (dns.resolver.Resolver) – A resolver object to use for DNS requests

  • timeout (float) – number of seconds to wait for an answer from DNS

  • timeout_retries (int) – The number of times to reattempt a query after a timeout

Returns:

A list of OrderedDicts; each containing a preference

integer and a hostname

Return type:

list

Raises:

checkdmarc.DNSException –

checkdmarc.utils.get_nameservers(domain: str, *, approved_nameservers: list[str] = None, nameservers: list[str] = None, resolver: Resolver = None, timeout: float = 2.0, timeout_retries: int = 2) → dict[source]

Gets a list of nameservers for a given domain

Parameters:

  • domain (str) – A domain name

  • approved_nameservers (list) – A list of approved nameserver substrings

  • nameservers (list) – A list of nameservers to query

  • resolver (dns.resolver.Resolver) – A resolver object to use for DNS requests

  • timeout (float) – number of seconds to wait for a record from DNS

  • timeout_retries (int) – The number of times to reattempt a query after a timeout

Returns:

A dictionary with the following keys:

  • hostnames - A list of nameserver hostnames

  • warnings - A list of warnings

Return type:

OrderedDict

checkdmarc.utils.get_reverse_dns(ip_address: str, *, nameservers: list[str] = None, resolver: Resolver = None, timeout: float = 2.0, timeout_retries: int = 2) → list[str][source]

Queries for an IP addresses reverse DNS hostname(s)

Parameters:

  • ip_address (str) – An IPv4 or IPv6 address

  • nameservers (list) – A list of nameservers to query

  • resolver (dns.resolver.Resolver) – A resolver object to use for DNS requests

  • timeout (float) – number of seconds to wait for an answer from DNS

  • timeout_retries (int) – The number of times to reattempt a query after a timeout

Returns:

A list of reverse DNS hostnames

Return type:

list

Raises:

checkdmarc.DNSException –

checkdmarc.utils.get_soa_record(domain: str, *, nameservers: list[str] = None, resolver: Resolver = None, timeout: float = 2.0, timeout_retries: int = 2) → list[str][source]

Queries DNS for an SOA record

Parameters:

  • domain (str) – A domain name

  • nameservers (list) – A list of nameservers to query

  • resolver (dns.resolver.Resolver) – A resolver object to use for DNS requests

  • timeout (float) – number of seconds to wait for an answer from DNS

  • timeout_retries (int) – The number of times to reattempt a query after a timeout

Returns:

An SOA record

Return type:

str

Raises:

checkdmarc.DNSException –

checkdmarc.utils.get_txt_records(domain: str, *, nameservers: list[str] = None, quoted_txt_segments: bool = False, resolver: Resolver = None, timeout: float = 2.0, timeout_retries: int = 2) → list[str][source]

Queries DNS for TXT records

Parameters:

  • domain (str) – A domain name

  • quoted_txt_segments (bool) – Preserve quotes in TXT records

  • nameservers (list) – A list of nameservers to query

  • resolver (dns.resolver.Resolver) – A resolver object to use for DNS requests

  • timeout (float) – number of seconds to wait for an answer from DNS

  • timeout_retries (int) – The number of times to reattempt a query after a timeout

Returns:

A list of TXT records

Return type:

list

Raises:

checkdmarc.DNSException –

checkdmarc.utils.normalize_domain(domain: str) → str[source]

Normalize an input domain by removing zero-width characters and lowering it

Parameters:

domain (str) – A domain or subdomain

Returns:

A normalized domain

Return type:

str

checkdmarc.utils.query_dns(domain: str, record_type: str, *, quoted_txt_segments: bool = False, nameservers: list[str] = None, resolver: Resolver = None, timeout: float = 2.0, timeout_retries: int = 2, _attempt: int = 0, cache: ExpiringDict = None) → list[str][source]

Queries DNS

Parameters:

  • domain (str) – The domain or subdomain to query about

  • record_type (str) – The record type to query for

  • quoted_txt_segments (bool) – Preserve quotes in TXT records

  • nameservers (list) – A list of one or more nameservers to use

  • resolver (dns.resolver.Resolver) – A resolver object to use for DNS requests

  • timeout (float) – Sets the DNS timeout in seconds

  • timeout_retries (int) – The number of times to reattempt a query after a timeout

  • cache (ExpiringDict) – Cache storage

Returns:

A list of answers

Return type:

list