dmarcator 1.2.1 → 1.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c588b9e28df99c70cd55c29c83854064092e2ff74436c9be680afc2b2a77824c
-  data.tar.gz: 3e6692aa15ea2aa28fa451dc847c3cadbd0cb36cdaf237e8bcb6e591206f92d0
+  metadata.gz: cbafae55c92fefeee56b1e5d5e714433cd595facbeb078925b5f54ae55c05ffb
+  data.tar.gz: 9be9ee7752f5ec16a6c7c6e2da499e909a9ff4d5d05c11af8057bf760bff4bac
 SHA512:
-  metadata.gz: 890fe93593dd8ae6cc2888910070d73606f2700ce3e6548b09cbfcca29f86067788894dbdd23d984a23a7662059514564f955ffdf476656d94110289603b8d4c
-  data.tar.gz: b3357457dbeb21bcd40dee7a412eacc9df9d60b148eae9b0f753c2ca6534d299f4ff6bd7585fcfcf67d4482eabc4f6227ac0878af1d839721de1e2cd7334853f
+  metadata.gz: 4206b0cd61595bcffb31487edf88fc6bb7bbc36a3148ab94dec83c5911b49a9d5b05de05dac01c13c232b733ed3a3d40bcd3ee1c96ed123a0a6dbbe812fded3e
+  data.tar.gz: dafdc7d98f728a42398a5a8e9c9c05709592b6e5b341d6b7e5848176b6a3563388608432f30f4e5a538621ba163107880357bdf7ff2e85aee6d1ba7623e576a1

data/ChangeLog.md

@@ -1,3 +1,18 @@
+### 1.4.0 / 2026-11-01
+
+* Enforce the per-record `max_auth_results` and `max_reasons` limits eagerly during the streaming pre-check, before any DOM is built. Previously a report with one record containing an enormous `auth_results`/`reason` collection reached DOM construction unless another global limit caught it.
+* Require a `<feedback>` root element: well-formed XML that is not a DMARC aggregate report is rejected with `InvalidReport` instead of being parsed into an empty report.
+* Stop echoing libxml2 error text (which can contain tag, attribute or entity names from the untrusted input) in `InvalidReport` messages; report only line and column position.
+* Add near-limit regression tests (reports just below every configured limit still parse) and a deterministic fuzz test that random bytes, tag soup, huge text and many attributes only ever raise `DMARCator::Error`.
+
+### 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`.

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,15 +343,39 @@ 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. A report must have a
+  `<feedback>` root element; arbitrary well-formed XML is rejected with
+  `DMARCator::InvalidReport`.
+* Report structural complexity is bounded before any DOM is built. Every limit
+  below — including the per-record `auth_results`/`reason` limits — is enforced
+  by a streaming pre-check, so a report that exceeds a configured limit raises
+  `DMARCator::ReportTooComplex` before a DOM is allocated:
+
+  | 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 }
   ```
+
+  These limits are not the outer boundary. They bound the work the C parser is
+  asked to do, but a libxml2 bug can still bypass Ruby-level checks. Applications
+  parsing reports from untrusted sources should still run the parse in an
+  isolated worker or subprocess with its own resource limits.
 * A warning is emitted at load time if the bundled `resolv` gem is affected by
   CVE-2026-80212/CVE-2026-80213.
 * Domain names are validated before resolution (labels ≤ 63 octets, total ≤

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,232 @@
+# 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. Every configured
+    # limit — including the per-record `auth_results` and `reason` limits — is
+    # enforced here, before DOM allocation.
+    #
+    # A report must have a `<feedback>` root element; arbitrary well-formed XML
+    # that is not a DMARC aggregate report is rejected.
+    #
+    # 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
+
+      # Message raised when a DTD or entity declaration is present.
+      #
+      # Kept free of input-derived content: declaration details are never
+      # echoed to callers.
+      FORBIDDEN_MESSAGE = 'DMARC XML reports must not contain a DTD or entity declaration'
+
+      #
+      # 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, FORBIDDEN_MESSAGE
+      end
+
+      def enforce_structural_limits!
+        reader = Nokogiri::XML::Reader(@xml, nil, nil, self.class.parse_options)
+
+        nodes = 0
+        records = 0
+        attributes = 0
+
+        stack = []
+        root_seen = false
+        record_auth_results = 0
+        record_reasons = 0
+
+        while reader.read
+          case reader.node_type
+          when Nokogiri::XML::Reader::TYPE_DOCUMENT_TYPE,
+               Nokogiri::XML::Reader::TYPE_ENTITY
+            raise ForbiddenXml, FORBIDDEN_MESSAGE
+          when Nokogiri::XML::Reader::TYPE_ELEMENT
+            nodes += 1
+            attributes += reader.attribute_count
+
+            enforce(:max_xml_nodes, nodes)
+            enforce(:max_xml_attributes, attributes)
+            enforce(:max_xml_depth, reader.depth + 1)
+
+            unless root_seen
+              root_seen = true
+
+              unless reader.name == 'feedback'
+                raise InvalidReport, 'DMARC XML report must have a <feedback> root element'
+              end
+            end
+
+            if reader.name == 'record'
+              records += 1
+              enforce(:max_report_records, records)
+
+              record_auth_results = 0
+              record_reasons = 0
+            elsif stack.include?('record')
+              if stack.last == 'auth_results'
+                record_auth_results += 1
+                enforce(:max_auth_results, record_auth_results)
+              elsif stack.last == 'policy_evaluated' && reader.name == 'reason'
+                record_reasons += 1
+                enforce(:max_reasons, record_reasons)
+              end
+            end
+
+            stack.push(reader.name) unless reader.empty_element?
+          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
+          when Nokogiri::XML::Reader::TYPE_END_ELEMENT
+            stack.pop
+          end
+        end
+      rescue Nokogiri::XML::SyntaxError => e
+        raise InvalidReport, sanitize_syntax_error(e)
+      end
+
+      def enforce(setting, value)
+        limit = @config.public_send(setting)
+        return unless value > limit
+
+        raise ReportTooComplex, "DMARC XML report exceeds #{setting} of #{limit}"
+      end
+
+      #
+      # Renders a parse error using only position information. Nokogiri's
+      # messages can echo tag, attribute or entity names from the input, and
+      # those are untrusted; line/column numbers are not.
+      #
+      def sanitize_syntax_error(error)
+        line = error.respond_to?(:line) ? error.line : nil
+        column = error.respond_to?(:column) ? error.column : nil
+
+        if line && column
+          "invalid DMARC XML report at line #{line}, column #{column}"
+        else
+          'invalid DMARC XML report'
+        end
+      end
+
+      def parse_document
+        document = Nokogiri::XML.parse(@xml, nil, nil, self.class.parse_options)
+
+        document
+      rescue Nokogiri::XML::SyntaxError => e
+        raise InvalidReport, sanitize_syntax_error(e)
+      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/version.rb

@@ -2,5 +2,5 @@
 
 module DMARCator
   # dmarcator version
-  VERSION = '1.2.1'
+  VERSION = '1.4.0'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: dmarcator
 version: !ruby/object:Gem::Version
-  version: 1.2.1
+  version: 1.4.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