dmarc-check 1.0.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (35) hide show
  1. dmarc_check-1.0.0/.gitignore +13 -0
  2. dmarc_check-1.0.0/LICENSE +21 -0
  3. dmarc_check-1.0.0/PKG-INFO +277 -0
  4. dmarc_check-1.0.0/README.md +248 -0
  5. dmarc_check-1.0.0/action.yml +88 -0
  6. dmarc_check-1.0.0/pyproject.toml +73 -0
  7. dmarc_check-1.0.0/src/dmarc_check/__init__.py +3 -0
  8. dmarc_check-1.0.0/src/dmarc_check/__main__.py +5 -0
  9. dmarc_check-1.0.0/src/dmarc_check/action.py +96 -0
  10. dmarc_check-1.0.0/src/dmarc_check/checks/__init__.py +47 -0
  11. dmarc_check-1.0.0/src/dmarc_check/checks/dkim.py +162 -0
  12. dmarc_check-1.0.0/src/dmarc_check/checks/dmarc.py +135 -0
  13. dmarc_check-1.0.0/src/dmarc_check/checks/mtasts.py +167 -0
  14. dmarc_check-1.0.0/src/dmarc_check/checks/mx.py +70 -0
  15. dmarc_check-1.0.0/src/dmarc_check/checks/spf.py +302 -0
  16. dmarc_check-1.0.0/src/dmarc_check/checks/tlsrpt.py +43 -0
  17. dmarc_check-1.0.0/src/dmarc_check/cli.py +56 -0
  18. dmarc_check-1.0.0/src/dmarc_check/dns_client.py +116 -0
  19. dmarc_check-1.0.0/src/dmarc_check/engine.py +182 -0
  20. dmarc_check-1.0.0/src/dmarc_check/findings.py +111 -0
  21. dmarc_check-1.0.0/src/dmarc_check/github.py +89 -0
  22. dmarc_check-1.0.0/src/dmarc_check/https.py +74 -0
  23. dmarc_check-1.0.0/src/dmarc_check/py.typed +0 -0
  24. dmarc_check-1.0.0/src/dmarc_check/report.py +74 -0
  25. dmarc_check-1.0.0/tests/__init__.py +0 -0
  26. dmarc_check-1.0.0/tests/conftest.py +90 -0
  27. dmarc_check-1.0.0/tests/test_cli_action.py +247 -0
  28. dmarc_check-1.0.0/tests/test_dkim.py +141 -0
  29. dmarc_check-1.0.0/tests/test_dmarc.py +116 -0
  30. dmarc_check-1.0.0/tests/test_engine_report.py +214 -0
  31. dmarc_check-1.0.0/tests/test_io.py +196 -0
  32. dmarc_check-1.0.0/tests/test_links.py +45 -0
  33. dmarc_check-1.0.0/tests/test_mtasts_tlsrpt.py +180 -0
  34. dmarc_check-1.0.0/tests/test_mx.py +64 -0
  35. dmarc_check-1.0.0/tests/test_spf.py +259 -0
@@ -0,0 +1,13 @@
1
+ __pycache__/
2
+ *.py[cod]
3
+ .venv/
4
+ venv/
5
+ dist/
6
+ build/
7
+ *.egg-info/
8
+ .coverage
9
+ coverage.xml
10
+ htmlcov/
11
+ .pytest_cache/
12
+ .mypy_cache/
13
+ .ruff_cache/
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Lookproof
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,277 @@
1
+ Metadata-Version: 2.5
2
+ Name: dmarc-check
3
+ Version: 1.0.0
4
+ Summary: CI checks for SPF, DMARC, DKIM, MX, MTA-STS and TLS-RPT. CLI and GitHub Action.
5
+ Project-URL: Homepage, https://github.com/lookproof/dmarc-check
6
+ Project-URL: Issues, https://github.com/lookproof/dmarc-check/issues
7
+ Project-URL: Findings, https://lookproof.dev/findings
8
+ Author-email: Lookproof <github@lookproof.dev>
9
+ License-Expression: MIT
10
+ License-File: LICENSE
11
+ Keywords: dkim,dmarc,dns,email,github-action,mta-sts,spf,tls-rpt
12
+ Classifier: Development Status :: 5 - Production/Stable
13
+ Classifier: Environment :: Console
14
+ Classifier: Intended Audience :: System Administrators
15
+ Classifier: Operating System :: OS Independent
16
+ Classifier: Programming Language :: Python :: 3
17
+ Classifier: Programming Language :: Python :: 3 :: Only
18
+ Classifier: Topic :: Communications :: Email
19
+ Classifier: Topic :: Internet :: Name Service (DNS)
20
+ Classifier: Typing :: Typed
21
+ Requires-Python: >=3.10
22
+ Requires-Dist: dnspython<3,>=2.6
23
+ Provides-Extra: dev
24
+ Requires-Dist: mypy>=1.11; extra == 'dev'
25
+ Requires-Dist: pytest-cov>=5; extra == 'dev'
26
+ Requires-Dist: pytest>=8; extra == 'dev'
27
+ Requires-Dist: ruff>=0.6; extra == 'dev'
28
+ Description-Content-Type: text/markdown
29
+
30
+ # dmarc-check
31
+
32
+ Checks a domain's mail authentication records (SPF, DMARC, DKIM, MX, MTA-STS and TLS-RPT) in CI. It is a GitHub Action and a command line tool, and both use the same engine.
33
+
34
+ All checks are local DNS lookups made with [dnspython](https://www.dnspython.org/), plus one HTTPS request for the MTA-STS policy. The tool sends nothing to Lookproof or anyone else and has no telemetry. Each finding links to a page on [lookproof.dev/findings](https://lookproof.dev/findings) that explains it and how to fix it.
35
+
36
+ ## What it checks
37
+
38
+ | Area | Checks |
39
+ | --- | --- |
40
+ | SPF | A record exists and there is exactly one. Syntax is valid. At most 10 DNS lookups, counted recursively through `include:` and `redirect=`. At most 2 void lookups. Includes that are missing or loop. `+all` (error) and `?all` (warning). |
41
+ | DMARC | A record exists at `_dmarc.<domain>` and there is exactly one. `p`, `sp` and `np` are valid, with a warning for `p=none` and for `sp=none` or `np=none` under an enforcing `p`. Warns when `pct` is below 100 or `t=y` is set. Notes a missing `rua` (info). |
42
+ | DKIM | Only the selectors you pass in. The key exists, there is one record and it parses. RSA keys under 2048 bits warn; keys under 1024 bits are an error. Revoked keys (`p=`) and testing mode (`t=y`). Ed25519 is supported. |
43
+ | MX | MX records exist. Null MX (`0 .`, RFC 7505) is recognised: the domain counts as accepting no mail, and MTA-STS and TLS-RPT are skipped. Null MX mixed with other records, MX targets that are IP addresses, and MX hosts without A/AAAA records. |
44
+ | MTA-STS | The `_mta-sts` TXT record (`v=STSv1`, `id`). The policy is fetched from `https://mta-sts.<domain>/.well-known/mta-sts.txt` with certificate and host name validation. Redirects are not followed, and the response must be `text/plain` and at most 64 KiB. Checks the policy syntax, `mode`, a `max_age` of at least one day, and that every MX host matches an `mx:` line. |
45
+ | TLS-RPT | `_smtp._tls` has one `v=TLSRPTv1` record with a `rua` of `mailto:` or `https:` URIs. |
46
+
47
+ DNS timeouts and resolver failures are reported as errors, so a check that could not run never passes silently.
48
+
49
+ ## Quick start
50
+
51
+ ### Check on pull requests
52
+
53
+ ```yaml
54
+ # .github/workflows/mail-auth.yml
55
+ name: Mail authentication
56
+ on:
57
+ pull_request:
58
+ push:
59
+ branches: [main]
60
+
61
+ permissions:
62
+ contents: read
63
+
64
+ jobs:
65
+ dmarc-check:
66
+ runs-on: ubuntu-latest
67
+ steps:
68
+ - uses: lookproof/dmarc-check@v1
69
+ with:
70
+ domains: example.com, example.org
71
+ dkim-selectors: google, s1
72
+ fail-on: error
73
+ ```
74
+
75
+ ### Daily check that opens an issue
76
+
77
+ The action opens one issue while the check fails, updates it on later runs, and closes it once the check passes. Issues are matched on their exact title.
78
+
79
+ ```yaml
80
+ # .github/workflows/mail-auth-daily.yml
81
+ name: Mail authentication (daily)
82
+ on:
83
+ schedule:
84
+ - cron: "23 5 * * *"
85
+ workflow_dispatch:
86
+
87
+ permissions:
88
+ contents: read
89
+ issues: write
90
+
91
+ jobs:
92
+ dmarc-check:
93
+ runs-on: ubuntu-latest
94
+ steps:
95
+ - uses: lookproof/dmarc-check@v1
96
+ with:
97
+ domains: example.com
98
+ dkim-selectors: google
99
+ fail-on: warn
100
+ create-issue: true
101
+ ```
102
+
103
+ ### Inputs
104
+
105
+ | Input | Default | Description |
106
+ | --- | --- | --- |
107
+ | `domains` | (required) | Comma-separated domains. |
108
+ | `dkim-selectors` | `""` | Comma-separated DKIM selectors, checked on every domain. DKIM is skipped when this is empty. |
109
+ | `fail-on` | `error` | `error`, `warn`, `info` or `none`, and/or a comma list of finding ids. A severity fails on that severity or worse. Ids fail on that finding whatever its severity. You can combine them, e.g. `error,dmarc-policy-none`. |
110
+ | `resolver` | `""` | Comma-separated DNS server IPs. Defaults to the runner's resolver. |
111
+ | `create-issue` | `false` | Open, update and close one tracking issue. Needs `issues: write`. |
112
+ | `issue-title` | `dmarc-check: mail authentication problems` | Title used to find the tracking issue. |
113
+ | `github-token` | `${{ github.token }}` | Token for `create-issue`. |
114
+ | `python-version` | `3.12` | Python used to run the tool. It is not added to `PATH` for later steps. |
115
+
116
+ ### Outputs
117
+
118
+ | Output | Description |
119
+ | --- | --- |
120
+ | `json` | Every finding as JSON (same format as `dmarc-check --json`). |
121
+ | `exit-code` | `0` when nothing matches `fail-on`, `1` when something does, `2` on invalid input. |
122
+
123
+ The step exits with the same code, so a failing check fails the job. To keep going and read the result yourself, set `continue-on-error: true` on the step and read `steps.<id>.outputs.json`.
124
+
125
+ ## Summary output
126
+
127
+ The action writes a table to the job summary. Findings that match `fail-on` are shown in bold:
128
+
129
+ > ## dmarc-check
130
+ >
131
+ > **❌ Failed** (fail-on: `error`): 1 error, 2 warnings, 1 info
132
+ >
133
+ > | Domain | Severity | Finding | Details |
134
+ > | --- | --- | --- | --- |
135
+ > | example.com | **error** | [`spf-too-many-lookups`](https://lookproof.dev/findings/spf-too-many-lookups) | SPF needs 13 DNS lookups (limit 10) |
136
+ > | example.com | warn | [`dmarc-policy-none`](https://lookproof.dev/findings/dmarc-policy-none) | DMARC policy is p=none: spoofed mail is reported but still delivered |
137
+ > | example.com | warn | [`dkim-weak-key`](https://lookproof.dev/findings/dkim-weak-key) | Selector s1: 1024-bit RSA key; use 2048 bits |
138
+ > | example.com | info | [`tlsrpt-not-found`](https://lookproof.dev/findings/tlsrpt-not-found) | No TLS-RPT record at \_smtp.\_tls.example.com; you will not hear about inbound TLS failures |
139
+ > | example.org | ok | | No findings |
140
+ >
141
+ > Want daily monitoring, alerts and DMARC report parsing? → https://senderward.com
142
+
143
+ Findings that match `fail-on` are also added to the run as error annotations.
144
+
145
+ ## Command line
146
+
147
+ ```bash
148
+ pip install dmarc-check
149
+ ```
150
+
151
+ ```bash
152
+ dmarc-check example.com --dkim-selector s1 --json
153
+ ```
154
+
155
+ ```
156
+ usage: dmarc-check [-h] [--dkim-selector SELECTOR] [--fail-on FAIL_ON] [--resolver IP]
157
+ [--timeout TIMEOUT] [--json] [--version]
158
+ domains [domains ...]
159
+ ```
160
+
161
+ `--dkim-selector` and `--resolver` can be repeated or comma-separated. The exit codes are the same as the action's: `0` passed, `1` a finding matched `--fail-on`, `2` invalid arguments.
162
+
163
+ Text output:
164
+
165
+ ```
166
+ example.com
167
+ error spf-too-many-lookups *
168
+ SPF needs 13 DNS lookups (limit 10)
169
+ https://lookproof.dev/findings/spf-too-many-lookups
170
+ warn dmarc-policy-none
171
+ DMARC policy is p=none: spoofed mail is reported but still delivered
172
+ https://lookproof.dev/findings/dmarc-policy-none
173
+
174
+ FAILED (fail-on: error): 1 error, 1 warning, 0 info
175
+ * = matches fail-on
176
+ ```
177
+
178
+ JSON output:
179
+
180
+ ```json
181
+ {
182
+ "tool": "dmarc-check",
183
+ "version": "1.0.0",
184
+ "fail_on": "error",
185
+ "failed": true,
186
+ "exit_code": 1,
187
+ "counts": { "error": 1, "warn": 1, "info": 0 },
188
+ "domains": [
189
+ {
190
+ "domain": "example.com",
191
+ "findings": [
192
+ {
193
+ "id": "spf-too-many-lookups",
194
+ "severity": "error",
195
+ "check": "spf",
196
+ "domain": "example.com",
197
+ "message": "SPF needs 13 DNS lookups (limit 10)",
198
+ "url": "https://lookproof.dev/findings/spf-too-many-lookups"
199
+ }
200
+ ]
201
+ }
202
+ ]
203
+ }
204
+ ```
205
+
206
+ ## Findings
207
+
208
+ | Id | Severity | Meaning |
209
+ | --- | --- | --- |
210
+ | [`spf-not-found`](https://lookproof.dev/findings/spf-not-found) | error | No SPF record. |
211
+ | [`spf-multiple-records`](https://lookproof.dev/findings/spf-multiple-records) | error | More than one SPF record on the domain or an included domain. |
212
+ | [`spf-syntax-error`](https://lookproof.dev/findings/spf-syntax-error) | error | Unknown mechanism, bad IP or prefix, invalid domain, duplicate modifier. |
213
+ | [`spf-too-many-lookups`](https://lookproof.dev/findings/spf-too-many-lookups) | error | More than 10 DNS-querying terms, counted recursively. |
214
+ | [`spf-too-many-void-lookups`](https://lookproof.dev/findings/spf-too-many-void-lookups) | error | More than 2 lookups returned NXDOMAIN or no data. |
215
+ | [`spf-include-not-found`](https://lookproof.dev/findings/spf-include-not-found) | error | An `include:` or `redirect=` target has no SPF record. |
216
+ | [`spf-include-loop`](https://lookproof.dev/findings/spf-include-loop) | error | Includes or redirects form a loop. |
217
+ | [`spf-pass-all`](https://lookproof.dev/findings/spf-pass-all) | error | The record ends in `+all` (or bare `all`). |
218
+ | [`spf-neutral-all`](https://lookproof.dev/findings/spf-neutral-all) | warn | The record ends in `?all`. |
219
+ | [`spf-ptr-mechanism`](https://lookproof.dev/findings/spf-ptr-mechanism) | warn | Uses the deprecated `ptr` mechanism. |
220
+ | [`spf-no-all`](https://lookproof.dev/findings/spf-no-all) | info | No `all` and no `redirect=`. |
221
+ | [`spf-macro-not-evaluated`](https://lookproof.dev/findings/spf-macro-not-evaluated) | info | Macro terms are counted but not resolved. |
222
+ | [`dmarc-not-found`](https://lookproof.dev/findings/dmarc-not-found) | error | No DMARC record at `_dmarc.<domain>`. |
223
+ | [`dmarc-multiple-records`](https://lookproof.dev/findings/dmarc-multiple-records) | error | More than one DMARC record. |
224
+ | [`dmarc-syntax-error`](https://lookproof.dev/findings/dmarc-syntax-error) | error | Malformed or duplicate tags, bad `pct`, `adkim` or `aspf`. |
225
+ | [`dmarc-invalid-policy`](https://lookproof.dev/findings/dmarc-invalid-policy) | error | `p` is missing, or `p`, `sp` or `np` has an invalid value. |
226
+ | [`dmarc-policy-none`](https://lookproof.dev/findings/dmarc-policy-none) | warn | `p=none`. |
227
+ | [`dmarc-subdomain-policy-none`](https://lookproof.dev/findings/spoof-subdomains-unprotected) | warn | `sp=none` or `np=none` while `p` enforces. |
228
+ | [`dmarc-partial-pct`](https://lookproof.dev/findings/dmarc-partial-pct) | warn | `pct` below 100. |
229
+ | [`dmarc-testing-mode`](https://lookproof.dev/findings/dmarc-testing-mode) | warn | `t=y`. |
230
+ | [`dmarc-invalid-report-uri`](https://lookproof.dev/findings/dmarc-invalid-report-uri) | warn | A `rua` or `ruf` URI is not a valid `mailto:`. |
231
+ | [`dmarc-no-rua`](https://lookproof.dev/findings/dmarc-no-rua) | info | No `rua` tag, so no aggregate reports are sent. |
232
+ | [`dmarc-unknown-tag`](https://lookproof.dev/findings/dmarc-unknown-tag) | info | Tags that receivers ignore. |
233
+ | [`dkim-not-found`](https://lookproof.dev/findings/dkim-not-found) | error | No key at `<selector>._domainkey.<domain>`. |
234
+ | [`dkim-multiple-records`](https://lookproof.dev/findings/dkim-multiple-records) | error | More than one key record for a selector. |
235
+ | [`dkim-syntax-error`](https://lookproof.dev/findings/dkim-syntax-error) | error | Malformed tags, or `v=` that is not `DKIM1` or not first. |
236
+ | [`dkim-invalid-key`](https://lookproof.dev/findings/dkim-invalid-key) | error | The key is not valid base64, cannot be parsed, or has an unknown `k=`. |
237
+ | [`dkim-key-too-short`](https://lookproof.dev/findings/dkim-weak-key) | error | RSA key under 1024 bits. |
238
+ | [`dkim-weak-key`](https://lookproof.dev/findings/dkim-weak-key) | warn | RSA key from 1024 up to 2047 bits. |
239
+ | [`dkim-key-revoked`](https://lookproof.dev/findings/dkim-key-revoked) | warn | Empty `p=`. |
240
+ | [`dkim-testing-mode`](https://lookproof.dev/findings/dkim-testing-mode) | info | `t=y`. |
241
+ | [`dns-domain-not-found`](https://lookproof.dev/findings/dns-domain-not-found) | error | The domain does not exist (NXDOMAIN). |
242
+ | [`mx-null-with-others`](https://lookproof.dev/findings/mx-null-with-others) | error | A null MX next to other MX records. |
243
+ | [`mx-target-is-ip`](https://lookproof.dev/findings/mx-target-is-ip) | error | An MX points to an IP address. |
244
+ | [`mx-target-unresolvable`](https://lookproof.dev/findings/mx-target-unresolvable) | error | An MX host has no A or AAAA record. |
245
+ | [`mx-not-found`](https://lookproof.dev/findings/mx-not-found) | warn | No MX records (implicit MX via A/AAAA). |
246
+ | [`mx-null`](https://lookproof.dev/findings/mx-null) | info | Null MX: the domain accepts no mail. |
247
+ | [`mtasts-multiple-records`](https://lookproof.dev/findings/mtasts-multiple-records) | error | More than one `_mta-sts` record. |
248
+ | [`mtasts-invalid-record`](https://lookproof.dev/findings/mtasts-invalid-record) | error | The `_mta-sts` record lacks `v=STSv1` or a valid `id`. |
249
+ | [`mtasts-policy-unavailable`](https://lookproof.dev/findings/mtasts-policy-unavailable) | error | The policy could not be fetched: TLS or certificate error, redirect, or a status other than 200. |
250
+ | [`mtasts-invalid-policy`](https://lookproof.dev/findings/mtasts-invalid-policy) | error | Wrong content type, too large, or invalid policy fields. |
251
+ | [`mtasts-mx-not-covered`](https://lookproof.dev/findings/mtasts-mx-not-covered) | error | An MX host matches no `mx:` line in an `enforce` policy. |
252
+ | [`mtasts-mx-not-covered-testing`](https://lookproof.dev/findings/mtasts-mx-not-covered-testing) | warn | Same, in a `testing` policy. |
253
+ | [`mtasts-mode-none`](https://lookproof.dev/findings/mtasts-mode-none) | warn | `mode: none`. |
254
+ | [`mtasts-low-max-age`](https://lookproof.dev/findings/mtasts-low-max-age) | warn | `max_age` under 86400 seconds. |
255
+ | [`mtasts-mode-testing`](https://lookproof.dev/findings/mtasts-mode-testing) | info | `mode: testing`. |
256
+ | [`mtasts-not-found`](https://lookproof.dev/findings/mtasts-not-found) | info | No MTA-STS record. |
257
+ | [`tlsrpt-invalid`](https://lookproof.dev/findings/tlsrpt-invalid) | warn | Several records, a missing `rua`, or a URI that is not `mailto:` or `https:`. |
258
+ | [`tlsrpt-not-found`](https://lookproof.dev/findings/tlsrpt-not-found) | info | No TLS-RPT record. |
259
+ | [`dns-resolver-timeout`](https://lookproof.dev/findings/dns-resolver-timeout) | error | A DNS query timed out, so the check is incomplete. |
260
+ | [`dns-resolver-failure`](https://lookproof.dev/findings/dns-resolver-failure) | error | A DNS query failed (SERVFAIL, refused), so the check is incomplete. |
261
+ | [`check-internal-error`](https://lookproof.dev/findings/check-internal-error) | error | A bug in dmarc-check. Please open an issue. |
262
+
263
+ ## Development
264
+
265
+ ```bash
266
+ pip install -e ".[dev]"
267
+ ```
268
+
269
+ ```bash
270
+ ruff check . && ruff format --check . && mypy && pytest
271
+ ```
272
+
273
+ The unit tests use a fake resolver and need no network. `pytest -m network` checks that every finding link exists in the lookproof.dev sitemap.
274
+
275
+ ## License
276
+
277
+ MIT
@@ -0,0 +1,248 @@
1
+ # dmarc-check
2
+
3
+ Checks a domain's mail authentication records (SPF, DMARC, DKIM, MX, MTA-STS and TLS-RPT) in CI. It is a GitHub Action and a command line tool, and both use the same engine.
4
+
5
+ All checks are local DNS lookups made with [dnspython](https://www.dnspython.org/), plus one HTTPS request for the MTA-STS policy. The tool sends nothing to Lookproof or anyone else and has no telemetry. Each finding links to a page on [lookproof.dev/findings](https://lookproof.dev/findings) that explains it and how to fix it.
6
+
7
+ ## What it checks
8
+
9
+ | Area | Checks |
10
+ | --- | --- |
11
+ | SPF | A record exists and there is exactly one. Syntax is valid. At most 10 DNS lookups, counted recursively through `include:` and `redirect=`. At most 2 void lookups. Includes that are missing or loop. `+all` (error) and `?all` (warning). |
12
+ | DMARC | A record exists at `_dmarc.<domain>` and there is exactly one. `p`, `sp` and `np` are valid, with a warning for `p=none` and for `sp=none` or `np=none` under an enforcing `p`. Warns when `pct` is below 100 or `t=y` is set. Notes a missing `rua` (info). |
13
+ | DKIM | Only the selectors you pass in. The key exists, there is one record and it parses. RSA keys under 2048 bits warn; keys under 1024 bits are an error. Revoked keys (`p=`) and testing mode (`t=y`). Ed25519 is supported. |
14
+ | MX | MX records exist. Null MX (`0 .`, RFC 7505) is recognised: the domain counts as accepting no mail, and MTA-STS and TLS-RPT are skipped. Null MX mixed with other records, MX targets that are IP addresses, and MX hosts without A/AAAA records. |
15
+ | MTA-STS | The `_mta-sts` TXT record (`v=STSv1`, `id`). The policy is fetched from `https://mta-sts.<domain>/.well-known/mta-sts.txt` with certificate and host name validation. Redirects are not followed, and the response must be `text/plain` and at most 64 KiB. Checks the policy syntax, `mode`, a `max_age` of at least one day, and that every MX host matches an `mx:` line. |
16
+ | TLS-RPT | `_smtp._tls` has one `v=TLSRPTv1` record with a `rua` of `mailto:` or `https:` URIs. |
17
+
18
+ DNS timeouts and resolver failures are reported as errors, so a check that could not run never passes silently.
19
+
20
+ ## Quick start
21
+
22
+ ### Check on pull requests
23
+
24
+ ```yaml
25
+ # .github/workflows/mail-auth.yml
26
+ name: Mail authentication
27
+ on:
28
+ pull_request:
29
+ push:
30
+ branches: [main]
31
+
32
+ permissions:
33
+ contents: read
34
+
35
+ jobs:
36
+ dmarc-check:
37
+ runs-on: ubuntu-latest
38
+ steps:
39
+ - uses: lookproof/dmarc-check@v1
40
+ with:
41
+ domains: example.com, example.org
42
+ dkim-selectors: google, s1
43
+ fail-on: error
44
+ ```
45
+
46
+ ### Daily check that opens an issue
47
+
48
+ The action opens one issue while the check fails, updates it on later runs, and closes it once the check passes. Issues are matched on their exact title.
49
+
50
+ ```yaml
51
+ # .github/workflows/mail-auth-daily.yml
52
+ name: Mail authentication (daily)
53
+ on:
54
+ schedule:
55
+ - cron: "23 5 * * *"
56
+ workflow_dispatch:
57
+
58
+ permissions:
59
+ contents: read
60
+ issues: write
61
+
62
+ jobs:
63
+ dmarc-check:
64
+ runs-on: ubuntu-latest
65
+ steps:
66
+ - uses: lookproof/dmarc-check@v1
67
+ with:
68
+ domains: example.com
69
+ dkim-selectors: google
70
+ fail-on: warn
71
+ create-issue: true
72
+ ```
73
+
74
+ ### Inputs
75
+
76
+ | Input | Default | Description |
77
+ | --- | --- | --- |
78
+ | `domains` | (required) | Comma-separated domains. |
79
+ | `dkim-selectors` | `""` | Comma-separated DKIM selectors, checked on every domain. DKIM is skipped when this is empty. |
80
+ | `fail-on` | `error` | `error`, `warn`, `info` or `none`, and/or a comma list of finding ids. A severity fails on that severity or worse. Ids fail on that finding whatever its severity. You can combine them, e.g. `error,dmarc-policy-none`. |
81
+ | `resolver` | `""` | Comma-separated DNS server IPs. Defaults to the runner's resolver. |
82
+ | `create-issue` | `false` | Open, update and close one tracking issue. Needs `issues: write`. |
83
+ | `issue-title` | `dmarc-check: mail authentication problems` | Title used to find the tracking issue. |
84
+ | `github-token` | `${{ github.token }}` | Token for `create-issue`. |
85
+ | `python-version` | `3.12` | Python used to run the tool. It is not added to `PATH` for later steps. |
86
+
87
+ ### Outputs
88
+
89
+ | Output | Description |
90
+ | --- | --- |
91
+ | `json` | Every finding as JSON (same format as `dmarc-check --json`). |
92
+ | `exit-code` | `0` when nothing matches `fail-on`, `1` when something does, `2` on invalid input. |
93
+
94
+ The step exits with the same code, so a failing check fails the job. To keep going and read the result yourself, set `continue-on-error: true` on the step and read `steps.<id>.outputs.json`.
95
+
96
+ ## Summary output
97
+
98
+ The action writes a table to the job summary. Findings that match `fail-on` are shown in bold:
99
+
100
+ > ## dmarc-check
101
+ >
102
+ > **❌ Failed** (fail-on: `error`): 1 error, 2 warnings, 1 info
103
+ >
104
+ > | Domain | Severity | Finding | Details |
105
+ > | --- | --- | --- | --- |
106
+ > | example.com | **error** | [`spf-too-many-lookups`](https://lookproof.dev/findings/spf-too-many-lookups) | SPF needs 13 DNS lookups (limit 10) |
107
+ > | example.com | warn | [`dmarc-policy-none`](https://lookproof.dev/findings/dmarc-policy-none) | DMARC policy is p=none: spoofed mail is reported but still delivered |
108
+ > | example.com | warn | [`dkim-weak-key`](https://lookproof.dev/findings/dkim-weak-key) | Selector s1: 1024-bit RSA key; use 2048 bits |
109
+ > | example.com | info | [`tlsrpt-not-found`](https://lookproof.dev/findings/tlsrpt-not-found) | No TLS-RPT record at \_smtp.\_tls.example.com; you will not hear about inbound TLS failures |
110
+ > | example.org | ok | | No findings |
111
+ >
112
+ > Want daily monitoring, alerts and DMARC report parsing? → https://senderward.com
113
+
114
+ Findings that match `fail-on` are also added to the run as error annotations.
115
+
116
+ ## Command line
117
+
118
+ ```bash
119
+ pip install dmarc-check
120
+ ```
121
+
122
+ ```bash
123
+ dmarc-check example.com --dkim-selector s1 --json
124
+ ```
125
+
126
+ ```
127
+ usage: dmarc-check [-h] [--dkim-selector SELECTOR] [--fail-on FAIL_ON] [--resolver IP]
128
+ [--timeout TIMEOUT] [--json] [--version]
129
+ domains [domains ...]
130
+ ```
131
+
132
+ `--dkim-selector` and `--resolver` can be repeated or comma-separated. The exit codes are the same as the action's: `0` passed, `1` a finding matched `--fail-on`, `2` invalid arguments.
133
+
134
+ Text output:
135
+
136
+ ```
137
+ example.com
138
+ error spf-too-many-lookups *
139
+ SPF needs 13 DNS lookups (limit 10)
140
+ https://lookproof.dev/findings/spf-too-many-lookups
141
+ warn dmarc-policy-none
142
+ DMARC policy is p=none: spoofed mail is reported but still delivered
143
+ https://lookproof.dev/findings/dmarc-policy-none
144
+
145
+ FAILED (fail-on: error): 1 error, 1 warning, 0 info
146
+ * = matches fail-on
147
+ ```
148
+
149
+ JSON output:
150
+
151
+ ```json
152
+ {
153
+ "tool": "dmarc-check",
154
+ "version": "1.0.0",
155
+ "fail_on": "error",
156
+ "failed": true,
157
+ "exit_code": 1,
158
+ "counts": { "error": 1, "warn": 1, "info": 0 },
159
+ "domains": [
160
+ {
161
+ "domain": "example.com",
162
+ "findings": [
163
+ {
164
+ "id": "spf-too-many-lookups",
165
+ "severity": "error",
166
+ "check": "spf",
167
+ "domain": "example.com",
168
+ "message": "SPF needs 13 DNS lookups (limit 10)",
169
+ "url": "https://lookproof.dev/findings/spf-too-many-lookups"
170
+ }
171
+ ]
172
+ }
173
+ ]
174
+ }
175
+ ```
176
+
177
+ ## Findings
178
+
179
+ | Id | Severity | Meaning |
180
+ | --- | --- | --- |
181
+ | [`spf-not-found`](https://lookproof.dev/findings/spf-not-found) | error | No SPF record. |
182
+ | [`spf-multiple-records`](https://lookproof.dev/findings/spf-multiple-records) | error | More than one SPF record on the domain or an included domain. |
183
+ | [`spf-syntax-error`](https://lookproof.dev/findings/spf-syntax-error) | error | Unknown mechanism, bad IP or prefix, invalid domain, duplicate modifier. |
184
+ | [`spf-too-many-lookups`](https://lookproof.dev/findings/spf-too-many-lookups) | error | More than 10 DNS-querying terms, counted recursively. |
185
+ | [`spf-too-many-void-lookups`](https://lookproof.dev/findings/spf-too-many-void-lookups) | error | More than 2 lookups returned NXDOMAIN or no data. |
186
+ | [`spf-include-not-found`](https://lookproof.dev/findings/spf-include-not-found) | error | An `include:` or `redirect=` target has no SPF record. |
187
+ | [`spf-include-loop`](https://lookproof.dev/findings/spf-include-loop) | error | Includes or redirects form a loop. |
188
+ | [`spf-pass-all`](https://lookproof.dev/findings/spf-pass-all) | error | The record ends in `+all` (or bare `all`). |
189
+ | [`spf-neutral-all`](https://lookproof.dev/findings/spf-neutral-all) | warn | The record ends in `?all`. |
190
+ | [`spf-ptr-mechanism`](https://lookproof.dev/findings/spf-ptr-mechanism) | warn | Uses the deprecated `ptr` mechanism. |
191
+ | [`spf-no-all`](https://lookproof.dev/findings/spf-no-all) | info | No `all` and no `redirect=`. |
192
+ | [`spf-macro-not-evaluated`](https://lookproof.dev/findings/spf-macro-not-evaluated) | info | Macro terms are counted but not resolved. |
193
+ | [`dmarc-not-found`](https://lookproof.dev/findings/dmarc-not-found) | error | No DMARC record at `_dmarc.<domain>`. |
194
+ | [`dmarc-multiple-records`](https://lookproof.dev/findings/dmarc-multiple-records) | error | More than one DMARC record. |
195
+ | [`dmarc-syntax-error`](https://lookproof.dev/findings/dmarc-syntax-error) | error | Malformed or duplicate tags, bad `pct`, `adkim` or `aspf`. |
196
+ | [`dmarc-invalid-policy`](https://lookproof.dev/findings/dmarc-invalid-policy) | error | `p` is missing, or `p`, `sp` or `np` has an invalid value. |
197
+ | [`dmarc-policy-none`](https://lookproof.dev/findings/dmarc-policy-none) | warn | `p=none`. |
198
+ | [`dmarc-subdomain-policy-none`](https://lookproof.dev/findings/spoof-subdomains-unprotected) | warn | `sp=none` or `np=none` while `p` enforces. |
199
+ | [`dmarc-partial-pct`](https://lookproof.dev/findings/dmarc-partial-pct) | warn | `pct` below 100. |
200
+ | [`dmarc-testing-mode`](https://lookproof.dev/findings/dmarc-testing-mode) | warn | `t=y`. |
201
+ | [`dmarc-invalid-report-uri`](https://lookproof.dev/findings/dmarc-invalid-report-uri) | warn | A `rua` or `ruf` URI is not a valid `mailto:`. |
202
+ | [`dmarc-no-rua`](https://lookproof.dev/findings/dmarc-no-rua) | info | No `rua` tag, so no aggregate reports are sent. |
203
+ | [`dmarc-unknown-tag`](https://lookproof.dev/findings/dmarc-unknown-tag) | info | Tags that receivers ignore. |
204
+ | [`dkim-not-found`](https://lookproof.dev/findings/dkim-not-found) | error | No key at `<selector>._domainkey.<domain>`. |
205
+ | [`dkim-multiple-records`](https://lookproof.dev/findings/dkim-multiple-records) | error | More than one key record for a selector. |
206
+ | [`dkim-syntax-error`](https://lookproof.dev/findings/dkim-syntax-error) | error | Malformed tags, or `v=` that is not `DKIM1` or not first. |
207
+ | [`dkim-invalid-key`](https://lookproof.dev/findings/dkim-invalid-key) | error | The key is not valid base64, cannot be parsed, or has an unknown `k=`. |
208
+ | [`dkim-key-too-short`](https://lookproof.dev/findings/dkim-weak-key) | error | RSA key under 1024 bits. |
209
+ | [`dkim-weak-key`](https://lookproof.dev/findings/dkim-weak-key) | warn | RSA key from 1024 up to 2047 bits. |
210
+ | [`dkim-key-revoked`](https://lookproof.dev/findings/dkim-key-revoked) | warn | Empty `p=`. |
211
+ | [`dkim-testing-mode`](https://lookproof.dev/findings/dkim-testing-mode) | info | `t=y`. |
212
+ | [`dns-domain-not-found`](https://lookproof.dev/findings/dns-domain-not-found) | error | The domain does not exist (NXDOMAIN). |
213
+ | [`mx-null-with-others`](https://lookproof.dev/findings/mx-null-with-others) | error | A null MX next to other MX records. |
214
+ | [`mx-target-is-ip`](https://lookproof.dev/findings/mx-target-is-ip) | error | An MX points to an IP address. |
215
+ | [`mx-target-unresolvable`](https://lookproof.dev/findings/mx-target-unresolvable) | error | An MX host has no A or AAAA record. |
216
+ | [`mx-not-found`](https://lookproof.dev/findings/mx-not-found) | warn | No MX records (implicit MX via A/AAAA). |
217
+ | [`mx-null`](https://lookproof.dev/findings/mx-null) | info | Null MX: the domain accepts no mail. |
218
+ | [`mtasts-multiple-records`](https://lookproof.dev/findings/mtasts-multiple-records) | error | More than one `_mta-sts` record. |
219
+ | [`mtasts-invalid-record`](https://lookproof.dev/findings/mtasts-invalid-record) | error | The `_mta-sts` record lacks `v=STSv1` or a valid `id`. |
220
+ | [`mtasts-policy-unavailable`](https://lookproof.dev/findings/mtasts-policy-unavailable) | error | The policy could not be fetched: TLS or certificate error, redirect, or a status other than 200. |
221
+ | [`mtasts-invalid-policy`](https://lookproof.dev/findings/mtasts-invalid-policy) | error | Wrong content type, too large, or invalid policy fields. |
222
+ | [`mtasts-mx-not-covered`](https://lookproof.dev/findings/mtasts-mx-not-covered) | error | An MX host matches no `mx:` line in an `enforce` policy. |
223
+ | [`mtasts-mx-not-covered-testing`](https://lookproof.dev/findings/mtasts-mx-not-covered-testing) | warn | Same, in a `testing` policy. |
224
+ | [`mtasts-mode-none`](https://lookproof.dev/findings/mtasts-mode-none) | warn | `mode: none`. |
225
+ | [`mtasts-low-max-age`](https://lookproof.dev/findings/mtasts-low-max-age) | warn | `max_age` under 86400 seconds. |
226
+ | [`mtasts-mode-testing`](https://lookproof.dev/findings/mtasts-mode-testing) | info | `mode: testing`. |
227
+ | [`mtasts-not-found`](https://lookproof.dev/findings/mtasts-not-found) | info | No MTA-STS record. |
228
+ | [`tlsrpt-invalid`](https://lookproof.dev/findings/tlsrpt-invalid) | warn | Several records, a missing `rua`, or a URI that is not `mailto:` or `https:`. |
229
+ | [`tlsrpt-not-found`](https://lookproof.dev/findings/tlsrpt-not-found) | info | No TLS-RPT record. |
230
+ | [`dns-resolver-timeout`](https://lookproof.dev/findings/dns-resolver-timeout) | error | A DNS query timed out, so the check is incomplete. |
231
+ | [`dns-resolver-failure`](https://lookproof.dev/findings/dns-resolver-failure) | error | A DNS query failed (SERVFAIL, refused), so the check is incomplete. |
232
+ | [`check-internal-error`](https://lookproof.dev/findings/check-internal-error) | error | A bug in dmarc-check. Please open an issue. |
233
+
234
+ ## Development
235
+
236
+ ```bash
237
+ pip install -e ".[dev]"
238
+ ```
239
+
240
+ ```bash
241
+ ruff check . && ruff format --check . && mypy && pytest
242
+ ```
243
+
244
+ The unit tests use a fake resolver and need no network. `pytest -m network` checks that every finding link exists in the lookproof.dev sitemap.
245
+
246
+ ## License
247
+
248
+ MIT
@@ -0,0 +1,88 @@
1
+ name: dmarc-check
2
+ description: Check SPF, DMARC, DKIM, MX, MTA-STS and TLS-RPT for your domains with local DNS lookups.
3
+ author: Lookproof
4
+ branding:
5
+ icon: shield
6
+ color: blue
7
+
8
+ inputs:
9
+ domains:
10
+ description: Comma-separated list of domains to check.
11
+ required: true
12
+ dkim-selectors:
13
+ description: Comma-separated DKIM selectors to check on every domain (e.g. "google,s1"). DKIM is skipped when empty.
14
+ required: false
15
+ default: ""
16
+ fail-on:
17
+ description: >-
18
+ When the step fails. "error" (default), "warn", "info", "none", and/or a comma list
19
+ of finding ids, e.g. "error,dmarc-policy-none".
20
+ required: false
21
+ default: error
22
+ resolver:
23
+ description: Comma-separated DNS server IPs to use instead of the runner's resolver.
24
+ required: false
25
+ default: ""
26
+ create-issue:
27
+ description: >-
28
+ "true" to open or update one issue while the check fails and close it when it passes.
29
+ Meant for scheduled runs. Needs "issues: write".
30
+ required: false
31
+ default: "false"
32
+ issue-title:
33
+ description: Title of the tracking issue. Issues are matched on this exact title.
34
+ required: false
35
+ default: "dmarc-check: mail authentication problems"
36
+ github-token:
37
+ description: Token used for create-issue.
38
+ required: false
39
+ default: ${{ github.token }}
40
+ python-version:
41
+ description: Python version used to run the check. It is not added to PATH for later steps.
42
+ required: false
43
+ default: "3.12"
44
+
45
+ outputs:
46
+ json:
47
+ description: All findings as JSON.
48
+ value: ${{ steps.check.outputs.json }}
49
+ exit-code:
50
+ description: 0 when nothing matches fail-on, 1 when something does, 2 on invalid input.
51
+ value: ${{ steps.check.outputs.exit-code }}
52
+
53
+ runs:
54
+ using: composite
55
+ steps:
56
+ - name: Set up Python
57
+ id: python
58
+ uses: actions/setup-python@v6
59
+ with:
60
+ python-version: ${{ inputs.python-version }}
61
+ update-environment: false
62
+
63
+ - name: Install dmarc-check
64
+ id: install
65
+ shell: bash
66
+ env:
67
+ PYTHON: ${{ steps.python.outputs.python-path }}
68
+ ACTION_PATH: ${{ github.action_path }}
69
+ run: |
70
+ venv="$RUNNER_TEMP/dmarc-check-venv"
71
+ "$PYTHON" -m venv "$venv"
72
+ if [ -x "$venv/bin/python" ]; then py="$venv/bin/python"; else py="$venv/Scripts/python.exe"; fi
73
+ "$py" -m pip install --quiet --disable-pip-version-check "$ACTION_PATH"
74
+ echo "python=$py" >> "$GITHUB_OUTPUT"
75
+
76
+ - name: Run dmarc-check
77
+ id: check
78
+ shell: bash
79
+ env:
80
+ PYTHON: ${{ steps.install.outputs.python }}
81
+ DMARC_CHECK_DOMAINS: ${{ inputs.domains }}
82
+ DMARC_CHECK_DKIM_SELECTORS: ${{ inputs.dkim-selectors }}
83
+ DMARC_CHECK_FAIL_ON: ${{ inputs.fail-on }}
84
+ DMARC_CHECK_RESOLVER: ${{ inputs.resolver }}
85
+ DMARC_CHECK_CREATE_ISSUE: ${{ inputs.create-issue }}
86
+ DMARC_CHECK_ISSUE_TITLE: ${{ inputs.issue-title }}
87
+ DMARC_CHECK_GITHUB_TOKEN: ${{ inputs.github-token }}
88
+ run: '"$PYTHON" -m dmarc_check.action'