Prepare customer DNS for an Outbound Filtering migration

cat > domains.txt <<'EOF'
example.com
example.net
mail.example.org
EOF

cat > provider-nameservers.txt <<'EOF'
ns1.hosting-provider.example
ns2.hosting-provider.example
EOF

python3 -m venv .spf-audit-venv
. .spf-audit-venv/bin/activate
python3 -m pip install 'dnspython>=2.6,<3'

cat > spf-audit.py <<'PY'
import csv
import ipaddress
from pathlib import Path
import re
import sys

import dns.exception
import dns.name
import dns.resolver


def read_names(path):
    names = set()
    for line in Path(path).read_text(encoding="utf-8-sig").splitlines():
        name = line.split("#", 1)[0].strip().rstrip(".")
        if not name:
            continue
        name = name.encode("idna").decode("ascii").lower()
        if len(name) > 253 or any(
            not re.fullmatch(r"[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?", label)
            for label in name.split(".")
        ):
            raise ValueError(f"Invalid domain in {path}: {name}")
        names.add(name)
    return sorted(names)


def classify(records):
    if not records:
        return "optional", "No SPF record"
    if len(records) != 1:
        return "review", "Multiple SPF records"
    if any(c.isspace() and c != " " for c in records[0]):
        return "review", "Invalid SPF whitespace"
    terms = records[0].lower().split()[1:]
    # Recognize common literal syntax; send complex policies for review.
    host = r"[a-z0-9_](?:[a-z0-9_.-]*[a-z0-9])?\.?"
    for term in terms:
        body = term[1:] if term[:1] in "+-~?" else term
        if body.startswith(("ip4:", "ip6:")):
            try:
                network = ipaddress.ip_network(body[4:], strict=False)
                if network.version != int(body[2]):
                    raise ValueError("IP version mismatch")
            except ValueError:
                return "review", "Invalid IP mechanism"
        elif not re.fullmatch(rf"(?:all|a|mx|include:{host})", body):
            return "review", "Redirect, macro, or syntax requiring review"
    all_terms = [t for t in terms if t.lstrip("+-~?") == "all"]
    if len(all_terms) > 1:
        return "review", "Multiple all mechanisms"
    end = terms.index(all_terms[0]) if all_terms else len(terms)
    active = terms[:end]
    if any(t.startswith(("-", "~", "?")) for t in active):
        return "review", "Qualified mechanism needs evaluation"
    if all_terms and all_terms[0] in ("all", "+all"):
        return "review", "Policy authorizes every sender"
    includes = [t.lstrip("+").rstrip(".") for t in active]
    if "include:relay.mailchannels.net" in includes:
        return "include_present", "Direct include found; validate full SPF"
    if all_terms == ["-all"]:
        if any(t.startswith("include:") for t in includes):
            return "review", "Strict policy; check indirect authorization"
        return "required", "Strict policy without MailChannels include"
    return "optional", "No hard-fail mechanism; adding MailChannels recommended"


def audit(domain, managed, resolver):
    row = dict(domain=domain, dns_zone="", nameservers="", dns_owner="review",
               spf_status="review", spf_record="", notes="")
    notes = []
    try:
        zone = dns.resolver.zone_for_name(domain + ".", resolver=resolver,
                                          lifetime=10)
        if zone == dns.name.root:
            raise ValueError("No customer DNS zone found")
        row["dns_zone"] = zone.to_text().rstrip(".")
        answer = resolver.resolve(zone, "NS", lifetime=10, search=False)
        nameservers = {r.target.to_text().lower().rstrip(".") for r in answer}
        row["nameservers"] = ";".join(sorted(nameservers))
        if nameservers and nameservers <= managed:
            row["dns_owner"] = "provider"
        elif nameservers and not nameservers & managed:
            row["dns_owner"] = "customer"
        else:
            notes.append("Mixed or missing nameservers; confirm zone access")
    except (dns.exception.DNSException, ValueError) as error:
        reason = str(error) if isinstance(error, ValueError) else type(error).__name__
        notes.append("NS lookup: " + reason)
    try:
        # NoAnswer means the name exists but has no TXT records.
        # NXDOMAIN, SERVFAIL, and timeouts must remain review items.
        answer = resolver.resolve(domain + ".", "TXT", lifetime=10,
                                  search=False, raise_on_no_answer=False)
        records = [b"".join(r.strings).decode("ascii") for r in answer]
        spf = [r for r in records if re.match(r"^v=spf1(?:\s|$)", r, re.I)]
        row["spf_record"] = " | ".join(spf)
        if answer.canonical_name != dns.name.from_text(domain + "."):
            notes.append("TXT follows a DNS alias; review the target zone")
        else:
            row["spf_status"], reason = classify(spf)
            notes.append(reason)
    except (dns.exception.DNSException, UnicodeError) as error:
        notes.append("TXT lookup: " + type(error).__name__)
    row["notes"] = "; ".join(notes)
    return row


def main():
    if len(sys.argv) != 3:
        raise SystemExit("Usage: python3 spf-audit.py domains.txt provider-nameservers.txt")
    domains = read_names(sys.argv[1])
    managed = set(read_names(sys.argv[2]))
    resolver = dns.resolver.Resolver()
    resolver.cache = dns.resolver.Cache()
    rows = []
    for index, domain in enumerate(domains, 1):
        print(f"[{index}/{len(domains)}] {domain}", file=sys.stderr)
        rows.append(audit(domain, managed, resolver))
    rows.sort(key=lambda r: (r["nameservers"], r["spf_status"], r["domain"]))
    fields = ["nameservers", "spf_status", "dns_owner", "domain",
              "dns_zone", "spf_record", "notes"]
    with open("spf-audit.csv", "w", newline="", encoding="utf-8") as output:
        writer = csv.DictWriter(output, fieldnames=fields)
        writer.writeheader()
        writer.writerows(rows)
    print(f"Wrote {len(rows)} domains to spf-audit.csv", file=sys.stderr)


if __name__ == "__main__":
    main()
PY

python3 spf-audit.py domains.txt provider-nameservers.txt

We are moving your outbound email to MailChannels.

Your sending domain: [domain]
Your DNS nameservers: [nameservers]
SPF update: [required before migration / optional but recommended]

In your DNS provider's control panel, edit the existing TXT record:
Record name: [sending domain or the provider's equivalent host field]
Current value: [current SPF record]
New value: [complete SPF record with include:relay.mailchannels.net before all]

Keep one SPF record at this name. Do not remove other sending services.
If you have no SPF record, create the TXT record with the value we supply.

Also configure the Domain Lockdown TXT record we provide:
Record name: _mailchannels.[domain]
Value: v=mc1 auth=[our MailChannels account ID]
If a Domain Lockdown record already exists, contact us to confirm the
combined value so existing authorized accounts remain permitted.

Please confirm when you have saved these changes so we can verify DNS
and test delivery before moving your email.