dmarcator 1.2.0 → 1.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 48797112128c5187471c9c2ad1f907c73450cf8ef0f6910e2a22815d74221222
-  data.tar.gz: 89727b4555cc67beddbcb53dbbfb4845dc69e6cb8c66e37b8549fa7a4ec2ec36
+  metadata.gz: 39f655b89bd8e953e40ba9ada0fe936fde9d754acfa93e5825378c8b261034c3
+  data.tar.gz: 19abc3658c2339af30ef478befdb01e5c4ab019d15abdf51c341e53e3ae9da9a
 SHA512:
-  metadata.gz: b6305c8a45f78711592f6a68b61236241d68a45410de08eaeeaa8e158b6337421e9b5d6c78b21ace4b0b38109fa74f3eec198ba4b5bbe6c2a49e5127ff2e69ff
-  data.tar.gz: 20111fdcf9bd38ff20f48a2be10ffdf4aa946850643fca2a48696fa10c041f5b3a4d49d37f6deed32f9767ed758828fce1ade967a8c12fc52cd0c1adc2ede6a2
+  metadata.gz: c64d68c98be76d6611d0a30407172f83dc7ed3c412123745007c21a46ced185d063a62654fd285ad0c81f94ed9d72e468223736aaf2f61024a9d0f345c7b0db8
+  data.tar.gz: 1dab899381cd01d67279ba81a173fec42599e46c585bbed0637e934cf059b8044d55676120ddd0b376c17ceb30bc081b9a773ab8cfae0f94433bca074c39f35c

data/ChangeLog.md

@@ -1,3 +1,18 @@
+### 1.3.0 / 2026-11-01
+
+* Treat report XML as hostile by rejecting DTD and entity declarations outright (`DMARCator::ForbiddenXml`). DMARC reports never need a DTD, so external-entity (XXE) and entity-expansion (billion-laughs) attacks are rejected before parsing rather than merely having their resolution disabled.
+* Parse report XML with an explicit hardening policy: `NONET` on, entity substitution, DTD loading, default DTD attributes and libxml2's `HUGE` relaxation all off, and strict (non-recovering) parsing.
+* Bound report structural complexity with configurable limits enforced by a streaming reader before any DOM is built. Exceeding a limit raises `DMARCator::ReportTooComplex` rather than `InvalidReport`.
+* Add `Config` limits `max_report_records` (10,000), `max_xml_nodes` (100,000), `max_xml_depth` (50), `max_text_length` (1 MiB), `max_xml_attributes` (100,000), `max_auth_results` (100) and `max_reasons` (100).
+* Add `DMARCator::ReportTooComplex` and `DMARCator::ForbiddenXml` error classes (both `DMARCator::Error`).
+
+### 1.2.1 / 2026-10-30
+
+* Add a record-parser corpus regression net: 143 records (published real-world records plus edge cases) with their accepted outcomes in lenient and strict mode, replayed by the test suite. A parser change that alters how any record parses now fails with a diff. Regenerate with `script/generate_record_corpus.rb`.
+* Report a TCP response body shorter than its declared length as `short DNS response (expected N bytes, got M)`, instead of the opaque `malformed DNS response: limit exceeded`.
+
+No public API changes.
+
 ### 1.2.0 / 2026-10-30
 
 * Plaintext lookups now use DNS over TCP (`DMARCator::Resolver::Plain`) instead of `Resolv::DNS`. `Resolv` reads UDP replies into a 512-byte buffer, so a larger answer cannot be decoded, is discarded, and the resulting timeout is swallowed. Any TXT set over 512 bytes — common for SPF and for domains with several DKIM keys — was therefore returned as an empty array, which is indistinguishable from "no records published". TCP has no such limit, and failures raise `ResolutionError`.

data/README.md

@@ -202,6 +202,15 @@ Process-wide defaults can be set from code, and take precedence over the
 DMARCator.configure do |config|
   config.resolver = DMARCator::Resolver::DoH.new(url: "https://dns.example/dns-query")
   config.max_report_bytes = 5 * 1024 * 1024
+
+  # XML report complexity limits (defaults shown)
+  config.max_report_records = 10_000
+  config.max_xml_nodes = 100_000
+  config.max_xml_depth = 50
+  config.max_text_length = 1 * 1024 * 1024
+  config.max_xml_attributes = 100_000
+  config.max_auth_results = 100
+  config.max_reasons = 100
 end
 ```
 
@@ -334,11 +343,26 @@ DMARC records and XML reports are treated as untrusted input. See
 [SECURITY.md](https://github.com/bermannoah/dmarcator/blob/main/SECURITY.md)
 for the reporting policy and scope.
 
-* XML reports are parsed with network access disabled (`NONET`), so external
-  entities are never resolved or fetched.
-* Reports larger than `DMARCator.config.max_report_bytes` (25 MiB by
-  default) are rejected before parsing. Parsing builds a DOM roughly 13× the
-  input size, so lower the limit to bound memory:
+* XML reports are treated as hostile: DTDs and entity declarations are
+  rejected outright (`DMARCator::ForbiddenXml`), and parsing disables network
+  access, entity substitution, DTD loading, and libxml2's `HUGE` relaxation.
+  External-entity (XXE) and entity-expansion (billion-laughs) attacks are
+  therefore impossible rather than merely mitigated.
+* Report structural complexity is bounded before any DOM is built. A report
+  that exceeds a configured limit raises `DMARCator::ReportTooComplex`:
+
+  | Setting | Default | Bounds |
+  |---|---|---|
+  | `max_report_bytes` | 25 MiB | input size |
+  | `max_report_records` | 10,000 | `record` elements |
+  | `max_xml_nodes` | 100,000 | element/text/comment nodes |
+  | `max_xml_depth` | 50 | element nesting depth |
+  | `max_text_length` | 1 MiB | bytes per text node |
+  | `max_xml_attributes` | 100,000 | attribute nodes |
+  | `max_auth_results` | 100 | `auth_results` entries per record |
+  | `max_reasons` | 100 | `reason` entries per record |
+
+  Lower them to bound memory and CPU for reports from untrusted sources:
 
   ```ruby
   DMARCator.configure { |config| config.max_report_bytes = 5 * 1024 * 1024 }
@@ -367,6 +391,21 @@ To run the RSpec tests:
 rake spec
 ```
 
+### Record parser corpus
+
+`spec/support/record_corpus.txt` holds representative records — real-world
+published records and edge cases — and `spec/support/record_corpus.json` the
+outcomes they produced when the corpus was last accepted. The suite replays both
+in lenient and strict mode, so a parser change that alters how any of them parses
+fails with a diff.
+
+If such a change is intentional, regenerate the file and review the JSON diff in
+the commit:
+
+```sh
+ruby -Ilib script/generate_record_corpus.rb
+```
+
 ## Releasing
 
 Every published version must have an annotated tag pointing at the commit that

data/lib/dmarcator/config.rb

@@ -16,6 +16,54 @@ module DMARCator
     #
     DEFAULT_MAX_REPORT_BYTES = 25 * 1024 * 1024
 
+    # Default maximum number of `record` elements accepted in a report.
+    #
+    # @since 1.3.0
+    #
+    DEFAULT_MAX_REPORT_RECORDS = 10_000
+
+    # Default maximum number of XML nodes accepted in a report.
+    #
+    # Counts element, text, CDATA, whitespace, comment and processing
+    # instruction nodes; attributes are counted separately by
+    # {DEFAULT_MAX_XML_ATTRIBUTES}.
+    #
+    # @since 1.3.0
+    #
+    DEFAULT_MAX_XML_NODES = 100_000
+
+    # Default maximum element nesting depth accepted in a report.
+    #
+    # The root element is depth 1.
+    #
+    # @since 1.3.0
+    #
+    DEFAULT_MAX_XML_DEPTH = 50
+
+    # Default maximum length in bytes of any single text node.
+    #
+    # @since 1.3.0
+    #
+    DEFAULT_MAX_TEXT_LENGTH = 1 * 1024 * 1024
+
+    # Default maximum number of attribute nodes accepted in a report.
+    #
+    # @since 1.3.0
+    #
+    DEFAULT_MAX_XML_ATTRIBUTES = 100_000
+
+    # Default maximum number of `auth_results` entries per record.
+    #
+    # @since 1.3.0
+    #
+    DEFAULT_MAX_AUTH_RESULTS = 100
+
+    # Default maximum number of `reason` entries per record.
+    #
+    # @since 1.3.0
+    #
+    DEFAULT_MAX_REASONS = 100
+
     #
     # The default resolver used when a lookup is not given one.
     #
@@ -57,6 +105,78 @@ module DMARCator
 
       @max_report_bytes = value
     end
+
+    #
+    # XML report complexity limits.
+    #
+    # Each accepts a positive Integer or `nil` (to restore the default). A
+    # report that exceeds one of these raises {ReportTooComplex} when parsed.
+    # They bound parser work on hostile input; see {DMARCator::Report}.
+    #
+    # @!method max_report_records
+    #   @return [Integer] the maximum number of `record` elements.
+    # @!method max_report_records=(value)
+    #   @param [Integer, nil] value
+    #   @raise [ArgumentError] the value is not a positive Integer or nil.
+    #
+    # @!method max_xml_nodes
+    #   @return [Integer] the maximum number of XML nodes.
+    # @!method max_xml_nodes=(value)
+    #   @param [Integer, nil] value
+    #   @raise [ArgumentError] the value is not a positive Integer or nil.
+    #
+    # @!method max_xml_depth
+    #   @return [Integer] the maximum element nesting depth (root is 1).
+    # @!method max_xml_depth=(value)
+    #   @param [Integer, nil] value
+    #   @raise [ArgumentError] the value is not a positive Integer or nil.
+    #
+    # @!method max_text_length
+    #   @return [Integer] the maximum text node length in bytes.
+    # @!method max_text_length=(value)
+    #   @param [Integer, nil] value
+    #   @raise [ArgumentError] the value is not a positive Integer or nil.
+    #
+    # @!method max_xml_attributes
+    #   @return [Integer] the maximum number of attribute nodes.
+    # @!method max_xml_attributes=(value)
+    #   @param [Integer, nil] value
+    #   @raise [ArgumentError] the value is not a positive Integer or nil.
+    #
+    # @!method max_auth_results
+    #   @return [Integer] the maximum number of `auth_results` entries per record.
+    # @!method max_auth_results=(value)
+    #   @param [Integer, nil] value
+    #   @raise [ArgumentError] the value is not a positive Integer or nil.
+    #
+    # @!method max_reasons
+    #   @return [Integer] the maximum number of `reason` entries per record.
+    # @!method max_reasons=(value)
+    #   @param [Integer, nil] value
+    #   @raise [ArgumentError] the value is not a positive Integer or nil.
+    #
+    {
+      max_report_records: DEFAULT_MAX_REPORT_RECORDS,
+      max_xml_nodes: DEFAULT_MAX_XML_NODES,
+      max_xml_depth: DEFAULT_MAX_XML_DEPTH,
+      max_text_length: DEFAULT_MAX_TEXT_LENGTH,
+      max_xml_attributes: DEFAULT_MAX_XML_ATTRIBUTES,
+      max_auth_results: DEFAULT_MAX_AUTH_RESULTS,
+      max_reasons: DEFAULT_MAX_REASONS
+    }.each do |name, default|
+      define_method(name) do
+        instance_variable_get(:"@#{name}") || default
+      end
+
+      define_method(:"#{name}=") do |value|
+        unless value.nil? || (value.is_a?(Integer) && value.positive?)
+          raise ArgumentError,
+                "#{name} must be a positive Integer or nil, got #{value.inspect}"
+        end
+
+        instance_variable_set(:"@#{name}", value)
+      end
+    end
   end
 
   #

data/lib/dmarcator/exceptions.rb

@@ -28,6 +28,32 @@ module DMARCator
   class InvalidReport < Error
   end
 
+  #
+  # Raised when a DMARC XML report is well-formed but exceeds a configured
+  # structural limit (record count, node count, nesting depth, text length,
+  # attribute count, or per-record auth_results/reasons entries).
+  #
+  # Distinct from {InvalidReport} so an application can audit or reject
+  # complexity attacks without treating them as ordinary malformed input.
+  #
+  # @since 1.3.0
+  #
+  class ReportTooComplex < Error
+  end
+
+  #
+  # Raised when a DMARC XML report contains a DTD or entity declaration.
+  #
+  # DMARC reports never need a DTD or custom entities, so declaring them is
+  # rejected outright. This eliminates external-entity (XXE) and
+  # entity-expansion (billion-laughs) attacks rather than merely disabling
+  # their resolution.
+  #
+  # @since 1.3.0
+  #
+  class ForbiddenXml < Error
+  end
+
   #
   # Raised when a DNS transport fails to return a usable answer.
   #

data/lib/dmarcator/internal/xml_guard.rb

@@ -0,0 +1,174 @@
+# frozen_string_literal: true
+
+require 'nokogiri'
+
+require_relative '../config'
+require_relative '../exceptions'
+
+module DMARCator
+  #
+  # Implementation details of the library. Nothing here is covered by the
+  # 1.0 compatibility promise.
+  #
+  # @api private
+  #
+  module Internal
+    #
+    # Hardens DMARC XML report parsing against hostile input.
+    #
+    # A DMARC report never needs a DTD or custom entities, so declarations are
+    # rejected outright, and libxml2 is configured to disable everything that
+    # could fetch or expand them. Structural complexity is bounded with a
+    # streaming reader pass before any DOM is built, so a report that exceeds a
+    # limit is rejected without first allocating a tree for it.
+    #
+    # Ruby's `Timeout` is deliberately not used here: it cannot reliably
+    # interrupt libxml2's C-level parsing. Callers that need a hard wall-clock
+    # bound must run the parse in a subprocess with resource limits; the limits
+    # enforced here bound the work the C parser is asked to do.
+    #
+    # @api private
+    #
+    class XmlGuard
+      # DTD and entity declarations, which are never legitimate in a report.
+      #
+      # Matched case-insensitively against the raw bytes as a cheap first line
+      # of defence; the streaming pass also rejects the parsed
+      # `DOCTYPE`/`ENTITY` nodes, which covers encodings this byte scan cannot
+      # see (for example UTF-16).
+      FORBIDDEN_DECLARATION = /<!doctype|<!entity/i
+
+      #
+      # Parse options shared by the streaming reader and the DOM parser.
+      #
+      # * `nonet` forbids network access (external entities are never fetched).
+      # * `nonoent`, `nodtdload` and `nodtdattr` keep entity substitution and
+      #   DTD loading disabled.
+      # * `nohuge` keeps libxml2's own hardcoded limits in force.
+      # * The base options are strict (`ParseOptions.new`), so malformed input
+      #   is reported rather than silently recovered.
+      #
+      # @return [Nokogiri::XML::ParseOptions]
+      #
+      def self.parse_options
+        Nokogiri::XML::ParseOptions.new.tap do |options|
+          options.nonet
+          options.nonoent
+          options.nodtdload
+          options.nodtdattr
+          options.nohuge
+        end
+      end
+
+      #
+      # @param [String] xml
+      #   The raw DMARC XML report.
+      # @param [Config] config
+      #   The configuration whose limits are enforced.
+      #
+      def initialize(xml, config = DMARCator.config)
+        @xml = xml
+        @config = config
+      end
+
+      #
+      # Rejects forbidden declarations and enforces structural limits without
+      # building a DOM.
+      #
+      # @return [XmlGuard] self
+      #
+      # @raise [ForbiddenXml]
+      #   The report contains a DTD or entity declaration.
+      # @raise [ReportTooComplex]
+      #   The report exceeds a configured structural limit.
+      # @raise [InvalidReport]
+      #   The report is not well-formed XML or its encoding is malformed.
+      #
+      def check!
+        reject_forbidden_declarations!
+        enforce_structural_limits!
+        self
+      end
+
+      #
+      # Parses the report into a hardened DOM.
+      #
+      # @return [Nokogiri::XML::Document]
+      #
+      # @raise [InvalidReport]
+      #   The report is not well-formed XML or its encoding is malformed.
+      #
+      def document
+        @document ||= parse_document
+      end
+
+      private
+
+      def reject_forbidden_declarations!
+        haystack = if @xml.encoding.ascii_compatible? && @xml.valid_encoding?
+                     @xml
+                   else
+                     @xml.b
+                   end
+
+        return unless haystack.match?(FORBIDDEN_DECLARATION)
+
+        raise ForbiddenXml, 'DMARC XML reports must not contain a DTD or entity declaration'
+      end
+
+      def enforce_structural_limits!
+        reader = Nokogiri::XML::Reader(@xml, nil, nil, self.class.parse_options)
+
+        nodes = 0
+        records = 0
+        attributes = 0
+
+        while reader.read
+          case reader.node_type
+          when Nokogiri::XML::Reader::TYPE_DOCUMENT_TYPE,
+               Nokogiri::XML::Reader::TYPE_ENTITY
+            raise ForbiddenXml, 'DMARC XML reports must not contain a DTD or entity declaration'
+          when Nokogiri::XML::Reader::TYPE_ELEMENT
+            nodes += 1
+            records += 1 if reader.name == 'record'
+            attributes += reader.attribute_count
+
+            enforce(:max_xml_nodes, nodes)
+            enforce(:max_report_records, records)
+            enforce(:max_xml_depth, reader.depth + 1)
+            enforce(:max_xml_attributes, attributes)
+          when Nokogiri::XML::Reader::TYPE_TEXT,
+               Nokogiri::XML::Reader::TYPE_CDATA,
+               Nokogiri::XML::Reader::TYPE_WHITESPACE,
+               Nokogiri::XML::Reader::TYPE_SIGNIFICANT_WHITESPACE,
+               Nokogiri::XML::Reader::TYPE_COMMENT,
+               Nokogiri::XML::Reader::TYPE_PROCESSING_INSTRUCTION,
+               Nokogiri::XML::Reader::TYPE_ENTITY_REFERENCE
+            nodes += 1
+            enforce(:max_xml_nodes, nodes)
+
+            value = reader.value
+            enforce(:max_text_length, value.bytesize) if value
+          end
+        end
+      rescue Nokogiri::XML::SyntaxError => e
+        raise InvalidReport, "invalid DMARC XML report: #{e.message}"
+      end
+
+      def enforce(setting, value)
+        limit = @config.public_send(setting)
+        return unless value > limit
+
+        raise ReportTooComplex, "DMARC XML report exceeds #{setting} of #{limit}"
+      end
+
+      def parse_document
+        document = Nokogiri::XML.parse(@xml, nil, nil, self.class.parse_options)
+
+        document
+      rescue Nokogiri::XML::SyntaxError => e
+        raise InvalidReport, "invalid DMARC XML report: #{e.message}"
+      end
+    end
+  end
+end

data/lib/dmarcator/report/row.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative '../config'
+require_relative '../exceptions'
 require_relative '../internal/xml_helper'
 require_relative 'auth_result'
 require_relative 'reason'
@@ -106,6 +108,11 @@ module DMARCator
             @spf ||= element.text.freeze
           when 'reason'
             @reason_nodes << element
+
+            if @reason_nodes.length > DMARCator.config.max_reasons
+              raise ReportTooComplex,
+                    "DMARC XML report exceeds max_reasons of #{DMARCator.config.max_reasons} per record"
+            end
           end
         end
       end
@@ -126,6 +133,11 @@ module DMARCator
       def collect_auth_results(auth_results)
         auth_results.element_children.each do |element|
           @auth_result_nodes << element
+
+          if @auth_result_nodes.length > DMARCator.config.max_auth_results
+            raise ReportTooComplex,
+                  "DMARC XML report exceeds max_auth_results of #{DMARCator.config.max_auth_results} per record"
+          end
         end
       end
     end

data/lib/dmarcator/report.rb

@@ -1,8 +1,7 @@
 # frozen_string_literal: true
 
-require 'nokogiri'
-
 require_relative 'config'
+require_relative 'internal/xml_guard'
 require_relative 'internal/xml_helper'
 require_relative 'exceptions'
 require_relative 'report/metadata'
@@ -13,8 +12,10 @@ module DMARCator
   #
   # Represents a parsed DMARC aggregate/forensic XML report.
   #
-  # Parsing disables network access (NONET) so external entities are never
-  # resolved or fetched; treat report XML as untrusted input.
+  # Report XML is treated as untrusted input: DTDs and entity declarations are
+  # rejected, network access and entity expansion are disabled, and structural
+  # complexity (nodes, depth, records, text and attribute counts) is bounded by
+  # {DMARCator.configure} limits before any DOM is built.
   #
   class Report
     include Internal::XmlHelper
@@ -63,6 +64,10 @@ module DMARCator
     # @raise [InvalidReport]
     #   The report is not a String, exceeds
     #   {Config#max_report_bytes}, or is not well-formed XML.
+    # @raise [ForbiddenXml]
+    #   The report contains a DTD or entity declaration.
+    # @raise [ReportTooComplex]
+    #   The report exceeds a configured structural limit.
     #
     def initialize(xml)
       unless xml.is_a?(String)
@@ -77,12 +82,10 @@ module DMARCator
         raise InvalidReport, "DMARC XML report exceeds maximum size of #{limit} bytes"
       end
 
-      @node = Nokogiri::XML(xml) { |config| config.nonet }
-
-      unless @node.errors.empty?
-        raise InvalidReport, "invalid DMARC XML report: #{@node.errors.first}"
-      end
+      guard = Internal::XmlGuard.new(xml)
+      guard.check!
 
+      @node = guard.document
       @node.remove_namespaces!
     end
 

data/lib/dmarcator/resolver/plain.rb

@@ -107,8 +107,13 @@ module DMARCator
         header = socket.read(2)
         raise ResolutionError, 'short DNS response' if header.nil? || header.bytesize < 2
 
-        body = socket.read(header.unpack1('n'))
-        raise ResolutionError, 'short DNS response' if body.nil?
+        length = header.unpack1('n')
+        body = socket.read(length)
+
+        if body.nil? || body.bytesize != length
+          raise ResolutionError,
+                "short DNS response (expected #{length} bytes, got #{body&.bytesize || 0})"
+        end
 
         body
       ensure

data/lib/dmarcator/version.rb

@@ -2,5 +2,5 @@
 
 module DMARCator
   # dmarcator version
-  VERSION = '1.2.0'
+  VERSION = '1.3.0'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: dmarcator
 version: !ruby/object:Gem::Version
-  version: 1.2.0
+  version: 1.3.0
 platform: ruby
 authors:
 - Noah Berman
@@ -38,6 +38,7 @@ files:
 - lib/dmarcator/config.rb
 - lib/dmarcator/exceptions.rb
 - lib/dmarcator/internal/parser.rb
+- lib/dmarcator/internal/xml_guard.rb
 - lib/dmarcator/internal/xml_helper.rb
 - lib/dmarcator/query.rb
 - lib/dmarcator/record.rb