faultypacket-audit 1.3.0__py3-none-any.whl

faultypacket_audit/__init__.py

@@ -0,0 +1,15 @@
+"""faultypacket-audit: cited, standards-current mail and DNS hygiene checks.
+
+Library use:
+    from faultypacket_audit import audit, load_rules, Resolver
+    report = audit("example.com", Resolver(doh="https://cloudflare-dns.com/dns-query"), load_rules())
+
+Checks are pure functions of (domain, resolver, rules, options); they never print.
+"""
+__version__ = "1.3.0"
+
+from .core.resolver import Resolver, Cached          # noqa: E402
+from .core.rules import load_rules                    # noqa: E402
+from .audit import audit, CHECKS                      # noqa: E402
+
+__all__ = ["__version__", "Resolver", "Cached", "load_rules", "audit", "CHECKS"]

faultypacket_audit/__main__.py

@@ -0,0 +1,2 @@
+from .cli import entry
+entry()

faultypacket_audit/audit.py

@@ -0,0 +1,52 @@
+"""Run checks for one domain. Pure: returns a report dict, never prints."""
+import datetime as dt
+
+from .checks import spf, dmarc, dkim, bulk_sender, mx, mtasts, caa, rdns, dnssec, dane, bimi, blocklist, lookalike
+from .core.finding import worst
+from .core.resolver import Cached
+
+CHECKS = {"spf": spf.check, "dmarc": dmarc.check, "dkim": dkim.check, "mx": mx.check,
+          "mta-sts": mtasts.check, "dnssec": dnssec.check, "dane": dane.check, "caa": caa.check,
+          "rdns": rdns.check, "bimi": bimi.check, "bulk-sender": bulk_sender.check,
+          "blocklist": blocklist.check, "lookalike": lookalike.check}
+# order matters: bulk-sender reuses spf, dmarc and dkim data; bimi reuses dmarc
+ORDER = ["spf", "dmarc", "dkim", "mx", "mta-sts", "dnssec", "dane", "caa", "rdns", "bimi", "bulk-sender"]
+# opt-in: they query third parties (blocklists) or many names (lookalike)
+EXTRA = ["blocklist", "lookalike"]
+ALL = ORDER + EXTRA
+INTERNAL = {"spf": "spf.internal", "dmarc": "dmarc.internal", "bulk-sender": "bulk.internal",
+            "mta-sts": "mtasts.internal",
+            "blocklist": "blocklist.internal", "lookalike": "lookalike.internal"}
+
+
+def now_utc():
+    return dt.datetime.now(dt.timezone.utc).isoformat(timespec="seconds")
+
+
+def audit(domain, res, rules, checks=None, options=None):
+    """-> {domain, checked_at_utc, rules_version, status, checks: [CheckResult]}.
+    Each check is isolated: an exception becomes a cited TOOL finding for that
+    check only."""
+    res = res if isinstance(res, Cached) else Cached(res)
+    wanted = [c for c in ALL if c in (checks or ORDER)]
+    opts = dict(options or {})
+    opts["results"] = {}
+    out = []
+    for name in wanted:
+        try:
+            r = CHECKS[name](domain, res, rules, opts)
+        except Exception as e:    # per-check isolation
+            r = {"check": name, "domain": domain, "data": {},
+                 "findings": [rules.finding(name, "error", INTERNAL.get(name, "core.internal"),
+                                            f"{type(e).__name__}: {e}")]}
+        r["status"] = worst(f.severity for f in r["findings"])
+        opts["results"][name] = r["data"]
+        out.append(r)
+    from .fixes import suggest
+    try:
+        fixes = suggest(domain, out)
+    except Exception:              # a fix suggestion must never break an audit
+        fixes = []
+    return {"domain": domain, "checked_at_utc": now_utc(), "rules_version": rules.version,
+            "resolvers": res.servers, "status": worst(c["status"] for c in out), "checks": out,
+            "fixes": fixes}

faultypacket_audit/checks/_common.py

@@ -0,0 +1,36 @@
+"""Small shared helpers for the DNS checks."""
+
+
+def tags(record):
+    """DKIM-style tag=value list (RFC 6376 3.2) -> ordered dict, lower-case names.
+    Duplicate names: first wins, duplicates listed under '__dup__'."""
+    out, dup = {}, []
+    for part in record.split(";"):
+        if "=" not in part:
+            continue
+        k, _, v = part.partition("=")
+        k, v = k.strip().lower(), "".join(v.split())
+        if k in out:
+            dup.append(k)
+            continue
+        out[k] = v
+    if dup:
+        out["__dup__"] = dup
+    return out
+
+
+def mx_hosts(domain, res):
+    """-> (list of (pref, host) or None on DNS error, status)."""
+    vals, st = res.query(domain, "MX")
+    if st.startswith("error"):
+        return None, st
+    out = []
+    for v in vals:
+        p = v.split()
+        if len(p) == 2 and p[0].isdigit():
+            out.append((int(p[0]), p[1].lower().rstrip(".")))
+    return sorted(out), st
+
+
+def result(name, domain, findings, data):
+    return {"check": name, "domain": domain, "findings": findings, "data": data}