FaultyPacket™ Audit

Is your domain's email set up to current rules? One command checks SPF, DMARC (RFC 9989), DKIM, MTA-STS, DNSSEC, DANE, CAA, BIMI and Google/Yahoo/Outlook sender requirements, and every finding cites the RFC section or provider page behind it.

pip install faultypacket-audit
# or from source: pip install git+https://github.com/FaultyPacket/faultypacket-audit
faultypacket-audit --doh europa.eu
faultypacket-audit --doh -f domains.txt --json out.json --sarif out.sarif

Sample output (live run, 2026-10-29 11:45 UTC, trimmed):

europa.eu: ERROR
  dmarc: error
    [error] no DMARC record at _dmarc.europa.eu and none found by the Tree Walk: DMARC does not apply (RFC 9989 4.10.1)
      rule dmarc.no_record | RFC 9989 4.10.1 | https://www.rfc-editor.org/rfc/rfc9989#section-4.10.1 | rules 2026.10.29.5
  bulk-sender: warning
    google: fail (not checkable from DNS: alignment, one_click_unsub, tls, spam_rate_max)
    outlook: fail (not checkable from DNS: alignment)
    yahoo: fail (not checkable from DNS: unsub_days_max)

Runs locally. No account, no upload. Also a GitHub Action, an MCP server and a weekly scan for your own repo. AI agents: see AGENTS.md.

Status: v1.4.0 (2026-10-29). JSON fields are stable within 1.x (schema); rule changes bump rules_version.

Checks

The two opt-in checks send extra queries (to third-party lists, or 180 queries for lookalikes), so they run only when named: --checks spf,dmarc,mx,blocklist,lookalike.

Install and run

pip install faultypacket-audit
# or from source: pip install git+https://github.com/FaultyPacket/faultypacket-audit
faultypacket-audit example.com
faultypacket-audit -f domains.txt --json out.json --csv out.csv --sarif out.sarif
faultypacket-audit example.com --html report.html        # self-contained; print to PDF from a browser
faultypacket-audit headers message.eml                  # alignment verdict from saved headers
faultypacket-audit example.com --dkim-selector s1 --sending-ip 192.0.2.10
faultypacket-audit -f domains.txt --json new.json --baseline old.json --diff changes.md --fail-on-new
python -m faultypacket_audit --checks spf,dmarc --doh example.com

Exit codes: 0 means clean, 1 means the --fail-on threshold (default error) was reached or an input was invalid, 2 means a usage error.

Output

• Text is the default.
• JSON gives one object per domain. Each check has a status, its findings and structured data.
• CSV gives one row per finding.
• SARIF 2.1.0 works with GitHub code scanning. Each rule carries a helpUri that links to its source.
• HTML (--html FILE) is one self-contained file (no scripts, fonts or remote assets): executive summary, per-provider verdicts, every finding with its linked source, and suggested fixes. Print it to PDF from any browser.
• PDF (--pdf FILE) is optional: pip install fpdf2 (pure-Python, but it pulls in Pillow and fontTools). The printed HTML looks better.

Each finding has these fields:

• rule_id (for example dmarc.historic_pct)
• severity
• message
• citation (for example RFC 9989 9.3)
• url
• level, which is MUST, SHOULD, MAY, PROVIDER or TOOL. TOOL covers the tool's own conditions, such as DNS errors.
• rules_version (for example 2026.10.29.5), so a finding can be traced to the exact rule set that produced it. SARIF messages end with [rule_id | citation | rules version].

Suggested fixes

Where the right change follows from the standard, the report includes a fix tied to the rule it answers (fixes in JSON, one per finding class). Each is a DNS record (TXT, MX, CAA), a file to publish (FILE), or ordered STEPS:

Anything only you know (report mailbox, CA, selector, logo URL) is a REPLACE- placeholder. The tests re-audit each suggested SPF, DMARC and MTA-STS fix to check it is itself valid.

Message headers

faultypacket-audit headers message.eml [--json] [--adkim s] [--aspf s] [--trust mx.yourdomain.example] [--doh]

Reads a saved message and reports: Authentication-Results (RFC 8601, comments and quoting handled), ARC sets and cv chain (RFC 8617), each DKIM-Signature (missing tags, rsa-sha1, l=, whether From is signed), the Received chain oldest first with per-hop delay, and a DMARC alignment verdict (RFC 9989 3.2.10 relaxed/strict, 4.4). By default only the topmost Authentication-Results is trusted (anything below it may have been added by the sender). Organizational Domains come from the Public Suffix List offline, or the RFC 9989 Tree Walk with --doh. It does not re-verify signatures. Exit 0 when aligned, 1 otherwise.

Provider verdicts

bulk-sender gives a separate verdict for Google, Yahoo and Outlook, with one row per published requirement and a link to the provider page. DKIM rows use the keys the dkim check found, including Google's rule that mail to personal Gmail accounts needs a DKIM key of 1024 bits or longer (support.google.com/a/answer/81126, checked 2026-10-29).

Library use

The checks are pure functions that return data and never print.

from faultypacket_audit import audit, load_rules, Resolver
report = audit("example.com", Resolver(), load_rules())

GitHub Action

- uses: FaultyPacket/faultypacket-audit@v1
  id: audit
  with:
    domains-file: domains.txt        # or domains: "example.com example.org"
    args: --dkim-selector s1         # any CLI flags
    fail-on: error                   # or warning
- uses: github/codeql-action/upload-sarif@v3
  if: always()
  with: {sarif_file: "${{ steps.audit.outputs.sarif }}"}

Outputs: exit-code, json, sarif, html. @v1 follows the latest 1.x release; pin a tag such as @v1.4.0 for fixed behaviour.

MCP server for AI agents

faultypacket-audit mcp --doh

A stdio Model Context Protocol server with two tools, audit_domain and list_rules. See AGENTS.md.

Weekly scan in your own repo

Copy templates/weekly-scan.yml into your repo's .github/workflows/ and add a domains.txt file. Once a week the workflow:

• uploads SARIF to the Security tab,
• keeps the JSON and CSV as an artifact,
• downloads the previous run's JSON and writes "What changed since the last run" (new problems, fixed, severity changes) to the job summary,
• opens one alert issue when there are warnings or errors (and comments on it on later runs), and closes it when all domains are clean.

For UK organisations that used NCSC Mail Check (retired 31 March 2026), this gives a weekly check you run and read yourself.

What it cannot check from DNS

The bulk-sender check is deliberately honest about its scope. Each requirement row is reported as pass, fail, unknown or not-dns-verifiable.

• Needs your input:

  • Forward-confirmed reverse DNS needs your sending IPs (--sending-ip).
  • DKIM needs your selectors (--dkim-selector). Selectors can't be discovered from DNS.

• Not visible from DNS at all:

  • TLS on the actual connection
  • spam-complaint rates
  • one-click unsubscribe headers (RFC 8058)
  • message formatting
  • whether the From domain aligns on real mail

  Those show as not-dns-verifiable and are never counted as passes. A provider verdict is fail, incomplete or dns-checks-pass. It is never "compliant".

• Other limits:

  • SMTP STARTTLS is only checked with --smtp. Many networks (including GitHub-hosted runners and most clouds) block outbound port 25; the result is then reported as not tested (port 25 blocked), never as a pass.
  • DKIM selectors can't be listed from DNS. A key found by probing a common selector may not be the one in use, so give your real selectors with --dkim-selector.
  • BIMI: the VMC/CMC certificate chain is not validated, only its presence.
  • DNSSEC validation relies on the resolver's AD bit (DoH, or --validating-resolver).
  • Tree Walk results depend on what intermediate domains publish. Where a public suffix has a DMARC record without psd=y, the Tree Walk and PSL methods can choose different Organizational Domains. The tool reports this as dmarc.org_method_differs.

Rules and maintenance

• maint/scripts/check_rules.py runs in CI. It fails if any rule has no source, URL or verified date, or if a code constant disagrees with the rules.

• Weekly workflows run:

  • canary domains,
  • the test suite,
  • a watch on the RFC errata pages, the IANA DMARC registry and the provider guideline pages.

  A change opens an issue for review. Nothing updates itself.

More at https://faultypacket.co.uk

Licence

AGPL-3.0-or-later. See LICENSE and NOTICE.

Copyright (c) 2026 FaultyPacket. FaultyPacket™ — https://faultypacket.co.uk