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.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: