Documentation
¶
Overview ¶
Package dnscheck answers the DNS questions deliverability depends on: SPF, DKIM, DMARC (with policy discovery), BIMI and MAIL FROM alignment for sending domains, forward-confirmed reverse DNS for IPs, and DNSBL listings for both.
Everything goes through the small Resolver interface. Client implements it with miekg/dns v1 (see docs/TECH_STACK.md: switch to codeberg.org/miekg/dns v2 here once it reaches 1.0); Zone is an in-memory resolver for tests and the demo. Checks are plain functions over a Resolver, so the deliverability checks and the sending-domain verification share one implementation.
Index ¶
- Constants
- Variables
- func Aligned(a, b string, strict bool) bool
- func IsNotFound(err error) bool
- func OrgDomain(name string) string
- func Pairs(lists []Blocklist, assets []Asset) [][2]int
- type Asset
- type AuthSummary
- type BIMI
- type Blocklist
- type Client
- func (c *Client) A(ctx context.Context, name string) ([]netip.Addr, error)
- func (c *Client) AAAA(ctx context.Context, name string) ([]netip.Addr, error)
- func (c *Client) CNAME(ctx context.Context, name string) (string, error)
- func (c *Client) MX(ctx context.Context, name string) ([]MX, error)
- func (c *Client) PTR(ctx context.Context, ip netip.Addr) ([]string, error)
- func (c *Client) TXT(ctx context.Context, name string) ([]string, error)
- type DKIM
- type DMARC
- type DMARCRecord
- type DomainAuth
- type Listing
- type MX
- type MailFrom
- type Options
- type RecordCheck
- type Requirement
- type Resolver
- type ReverseDNS
- type SPF
- type Zone
- func (z *Zone) A(_ context.Context, name string) ([]netip.Addr, error)
- func (z *Zone) AAAA(_ context.Context, name string) ([]netip.Addr, error)
- func (z *Zone) Add(name, typ, value string) *Zone
- func (z *Zone) CNAME(_ context.Context, name string) (string, error)
- func (z *Zone) Fail(name string) *Zone
- func (z *Zone) Has(name string) bool
- func (z *Zone) MX(_ context.Context, name string) ([]MX, error)
- func (z *Zone) PTR(_ context.Context, ip netip.Addr) ([]string, error)
- func (z *Zone) TXT(_ context.Context, name string) ([]string, error)
Constants ¶
const ( StatusPass = "pass" // present, valid and doing its job StatusMissing = "missing" // no record StatusInvalid = "invalid" // a record exists but is broken StatusFail = "fail" // valid record that doesn't cover what it must StatusError = "error" // DNS didn't answer; try again StatusRevoked = "revoked" // DKIM key with an empty p= StatusTooMany = "too_many_lookups" StatusAligned = "aligned" StatusMisalign = "misaligned" )
Status words shared by every check result.
const ( KindIP = "ip" KindDomain = "domain" )
Asset kinds checked against blocklists.
const ( RecordVerified = "verified" RecordWrongValue = "wrong_value" RecordMissing = "missing" RecordError = "error" )
Record check statuses (the live verification of one required record).
const MaxSPFLookups = 10
MaxSPFLookups is the RFC 7208 limit on DNS-querying terms.
Variables ¶
var ( // ErrNotFound is wrapped by ErrNXDomain and ErrNoData. ErrNotFound = errors.New("dnscheck: not found") // ErrNXDomain means the name does not exist. ErrNXDomain = fmt.Errorf("%w: no such domain", ErrNotFound) // ErrNoData means the name exists but has no record of the asked type. ErrNoData = fmt.Errorf("%w: no record of that type", ErrNotFound) // ErrTemporary means no server gave a usable answer (timeout, SERVFAIL). ErrTemporary = errors.New("dnscheck: temporary failure") )
Errors returned by resolvers.
var Builtin = []Blocklist{ {Name: "Spamhaus ZEN", Zone: "zen.spamhaus.org", Kind: KindIP, Impact: "high", Rank: 1, DelistURL: "https://check.spamhaus.org/", /* contains filtered or unexported fields */}, {Name: "Spamhaus DBL", Zone: "dbl.spamhaus.org", Kind: KindDomain, Impact: "high", Rank: 2, DelistURL: "https://check.spamhaus.org/", /* contains filtered or unexported fields */}, {Name: "SURBL", Zone: "multi.surbl.org", Kind: KindDomain, Impact: "high", Rank: 3, DelistURL: "https://surbl.org/surbl-analysis", /* contains filtered or unexported fields */}, {Name: "URIBL", Zone: "multi.uribl.com", Kind: KindDomain, Impact: "high", Rank: 4, DelistURL: "https://admin.uribl.com/", /* contains filtered or unexported fields */}, {Name: "Barracuda BRBL", Zone: "b.barracudacentral.org", Kind: KindIP, Impact: "high", Rank: 5, DelistURL: "https://www.barracudacentral.org/rbl/removal-request"}, {Name: "SpamCop", Zone: "bl.spamcop.net", Kind: KindIP, Impact: "medium", Rank: 6, DelistURL: "https://www.spamcop.net/bl.shtml"}, {Name: "Mailspike", Zone: "bl.mailspike.net", Kind: KindIP, Impact: "medium", Rank: 7, DelistURL: "https://mailspike.org/anubis/lookup.html"}, {Name: "PSBL", Zone: "psbl.surriel.com", Kind: KindIP, Impact: "low", Rank: 8, DelistURL: "https://psbl.org/"}, }
Builtin is the set ReputeCast checks itself when HostRepute isn't connected: eight major public lists, checked daily. (SORBS, still on some lists of "major DNSBLs", shut down in 2024 and is replaced by Mailspike.)
var ErrRefused = errors.New("dnscheck: blocklist refused the query")
ErrRefused means the list answered with an error code instead of a listing, usually because the query came through a public resolver.
Functions ¶
func Aligned ¶
Aligned reports whether two domains align: identical in strict mode, the same organizational domain in relaxed mode.
func IsNotFound ¶
IsNotFound reports whether err means "no such record".
Types ¶
type AuthSummary ¶
type AuthSummary struct {
SPF string `json:"spf"` // pass, missing, invalid, fail, too_many_lookups, error
DKIM string `json:"dkim"` // pass, missing, invalid, revoked, fail, unknown, error
// DMARC is the policy (none, quarantine, reject) or missing / invalid.
DMARC string `json:"dmarc"`
BIMI string `json:"bimi"` // pass, missing, invalid
ReturnPath string `json:"return_path"` // aligned, misaligned, missing, default
}
AuthSummary is the one-line verdict per mechanism for a sending domain, as shown on Deliverability ("pass · pass · p=quarantine") and stored on the sending domain.
type BIMI ¶
type BIMI struct {
Domain string `json:"domain"`
Status string `json:"status"`
Logo string `json:"logo,omitempty"`
// Certificate is the VMC/CMC URL (a=); Gmail requires one.
Certificate string `json:"certificate,omitempty"`
Error string `json:"error,omitempty"`
}
BIMI is the result of checking default._bimi.<domain>.
type Blocklist ¶
type Blocklist struct {
Name string `json:"name"`
Zone string `json:"zone"`
// Kind is KindIP or KindDomain: what the list is queried with.
Kind string `json:"kind"`
// Impact on inbox placement when listed: high, medium or low.
Impact string `json:"impact"`
// Rank orders lists of the same impact (lower first).
Rank int `json:"rank"`
// DelistURL is the list's lookup and removal page.
DelistURL string `json:"delistUrl"`
// contains filtered or unexported fields
}
Blocklist is a DNS-based blocklist (DNSBL for IPs, URI/domain list for domains).
type Client ¶
type Client struct {
// contains filtered or unexported fields
}
Client is the miekg/dns implementation of Resolver: UDP with EDNS0, TCP when an answer is truncated, and the next server on errors.
type DKIM ¶
type DKIM struct {
Selector string `json:"selector"`
Domain string `json:"domain"`
Status string `json:"status"`
// Target is the CNAME the selector points to (provider-hosted keys).
Target string `json:"target,omitempty"`
KeyType string `json:"keyType,omitempty"`
// KeyBits is an estimate from the public key length (RSA only).
KeyBits int `json:"keyBits,omitempty"`
Error string `json:"error,omitempty"`
}
DKIM is the result of checking one DKIM selector.
type DMARC ¶
type DMARC struct {
Domain string `json:"domain"`
// PolicyDomain is where the record was found: the domain itself or the
// parent the DNS Tree Walk found it at (RFC 9989 §4.10.1).
PolicyDomain string `json:"policyDomain,omitempty"`
Status string `json:"status"`
Record string `json:"record,omitempty"`
// Policy applied to Domain: p= of its own record; of a parent's, np=
// when Domain doesn't exist (NXDOMAIN), else sp=, both defaulting to p=.
Policy string `json:"policy,omitempty"`
SubdomainPolicy string `json:"subdomainPolicy,omitempty"`
NonexistentPolicy string `json:"nonexistentPolicy,omitempty"`
// TestMode is t=y: receivers apply the policy one level lower.
TestMode bool `json:"testMode,omitempty"`
// PSD is the record's psd= flag, y or n; empty for the default u.
PSD string `json:"psd,omitempty"`
RUA []string `json:"rua,omitempty"`
RUF []string `json:"ruf,omitempty"`
StrictDKIM bool `json:"strictDkim"`
StrictSPF bool `json:"strictSpf"`
Error string `json:"error,omitempty"`
}
DMARC is the result of DMARC policy discovery for a domain.
func CheckDMARC ¶
CheckDMARC finds the DMARC policy for domain by RFC 9989 policy discovery (§4.10.1): _dmarc.<domain>, then the DNS Tree Walk up its parents, at most 8 queries, to the first usable record or one with psd=y or psd=n. Receivers discard several records at one name and keep walking; at the domain itself several records, or one receivers can't use, are invalid: its owner has to fix them. A DNS error stops the walk: the policy is unknown, not missing.
type DMARCRecord ¶
type DMARCRecord struct {
Policy, SubdomainPolicy, NonexistentPolicy, PSD string
TestMode, StrictDKIM, StrictSPF bool
RUA, RUF []string
}
DMARCRecord is a DMARC Policy Record (RFC 9989 §4.7) with its defaults filled in: SubdomainPolicy is p= without an sp= tag, NonexistentPolicy is the subdomain policy without an np= tag, and PSD is "u" without a valid psd= tag.
func ParseDMARC ¶
func ParseDMARC(txt string) (DMARCRecord, bool)
ParseDMARC reads a DMARC Policy Record. ok is false when txt isn't one (its first tag isn't v=DMARC1) or when receivers apply no DMARC with it (§4.10.1): p= missing or invalid, or sp= or np= invalid, and no valid rua= URI. With a valid rua= URI such a record reads as p=none. Tags RFC 9989 doesn't define (pct=, ri=, rf=, anything unknown) are ignored, and other invalid values fall back to their defaults. Tag names and the values of p, sp, np, adkim, aspf, t and psd are case-insensitive (ABNF strings); the alignment and test-mode fields are filled even when ok is false.
type DomainAuth ¶
type DomainAuth struct {
Domain string `json:"domain"`
SPF SPF `json:"spf"`
DKIM []DKIM `json:"dkim"`
DMARC DMARC `json:"dmarc"`
BIMI BIMI `json:"bimi"`
MailFrom []MailFrom `json:"mailFrom"`
Records []RecordCheck `json:"records"`
Summary AuthSummary `json:"summary"`
}
DomainAuth is the full authentication check of one sending domain.
func CheckDomain ¶
func CheckDomain(ctx context.Context, r Resolver, domain string, reqs []Requirement) DomainAuth
CheckDomain runs every authentication check for a sending domain against the records its providers require.
type Listing ¶
type Listing struct {
List Blocklist `json:"list"`
Asset string `json:"asset"`
Listed bool `json:"listed"`
// Codes are the list's answers ("127.0.0.2"); the code says why.
Codes []string `json:"codes,omitempty"`
// Reason is the list's TXT explanation, when it publishes one.
Reason string `json:"reason,omitempty"`
Err error `json:"-"`
}
Listing is the result of one asset on one list.
func CheckAll ¶
func CheckAll(ctx context.Context, r Resolver, lists []Blocklist, assets []Asset, concurrency int, timeout time.Duration, progress func(done, total int)) []Listing
CheckAll looks up every asset on every list that applies, at most concurrency at a time, each with its own timeout. progress (optional) is called after each answer with the number done and the total.
type MailFrom ¶
type MailFrom struct {
Domain string `json:"domain"`
FromDomain string `json:"fromDomain"`
Status string `json:"status"` // aligned, misaligned, missing, error
// Alignment under relaxed (default) DMARC SPF alignment.
Aligned bool `json:"aligned"`
// MX is true when bounces can be received (MX, or a CNAME to the provider).
MX bool `json:"mx"`
SPF string `json:"spf"`
Error string `json:"error,omitempty"`
}
MailFrom is the result of checking a custom MAIL FROM (return-path) domain against the From domain it sends for.
type Options ¶
type Options struct {
// Servers are resolvers as host or host:port. Empty means the system's
// resolvers from /etc/resolv.conf. Public resolvers (1.1.1.1, 8.8.8.8)
// work for authentication checks but are refused by Spamhaus and URIBL,
// so DNSBL lookups need your own recursive resolver.
Servers []string
// Timeout per query and server (default 4 s).
Timeout time.Duration
}
Options configures Client.
type RecordCheck ¶
type RecordCheck struct {
Requirement
Status string `json:"status"`
// Found is what DNS returned when it differs from the requirement.
Found string `json:"found,omitempty"`
}
RecordCheck is the live status of one required record.
func VerifyRecord ¶
func VerifyRecord(ctx context.Context, r Resolver, req Requirement) RecordCheck
VerifyRecord checks one required record against DNS: a CNAME must point to the value, a TXT record must contain it, an MX must name the host.
type Requirement ¶
type Requirement struct {
ProviderID string `json:"providerId,omitempty"`
// Purpose is dkim, spf, return_path, dmarc or verification.
Purpose string `json:"purpose"`
Type string `json:"type"` // CNAME, TXT, MX
Name string `json:"name"`
Value string `json:"value"`
}
Requirement is a DNS record a sending provider needs for a domain (the records its DomainManager returns, stored on the sending domain).
type Resolver ¶
type Resolver interface {
// TXT returns one string per TXT record (multi-string records joined).
TXT(ctx context.Context, name string) ([]string, error)
// CNAME returns the target of the CNAME at name, without the trailing dot.
CNAME(ctx context.Context, name string) (string, error)
MX(ctx context.Context, name string) ([]MX, error)
A(ctx context.Context, name string) ([]netip.Addr, error)
AAAA(ctx context.Context, name string) ([]netip.Addr, error)
// PTR returns the reverse DNS names of ip, without trailing dots.
PTR(ctx context.Context, ip netip.Addr) ([]string, error)
}
Resolver looks up DNS records. Names may omit the trailing dot. Implementations return an error wrapping ErrNotFound when the name does not exist (NXDOMAIN) or has no record of the asked type (NODATA).
func NewResolver ¶
NewResolver returns a Client for the configured servers, or the system resolver of the Go standard library when no server is configured and /etc/resolv.conf is unavailable (Windows).
type ReverseDNS ¶
type ReverseDNS struct {
IP string `json:"ip"`
PTR string `json:"ptr,omitempty"`
Status string `json:"status"` // pass, fail (doesn't resolve back), missing, error
// Matches is true when PTR resolves back to IP.
Matches bool `json:"matches"`
Error string `json:"error,omitempty"`
}
ReverseDNS is the forward-confirmed reverse DNS (FCrDNS) of an IP: its PTR name, and whether that name resolves back to the same IP. Mailbox providers expect sending IPs to pass this check.
func CheckReverseDNS ¶
CheckReverseDNS looks up the PTR of ip and confirms it forward.
type SPF ¶
type SPF struct {
Domain string `json:"domain"`
Status string `json:"status"`
Record string `json:"record,omitempty"`
// All is the final "all" mechanism with its qualifier: "-all", "~all"…
All string `json:"all,omitempty"`
// Lookups counts DNS-querying terms, including nested includes (max 10).
Lookups int `json:"lookups"`
Includes []string `json:"includes,omitempty"`
IP4 []string `json:"ip4,omitempty"`
IP6 []string `json:"ip6,omitempty"`
Error string `json:"error,omitempty"`
}
SPF is the result of checking a domain's SPF record.
type Zone ¶
type Zone struct {
// contains filtered or unexported fields
}
Zone is an in-memory Resolver: tests describe the DNS they need, and the demo answers for its sample domains without touching the network. Names are case-insensitive. A name with no records of any type is NXDOMAIN; a name with other records is NODATA. CNAMEs are followed for other types.
func (*Zone) Add ¶
Add adds a record: Add("news.acme.io", "TXT", "v=spf1 -all"). For MX the value is "10 host"; for PTR the name is the IP address ("203.0.113.25").