1
---
2
name: dns-zone-record-linter
3
description: Lints a DNS zone file or a provider's CSV record export before it breaks web or mail - CNAME at the apex or next to other records, MX/NS pointing at a CNAME or IP, missing trailing dots, missing or duplicate SPF, +all/?all and the 10-lookup limit, DMARC and DKIM presence, syntax and key size, TTL extremes, private IPs and SOA mistakes. Returns corrected records. Includes an offline stdlib Python linter with --self-test.
4
---
5
6
# DNS Zone Record Linter
7
8
You review DNS records the way a careful DNS operator would before a migration or a mail setup goes live. You find the mistakes that silently break things (a CNAME at the apex, an MX that points at a CNAME, `mail.example.com` written without its trailing dot, two SPF records), explain the effect in plain words, and hand back corrected records. You work offline from the file; you never claim a live lookup you did not make.
9
10
## Files in this skill
11
12
- `scripts/dns_lint.py` - parses a BIND zone file ($ORIGIN, $TTL, @, relative names, multi-line SOA, quoted TXT) or a CSV export (name,type,value,ttl,priority) and reports findings with line numbers, then lists out-of-zone targets to check live (Python 3.8+ standard library only)
13
- `references/record-rules.md` - the rules behind each check with RFC pointers: CNAME exclusivity, MX/NS targets, trailing dots, SPF, DMARC, DKIM, TTL and SOA values
14
- `references/finding-codes.md` - every finding code with severity, when it is acceptable, and the usual fix
15
- `templates/dns-review.md` - the review to hand back (summary, fixes as records, live checks, rollout notes)
16
- `examples/example.com.zone` - a zone exported before a DNS host move, with mistakes on purpose
17
- `examples/example.com.fixed.zone` - the corrected zone (lints clean)
18
- `examples/lint-report.md` - the real output of the linter on the broken example
19
20
## Workflow
21
22
### 1. Get the records and the context
23
Ask for the zone file (BIND format, `dig AXFR` output or the provider's export) or a CSV (`name,type,value,ttl,priority`), the zone name, and what the domain is for: website only, sending mail (which services: Google Workspace, Microsoft 365, a newsletter tool, a helpdesk), or no mail at all. If the user pastes records from a provider UI, note that host names there usually have no trailing dot and that NS/SOA are often managed by the provider.
24
25
### 2. Run the linter
26
```
27
python3 scripts/dns_lint.py examples/example.com.zone
28
python3 scripts/dns_lint.py records.csv --origin example.com
29
python3 scripts/dns_lint.py zone.db --origin example.com --min-severity MEDIUM --ignore CAA_MISSING --json
30
python3 scripts/dns_lint.py --self-test
31
```
32
Exit 0 = no HIGH findings, 1 = HIGH findings, 2 = bad input (unclosed parenthesis or quote, unknown zone name). If you cannot run code, apply `references/record-rules.md` by hand in the same order.
33
34
### 3. Read the findings
35
- **HIGH** breaks resolution or mail now (CNAME conflicts, MX to CNAME, missing trailing dot, two SPF records, `+all`, DMARC at the wrong name, invalid SPF terms, weak DKIM key).
36
- **MEDIUM** is wrong or risky but may still work (missing DMARC/DKIM/SPF, `?all`, private IPs, TTL extremes, dangling targets, a single name server).
37
- **LOW** is hygiene (duplicates, `p=none`, 1024-bit DKIM, no CAA, obsolete SPF type).
38
- The linter counts only top-level SPF lookups; nested includes add more. It cannot see records that live at the provider (DKIM selectors created by a mail host) or targets outside the zone. Say so, and list the live checks from the "Out-of-zone targets" table (`dig +short CNAME shop.example.com`, `dig TXT _dmarc.example.com`).
39
40
### 4. Deliver
41
Fill `templates/dns-review.md`: a short summary, the corrected records in the user's format (zone lines or provider form fields), what to verify live, and the rollout order: lower TTLs a day ahead, change, verify, raise TTLs again; bump the SOA serial. For mail changes, recommend DMARC `p=none` with `rua` first, then `quarantine`, then `reject` once reports are clean.
42
43
## Example result
44
On `examples/example.com.zone` the linter reports 19 findings (HIGH 7, MEDIUM 8, LOW 4): the website was moved with `@ CNAME bakery-site.example.net.` (CNAME at the apex, next to SOA, NS, MX and TXT), `www` has both a CNAME and a verification TXT, `MX 10 mail.example.com` lacks its trailing dot so it means `mail.example.com.example.com.`, the backup MX points at a CNAME, there are two `v=spf1` records (one with `?all`), DMARC sits at `dmarc` instead of `_dmarc`, an old DKIM selector is revoked, the SOA contact contains `@`, and `intranet` publishes 10.0.4.12. `examples/example.com.fixed.zone` fixes all of them and lints clean (exit 0).
45
46
## Rules
47
48
- Never invent record values (IPs, DKIM keys, provider host names); use placeholders and say what the user must copy from the provider.
49
- Keep exactly one SPF record per name; merge includes instead of adding a second record.
50
- Do not suggest deleting DKIM selectors or MX records that may still be in use without asking which services send mail.
51
- Explain trailing-dot effects with the expanded name, so the user sees the bug.
52
- Mark anything that needs a live lookup as "to verify"; never present it as checked.
53
- Changes to NS, MX or apex records go with a rollout and rollback note (old values, TTLs, when to check).
54