dnscheck

package
v1.4.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 4, 2026 License: AGPL-3.0 Imports: 12 Imported by: 0

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

View Source
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.

View Source
const (
	KindIP     = "ip"
	KindDomain = "domain"
)

Asset kinds checked against blocklists.

View Source
const (
	RecordVerified   = "verified"
	RecordWrongValue = "wrong_value"
	RecordMissing    = "missing"
	RecordError      = "error"
)

Record check statuses (the live verification of one required record).

View Source
const MaxSPFLookups = 10

MaxSPFLookups is the RFC 7208 limit on DNS-querying terms.

Variables

View Source
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.

View Source
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.)

View Source
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

func Aligned(a, b string, strict bool) bool

Aligned reports whether two domains align: identical in strict mode, the same organizational domain in relaxed mode.

func IsNotFound

func IsNotFound(err error) bool

IsNotFound reports whether err means "no such record".

func OrgDomain

func OrgDomain(name string) string

OrgDomain returns the organizational domain (RFC 7489 §3.2) of a name: "news.acme.io" → "acme.io", "mail.example.co.uk" → "example.co.uk".

func Pairs

func Pairs(lists []Blocklist, assets []Asset) [][2]int

Pairs returns the (list, asset) lookups for assets on lists.

Types

type Asset

type Asset struct {
	Name string `json:"name"`
	Kind string `json:"kind"` // KindIP or KindDomain
}

Asset is something checked against blocklists.

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"`
	// 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>.

func CheckBIMI

func CheckBIMI(ctx context.Context, r Resolver, domain string) BIMI

CheckBIMI looks up the default BIMI record of 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).

func (Blocklist) Applies

func (b Blocklist) Applies(a Asset) bool

Applies reports whether the list checks this kind of asset.

func (Blocklist) QueryName

func (b Blocklist) QueryName(asset string) (string, error)

QueryName returns the DNS name to look up asset on the list: reversed octets (or nibbles for IPv6) for IPs, the domain itself 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.

func NewClient

func NewClient(o Options) (*Client, error)

NewClient returns a miekg/dns client for the given servers.

func (*Client) A

func (c *Client) A(ctx context.Context, name string) ([]netip.Addr, error)

A implements Resolver.

func (*Client) AAAA

func (c *Client) AAAA(ctx context.Context, name string) ([]netip.Addr, error)

AAAA implements Resolver.

func (*Client) CNAME

func (c *Client) CNAME(ctx context.Context, name string) (string, error)

CNAME implements Resolver.

func (*Client) MX

func (c *Client) MX(ctx context.Context, name string) ([]MX, error)

MX implements Resolver.

func (*Client) PTR

func (c *Client) PTR(ctx context.Context, ip netip.Addr) ([]string, error)

PTR implements Resolver.

func (*Client) TXT

func (c *Client) TXT(ctx context.Context, name string) ([]string, error)

TXT implements Resolver.

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.

func CheckDKIM

func CheckDKIM(ctx context.Context, r Resolver, selector, domain string) DKIM

CheckDKIM looks up selector._domainkey.domain (following a CNAME to a provider-hosted key) and checks that it publishes a usable key.

type DMARC

type DMARC struct {
	Domain string `json:"domain"`
	// PolicyDomain is where the record was found: the domain itself or its
	// organizational domain (RFC 7489 §6.6.3).
	PolicyDomain string `json:"policyDomain,omitempty"`
	Status       string `json:"status"`
	Record       string `json:"record,omitempty"`
	// Policy applied to Domain: p= or, for a subdomain, sp= when present.
	Policy          string   `json:"policy,omitempty"`
	SubdomainPolicy string   `json:"subdomainPolicy,omitempty"`
	Percent         int      `json:"percent"`
	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

func CheckDMARC(ctx context.Context, r Resolver, domain string) DMARC

CheckDMARC finds the DMARC policy for domain: _dmarc.<domain>, then _dmarc.<organizational domain>.

func (DMARC) Enforced

func (d DMARC) Enforced() bool

Enforced reports whether the policy keeps failing mail out of inboxes.

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.

func Lookup

func Lookup(ctx context.Context, r Resolver, list Blocklist, asset string) Listing

Lookup checks one asset on one list. Not listed is a NXDOMAIN/NODATA answer; errors are returned in Listing.Err and never count as listed.

type MX

type MX struct {
	Host string `json:"host"`
	Pref uint16 `json:"pref"`
}

MX is one mail exchanger.

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.

func CheckMailFrom

func CheckMailFrom(ctx context.Context, r Resolver, mailFrom, fromDomain string, strict bool) MailFrom

CheckMailFrom checks that the MAIL FROM domain aligns with the From domain, can receive bounces and publishes SPF (directly or through a CNAME).

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

func NewResolver(o Options) Resolver

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).

func Overlay

func Overlay(z *Zone, suffixes []string, fallback Resolver) Resolver

Overlay answers names the zone knows (and names under its suffixes) from the zone and everything else from fallback. The demo uses it so the Acme sample domains check clean without real DNS.

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

func CheckReverseDNS(ctx context.Context, r Resolver, ip netip.Addr) ReverseDNS

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.

func CheckSPF

func CheckSPF(ctx context.Context, r Resolver, domain string) SPF

CheckSPF fetches and evaluates the SPF record of domain: exactly one "v=spf1" record, parseable terms and at most 10 DNS lookups.

func (SPF) Covers

func (s SPF) Covers(include string, ip netip.Addr) bool

Covers reports whether the SPF result authorizes a provider: either the include domain (e.g. "amazonses.com") or the IP appears in the record or in anything it includes.

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 NewZone

func NewZone() *Zone

NewZone returns an empty zone.

func (*Zone) A

func (z *Zone) A(_ context.Context, name string) ([]netip.Addr, error)

A implements Resolver.

func (*Zone) AAAA

func (z *Zone) AAAA(_ context.Context, name string) ([]netip.Addr, error)

AAAA implements Resolver.

func (*Zone) Add

func (z *Zone) Add(name, typ, value string) *Zone

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").

func (*Zone) CNAME

func (z *Zone) CNAME(_ context.Context, name string) (string, error)

CNAME implements Resolver.

func (*Zone) Fail

func (z *Zone) Fail(name string) *Zone

Fail makes lookups of name return ErrTemporary.

func (*Zone) Has

func (z *Zone) Has(name string) bool

Has reports whether the zone holds any record for name.

func (*Zone) MX

func (z *Zone) MX(_ context.Context, name string) ([]MX, error)

MX implements Resolver.

func (*Zone) PTR

func (z *Zone) PTR(_ context.Context, ip netip.Addr) ([]string, error)

PTR implements Resolver. PTR records are added under the IP address or its in-addr.arpa / ip6.arpa name.

func (*Zone) TXT

func (z *Zone) TXT(_ context.Context, name string) ([]string, error)

TXT implements Resolver.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL