Initial commit

2026-04-23 19:37:14 +07:00 · 2026-04-23 19:37:14 +07:00 · 34ce70272a
commit 34ce70272a
18 changed files with 1866 additions and 0 deletions
--- a/checker/collect.go
+++ b/checker/collect.go
@ -0,0 +1,561 @@
+// This file is part of the happyDomain (R) project.
+// Copyright (c) 2026 happyDomain
+// Authors: Pierre-Olivier Mercier, et al.
+
+package checker
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"strings"
+
+	"github.com/miekg/dns"
+
+	sdk "git.happydns.org/checker-sdk-go/checker"
+)
+
+// Collect runs the alias testsuite and returns an *AliasData populated with
+// findings, a resolution chain, and optional coexistence / DNSSEC observations.
+func (p *aliasProvider) Collect(ctx context.Context, opts sdk.CheckerOptions) (any, error) {
+	owner, err := resolveOwner(opts)
+	if err != nil {
+		return nil, err
+	}
+
+	maxChain := sdk.GetIntOption(opts, "maxChainLength", 8)
+	minTTL := uint32(sdk.GetIntOption(opts, "minTargetTTL", 60))
+	requireTarget := sdk.GetBoolOption(opts, "requireResolvableTarget", true)
+	allowApexCNAME := sdk.GetBoolOption(opts, "allowApexCNAME", false)
+	recognizeApex := sdk.GetBoolOption(opts, "recognizeApexFlattening", true)
+
+	data := &AliasData{Owner: owner}
+
+	// 1. Find apex and authoritative servers.
+	apex, servers, err := findApex(ctx, owner)
+	if err != nil {
+		data.Findings = append(data.Findings, AliasFinding{
+			Code:     "alias_no_apex",
+			Severity: SeverityCrit,
+			Message:  fmt.Sprintf("could not locate zone apex of %s: %v", owner, err),
+			Subject:  owner,
+			Hint:     "Check that the parent delegation exists and that the zone is published.",
+		})
+		return data, nil
+	}
+	data.Apex = apex
+	data.AuthServers = servers
+	data.OwnerIsApex = lowerFQDN(owner) == lowerFQDN(apex)
+
+	// 2. Detect DNAME substitutions from owner up to apex (exclusive of apex).
+	data.DNAMESubstitutions = collectDNAMEs(ctx, servers, owner, apex)
+
+	// 3. Walk the CNAME/DNAME chain.
+	chainCtx := &chainCtx{
+		data:         data,
+		maxLen:       maxChain,
+		minTTL:       minTTL,
+		servers:      servers,
+		apex:         apex,
+		seenOwners:   map[string]bool{},
+		recFallback:  systemResolver(),
+		followTarget: requireTarget,
+	}
+	chainCtx.walk(ctx, owner)
+
+	// 4. Apex checks (flattening, CNAME-at-apex coexistence).
+	if data.OwnerIsApex {
+		checkApex(ctx, data, servers, apex, allowApexCNAME, recognizeApex)
+	}
+
+	// 5. Coexistence at owner (applies at any level, not just apex).
+	checkCoexistence(ctx, data, servers, owner, allowApexCNAME, recognizeApex)
+
+	// 6. DNSSEC checks.
+	checkDNSSEC(ctx, data, servers, apex, owner)
+
+	// 7. Chain-level validations (loops, length, TTL, target resolvability).
+	validateChain(data, maxChain, minTTL, requireTarget)
+
+	return data, nil
+}
+
+// resolveOwner derives the FQDN to check from the auto-filled options. The
+// "service" option takes precedence (it carries a dns.CNAME whose owner is
+// authoritative); otherwise we fall back to subdomain + domain_name.
+func resolveOwner(opts sdk.CheckerOptions) (string, error) {
+	if svcMsg, ok := sdk.GetOption[serviceMessage](opts, "service"); ok && len(svcMsg.Service) > 0 {
+		var c cnameService
+		if err := json.Unmarshal(svcMsg.Service, &c); err == nil && c.Record != nil && c.Record.Hdr.Name != "" {
+			return lowerFQDN(c.Record.Hdr.Name), nil
+		}
+	}
+
+	parent, _ := sdk.GetOption[string](opts, "domain_name")
+	sub, _ := sdk.GetOption[string](opts, "subdomain")
+	if parent == "" {
+		return "", fmt.Errorf("missing 'domain_name' option")
+	}
+	parent = strings.TrimSuffix(parent, ".")
+	if sub == "" || sub == "@" {
+		return lowerFQDN(parent), nil
+	}
+	sub = strings.TrimSuffix(sub, ".")
+	return lowerFQDN(sub + "." + parent), nil
+}
+
+// chainCtx carries the mutable state of a chain walk.
+type chainCtx struct {
+	data         *AliasData
+	maxLen       int
+	minTTL       uint32
+	servers      []string
+	apex         string
+	seenOwners   map[string]bool
+	recFallback  string
+	followTarget bool
+}
+
+// walk follows CNAME/DNAME hops starting from name. It writes hops into
+// data.Chain and may add findings.
+func (c *chainCtx) walk(ctx context.Context, name string) {
+	current := lowerFQDN(name)
+	currentServers := c.servers
+
+	for i := 0; i <= c.maxLen+1; i++ {
+		if c.seenOwners[current] {
+			c.data.Findings = append(c.data.Findings, AliasFinding{
+				Code:     "alias_loop",
+				Severity: SeverityCrit,
+				Message:  fmt.Sprintf("chain loops back to %s", current),
+				Subject:  current,
+				Hint:     "Break the loop by pointing the last CNAME at an A/AAAA-bearing name.",
+			})
+			c.data.FinalTarget = current
+			return
+		}
+		c.seenOwners[current] = true
+
+		if i > c.maxLen {
+			c.data.Findings = append(c.data.Findings, AliasFinding{
+				Code:     "alias_chain_too_long",
+				Severity: SeverityCrit,
+				Message:  fmt.Sprintf("chain exceeds %d hops at %s; many resolvers will give up", c.maxLen, current),
+				Subject:  current,
+				Hint:     "Flatten intermediate CNAMEs so that the chain is at most a few hops long.",
+			})
+			c.data.FinalTarget = current
+			return
+		}
+
+		q := dns.Question{Name: current, Qtype: dns.TypeCNAME, Qclass: dns.ClassINET}
+		r, server, err := c.queryFor(ctx, current, currentServers, q)
+		if err != nil {
+			c.data.Findings = append(c.data.Findings, AliasFinding{
+				Code:     "alias_query_failed",
+				Severity: SeverityWarn,
+				Message:  fmt.Sprintf("CNAME query for %s failed: %v", current, err),
+				Subject:  current,
+			})
+			c.data.FinalTarget = current
+			return
+		}
+
+		if r.Rcode != dns.RcodeSuccess {
+			c.data.Rcode = rcodeText(r.Rcode)
+			sev := SeverityCrit
+			c.data.Findings = append(c.data.Findings, AliasFinding{
+				Code:     "alias_rcode",
+				Severity: sev,
+				Message:  fmt.Sprintf("server answered %s for %s", c.data.Rcode, current),
+				Subject:  current,
+				Hint:     "Ensure the zone publishes the expected record; NXDOMAIN/SERVFAIL mid-chain breaks the alias.",
+			})
+			c.data.FinalTarget = current
+			return
+		}
+
+		cname, synthesizedFromDNAME, ttl := extractCNAME(r, current)
+		if cname == "" {
+			// No CNAME at this name: terminal hop, resolve A/AAAA.
+			c.data.Chain = append(c.data.Chain, ChainHop{
+				Owner:  current,
+				Kind:   KindTarget,
+				Server: server,
+			})
+			c.data.FinalTarget = current
+			c.resolveFinal(ctx, current, currentServers)
+			return
+		}
+
+		target := lowerFQDN(cname)
+		kind := KindCNAME
+		if synthesizedFromDNAME {
+			kind = KindDNAME
+		}
+		c.data.Chain = append(c.data.Chain, ChainHop{
+			Owner:       current,
+			Kind:        kind,
+			Target:      target,
+			TTL:         ttl,
+			Server:      server,
+			Synthesized: synthesizedFromDNAME,
+		})
+		if ttl < c.minTTL {
+			c.data.Findings = append(c.data.Findings, AliasFinding{
+				Code:     "alias_low_ttl",
+				Severity: SeverityWarn,
+				Message:  fmt.Sprintf("hop %s → %s has TTL %ds (< %d)", current, target, ttl, c.minTTL),
+				Subject:  current,
+				Hint:     "Raise the CNAME TTL to improve cache efficiency (5–15 minutes is a common floor).",
+			})
+		}
+
+		// Re-evaluate servers for the next hop: if target leaves the apex,
+		// we need its own authoritative servers. Out-of-zone targets are
+		// resolved via the system resolver (recursive path).
+		if isSubdomain(target, c.apex) {
+			currentServers = c.servers
+		} else {
+			ns, err := resolveZoneNSAddrs(ctx, findZoneOf(ctx, target))
+			if err != nil || len(ns) == 0 {
+				currentServers = []string{c.recFallback}
+			} else {
+				currentServers = ns
+			}
+		}
+		current = target
+	}
+}
+
+// queryFor sends q, retrying via the recursive resolver if the authoritative
+// set is empty (useful for foreign targets).
+func (c *chainCtx) queryFor(ctx context.Context, name string, servers []string, q dns.Question) (*dns.Msg, string, error) {
+	if len(servers) == 0 {
+		r, err := recursiveExchange(ctx, c.recFallback, q)
+		return r, c.recFallback, err
+	}
+	return queryAtAuth(ctx, servers, q)
+}
+
+// extractCNAME returns the first CNAME target matched for owner, and reports
+// whether it was synthesized from a DNAME present in the same response.
+func extractCNAME(r *dns.Msg, owner string) (target string, fromDNAME bool, ttl uint32) {
+	for _, rr := range r.Answer {
+		if c, ok := rr.(*dns.CNAME); ok && strings.EqualFold(dns.Fqdn(c.Hdr.Name), dns.Fqdn(owner)) {
+			target = c.Target
+			ttl = c.Hdr.Ttl
+			break
+		}
+	}
+	if target == "" {
+		return "", false, 0
+	}
+	for _, rr := range r.Answer {
+		if _, ok := rr.(*dns.DNAME); ok {
+			fromDNAME = true
+			break
+		}
+	}
+	return
+}
+
+// resolveFinal fetches A/AAAA of the final target and records them.
+func (c *chainCtx) resolveFinal(ctx context.Context, name string, servers []string) {
+	var r *dns.Msg
+	var err error
+
+	q := dns.Question{Name: dns.Fqdn(name), Qtype: dns.TypeA, Qclass: dns.ClassINET}
+	if len(servers) > 0 {
+		r, _, err = queryAtAuth(ctx, servers, q)
+	} else {
+		r, err = recursiveExchange(ctx, c.recFallback, q)
+	}
+	if err == nil && r != nil {
+		if r.Rcode != dns.RcodeSuccess {
+			c.data.Rcode = rcodeText(r.Rcode)
+		}
+		for _, rr := range r.Answer {
+			if a, ok := rr.(*dns.A); ok {
+				c.data.FinalA = append(c.data.FinalA, a.A.String())
+			}
+		}
+	}
+
+	q.Qtype = dns.TypeAAAA
+	if len(servers) > 0 {
+		r, _, err = queryAtAuth(ctx, servers, q)
+	} else {
+		r, err = recursiveExchange(ctx, c.recFallback, q)
+	}
+	if err == nil && r != nil {
+		for _, rr := range r.Answer {
+			if aaaa, ok := rr.(*dns.AAAA); ok {
+				c.data.FinalAAAA = append(c.data.FinalAAAA, aaaa.AAAA.String())
+			}
+		}
+	}
+}
+
+// findZoneOf walks the labels of name until the system resolver gives it an
+// SOA; used to locate authoritative servers for foreign chain targets.
+func findZoneOf(ctx context.Context, name string) string {
+	apex, _, err := findApex(ctx, name)
+	if err != nil {
+		return ""
+	}
+	return apex
+}
+
+// collectDNAMEs queries every label from owner up to (but excluding) apex for
+// a DNAME record, returning any substitutions found.
+func collectDNAMEs(ctx context.Context, servers []string, owner, apex string) []ChainHop {
+	var out []ChainHop
+	labels := dns.SplitDomainName(owner)
+	apexLabels := dns.SplitDomainName(apex)
+	stop := len(labels) - len(apexLabels)
+	if stop < 0 {
+		stop = 0
+	}
+	for i := 0; i < stop; i++ {
+		name := dns.Fqdn(strings.Join(labels[i:], "."))
+		q := dns.Question{Name: name, Qtype: dns.TypeDNAME, Qclass: dns.ClassINET}
+		r, server, err := queryAtAuth(ctx, servers, q)
+		if err != nil || r == nil || r.Rcode != dns.RcodeSuccess {
+			continue
+		}
+		for _, rr := range r.Answer {
+			if d, ok := rr.(*dns.DNAME); ok {
+				out = append(out, ChainHop{
+					Owner:  lowerFQDN(d.Hdr.Name),
+					Kind:   KindDNAME,
+					Target: lowerFQDN(d.Target),
+					TTL:    d.Hdr.Ttl,
+					Server: server,
+				})
+			}
+		}
+	}
+	return out
+}
+
+// checkApex verifies that a CNAME at apex does not break SOA/NS, and
+// detects ALIAS/ANAME provider-side flattening.
+func checkApex(ctx context.Context, data *AliasData, servers []string, apex string, allowApexCNAME, recognizeApex bool) {
+	// Collect A/AAAA at apex.
+	hasA := false
+	for _, qt := range []uint16{dns.TypeA, dns.TypeAAAA} {
+		q := dns.Question{Name: apex, Qtype: qt, Qclass: dns.ClassINET}
+		r, _, err := queryAtAuth(ctx, servers, q)
+		if err != nil || r == nil {
+			continue
+		}
+		for _, rr := range r.Answer {
+			switch rr.(type) {
+			case *dns.A, *dns.AAAA:
+				hasA = true
+			}
+		}
+	}
+
+	// CNAME at apex?
+	hasCNAME := false
+	for _, h := range data.Chain {
+		if h.Kind == KindCNAME && lowerFQDN(h.Owner) == lowerFQDN(apex) {
+			hasCNAME = true
+			break
+		}
+	}
+
+	if hasCNAME {
+		sev := SeverityCrit
+		if allowApexCNAME {
+			sev = SeverityWarn
+		}
+		data.Findings = append(data.Findings, AliasFinding{
+			Code:     "alias_cname_at_apex",
+			Severity: sev,
+			Message:  fmt.Sprintf("CNAME at apex %s conflicts with the SOA/NS records a zone apex must carry (RFC 1912 §2.4)", apex),
+			Subject:  apex,
+			Hint:     "Use the provider's ALIAS/ANAME flattening, an HTTP redirect, or move content to a sub-label such as www.",
+		})
+	}
+
+	if hasA && !hasCNAME {
+		// A present at apex alongside SOA/NS — classic ALIAS/ANAME flattening.
+		data.ApexFlattening = true
+		if recognizeApex {
+			data.Findings = append(data.Findings, AliasFinding{
+				Code:     "alias_apex_flattening",
+				Severity: SeverityInfo,
+				Message:  fmt.Sprintf("apex %s serves A/AAAA directly (provider-side ALIAS/ANAME flattening)", apex),
+				Subject:  apex,
+				Hint:     "Keep the upstream target's TTL in mind: apex A/AAAA will only update as fast as the provider re-flattens.",
+			})
+		}
+	}
+}
+
+// checkCoexistence verifies that a CNAME at owner is the only record type
+// present (RFC 1034 §3.6.2, RFC 2181 §10.1).
+func checkCoexistence(ctx context.Context, data *AliasData, servers []string, owner string, allowApexCNAME, recognizeApex bool) {
+	hasCNAME := false
+	for _, h := range data.Chain {
+		if h.Kind == KindCNAME && lowerFQDN(h.Owner) == lowerFQDN(owner) {
+			hasCNAME = true
+			break
+		}
+	}
+	if !hasCNAME {
+		return
+	}
+
+	// Query a handful of common sibling types at owner.
+	siblings := []uint16{
+		dns.TypeA, dns.TypeAAAA, dns.TypeMX, dns.TypeTXT,
+		dns.TypeNS, dns.TypeSRV, dns.TypeCAA,
+	}
+	seen := map[string]uint32{}
+	for _, qt := range siblings {
+		q := dns.Question{Name: owner, Qtype: qt, Qclass: dns.ClassINET}
+		r, _, err := queryAtAuth(ctx, servers, q)
+		if err != nil || r == nil {
+			continue
+		}
+		// A synthesized CNAME from DNAME will be present in Answer for any
+		// type; only count answers whose owner matches and whose type is qt.
+		for _, rr := range r.Answer {
+			if rr.Header().Rrtype != qt {
+				continue
+			}
+			if !strings.EqualFold(dns.Fqdn(rr.Header().Name), dns.Fqdn(owner)) {
+				continue
+			}
+			seen[dns.TypeToString[qt]] = rr.Header().Ttl
+			break
+		}
+	}
+
+	// Apex with ALIAS/ANAME flattening is a known exception when requested.
+	isApex := lowerFQDN(owner) == lowerFQDN(data.Apex)
+
+	for t, ttl := range seen {
+		// A/AAAA at apex alongside a CNAME is impossible in a standard zone;
+		// a provider may still serve it through flattening. Still report it
+		// as critical — two different owners cannot legally exist.
+		if isApex && (t == "A" || t == "AAAA") && recognizeApex && data.ApexFlattening {
+			continue
+		}
+		sev := SeverityCrit
+		if isApex && !allowApexCNAME == false {
+			sev = SeverityWarn
+		}
+		data.Coexisting = append(data.Coexisting, CoexistingRRset{Type: t, TTL: ttl})
+		data.Findings = append(data.Findings, AliasFinding{
+			Code:     "alias_coexisting_rrset",
+			Severity: sev,
+			Message:  fmt.Sprintf("%s and CNAME both exist at %s (RFC 1034 §3.6.2 / RFC 2181 §10.1)", t, owner),
+			Subject:  owner,
+			Hint:     "Remove the sibling record or move it under a different label; a name cannot simultaneously carry a CNAME and other data.",
+		})
+	}
+}
+
+// checkDNSSEC verifies that, if the zone is signed, the CNAME at owner is
+// properly signed (RRSIG covers it).
+func checkDNSSEC(ctx context.Context, data *AliasData, servers []string, apex, owner string) {
+	qk := dns.Question{Name: apex, Qtype: dns.TypeDNSKEY, Qclass: dns.ClassINET}
+	r, _, err := queryAtAuthTCP(ctx, servers, qk)
+	if err != nil || r == nil || r.Rcode != dns.RcodeSuccess {
+		return
+	}
+	signed := false
+	for _, rr := range r.Answer {
+		if _, ok := rr.(*dns.DNSKEY); ok {
+			signed = true
+			break
+		}
+	}
+	data.ZoneSigned = signed
+	if !signed {
+		return
+	}
+
+	// Query CNAME with DO; check for an RRSIG covering it.
+	q := dns.Question{Name: owner, Qtype: dns.TypeCNAME, Qclass: dns.ClassINET}
+	r, _, err = queryAtAuthTCP(ctx, servers, q)
+	if err != nil || r == nil {
+		return
+	}
+	sawCNAME := false
+	sawSig := false
+	for _, rr := range r.Answer {
+		switch v := rr.(type) {
+		case *dns.CNAME:
+			sawCNAME = true
+		case *dns.RRSIG:
+			if v.TypeCovered == dns.TypeCNAME {
+				sawSig = true
+			}
+		}
+	}
+	if sawCNAME {
+		data.CNAMESigned = sawSig
+		if !sawSig {
+			data.Findings = append(data.Findings, AliasFinding{
+				Code:     "alias_cname_not_signed",
+				Severity: SeverityCrit,
+				Message:  fmt.Sprintf("zone %s is DNSSEC-signed but CNAME at %s has no RRSIG", apex, owner),
+				Subject:  owner,
+				Hint:     "Re-sign the zone or verify your signer covers the alias RRset; unsigned answers in a signed zone SERVFAIL at validating resolvers.",
+			})
+		}
+	}
+}
+
+// validateChain enforces global chain invariants.
+func validateChain(data *AliasData, maxChain int, minTTL uint32, requireTarget bool) {
+	if len(data.Chain) == 0 {
+		return
+	}
+
+	// Target resolvability.
+	if last := data.Chain[len(data.Chain)-1]; last.Kind == KindTarget {
+		if len(data.FinalA) == 0 && len(data.FinalAAAA) == 0 {
+			sev := SeverityWarn
+			if requireTarget {
+				sev = SeverityCrit
+			}
+			rcode := data.Rcode
+			if rcode == "" {
+				rcode = "no A/AAAA"
+			}
+			data.Findings = append(data.Findings, AliasFinding{
+				Code:     "alias_target_unresolvable",
+				Severity: sev,
+				Message:  fmt.Sprintf("final target %s does not resolve to an address (%s)", last.Owner, rcode),
+				Subject:  last.Owner,
+				Hint:     "Point the alias at a name that publishes at least one A or AAAA record, or fix the upstream zone.",
+			})
+		}
+	}
+
+	// Multiple CNAME/DNAME kinds with same owner (malformed zone).
+	seen := map[string]int{}
+	for _, h := range data.Chain {
+		if h.Kind == KindCNAME || h.Kind == KindDNAME {
+			seen[h.Owner]++
+		}
+	}
+	for o, n := range seen {
+		if n > 1 {
+			data.Findings = append(data.Findings, AliasFinding{
+				Code:     "alias_multiple_records",
+				Severity: SeverityCrit,
+				Message:  fmt.Sprintf("%s carries %d CNAME/DNAME records in the chain; only one is legal per owner", o, n),
+				Subject:  o,
+				Hint:     "Keep a single CNAME per name; remove duplicates at the authoritative zone.",
+			})
+		}
+	}
+}