Skip to content

Secure, Fast, and Extensible Sandbox runtime for AI agents.

25.9 KB
Raw Blame
// Copyright 2026 The OpenSandbox Authors
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//     http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

package dnsproxy

import (
	"context"
	"fmt"
	"net"
	"net/netip"
	"os"
	"strconv"
	"strings"
	"sync"
	"sync/atomic"
	"time"

	"github.com/miekg/dns"

	"github.com/alibaba/opensandbox/egress/pkg/constants"
	"github.com/alibaba/opensandbox/egress/pkg/events"
	"github.com/alibaba/opensandbox/egress/pkg/log"
	"github.com/alibaba/opensandbox/egress/pkg/nftables"
	"github.com/alibaba/opensandbox/egress/pkg/policy"
	"github.com/alibaba/opensandbox/egress/pkg/telemetry"
	slogger "github.com/alibaba/opensandbox/internal/logger"
	"github.com/alibaba/opensandbox/internal/safego"
)

const defaultListenAddr = "127.0.0.1:15353"

type Proxy struct {
	policyMu                sync.RWMutex
	userPolicy              *policy.NetworkPolicy
	effectivePolicy         *policy.NetworkPolicy
	alwaysDeny              []policy.EgressRule
	alwaysAllow             []policy.EgressRule
	listenAddr              string
	upstreams               []string // ordered resolver chain from discovery (immutable after New)
	upstreamMu              sync.RWMutex
	activeUpstreams         []string // healthy subset; same order as upstreams; used for forwarding
	upstreamProbeName       string   // wire name for probe (FQDN or "." for root)
	upstreamProbeQType      uint16   // dns.TypeA or dns.TypeNS etc.
	upstreamProbeInterval   time.Duration
	upstreamExchangeTimeout time.Duration
	servers                 []*dns.Server
	shutdownOnce            sync.Once

	// When set, called synchronously for allowed A/AAAA answers (dns+nft: program nft before client connects).
	onResolved func(domain string, ips []nftables.ResolvedIP)

	// infraDomains maps normalized infra FQDNs to their resolved-IP callback.
	// These names resolve without sandbox policy evaluation and bypass
	// onResolved, so their IPs never land in the sandbox allow sets.
	infraDomains map[string]func(domain string, ips []nftables.ResolvedIP)
	// Optional: async fan-out for denied lookups (e.g. webhook).
	blockedBroadcaster *events.Broadcaster

	// queryPolicySelector, when set, resolves the per-query policy (and
	// per-query resolved-IP callback) from the client's source address. This
	// is the fast-sandbox-profile dispatch seam: one shared listener, N
	// subject policies. nil keeps the single-policy behavior unchanged. A nil
	// result denies the query (fail closed); the returned denyReason carries
	// the selector's actual reason for the denial log.
	queryPolicySelector func(remoteAddr netip.Addr) (*QueryPolicy, string)

	// Hosts whose successful outbound DNS log line should be suppressed (audit
	// errors are still logged). Loaded once at startup; nil means "log all".
	logSkip atomic.Pointer[policy.DomainSet]
}

// New constructs the DNS proxy: discovers upstreams, default listen 127.0.0.1:15353 if listenAddr is "".
// alwaysDeny/alwaysAllow are merged via policy.MergeAlwaysOverlay; they are file/operator rules, not persisted by POST /policy.
func New(p *policy.NetworkPolicy, listenAddr string, alwaysDeny, alwaysAllow []policy.EgressRule) (*Proxy, error) {
	if listenAddr == "" {
		listenAddr = defaultListenAddr
	}
	if p == nil {
		p = policy.DefaultDenyPolicy()
	}
	upstreams, err := DiscoverUpstreams()
	if err != nil {
		return nil, err
	}
	probeName, probeQType := upstreamProbeFromEnv()
	proxy := &Proxy{
		listenAddr:              listenAddr,
		upstreams:               upstreams,
		activeUpstreams:         append([]string(nil), upstreams...),
		upstreamProbeName:       probeName,
		upstreamProbeQType:      probeQType,
		upstreamProbeInterval:   upstreamProbeIntervalFromEnv(),
		upstreamExchangeTimeout: upstreamExchangeTimeoutFromEnv(),
		userPolicy:              ensurePolicyDefaults(p),
		alwaysDeny:              append([]policy.EgressRule(nil), alwaysDeny...),
		alwaysAllow:             append([]policy.EgressRule(nil), alwaysAllow...),
	}
	proxy.refreshEffectivePolicy()
	return proxy, nil
}

func (p *Proxy) refreshEffectivePolicy() {
	p.effectivePolicy = policy.MergeAlwaysOverlay(p.userPolicy, p.alwaysDeny, p.alwaysAllow)
}

func upstreamExchangeTimeoutFromEnv() time.Duration {
	s := strings.TrimSpace(os.Getenv(constants.EnvDNSUpstreamTimeout))
	if s == "" {
		return time.Duration(constants.DefaultDNSUpstreamTimeoutSec) * time.Second
	}
	n, err := strconv.Atoi(s)
	if err != nil || n <= 0 {
		return time.Duration(constants.DefaultDNSUpstreamTimeoutSec) * time.Second
	}
	if n > 120 {
		n = 120
	}
	return time.Duration(n) * time.Second
}

func (p *Proxy) Start(ctx context.Context) error {
	handler := dns.HandlerFunc(p.serveDNS)

	udpServer := &dns.Server{Addr: p.listenAddr, Net: "udp", Handler: handler}
	tcpServer := &dns.Server{Addr: p.listenAddr, Net: "tcp", Handler: handler}
	p.servers = []*dns.Server{udpServer, tcpServer}

	readyCh := make(chan struct{}, len(p.servers))
	errCh := make(chan error, len(p.servers))
	for _, srv := range p.servers {
		s := srv
		s.NotifyStartedFunc = func() { readyCh <- struct{}{} }
		safego.Go(func() {
			if err := s.ListenAndServe(); err != nil {
				errCh <- err
			}
		})
	}

	// Wait for all servers (UDP + TCP) to bind, or fail fast on error.
	for i := 0; i < len(p.servers); i++ {
		select {
		case err := <-errCh:
			return fmt.Errorf("dns proxy failed: %w", err)
		case <-readyCh:
		}
	}

	// The ip6 OUTPUT REDIRECT delivers a query for an IPv6 nameserver to [::1]:<port>; listen there
	// too so a resolv.conf that names an IPv6 resolver keeps working. Best-effort: a host without
	// IPv6 loopback (ipv6.disable=1) simply has no v6 redirect to serve.
	if v6Addr := loopbackV6Addr(p.listenAddr); v6Addr != "" {
		p.startLoopbackV6(v6Addr, handler)
	}

	safego.Go(func() { p.runUpstreamProbes(ctx) })

	return nil
}

// loopbackV6Addr maps the IPv4-loopback listen address to its ::1 twin ("" when listenAddr is not
// 127.0.0.1:<port>, e.g. a test binding an ephemeral address).
func loopbackV6Addr(listenAddr string) string {
	host, port, err := net.SplitHostPort(listenAddr)
	if err != nil || host != "127.0.0.1" {
		return ""
	}
	return net.JoinHostPort("::1", port)
}

func (p *Proxy) startLoopbackV6(addr string, handler dns.Handler) {
	udpServer := &dns.Server{Addr: addr, Net: "udp6", Handler: handler}
	tcpServer := &dns.Server{Addr: addr, Net: "tcp6", Handler: handler}
	readyCh := make(chan struct{}, 2)
	errCh := make(chan error, 2)
	for _, srv := range []*dns.Server{udpServer, tcpServer} {
		s := srv
		s.NotifyStartedFunc = func() { readyCh <- struct{}{} }
		safego.Go(func() {
			if err := s.ListenAndServe(); err != nil {
				errCh <- err
			}
		})
	}
	for i := 0; i < 2; i++ {
		select {
		case err := <-errCh:
			log.Warnf("[dns] IPv6 loopback listener %s unavailable, IPv6 nameservers will not be proxied: %v", addr, err)
			_ = udpServer.Shutdown()
			_ = tcpServer.Shutdown()
			return
		case <-readyCh:
		}
	}
	p.servers = append(p.servers, udpServer, tcpServer)
	log.Infof("[dns] also listening on %s for IPv6 nameserver redirects", addr)
}

// Shutdown stops UDP and TCP DNS listeners. Safe to call more than once.
func (p *Proxy) Shutdown() error {
	var outErr error
	p.shutdownOnce.Do(func() {
		for _, srv := range p.servers {
			if e := srv.Shutdown(); e != nil && outErr == nil {
				outErr = e
			}
		}
	})
	return outErr
}

func (p *Proxy) serveDNS(w dns.ResponseWriter, r *dns.Msg) {
	if len(r.Question) == 0 {
		p.writeReply(w, r, new(dns.Msg), telemetry.DNSReplyStageMalformed)
		return
	}
	q := r.Question[0]
	domain := q.Name
	host := normalizeDNSHost(domain)

	// Infrastructure domains (e.g. a configured upstream CONNECT proxy) resolve
	// outside the sandbox policy and never populate the sandbox allow sets —
	// their answers go to the infra callback, which is UID-scoped in nft. An
	// infra name stays resolvable even under a deny-all policy; reachability
	// remains gated by the uid-scoped nft rule, not by DNS secrecy.
	if cb := p.infraCallback(host); cb != nil {
		p.forwardAndReply(w, r, domain, host, cb)
		return
	}

	policyToEval := p.currentPolicy()
	notifyResolved := p.onResolved
	if sel := p.queryPolicySelector; sel != nil {
		qp, denyReason := sel(requestRemoteAddr(w))
		if qp == nil {
			// Fail closed (NXDOMAIN), never fall back to a default policy
			// that could open the subject. The selector supplies the actual
			// denial reason; the denial is logged here only, in a single
			// layer, so the reason stays accurate and is not duplicated.
			if denyReason == "" {
				denyReason = "unknown source"
			}
			telemetry.RecordDNSDenied()
			log.Warnf("[dns] denied query (remote=%s question=%q reason=%s)",
				requestRemoteAddr(w), host, denyReason)
			resp := new(dns.Msg)
			resp.SetRcode(r, dns.RcodeNameError)
			p.writeReply(w, r, resp, telemetry.DNSReplyStageUnknownSource)
			return
		}
		policyToEval = qp.Policy
		notifyResolved = qp.OnResolved
		if notifyResolved == nil {
			notifyResolved = p.onResolved
		}
	}
	if policyToEval != nil && policyToEval.Evaluate(domain) == policy.ActionDeny {
		telemetry.RecordDNSDenied()
		p.publishBlocked(domain)
		log.Warnf("[dns] denied by policy (remote=%s question=%q)",
			requestRemoteAddr(w), host)
		resp := new(dns.Msg)
		resp.SetRcode(r, dns.RcodeNameError)
		p.writeReply(w, r, resp, telemetry.DNSReplyStageDeny)
		return
	}

	p.forwardAndReply(w, r, domain, host, notifyResolved)
}

// forwardAndReply resolves r upstream and answers w; a successful answer feeds
// notify (infra callback or the policy's resolved-IP callback) before the
// reply is written, so nft programming lands before the client can dial.
func (p *Proxy) forwardAndReply(w dns.ResponseWriter, r *dns.Msg, domain, host string, notify func(string, []nftables.ResolvedIP)) {
	start := time.Now()
	resp, failure, err := p.forward(r, upstreamNetwork(w))
	elapsed := time.Since(start).Seconds()
	if err != nil {
		telemetry.RecordDNSForward(elapsed)
		telemetry.RecordDNSQueryFailed(failure)
		logOutboundDNS(host, nil, "", err.Error())
		fail := new(dns.Msg)
		fail.SetRcode(r, dns.RcodeServerFailure)
		p.writeReply(w, r, fail, telemetry.DNSReplyStageUpstreamError)
		return
	}
	telemetry.RecordDNSForward(elapsed)
	if !p.shouldSkipOutboundLog(host) {
		logOutboundDNS(host, resolvedIPStrings(resp), "", "")
	}
	p.maybeNotifyResolvedWith(domain, resp, notify)
	p.writeReply(w, r, resp, telemetry.DNSReplyStageAnswer)
}

// writeReply sends a DNS response and surfaces write failures. A reply can be
// decided and still never reach the client (e.g. the kernel cannot route it
// back to a REDIRECTed flow); until the error was reported, such windows were
// indistinguishable from "query never handled" (issue #1704).
func (p *Proxy) writeReply(w dns.ResponseWriter, r *dns.Msg, resp *dns.Msg, stage string) {
	if err := w.WriteMsg(resp); err != nil {
		telemetry.RecordDNSReplyFailed(stage)
		qname := "."
		if len(r.Question) > 0 {
			qname = normalizeDNSHost(r.Question[0].Name)
		}
		log.Warnf("[dns] reply write failed (stage=%s remote=%s question=%q): %v",
			stage, requestRemoteAddr(w), qname, err)
	}
}

// requestRemoteAddr extracts the client IP from a DNS response writer.
func requestRemoteAddr(w dns.ResponseWriter) netip.Addr {
	host, _, err := net.SplitHostPort(w.RemoteAddr().String())
	if err != nil {
		host = w.RemoteAddr().String()
	}
	ip, err := netip.ParseAddr(strings.TrimSpace(host))
	if err != nil {
		return netip.Addr{}
	}
	return ip.Unmap()
}

// currentPolicy returns the single-instance effective policy (sidecar mode).
func (p *Proxy) currentPolicy() *policy.NetworkPolicy {
	p.policyMu.RLock()
	defer p.policyMu.RUnlock()
	return p.effectivePolicy
}

// QueryPolicy carries the per-query policy and the per-subject resolved-IP
// callback selected by SetQueryPolicySelector. OnResolved may be nil; the
// proxy then falls back to the proxy-wide callback.
type QueryPolicy struct {
	Policy     *policy.NetworkPolicy
	OnResolved func(domain string, ips []nftables.ResolvedIP)
}

// SetQueryPolicySelector installs the per-query policy dispatch (fast-sandbox
// profile). Passing nil restores the single-policy behavior; the selector is
// invoked on the serveDNS goroutine. A nil *QueryPolicy result denies the
// query (fail closed); the returned denyReason describes why and is included
// in the denial log (empty falls back to "unknown source").
func (p *Proxy) SetQueryPolicySelector(sel func(remoteAddr netip.Addr) (*QueryPolicy, string)) {
	p.queryPolicySelector = sel
}

// SetLogSkip replaces the set of hosts whose successful DNS outbound log line
// is suppressed. Passing nil or an empty slice restores the default of logging
// every outbound. Safe to call concurrently; reads use an atomic pointer.
func (p *Proxy) SetLogSkip(patterns []string) {
	p.logSkip.Store(policy.NewDomainSet(patterns))
}

func (p *Proxy) shouldSkipOutboundLog(host string) bool {
	ds := p.logSkip.Load()
	if ds == nil || ds.Empty() {
		return false
	}
	return ds.Match(host)
}

// maybeNotifyResolvedWith calls the per-query resolved callback (falling back
// to the proxy-wide one) before w.WriteMsg so dynamic nft allows are installed
// before the client receives the answer and may open a connection.
func (p *Proxy) maybeNotifyResolvedWith(domain string, resp *dns.Msg, fn func(string, []nftables.ResolvedIP)) {
	if fn == nil {
		return
	}
	ips := extractResolvedIPs(resp)
	if len(ips) == 0 {
		return
	}
	fn(domain, ips)
}

// maybeNotifyResolved calls the proxy-wide resolved callback.
func (p *Proxy) maybeNotifyResolved(domain string, resp *dns.Msg) {
	p.maybeNotifyResolvedWith(domain, resp, p.onResolved)
}

// forward returns the response, or the bounded failure reason (a telemetry.DNSFailure*
// constant) alongside the error. The reason is what the last attempted upstream failed
// with: the loop keeps trying, so only the final outcome is reported.
func (p *Proxy) forward(r *dns.Msg, network string) (*dns.Msg, string, error) {
	return p.forwardContext(context.Background(), r, network)
}

// upstreamNetwork returns the transport the client used, to forward its query
// over the same one. A client retries over TCP after a truncated UDP answer,
// and only a TCP exchange with the upstream returns that answer in full.
func upstreamNetwork(w dns.ResponseWriter) string {
	if _, ok := w.RemoteAddr().(*net.TCPAddr); ok {
		return "tcp"
	}
	return "udp"
}

func (p *Proxy) ResolveDomain(ctx context.Context, domain string) ([]nftables.ResolvedIP, error) {
	var ips []nftables.ResolvedIP
	var nameError bool
	for _, queryType := range []uint16{dns.TypeA, dns.TypeAAAA} {
		query := new(dns.Msg)
		query.SetQuestion(dns.Fqdn(domain), queryType)
		response, _, err := p.forwardContext(ctx, query, "udp")
		if err != nil {
			return nil, err
		}
		if response.Truncated {
			return nil, fmt.Errorf("truncated DNS response for %q", domain)
		}
		if response.Rcode == dns.RcodeNameError {
			nameError = true
			continue
		}
		ips = append(ips, extractResolvedIPs(response)...)
	}
	if nameError {
		if len(ips) > 0 {
			return nil, fmt.Errorf("inconsistent NXDOMAIN for %q with %d addresses", domain, len(ips))
		}
		return nil, nil
	}
	return ips, nil
}

func (p *Proxy) forwardContext(ctx context.Context, r *dns.Msg, network string) (*dns.Msg, string, error) {
	list := p.forwardUpstreams()
	var lastErr error
	lastFailure := telemetry.DNSFailureNoUpstreams
	for _, upstream := range list {
		if err := ctx.Err(); err != nil {
			return nil, telemetry.DNSFailureUpstreamError, err
		}
		const upstreamUDPSize = 4096
		query := r.Copy()
		if query.IsEdns0() == nil {
			query.SetEdns0(upstreamUDPSize, false)
		}
		c := &dns.Client{
			Net:     network,
			Timeout: p.upstreamExchangeTimeout,
			Dialer:  p.dialerForUpstream(upstream),
			UDPSize: upstreamUDPSize,
		}
		resp, _, err := c.ExchangeContext(ctx, query, upstream)
		if err != nil {
			lastErr = err
			lastFailure = telemetry.DNSFailureUpstreamError
			log.Warnf("[dns] upstream %s exchange error: %v", upstream, err)
			continue
		}
		if resp == nil {
			lastErr = fmt.Errorf("nil response from %s", upstream)
			lastFailure = telemetry.DNSFailureEmptyResponse
			continue
		}
		if tryNext, reason := p.shouldFailoverAfterResponse(resp); tryNext {
			lastErr = fmt.Errorf("%s from %s", reason, upstream)
			lastFailure = telemetry.DNSFailureRcode
			log.Warnf("[dns] upstream %s: %s; trying next", upstream, reason)
			continue
		}
		return resp, "", nil
	}
	if lastErr != nil {
		return nil, lastFailure, lastErr
	}
	return nil, telemetry.DNSFailureNoUpstreams, fmt.Errorf("no upstream resolvers configured")
}

// shouldFailoverAfterResponse: treat NXDOMAIN and NOERROR as final (no retry). Other rcodes may
// move to the next upstream (e.g. SERVFAIL).
func (p *Proxy) shouldFailoverAfterResponse(resp *dns.Msg) (tryNext bool, reason string) {
	if resp == nil {
		return true, "nil response"
	}
	switch resp.Rcode {
	case dns.RcodeNameError:
		return false, ""
	case dns.RcodeSuccess:
		return false, ""
	default:
		rcStr := dns.RcodeToString[resp.Rcode]
		if rcStr == "" {
			rcStr = fmt.Sprintf("rcode %d", resp.Rcode)
		}
		return true, rcStr
	}
}

// UpdatePolicy replaces the user policy from POST/GET /policy (not the always file overlay). Nil → default deny-all.
func (p *Proxy) UpdatePolicy(newPolicy *policy.NetworkPolicy) {
	p.policyMu.Lock()
	defer p.policyMu.Unlock()

	p.userPolicy = ensurePolicyDefaults(newPolicy)
	p.refreshEffectivePolicy()
}

// UpdateAlwaysRules replaces the always-deny/always-allow file overlay used only for evaluation (merged in refreshEffectivePolicy).
func (p *Proxy) UpdateAlwaysRules(alwaysDeny, alwaysAllow []policy.EgressRule) {
	p.policyMu.Lock()
	defer p.policyMu.Unlock()

	p.alwaysDeny = append([]policy.EgressRule(nil), alwaysDeny...)
	p.alwaysAllow = append([]policy.EgressRule(nil), alwaysAllow...)
	p.refreshEffectivePolicy()
}

// CurrentPolicy is the last user policy from the API, without always file overlay in the struct (overlay is in effectivePolicy).
func (p *Proxy) CurrentPolicy() *policy.NetworkPolicy {
	p.policyMu.RLock()
	defer p.policyMu.RUnlock()

	return p.userPolicy
}

// SetInfraDomain registers an infrastructure FQDN that resolves without
// sandbox policy evaluation. Answers are reported to onResolved (UID-scoped
// nft programming) instead of the sandbox dyn-allow sets. Register before
// Start; onResolved may be nil when only reachability — not set updates — is
// needed.
func (p *Proxy) SetInfraDomain(domain string, onResolved func(domain string, ips []nftables.ResolvedIP)) {
	host := normalizeDNSHost(domain)
	if host == "" {
		return
	}
	if p.infraDomains == nil {
		p.infraDomains = make(map[string]func(string, []nftables.ResolvedIP))
	}
	if onResolved == nil {
		onResolved = func(string, []nftables.ResolvedIP) {}
	}
	p.infraDomains[host] = onResolved
}

// infraCallback returns the infra-domain callback for host, or nil.
func (p *Proxy) infraCallback(host string) func(string, []nftables.ResolvedIP) {
	if p.infraDomains == nil {
		return nil
	}
	return p.infraDomains[host]
}

// SetOnResolved registers the dns+nft path (nil in dns-only). Invoked on the same goroutine as serveDNS, before WriteMsg.
func (p *Proxy) SetOnResolved(fn func(domain string, ips []nftables.ResolvedIP)) {
	p.onResolved = fn
}

// SetBlockedBroadcaster wires the optional publisher for policy-denied lookups.
func (p *Proxy) SetBlockedBroadcaster(b *events.Broadcaster) {
	p.blockedBroadcaster = b
}

func (p *Proxy) publishBlocked(domain string) {
	if p.blockedBroadcaster == nil {
		return
	}
	normalized := strings.ToLower(strings.TrimSuffix(domain, "."))
	if normalized == "" {
		return
	}

	p.blockedBroadcaster.Publish(events.BlockedEvent{
		Hostname:  normalized,
		Timestamp: time.Now().UTC(),
	})
}

// extractResolvedIPs collects A/AAAA from resp.Answer with TTLs for dynamic nft elements.
func extractResolvedIPs(resp *dns.Msg) []nftables.ResolvedIP {
	if resp == nil || len(resp.Answer) == 0 {
		return nil
	}

	var out []nftables.ResolvedIP
	for _, rr := range resp.Answer {
		switch v := rr.(type) {
		case *dns.A:
			if v.A == nil {
				continue
			}
			addr, err := netip.ParseAddr(v.A.String())
			if err != nil {
				continue
			}
			out = append(out, nftables.ResolvedIP{Addr: addr, TTL: time.Duration(v.Hdr.Ttl) * time.Second})
		case *dns.AAAA:
			if v.AAAA == nil {
				continue
			}
			addr, err := netip.ParseAddr(v.AAAA.String())
			if err != nil {
				continue
			}
			out = append(out, nftables.ResolvedIP{Addr: addr, TTL: time.Duration(v.Hdr.Ttl) * time.Second})
		}
	}
	return out
}

const fallbackUpstream = "8.8.8.8:53"

// DiscoverUpstreams is env OPENSANDBOX_EGRESS_DNS_UPSTREAM if set, else /etc/resolv.conf (with caps/fallbacks).
func DiscoverUpstreams() ([]string, error) {
	raw := strings.TrimSpace(os.Getenv(constants.EnvDNSUpstream))
	if raw != "" {
		return parseEnvDNSUpstreams(raw)
	}
	return discoverUpstreamsFromResolv()
}

// parseEnvDNSUpstreams splits OPENSANDBOX_EGRESS_DNS_UPSTREAM (comma-separated); each entry must pass normalizeEnvUpstreamAddr.
func parseEnvDNSUpstreams(raw string) ([]string, error) {
	var out []string
	for _, part := range strings.Split(raw, ",") {
		part = strings.TrimSpace(part)
		if part == "" {
			continue
		}
		addr, err := normalizeEnvUpstreamAddr(part)
		if err != nil {
			return nil, fmt.Errorf("%s: %w", constants.EnvDNSUpstream, err)
		}
		out = append(out, addr)
	}
	if len(out) == 0 {
		return nil, fmt.Errorf("%s must list at least one upstream resolver", constants.EnvDNSUpstream)
	}
	return dedupeUpstreamAddrs(out), nil
}

// normalizeEnvUpstreamAddr requires a literal IP (optional :port). Resolving a hostname to :53 would hit
// OUTPUT REDIRECT to this proxy again and recurse.
func normalizeEnvUpstreamAddr(s string) (string, error) {
	s = strings.TrimSpace(s)
	if s == "" {
		return "", fmt.Errorf("empty upstream address")
	}
	if host, port, err := net.SplitHostPort(s); err == nil {
		if port == "" {
			return "", fmt.Errorf("invalid port in %q", s)
		}
		if _, err := netip.ParseAddr(host); err != nil {
			return "", fmt.Errorf("host %q must be a literal IP address, not a hostname (avoids DNS self-recursion with REDIRECT)", host)
		}
		return net.JoinHostPort(host, port), nil
	}
	if strings.HasPrefix(s, "[") {
		if !strings.HasSuffix(s, "]") {
			return "", fmt.Errorf("invalid bracketed IPv6 %q", s)
		}
		inner := strings.TrimPrefix(strings.TrimSuffix(s, "]"), "[")
		if _, err := netip.ParseAddr(inner); err != nil {
			return "", fmt.Errorf("invalid IP inside brackets %q", s)
		}
		return net.JoinHostPort(inner, "53"), nil
	}
	addr, err := netip.ParseAddr(s)
	if err != nil {
		return "", fmt.Errorf("upstream %q must be a literal IP address, not a hostname: %w", s, err)
	}
	return net.JoinHostPort(addr.String(), "53"), nil
}

func discoverUpstreamsFromResolv() ([]string, error) {
	cfg, err := dns.ClientConfigFromFile("/etc/resolv.conf")
	if err != nil || len(cfg.Servers) == 0 {
		if err != nil {
			log.Warnf("[dns] fallback upstream resolver due to error: %v", err)
		}
		return []string{fallbackUpstream}, nil
	}
	port := cfg.Port
	if port == "" {
		port = "53"
	}
	var nonLoop, loop []string
	for _, s := range cfg.Servers {
		addr := net.JoinHostPort(s, port)
		if ip := net.ParseIP(s); ip != nil && ip.IsLoopback() {
			loop = append(loop, addr)
			continue
		}
		nonLoop = append(nonLoop, addr)
	}
	out := append(nonLoop, loop...)
	if len(out) == 0 {
		out = []string{net.JoinHostPort(cfg.Servers[0], port)}
	}
	if len(out) > constants.ResolvNameserverCap {
		out = out[:constants.ResolvNameserverCap]
	}
	return dedupeUpstreamAddrs(out), nil
}

func dedupeUpstreamAddrs(addrs []string) []string {
	seen := make(map[string]struct{}, len(addrs))
	var out []string
	for _, a := range addrs {
		if _, ok := seen[a]; ok {
			continue
		}
		seen[a] = struct{}{}
		out = append(out, a)
	}
	return out
}

// AllowIPsFromUpstreamAddrs collects literal resolver IPs from the host:port upstream list (nft allow, deduped).
func AllowIPsFromUpstreamAddrs(upstreams []string) []netip.Addr {
	var out []netip.Addr
	seen := make(map[netip.Addr]struct{})
	for _, a := range upstreams {
		host, _, err := net.SplitHostPort(a)
		if err != nil {
			continue
		}
		ip, err := netip.ParseAddr(host)
		if err != nil {
			continue
		}
		if _, ok := seen[ip]; ok {
			continue
		}
		seen[ip] = struct{}{}
		out = append(out, ip)
	}
	return out
}

// ResolvNameserverIPs parses resolvPath nameserver lines; used to allow the system resolver IPs in nft
// and align client vs. proxy forward path.
func ResolvNameserverIPs(resolvPath string) ([]netip.Addr, error) {
	cfg, err := dns.ClientConfigFromFile(resolvPath)
	if err != nil || len(cfg.Servers) == 0 {
		return nil, nil
	}
	var out []netip.Addr
	for _, s := range cfg.Servers {
		ip, err := netip.ParseAddr(s)
		if err != nil {
			continue
		}
		out = append(out, ip)
	}
	return out, nil
}

func normalizeDNSHost(domain string) string {
	return strings.ToLower(strings.TrimSuffix(domain, "."))
}

func resolvedIPStrings(resp *dns.Msg) []string {
	ri := extractResolvedIPs(resp)
	if len(ri) == 0 {
		return nil
	}
	out := make([]string, 0, len(ri))
	for _, x := range ri {
		out = append(out, x.Addr.String())
	}
	return out
}

func logOutboundDNS(host string, ips []string, peer string, errStr string) {
	fields := []slogger.Field{
		{Key: "opensandbox.event", Value: "egress.outbound"},
	}
	if host != "" {
		fields = append(fields, slogger.Field{Key: "target.host", Value: host})
	}
	if peer != "" {
		fields = append(fields, slogger.Field{Key: "peer", Value: peer})
	}
	if len(ips) > 0 {
		fields = append(fields, slogger.Field{Key: "target.ips", Value: ips})
	}
	if errStr != "" {
		fields = append(fields, slogger.Field{Key: "error", Value: errStr})
	}
	log.Logger.With(fields...).Infof("egress outbound")
}

func ensurePolicyDefaults(p *policy.NetworkPolicy) *policy.NetworkPolicy {
	if p == nil {
		return policy.DefaultDenyPolicy()
	}
	if p.DefaultAction == "" {
		p.DefaultAction = policy.ActionDeny
	}
	return p
}