checkdmarc module

Validates and parses SPF amd DMARC DNS records

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

Bases: Exception

Parameters

msg (str) – The error message
data (dict) – A dictionary of data to include in the results

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

Bases: BIMIError

Parameters

msg (str) – The error message
data (dict) – A dictionary of data to include in the results

exception checkdmarc.BIMIRecordNotFound(error)[source]

Bases: BIMIError

Parameters

msg (str) – The error message
data (dict) – A dictionary of data to include in the results

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

Bases: BIMIError

Parameters

msg (str) – The error message
data (dict) – A dictionary of data to include in the results

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

Bases: Exception

Parameters

msg (str) – The error message
data (dict) – A dictionary of data to include in the results

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

Bases: DMARCError

Parameters

msg (str) – The error message
data (dict) – A dictionary of data to include in the results

exception checkdmarc.DMARCRecordNotFound(error)[source]

Bases: DMARCError

Parameters

msg (str) – The error message
data (dict) – A dictionary of data to include in the results

exception checkdmarc.DMARCReportEmailAddressMissingMXRecords[source]

Bases: _DMARCWarning

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

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

Bases: DMARCError

Parameters

msg (str) – The error message
data (dict) – A dictionary of data to include in the results

exception checkdmarc.DNSException(error)[source]

Bases: Exception

Raised when a general DNS error occurs

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

Bases: InvalidBIMITagValue

Parameters

msg (str) – The error message
data (dict) – A dictionary of data to include in the results

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

Bases: BIMISyntaxError

Parameters

msg (str) – The error message
data (dict) – A dictionary of data to include in the results

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

Bases: BIMISyntaxError

Parameters

msg (str) – The error message
data (dict) – A dictionary of data to include in the results

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

Bases: InvalidDMARCTagValue

Parameters

msg (str) – The error message
data (dict) – A dictionary of data to include in the results

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

Bases: DMARCSyntaxError

Parameters

msg (str) – The error message
data (dict) – A dictionary of data to include in the results

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

Bases: DMARCSyntaxError

Parameters

msg (str) – The error message
data (dict) – A dictionary of data to include in the results

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

Bases: BIMIError

Parameters

msg (str) – The error message
data (dict) – A dictionary of data to include in the results

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

Bases: DMARCError

Parameters

msg (str) – The error message
data (dict) – A dictionary of data to include in the results

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

Bases: SPFError

Parameters

msg (str) – The error message
data (dict) – A dictionary of data to include in the output

exception checkdmarc.SMTPError[source]

Bases: Exception

Raised when n SMTP error occurs

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

Bases: Exception

Parameters

msg (str) – The error message
data (dict) – A dictionary of data to include in the output

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

Bases: SPFError

Parameters

msg (str) – The error message
data (dict) – A dictionary of data to include in the output

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

Bases: UnrelatedTXTRecordFoundAtBIMI

Parameters

msg (str) – The error message
data (dict) – A dictionary of data to include in the results

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

Bases: UnrelatedTXTRecordFoundAtDMARC

Parameters

msg (str) – The error message
data (dict) – A dictionary of data to include in the results

exception checkdmarc.SPFRecordNotFound(error)[source]

Bases: SPFError

Parameters

msg (str) – The error message
data (dict) – A dictionary of data to include in the output

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

Bases: SPFError

Parameters

msg (str) – The error message
data (dict) – A dictionary of data to include in the output

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

Bases: SPFError

Parameters

msg (str) – The error message
data (dict) – A dictionary of data to include in the output

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

Bases: SPFError

Parameters

msg (str) – The error message
data (dict) – A dictionary of data to include in the output

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

Bases: BIMIError

Parameters

msg (str) – The error message
data (dict) – A dictionary of data to include in the results

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

Bases: DMARCError

Parameters

msg (str) – The error message
data (dict) – A dictionary of data to include in the results

exception checkdmarc.UnverifiedDMARCURIDestination[source]

Bases: _DMARCWarning

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=2.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
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

domain - The domain name
base_domain The base domain
mx - See checkdmarc.get_mx_hosts()
spf - A valid flag, plus the output of checkdmarc.parse_spf_record() or an error
dmarc - A valid flag, plus the output of checkdmarc.parse_dmarc_record() or an error

checkdmarc.check_wildcard_dmarc_report_authorization(domain, nameservers=None, timeout=2.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
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=2.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
timeout (float) – number of seconds to wait for an answer from DNS

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.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=2.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
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=2.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 query
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=2.0)[source]

Retrieves and parses an SPF record

Parameters

domain (str) – A domain name
nameservers (list) – A list of nameservers to query
timeout (float) – Number of seconds to wait for an answer from DNS

Returns

An SPF record parsed by result

Return type

OrderedDict

Raises

checkdmarc.SPFRecordNotFound –
checkdmarc.SPFIncludeLoop –
checkdmarc.SPFRedirectLoop –
checkdmarc.SPFSyntaxError –
checkdmarc.SPFTooManyDNSLookups –

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=2.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
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.DMARCSyntaxError –
checkdmarc.InvalidDMARCTag –
checkdmarc.InvaliddDMARCTagValue –
checkdmarc.InvalidDMARCReportURI –
checkdmarc.UnverifiedDMARCURIDestination –
checkdmarc.UnrelatedTXTRecordFound –
checkdmarc.DMARCReportEmailAddressMissingMXRecords –

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=2.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
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.SPFIncludeLoop –
checkdmarc.SPFRedirectLoop –
checkdmarc.SPFSyntaxError –
checkdmarc.SPFTooManyDNSLookups –

checkdmarc.query_bimi_record(domain, selector='default', nameservers=None, timeout=2.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
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=2.0)[source]

Queries DNS for a DMARC record

Parameters

domain (str) – A domain name
nameservers (list) – A list of nameservers to query
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=2.0)[source]

Queries DNS for a SPF record

Parameters

domain (str) – A domain name
nameservers (list) – A list of nameservers to query
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 CSV

Parameters: results (dict) – A dictionary of results
Returns: A CSV of results
Return type: str

checkdmarc.results_to_csv_rows(results)[source]

Converts a dictionary of results list of CSV row dicts

Parameters: results (dict) – A dictionary of results
Returns: A list of CSV row dicts
Return type: list

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_dnssec(domain, nameservers=None, timeout=2.0)[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

Returns

DNSSEC status

Return type

bool

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=2.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
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

checkdmarc.UnverifiedDMARCURIDestination –
checkdmarc.UnrelatedTXTRecordFound –