dmarcator 0.5.1 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d474c30401fa6eddca63e996bfbc7bf2726930386282d12aad8fbbe3f67353bf
-  data.tar.gz: eca8a030b0b6abf0a2ceeaa9c446843f502ec8132f4d409c386e639806e7db69
+  metadata.gz: 50fb6579de6a2c481e5154bd28500cdb8c9800ba6897cd6aa76952c985531f22
+  data.tar.gz: d36d360f6d6cfe6e022cca51af4eec27c03349951c6259b486e178d31d2e32ad
 SHA512:
-  metadata.gz: 0c20cb2c3576c6acce7619b5c20ac0ea3b335a0ae14c6e3f1cb0876f09eb232d559dad8ce9197923c1c0b33828ed1c8e3d63437c7ddc1670828bad8ae0fdf8cf
-  data.tar.gz: bf4fac1cb1c98fcd597424ad913b1e2eb02e5e1fb93f985b21c4a5cbbc8fae87b29aaa83ff73b6edc2c9c40f468be712554a3c6d61ff61e592cbe215d0188805
+  metadata.gz: 8aaea7f0723b6a2eb070345ba516e09b0b6a0391d35c19349eab9791b72ddc06b90f149706c8bf988f3c80784cfe47319577f3c10d190592c482c84320e4962d
+  data.tar.gz: bafee6506fdd045ff918bcbb89a7553fd761bcbbdd91eb274d737dc02d87b14014a5011566799f570197dbc0ffd71cc37872f3cf915eadeda8022c591e594b97

data/ChangeLog.md

@@ -1,3 +1,10 @@
+### 0.6.0 / 2026-10-28
+
+* Add DNS over HTTPS (RFC 8484) and DNS over TLS (RFC 7858) transports, selected with `DMARCATOR_DNS` (`doh` or `dot`). No provider is bundled and plaintext remains the default.
+* Encrypted transports verify TLS certificates, validate the response id, question and TC bit, and follow CNAMEs up to a bounded depth.
+* Add `DMARCator::ResolutionError`; encrypted transport failures raise instead of being reported as a missing record.
+* Add `DMARCator.default_resolver` and `DMARCator::Resolver.build` for explicit transport configuration.
+
 ### 0.5.1 / 2026-10-28
 
 * Point the gem metadata (`homepage`, `source_code_uri`, `bug_tracker_uri`) at the renamed GitHub repository (`dmarc` → `dmarcator`).

data/README.md

@@ -123,6 +123,43 @@ report.records.first.source_ip
 # => "209.85.220.69"
 ```
 
+## DNS transport
+
+By default, DMARC lookups use plain DNS through `Resolv`. Encrypted transports
+can be selected with environment variables; no DNS provider is baked in:
+
+```sh
+# DNS over HTTPS (RFC 8484)
+export DMARCATOR_DNS=doh
+export DMARCATOR_DOH_URL=https://cloudflare-dns.com/dns-query
+export DMARCATOR_DOH_IP=1.1.1.1          # optional: pin the endpoint
+
+# DNS over TLS (RFC 7858)
+export DMARCATOR_DNS=dot
+export DMARCATOR_DOT_SERVER=1.1.1.1:853
+export DMARCATOR_DOT_SNI=cloudflare-dns.com   # optional: name to verify
+
+# optional, both transports (seconds, default 5)
+export DMARCATOR_DNS_TIMEOUT=5
+```
+
+Certificates are always verified. `DMARCATOR_DOH_IP` pins the address so the
+DoH endpoint does not have to be resolved first; TLS still verifies the URL's
+hostname.
+
+Encrypted transports fail closed: a transport failure raises
+`DMARCator::ResolutionError` instead of being reported as a domain without a
+DMARC record. Plaintext is the default because forcing a public resolver breaks
+private and split-horizon zones, and some networks block port 853 or public
+resolvers.
+
+A resolver can also be built explicitly:
+
+```ruby
+resolver = DMARCator::Resolver::DoH.new(url: "https://dns.example/dns-query")
+record   = DMARCator::Record.query("example.com", resolver)
+```
+
 ## Security
 
 DMARC records and XML reports are treated as untrusted input:
@@ -156,6 +193,30 @@ To run the RSpec tests:
 rake spec
 ```
 
+## Releasing
+
+Every published version must have an annotated tag pointing at the commit that
+was built, so a gem can always be traced back to its source:
+
+```sh
+# 1. Bump VERSION in lib/dmarcator/version.rb and add a ChangeLog entry.
+# 2. Commit the release.
+git commit -am "Bump version to X.Y.Z"
+
+# 3. Tag that commit before building anything.
+git tag -a vX.Y.Z -m "dmarcator X.Y.Z"
+
+# 4. Push the commit and its tags.
+git push origin main --follow-tags
+
+# 5. Build and publish from the tagged checkout.
+gem build dmarc.gemspec
+gem push dmarcator-X.Y.Z.gem
+```
+
+Tag before publishing, never after: a tag without a published gem, or a gem
+without a tag, makes the two hard to reconcile later.
+
 ## License
 
 This project is released under the MIT License. See the [LICENSE.txt] file for

data/lib/dmarcator/exceptions.rb

@@ -11,4 +11,15 @@ module DMARCator
   #
   class InvalidReport < StandardError
   end
+
+  #
+  # Raised when an encrypted DNS transport fails to return a usable answer.
+  #
+  # This is deliberately distinct from a missing record: a failed lookup must
+  # not be mistaken for a domain without a DMARC policy.
+  #
+  # @since 0.6.0
+  #
+  class ResolutionError < StandardError
+  end
 end

data/lib/dmarcator/query.rb

@@ -3,6 +3,8 @@
 require 'resolv'
 require 'rubygems'
 
+require_relative 'resolver'
+
 module DMARCator
   #
   # Resolv gem versions affected by CVE-2026-80212 and CVE-2026-80213.
@@ -77,26 +79,45 @@ module DMARCator
     domain
   end
 
+  #
+  # Builds the resolver configured by the environment.
+  #
+  # @return [Resolv::DNS, Resolver::DoH, Resolver::DoT]
+  #
+  # @raise [ArgumentError]
+  #   The configured transport or its settings are invalid.
+  #
+  # @since 0.6.0
+  #
+  def self.default_resolver
+    Resolver.build
+  end
+
   #
   # Queries a domain for the DMARC record.
   #
   # @param [String] domain
   #   The domain to query DMARC for.
   #
-  # @param [Resolv::DNS] resolver
-  #   The resolver to use. Its timeouts are set to {DNS_TIMEOUTS}.
+  # @param [Resolv::DNS, Resolver::DoH, Resolver::DoT] resolver
+  #   The resolver to use. When omitted, one is built from `DMARCATOR_DNS`;
+  #   plaintext resolvers receive {DNS_TIMEOUTS}.
   #
   # @return [String, nil]
   #   The domain's DMARC record or `nil` if none exists.
   #
+  # @raise [Resolver::DoH, Resolver::DoT] resolution errors
+  #   Encrypted transports raise {ResolutionError} when the lookup fails, so
+  #   a transport problem is never reported as a missing record.
+  #
   # @api semipublic
   #
   # @since 0.3.0
   #
-  def self.query(domain,resolver=Resolv::DNS.new)
+  def self.query(domain,resolver=default_resolver)
     validate_domain(domain)
 
-    resolver.timeouts = DNS_TIMEOUTS
+    resolver.timeouts = DNS_TIMEOUTS if resolver.respond_to?(:timeouts=)
 
     host = "_dmarc.#{domain}"
 

data/lib/dmarcator/record.rb

@@ -338,7 +338,7 @@ module DMARCator
     #
     # @api public
     #
-    def self.query(domain,resolver=Resolv::DNS.new)
+    def self.query(domain,resolver=DMARCator.default_resolver)
       if (dmarc = DMARCator.query(domain,resolver))
         parse(dmarc)
       end

data/lib/dmarcator/resolver/doh.rb

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+require 'net/http'
+require 'openssl'
+require 'uri'
+
+require_relative '../exceptions'
+require_relative 'encrypted'
+
+module DMARCator
+  module Resolver
+    #
+    # DNS over HTTPS transport ([RFC 8484]).
+    #
+    # The endpoint is configured by the caller; no provider is assumed. To avoid
+    # needing DNS to reach the DNS server, pass `ipaddr:` (or set
+    # `DMARCATOR_DOH_IP`) to pin the connection while TLS still verifies the
+    # certificate against the URL's hostname.
+    #
+    # [RFC 8484]: https://www.rfc-editor.org/rfc/rfc8484
+    #
+    # @since 0.6.0
+    #
+    class DoH < Encrypted
+      # Default connect/read timeout in seconds.
+      DEFAULT_TIMEOUT = 5
+
+      # @return [URI::HTTPS] the DoH endpoint.
+      attr_reader :url
+
+      # @return [String, nil] the address to connect to instead of resolving
+      #   the endpoint hostname.
+      attr_reader :ipaddr
+
+      # @return [Integer] connect/read timeout in seconds.
+      attr_reader :timeout
+
+      #
+      # Builds a resolver from environment variables.
+      #
+      # @param [Hash] env
+      #
+      # @return [DoH]
+      #
+      # @raise [ArgumentError]
+      #   `DMARCATOR_DOH_URL` is missing or not an HTTPS URL.
+      #
+      def self.from_env(env = ENV)
+        url = env['DMARCATOR_DOH_URL']
+
+        if url.nil? || url.empty?
+          raise ArgumentError, 'DMARCATOR_DNS=doh requires DMARCATOR_DOH_URL'
+        end
+
+        new(
+          url: url,
+          ipaddr: presence(env['DMARCATOR_DOH_IP']),
+          timeout: timeout_from(env)
+        )
+      end
+
+      def self.presence(value)
+        value unless value.nil? || value.empty?
+      end
+
+      def self.timeout_from(env)
+        value = env['DMARCATOR_DNS_TIMEOUT']
+
+        value.nil? || value.empty? ? DEFAULT_TIMEOUT : Integer(value, 10)
+      end
+
+      def initialize(url:, ipaddr: nil, timeout: DEFAULT_TIMEOUT)
+        @url = URI.parse(url)
+
+        unless @url.is_a?(URI::HTTPS) && @url.host
+          raise ArgumentError, "DoH endpoint must be an https URL: #{url.inspect}"
+        end
+
+        @ipaddr = ipaddr
+        @timeout = timeout
+      end
+
+      private
+
+      def exchange(query)
+        http = Net::HTTP.new(@url.host, @url.port)
+        http.use_ssl = true
+        http.verify_mode = OpenSSL::SSL::VERIFY_PEER
+        http.open_timeout = @timeout
+        http.read_timeout = @timeout
+        http.write_timeout = @timeout
+        http.ipaddr = @ipaddr if @ipaddr
+
+        request = Net::HTTP::Post.new(@url.request_uri)
+        request['content-type'] = 'application/dns-message'
+        request['accept'] = 'application/dns-message'
+        request.body = query.encode
+
+        response = http.start { |connection| connection.request(request) }
+
+        status = response.code.to_i
+
+        unless status.between?(200, 299)
+          raise ResolutionError, "DoH endpoint returned HTTP #{status}"
+        end
+
+        response.body.to_s.b
+      rescue ResolutionError
+        raise
+      rescue StandardError => error
+        raise ResolutionError, "DoH request failed: #{error.message}"
+      end
+    end
+  end
+end

data/lib/dmarcator/resolver/dot.rb

@@ -0,0 +1,163 @@
+# frozen_string_literal: true
+
+require 'ipaddr'
+require 'openssl'
+require 'socket'
+
+require_relative '../exceptions'
+require_relative 'encrypted'
+
+module DMARCator
+  module Resolver
+    #
+    # DNS over TLS transport ([RFC 7858]).
+    #
+    # The server is configured by the caller; no provider is assumed. When the
+    # server is an IP literal, TLS still verifies the certificate against that
+    # address, and `sni:` can name a hostname to verify instead.
+    #
+    # [RFC 7858]: https://www.rfc-editor.org/rfc/rfc7858
+    #
+    # @since 0.6.0
+    #
+    class DoT < Encrypted
+      # Default DoT port.
+      DEFAULT_PORT = 853
+
+      # Default connect/read timeout in seconds.
+      DEFAULT_TIMEOUT = 5
+
+      # @return [String] the server host or address.
+      attr_reader :host
+
+      # @return [Integer] the server port.
+      attr_reader :port
+
+      # @return [String] the name to verify the certificate against.
+      attr_reader :sni
+
+      # @return [Integer] connect/read timeout in seconds.
+      attr_reader :timeout
+
+      #
+      # Builds a resolver from environment variables.
+      #
+      # @param [Hash] env
+      #
+      # @return [DoT]
+      #
+      # @raise [ArgumentError]
+      #   `DMARCATOR_DOT_SERVER` is missing or malformed.
+      #
+      def self.from_env(env = ENV)
+        server = env['DMARCATOR_DOT_SERVER']
+
+        if server.nil? || server.empty?
+          raise ArgumentError, 'DMARCATOR_DNS=dot requires DMARCATOR_DOT_SERVER (host[:port])'
+        end
+
+        host, port = split_server(server)
+        sni = env['DMARCATOR_DOT_SNI']
+
+        new(
+          host: host,
+          port: port,
+          sni: sni.nil? || sni.empty? ? nil : sni,
+          timeout: timeout_from(env)
+        )
+      end
+
+      #
+      # Splits `host`, `host:port`, `[v6]`, or `[v6]:port`.
+      #
+      # @param [String] server
+      #
+      # @return [Array(String, Integer)]
+      #
+      # @raise [ArgumentError]
+      #   The value is malformed.
+      #
+      def self.split_server(server)
+        if (match = /\A\[(?<host>[^\]]+)\](?::(?<port>\d+))?\z/.match(server))
+          [match[:host], (match[:port] || DEFAULT_PORT).to_i]
+        elsif (match = /\A(?<host>[^:]+)(?::(?<port>\d+))?\z/.match(server))
+          [match[:host], (match[:port] || DEFAULT_PORT).to_i]
+        else
+          raise ArgumentError, "invalid DMARCATOR_DOT_SERVER: #{server.inspect}"
+        end
+      end
+
+      def self.timeout_from(env)
+        value = env['DMARCATOR_DNS_TIMEOUT']
+
+        value.nil? || value.empty? ? DEFAULT_TIMEOUT : Integer(value, 10)
+      end
+
+      def initialize(host:, port: DEFAULT_PORT, sni: nil, timeout: DEFAULT_TIMEOUT)
+        @host = host
+        @port = port
+        @sni = sni || host
+        @timeout = timeout
+      end
+
+      private
+
+      def exchange(query)
+        wire = query.encode
+
+        with_tls do |socket|
+          socket.write([wire.bytesize].pack('n') + wire)
+
+          header = socket.read(2)
+
+          raise ResolutionError, 'short DoT response' if header.nil? || header.bytesize < 2
+
+          body = socket.read(header.unpack1('n'))
+          raise ResolutionError, 'short DoT response' if body.nil?
+
+          body
+        end
+      rescue ResolutionError
+        raise
+      rescue StandardError => error
+        raise ResolutionError, "DoT request failed: #{error.message}"
+      end
+
+      def with_tls
+        tcp = Socket.tcp(@host, @port, connect_timeout: @timeout)
+        tcp.timeout = @timeout if tcp.respond_to?(:timeout=)
+
+        context = OpenSSL::SSL::SSLContext.new
+        context.verify_mode = OpenSSL::SSL::VERIFY_PEER
+        context.set_params
+
+        socket = OpenSSL::SSL::SSLSocket.new(tcp, context)
+        socket.hostname = @sni unless ip_literal?(@sni)
+        socket.sync_close = true
+        socket.connect
+        socket.post_connection_check(@sni)
+
+        begin
+          yield socket
+        ensure
+          close_quietly(socket)
+          close_quietly(tcp)
+        end
+      end
+
+      def ip_literal?(value)
+        IPAddr.new(value.to_s)
+
+        true
+      rescue IPAddr::Error, ArgumentError
+        false
+      end
+
+      def close_quietly(io)
+        io.close
+      rescue StandardError
+        nil
+      end
+    end
+  end
+end

data/lib/dmarcator/resolver/encrypted.rb

@@ -0,0 +1,131 @@
+# frozen_string_literal: true
+
+require 'resolv'
+
+require_relative '../exceptions'
+
+module DMARCator
+  module Resolver
+    #
+    # Base class for encrypted DNS transports (DoH and DoT).
+    #
+    # Subclasses implement {#exchange}, which sends one encoded DNS query and
+    # returns the encoded response. Everything else - query construction,
+    # response validation and CNAME following - is shared here.
+    #
+    # @abstract
+    #
+    # @since 0.6.0
+    #
+    # @api private
+    #
+    class Encrypted
+      # Maximum number of CNAME indirections to follow.
+      MAX_CNAME_DEPTH = 8
+
+      #
+      # Looks up resource records, matching `Resolv::DNS#getresources`.
+      #
+      # @param [String, Resolv::DNS::Name] name
+      #   The name to look up.
+      #
+      # @param [Class] type
+      #   The resource record type, e.g.
+      #   `Resolv::DNS::Resource::IN::TXT`.
+      #
+      # @return [Array<Resolv::DNS::Resource>]
+      #
+      # @raise [ResolutionError]
+      #   The transport failed or returned an unusable response.
+      #
+      def getresources(name, type)
+        fetch(dns_name(name), type, MAX_CNAME_DEPTH)
+      end
+
+      private
+
+      def dns_name(name)
+        return name if name.is_a?(Resolv::DNS::Name)
+
+        Resolv::DNS::Name.create(name.to_s)
+      end
+
+      def fetch(name, type, depth)
+        id = Random.rand(0x10000)
+        message = decode_response(exchange(build_query(id, name, type)), id, name, type)
+
+        case message.rcode
+        when Resolv::DNS::RCode::NoError
+          collect(message, name, type, depth)
+        when Resolv::DNS::RCode::NXDomain
+          []
+        else
+          raise ResolutionError, "DNS query failed with rcode #{message.rcode}"
+        end
+      end
+
+      def collect(message, name, type, depth)
+        matching = message.answer.select { |_name, _ttl, record| record.is_a?(type) }
+        return matching.map { |_name, _ttl, record| record } unless matching.empty?
+
+        cname = message.answer.find do |_name, _ttl, record|
+          record.is_a?(Resolv::DNS::Resource::IN::CNAME)
+        end
+
+        return fetch(cname[2].name, type, depth - 1) if cname && depth.positive?
+
+        []
+      end
+
+      def build_query(id, name, type)
+        message = Resolv::DNS::Message.new(id)
+        message.rd = 1
+        message.add_question(name, type)
+        message
+      end
+
+      def decode_response(wire, id, name, type)
+        raise ResolutionError, 'empty DNS response' if wire.nil? || wire.empty?
+
+        message = begin
+          Resolv::DNS::Message.decode(wire)
+        rescue StandardError => error
+          raise ResolutionError, "malformed DNS response: #{error.message}"
+        end
+
+        unless message.id == id
+          raise ResolutionError, 'unexpected DNS response (transaction mismatch)'
+        end
+
+        # `Message.decode` returns early for truncated responses, leaving the
+        # remaining header fields unset, so check the TC bit first.
+        raise ResolutionError, 'truncated DNS response' unless message.tc.to_i.zero?
+
+        unless message.qr == 1
+          raise ResolutionError, 'unexpected DNS response (not a response)'
+        end
+
+        question = message.question.first
+
+        unless question && same_name?(question[0], name) && question[1] == type
+          raise ResolutionError, 'unexpected DNS response (question mismatch)'
+        end
+
+        message
+      end
+
+      #
+      # Compares DNS names case-insensitively and ignoring a trailing root dot.
+      # `Resolv::DNS::Name#==` treats `example.com` and `example.com.` as
+      # different, but a decoded response always carries the absolute form.
+      #
+      def same_name?(left, right)
+        normalize_name(left) == normalize_name(right)
+      end
+
+      def normalize_name(value)
+        value.to_s.downcase.chomp('.')
+      end
+    end
+  end
+end

data/lib/dmarcator/resolver.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+require 'resolv'
+
+require_relative 'exceptions'
+require_relative 'resolver/encrypted'
+require_relative 'resolver/doh'
+require_relative 'resolver/dot'
+
+module DMARCator
+  #
+  # Selects the DNS transport used for DMARC lookups.
+  #
+  # The transport is chosen with the `DMARCATOR_DNS` environment variable, or
+  # explicitly via {.build}:
+  #
+  #   DMARCATOR_DNS=plaintext          # default: Resolv::DNS (UDP/TCP)
+  #   DMARCATOR_DNS=doh                # requires DMARCATOR_DOH_URL
+  #   DMARCATOR_DNS=dot                # requires DMARCATOR_DOT_SERVER
+  #
+  # Encrypted transports fail closed: a transport failure raises
+  # {ResolutionError} instead of being reported as "no DMARC record".
+  #
+  # @since 0.6.0
+  #
+  module Resolver
+    # Supported transport names.
+    MODES = %w[plaintext doh dot].freeze
+
+    # Transport used when `DMARCATOR_DNS` is unset.
+    DEFAULT_MODE = 'plaintext'
+
+    #
+    # Reads the configured transport name.
+    #
+    # @param [Hash] env
+    #
+    # @return [String]
+    #
+    def self.mode(env = ENV)
+      value = env['DMARCATOR_DNS']
+
+      value.nil? || value.empty? ? DEFAULT_MODE : value.to_s.strip.downcase
+    end
+
+    #
+    # Builds the configured resolver.
+    #
+    # @param [String, nil] mode
+    #   Overrides the `DMARCATOR_DNS` environment variable.
+    #
+    # @param [Hash] env
+    #
+    # @return [Resolv::DNS, DoH, DoT]
+    #
+    # @raise [ArgumentError]
+    #   The mode or its required settings are invalid.
+    #
+    def self.build(mode: nil, env: ENV)
+      name = (mode || self.mode(env)).to_s.strip.downcase
+
+      case name
+      when 'plaintext'
+        Resolv::DNS.new
+      when 'doh'
+        DoH.from_env(env)
+      when 'dot'
+        DoT.from_env(env)
+      else
+        raise ArgumentError,
+              "unknown DMARCATOR_DNS value: #{name.inspect} " \
+              "(expected one of #{MODES.join(', ')})"
+      end
+    end
+  end
+end

data/lib/dmarcator/version.rb

@@ -2,5 +2,5 @@
 
 module DMARCator
   # dmarcator version
-  VERSION = '0.5.1'
+  VERSION = '0.6.0'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: dmarcator
 version: !ruby/object:Gem::Version
-  version: 0.5.1
+  version: 0.6.0
 platform: ruby
 authors:
 - Noah Berman
@@ -79,6 +79,10 @@ files:
 - lib/dmarcator/report/policy.rb
 - lib/dmarcator/report/reason.rb
 - lib/dmarcator/report/record.rb
+- lib/dmarcator/resolver.rb
+- lib/dmarcator/resolver/doh.rb
+- lib/dmarcator/resolver/dot.rb
+- lib/dmarcator/resolver/encrypted.rb
 - lib/dmarcator/uri.rb
 - lib/dmarcator/version.rb
 - lib/dmarcator/xml_helper.rb