checkdmarc module

Validates and parses SPF amd DMARC DNS records

exception checkdmarc.BIMIError(msg, data=None)[source]

Bases: Exception

Raised when a fatal BIMI error occurs

exception checkdmarc.BIMIRecordInWrongLocation(msg, data=None)[source]

Bases: checkdmarc.BIMIError

Raised when a BIMI record is found at the root of a domain

exception checkdmarc.BIMIRecordNotFound(error)[source]

Bases: checkdmarc.BIMIError

Raised when a BIMI record could not be found

exception checkdmarc.BIMISyntaxError(msg, data=None)[source]

Bases: checkdmarc.BIMIError

Raised when a BIMI syntax error is found

exception checkdmarc.DMARCError(msg, data=None)[source]

Bases: Exception

Raised when a fatal DMARC error occurs

exception checkdmarc.DMARCRecordInWrongLocation(msg, data=None)[source]

Bases: checkdmarc.DMARCError

Raised when a DMARC record is found at the root of a domain

exception checkdmarc.DMARCRecordNotFound(error)[source]

Bases: checkdmarc.DMARCError

Raised when a DMARC record could not be found

exception checkdmarc.DMARCReportEmailAddressMissingMXRecords(msg, data=None)[source]

Bases: checkdmarc.DMARCError

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

exception checkdmarc.DMARCSyntaxError(msg, data=None)[source]

Bases: checkdmarc.DMARCError

Raised when a DMARC syntax error is found

exception checkdmarc.DNSException(error)[source]

Bases: Exception

Raised when a general DNS error occurs

exception checkdmarc.InvalidBIMIIndicatorURI(msg, data=None)[source]

Bases: checkdmarc.InvalidBIMITagValue

Raised when an invalid BIMI indicator URI is found

exception checkdmarc.InvalidBIMITag(msg, data=None)[source]

Bases: checkdmarc.BIMISyntaxError

Raised when an invalid BIMI tag is found

exception checkdmarc.InvalidBIMITagValue(msg, data=None)[source]

Bases: checkdmarc.BIMISyntaxError

Raised when an invalid BIMI tag value is found

exception checkdmarc.InvalidDMARCReportURI(msg, data=None)[source]

Bases: checkdmarc.InvalidDMARCTagValue

Raised when an invalid DMARC reporting URI is found

exception checkdmarc.InvalidDMARCTag(msg, data=None)[source]

Bases: checkdmarc.DMARCSyntaxError

Raised when an invalid DMARC tag is found

exception checkdmarc.InvalidDMARCTagValue(msg, data=None)[source]

Bases: checkdmarc.DMARCSyntaxError

Raised when an invalid DMARC tag value is found

exception checkdmarc.MultipleBIMIRecords(msg, data=None)[source]

Bases: checkdmarc.BIMIError

Raised when multiple BIMI records are found

exception checkdmarc.MultipleDMARCRecords(msg, data=None)[source]

Bases: checkdmarc.DMARCError

Raised when multiple DMARC records are found, in violation of RFC 7486, section 6.6.3

exception checkdmarc.MultipleSPFRTXTRecords(msg, data=None)[source]

Bases: checkdmarc.SPFError

Raised when multiple TXT spf1 records are found

exception checkdmarc.SMTPError[source]

Bases: Exception

Raised when n SMTP error occurs

exception checkdmarc.SPFError(msg, data=None)[source]

Bases: Exception

Raised when a fatal SPF error occurs

exception checkdmarc.SPFIncludeLoop(msg, data=None)[source]

Bases: checkdmarc.SPFError

Raised when a SPF include loop is detected

exception checkdmarc.SPFRecordFoundWhereBIMIRecordShouldBe(msg, data=None)[source]

Bases: checkdmarc.UnrelatedTXTRecordFoundAtBIMI

Raised when a SPF record is found where a BIMI record should be; most likely, the selector_bimi subdomain record does not actually exist, and the request for TXT records was redirected to the base domain

exception checkdmarc.SPFRecordFoundWhereDMARCRecordShouldBe(msg, data=None)[source]

Bases: checkdmarc.UnrelatedTXTRecordFoundAtDMARC

Raised when a SPF record is found where a DMARC record should be; most likely, the _dmarc subdomain record does not actually exist, and the request for TXT records was redirected to the base domain

exception checkdmarc.SPFRecordNotFound(error)[source]

Bases: checkdmarc.SPFError

Raised when an SPF record could not be found

exception checkdmarc.SPFRedirectLoop(msg, data=None)[source]

Bases: checkdmarc.SPFError

Raised when a SPF redirect loop is detected

exception checkdmarc.SPFSyntaxError(msg, data=None)[source]

Bases: checkdmarc.SPFError

Raised when an SPF syntax error is found

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

Bases: checkdmarc.SPFError

Raised when an SPF record requires too many DNS lookups (10 max)

exception checkdmarc.UnrelatedTXTRecordFoundAtBIMI(msg, data=None)[source]

Bases: checkdmarc.BIMIError

Raised when a TXT record unrelated to BIMI is found

exception checkdmarc.UnrelatedTXTRecordFoundAtDMARC(msg, data=None)[source]

Bases: checkdmarc.DMARCError

Raised when a TXT record unrelated to DMARC is found

exception checkdmarc.UnverifiedDMARCURIDestination(msg, data=None)[source]

Bases: checkdmarc.DMARCError

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

checkdmarc.check_domains(domains, parked=False, approved_nameservers=None, approved_mx_hostnames=None, skip_tls=False, include_dmarc_tag_descriptions=False, nameservers=None, timeout=6.0, wait=0.0)[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

  • (bool (skip_tls) – Skip STARTTLS testing

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

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

  • by default) ((Cloudflare's) –

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

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

Returns

An OrderedDict or list of OrderedDict with the following keys

checkdmarc.check_wildcard_dmarc_report_authorization(domain, nameservers=None, timeout=6.0)[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

  • by default) ((Cloudflare's) –

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

Returns

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

Return type

bool

checkdmarc.get_base_domain(domain, use_fresh_psl=False)[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

  • use_fresh_psl (bool) – Download a fresh Public Suffix List

Returns

The base domain of the given domain

Return type

str

checkdmarc.get_dmarc_record(domain, include_tag_descriptions=False, nameservers=None, timeout=6.0)[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

  • by default) ((Cloudflare's) –

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

Returns

An OrderedDict with the following keys:

Return type

OrderedDict

Raises:

checkdmarc.DMARCRecordNotFound checkdmarc.DMARCRecordInWrongLocation checkdmarc.MultipleDMARCRecords checkdmarc.SPFRecordFoundWhereDMARCRecordShouldBe checkdmarc.UnverifiedDMARCURIDestination checkdmarc.DMARCSyntaxError checkdmarc.InvalidDMARCTag checkdmarc.InvalidDMARCTagValue checkdmarc.InvalidDMARCReportURI checkdmarc.UnverifiedDMARCURIDestination checkdmarc.UnrelatedTXTRecordFound checkdmarc.DMARCReportEmailAddressMissingMXRecords

checkdmarc.get_dmarc_tag_description(tag, value=None)[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 (str) – 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.get_mx_hosts(domain, skip_tls=False, approved_hostnames=None, parked=False, nameservers=None, timeout=6.0)[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

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

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

  • by default) ((Cloudflare's) –

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

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

Return type

OrderedDict

checkdmarc.get_nameservers(domain, approved_nameservers=None, nameservers=None, timeout=6.0)[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 qu+ery

  • by default) ((Cloudflare's) –

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

Returns

A dictionary with the following keys:
  • hostnames - A list of nameserver hostnames

  • warnings - A list of warnings

Return type

Dict

checkdmarc.get_spf_record(domain, nameservers=None, timeout=6.0)[source]

Retrieves and parses an SPF record

Parameters
  • domain (str) – A domain name

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

  • by default) ((Cloudflare's) –

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

Returns

An SPF record parsed by result

Return type

OrderedDict

Raises
checkdmarc.output_to_file(path, content)[source]

Write given content to the given path

Parameters
  • path (str) – A file path

  • content (str) – JSON or CSV text

checkdmarc.parse_dmarc_record(record, domain, parked=False, include_tag_descriptions=False, nameservers=None, timeout=6.0)[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

  • by default) ((Cloudflare's) –

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

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.parse_dmarc_report_uri(uri)[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.InvalidDMARCReportURI

checkdmarc.parse_spf_record(record, domain, parked=False, seen=None, nameservers=None, timeout=6.0)[source]

Parses a 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

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

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

  • by default) ((Cloudflare's) –

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

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.query_bimi_record(domain, selector='default', nameservers=None, timeout=6.0)[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

  • by default) ((Cloudflare's) –

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

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.BIMIRecordNotFound checkdmarc.BIMIRecordInWrongLocation checkdmarc.MultipleBIMIRecords

checkdmarc.query_dmarc_record(domain, nameservers=None, timeout=6.0)[source]

Queries DNS for a DMARC record

Parameters
  • domain (str) – A domain name

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

  • by default) ((Cloudflare's) –

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

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.DMARCRecordNotFound checkdmarc.DMARCRecordInWrongLocation checkdmarc.MultipleDMARCRecords checkdmarc.SPFRecordFoundWhereDMARCRecordShouldBe

checkdmarc.query_spf_record(domain, nameservers=None, timeout=6.0)[source]

Queries DNS for a SPF record

Parameters
  • domain (str) – A domain name

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

  • by default) ((Cloudflare's) –

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

Returns

An OrderedDict with the following keys:
  • record - The SPF record string

  • warnings - A list of warnings

Return type

OrderedDict

Raises

checkdmarc.SPFRecordNotFound

checkdmarc.results_to_csv(results)[source]

Converts a dictionary of results to a CSV string

Parameters

results (dict) – A dictionary of results

Returns

Results in CSV format

Return type

str

checkdmarc.results_to_json(results)[source]

Converts a dictionary of results to a JSON string

Parameters

results (dict) – A dictionary of results

Returns

Results in JSON format

Return type

str

checkdmarc.test_starttls(hostname, ssl_context=None, cache=None)[source]

Attempt to connect to a SMTP server and validate STARTTLS support

Parameters
  • hostname (str) – The hostname

  • cache (ExpiringDict) – Cache storage

  • ssl_context – A SSL context

Returns

STARTTLS supported

Return type

bool

checkdmarc.test_tls(hostname, ssl_context=None, cache=None)[source]

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

Parameters
  • hostname (str) – The hostname

  • cache (ExpiringDict) – Cache storage

  • ssl_context – A SSL context

Returns

TLS supported

Return type

bool

checkdmarc.verify_dmarc_report_destination(source_domain, destination_domain, nameservers=None, timeout=6.0)[source]

Checks if the report destination accepts reports for the source domain per RFC 7489, section 7.1

Parameters
  • source_domain (str) – The source domain

  • destination_domain (str) – The destination domain

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

  • by default) ((Cloudflare's) –

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

Returns

Indicates if the report domain accepts reports from the given domain

Return type

bool

Raises