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 = None, include_tag_descriptions: bool = False, nameservers: list[str] = None, resolver: Resolver = None, timeout: float = 2.0, 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

  • 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) → 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', include_tag_descriptions: bool = False, nameservers: list[str] = None, resolver: Resolver = None, timeout: float = 2.0) → 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

  • 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

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.parse_bimi_record(record: str, include_tag_descriptions: bool = False, syntax_error_marker: str = '➞') → OrderedDict[source]

Parses a BIMI record

Parameters:

  • record (str) – A BIMI 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 BIMI tags

    • value - The BIMI tag value

    • description - A description of the tag/value

  • 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) → 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

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

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) → 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

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, resolver: Resolver = None, timeout: float = 2.0) → 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

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

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) → 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

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.DMARCRecordNotFound checkdmarc.dmarc.DMARCRecordInWrongLocation checkdmarc.dmarc.MultipleDMARCRecords checkdmarc.dmarc.SPFRecordFoundWhereDMARCRecordShouldBe checkdmarc.dmarc.UnverifiedDMARCURIDestination checkdmarc.dmarc.DMARCSyntaxError checkdmarc.dmarc.InvalidDMARCTag checkdmarc.dmarc.InvalidDMARCTagValue checkdmarc.dmarc.InvalidDMARCReportURI checkdmarc.dmarc.UnverifiedDMARCURIDestination checkdmarc.dmarc.UnrelatedTXTRecordFound checkdmarc.dmarc.DMARCReportEmailAddressMissingMXRecords

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, resolver: Resolver = None, timeout: float = 2.0, 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

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

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

  • 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, 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

  • 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, resolver: Resolver = None, timeout: float = 2.0) → bool[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

  • resolver – A resolver object to use for DNS requests

Returns:

Indicates if the report domain accepts reports from the given domain

Return type:

bool

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) → 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

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) → OrderedDict[source]

Downloads a domains MTA-HTS policy

Parameters:

domain (str) – A domain name

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.MTASTSSyntaxError –

  • checkdmarc.mta_sts.InvalidMTASTSTag –

  • checkdmarc.mta_sts.InvalidMTASTSTagValue –

  • checkdmarc.mta_sts.SPFRecordFoundWhereSTSRecordShouldBe –

checkdmarc.mta_sts.query_mta_sts_record(domain: str, nameservers: list[str] = None, resolver: Resolver = None, timeout: float = 2.0) → 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

Returns:

An OrderedDict with the following keys:

  • record - the unparsed MTA-STS record string

  • warnings - warning conditions found

Return type:

OrderedDict

Raises:

checkdmarc.mta_sts.MTASTSRecordNotFound checkdmarc.mta_sts.MTASTSRecordInWrongLocation checkdmarc.mta_sts.MultipleMTASTSRecords

checkdmarc.smtp_tls_reporting

## checkdmarc.smtp

```{eval-rst} .. automodule:: checkdmarc.smtp

members:

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

checkdmarc.spf.check_spf(domain: str, parked: bool = False, nameservers: list[str] = None, resolver: Resolver = None, timeout: float = 2.0) → 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

Returns:

An OrderedDict with the following keys:

  • record - The SPF record string

  • parsed - The parsed SPF record

  • dns_lookups - The number of DNS lookups

  • dns_void_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) → 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

Returns:

An SPF record parsed by result

Return type:

OrderedDict

Raises:

  • checkdmarc.SPFRecordNotFound –

  • checkdmarc.SPFIncludeLoop –

  • checkdmarc.SPFRedirectLoop –

  • checkdmarc.SPFSyntaxError –

  • checkdmarc.SPFTooManyDNSLookups –

checkdmarc.spf.parse_spf_record(record: str, domain: str, parked: bool = False, seen: bool = None, nameservers: list[str] = None, resolver: Resolver = None, recursion: OrderedDict = None, timeout: float = 2.0, 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

  • 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

  • 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.SPFIncludeLoop –

  • checkdmarc.SPFRedirectLoop –

  • checkdmarc.SPFSyntaxError –

  • checkdmarc.SPFTooManyDNSLookups –

checkdmarc.spf.query_spf_record(domain: str, nameservers: list[str] = None, resolver: Resolver = None, timeout: float = 2.0) → OrderedDict[source]

Queries DNS for 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

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) → 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) → 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

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) → 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

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) → 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

Returns:

A list of reverse DNS hostnames

Return type:

list

Raises:

checkdmarc.DNSException –

checkdmarc.utils.get_txt_records(domain: str, nameservers: list[str] = None, resolver: Resolver = None, timeout: float = 2.0) → list[str][source]

Queries DNS for TXT 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 list of TXT records

Return type:

list

Raises:

checkdmarc.DNSException

checkdmarc.utils.query_dns(domain: str, record_type: str, nameservers: list[str] = None, resolver: Resolver = None, timeout: float = 2.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

  • 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

  • cache (ExpiringDict) – Cache storage

Returns:

A list of answers

Return type:

list