dmarcator 0.1.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e13144ffc39b0f47db1c26f65201c05db51af4701cf51ffd2398dcab8011a791
-  data.tar.gz: 7560c54eb55c97de2a841e22f5c1ff4469741b23a2bd3f593934eb24b21c3582
+  metadata.gz: '03348cb4b245b8e35dde8ba708559df27d8fd40a6e52d1e15bd73db8732e49d8'
+  data.tar.gz: fac2e24464f16d080f27e7fd1fede61720947dffda32a792d5b5b20d4f507373
 SHA512:
-  metadata.gz: f7966f69b4b9741fad6a84c6f502631137f32891955d81a3f94e3b83fe01810fca1a8a94544dbb4f81f6adbc361b6d6d89374377d435e46f8df44a82e247a37a
-  data.tar.gz: 016b57445827a1c297870e079a148be4c0ce786dabc3f0cb2574a09beb00c8d91742a117b0d03e8095c3b4f4aeeb46a22a88431c3c4b781df948021a77f1bab4
+  metadata.gz: 2c5c33baf620a3520d927f4eb1f7b3078703201f3c314779fd42aef5f97d844280a5d25e82103f2a6e6aae963779a9f8f25962ea92758b44e4a4054844363c50
+  data.tar.gz: bc9e4584af2e2a158c918f855e80e76d590f539d69d3571b1edcac12a036bca01ee269cc88c3f3d63f670b65c753dc068cce3d1f9e7d7a4a38b0783a41a7ad2d

data/ChangeLog.md

@@ -1,3 +1,18 @@
+### 0.3.0 / 2026-10-26
+
+* Raise `DMARCator::InvalidReport` for malformed XML reports instead of returning an empty report.
+* Return `nil` for a non-numeric report `version` instead of raising `ArgumentError`.
+* Return `nil` for a non-numeric report timestamp instead of coercing it to the Unix epoch.
+* Add `DMARCator::Uri#eql?` and `#hash` for correct Hash/Set semantics.
+* Harden `DMARCator.validate_domain` against CVE-2026-80213 (63-octet label limit and 248-octet total limit).
+* Warn at load time when the `resolv` gem is affected by CVE-2026-80212/CVE-2026-80213.
+* Require Ruby >= 3.3.13 to pick up the Regexp compilation fixes behind GitLab's CVE-2026-89078, CVE-2026-93577, CVE-2026-97229 and CVE-2026-110264.
+
+### 0.2.0 / 2026-10-13
+
+* Added DMARC XML report parsing, ported from the `dmarc_parser` gem by D Salko.
+* Added `nokogiri` and `bigdecimal` runtime dependencies.
+
 ### 0.1.0 / 2026-10-13
 
 * Forked from the Trail of Bits `dmarc` gem and published as `dmarcator`.

data/LICENSE.txt

@@ -1,6 +1,7 @@
 The MIT License (MIT)
 
 Copyright (c) 2014-2016 Trail of Bits
+Copyright (c) 2020 D Salko
 Copyright (c) 2026 Noah Berman
 
 Permission is hereby granted, free of charge, to any person obtaining a copy of

data/README.md

@@ -11,8 +11,9 @@ DMARCator is a Ruby library for parsing and querying [DMARC] records.
 > a stricter parser. See [Acknowledgments](#acknowledgments) below.
 
 [DMARC] policies are published as DNS TXT records at `_dmarc.<domain>`. This
-library parses those records into a structured `DMARCator::Record` and can query
-them directly through Ruby's `Resolv` DNS client.
+library parses those records into a structured `DMARCator::Record`, queries them
+directly through Ruby's `Resolv` DNS client, and parses the XML aggregate
+reports those policies generate.
 
 ## Installation
 
@@ -92,10 +93,32 @@ record = DMARCator::Record.query("twitter.com")
 # => #<DMARCator::Record ... @p=:reject, @rua=[...], ...>
 ```
 
+## Parsing XML reports
+
+Parse a DMARC aggregate/forensic report:
+
+```ruby
+report = DMARCator::Report.new(xml_string)
+
+report.version
+# => 0.1e0
+
+report.metadata.org_name
+# => "google.com"
+
+report.policy.domain
+# => "opserv.io"
+
+report.records.first.source_ip
+# => "209.85.220.69"
+```
+
 ## Requirements
 
-* [Ruby] >= 3.0.0
+* [Ruby] >= 3.3.13
 * [parslet] >= 1.0.0, < 3.0.0
+* [nokogiri] >= 1.10
+* [bigdecimal] >= 1.0
 
 ## Testing
 
@@ -129,9 +152,15 @@ This fork renames the `DMARC` module to `DMARCator` (loaded via
 * a DNS query path that selects the `v=DMARC1` TXT record per RFC 7489,
 * hardened packaging and test fixtures.
 
+The DMARC XML report parser is ported from [`dmarc_parser`][dmarc-parser-gem],
+created by D Salko and released under the MIT License.
+
 [DMARC]: https://www.rfc-editor.org/rfc/rfc7489
 [dmarc-gem]: https://rubygems.org/gems/dmarc
+[dmarc-parser-gem]: https://rubygems.org/gems/dmarc_parser
 [Trail of Bits]: https://www.trailofbits.com
 [Ruby]: https://www.ruby-lang.org
 [parslet]: https://kschiess.github.io/parslet/
+[nokogiri]: https://nokogiri.org
+[bigdecimal]: https://github.com/ruby/bigdecimal
 [LICENSE.txt]: LICENSE.txt

data/lib/dmarcator/exceptions.rb

@@ -3,4 +3,10 @@ require 'parslet'
 module DMARCator
   class InvalidRecord < Parslet::ParseFailed
   end
+
+  #
+  # Raised when a DMARC XML report cannot be parsed.
+  #
+  class InvalidReport < StandardError
+  end
 end

data/lib/dmarcator/query.rb

@@ -1,6 +1,43 @@
 require 'resolv'
+require 'rubygems'
 
 module DMARCator
+  #
+  # Resolv gem versions affected by CVE-2026-80212 and CVE-2026-80213.
+  #
+  VULNERABLE_RESOLV = [
+    Gem::Requirement.new('< 0.3.2'),
+    Gem::Requirement.new('>= 0.4.0', '< 0.7.2')
+  ].freeze
+
+  #
+  # Determines the version of the loaded `resolv` gem, if available.
+  #
+  # @return [String, nil]
+  #
+  def self.resolv_version
+    if defined?(Resolv::VERSION)
+      Resolv::VERSION
+    elsif (spec = Gem.loaded_specs['resolv'])
+      spec.version.to_s
+    end
+  end
+
+  #
+  # Determines whether the loaded `resolv` gem is affected by
+  # CVE-2026-80212 or CVE-2026-80213.
+  #
+  # @return [Boolean]
+  #
+  def self.vulnerable_resolv?
+    version = resolv_version
+    return false unless version
+
+    VULNERABLE_RESOLV.any? do |requirement|
+      requirement.satisfied_by?(Gem::Version.new(version))
+    end
+  end
+
   #
   # Validates a domain before using it in a DNS query.
   #
@@ -15,10 +52,11 @@ module DMARCator
   #
   def self.validate_domain(domain)
     unless domain.is_a?(String) && !domain.empty? &&
-           domain.length <= 253 &&
+           domain.length <= 248 &&
            !domain.start_with?('.') &&
            !domain.include?('..') &&
-           !domain.match?(/[^A-Za-z0-9._-]/)
+           !domain.match?(/[^A-Za-z0-9._-]/) &&
+           domain.split('.').all? { |label| label.length <= 63 }
       raise ArgumentError, "invalid domain: #{domain.inspect}"
     end
 
@@ -61,3 +99,9 @@ module DMARCator
     nil
   end
 end
+
+if DMARCator.vulnerable_resolv?
+  warn "dmarcator: resolv #{DMARCator.resolv_version} is affected by " \
+       "CVE-2026-80212 and CVE-2026-80213; upgrade to resolv >= 0.7.2 " \
+       "(or >= 0.3.2 on Ruby 3.3)"
+end

data/lib/dmarcator/report/auth_result.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require_relative '../xml_helper'
+
+module DMARCator
+  class Report
+    #
+    # Represents an `auth_results` entry (DKIM/SPF) in a DMARC XML report.
+    #
+    class AuthResult
+      include XmlHelper
+
+      ATTRIBUTES = [:type, :domain, :result, :selector, :scope]
+
+      attr_accessor(*ATTRIBUTES)
+
+      def initialize(node)
+        @node = node
+        self.type = node.name
+        self.domain = get_text('domain')
+        self.result = get_text('result')
+        self.selector = get_text('selector')
+        self.scope = get_text('scope')
+      end
+    end
+  end
+end

data/lib/dmarcator/report/metadata.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require_relative '../xml_helper'
+
+module DMARCator
+  class Report
+    #
+    # Represents the `report_metadata` element of a DMARC XML report.
+    #
+    class Metadata
+      include XmlHelper
+
+      ATTRIBUTES = [
+        :org_name, :email, :extra_contact_info, :report_id,
+        :begin_at, :end_at, :errors
+      ]
+
+      attr_accessor(*ATTRIBUTES)
+
+      def initialize(node)
+        @node = node
+        self.org_name = get_text('feedback/report_metadata/org_name')
+        self.email = get_text('feedback/report_metadata/email')
+        self.extra_contact_info = get_text('feedback/report_metadata/extra_contact_info')
+        self.report_id = get_text('feedback/report_metadata/report_id')
+        self.begin_at = get_timestamp('feedback/report_metadata/date_range/begin')
+        self.end_at = get_timestamp('feedback/report_metadata/date_range/end')
+        self.errors = @node.xpath('feedback/report_metadata/error').map(&:text)
+      end
+    end
+  end
+end

data/lib/dmarcator/report/policy.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require_relative '../xml_helper'
+
+module DMARCator
+  class Report
+    #
+    # Represents the `policy_published` element of a DMARC XML report.
+    #
+    class Policy
+      include XmlHelper
+
+      ATTRIBUTES = [:domain, :adkim, :aspf, :p, :sp, :pct, :fo]
+
+      attr_accessor(*ATTRIBUTES)
+
+      def initialize(node)
+        @node = node
+
+        ATTRIBUTES.each do |attr|
+          self.public_send("#{attr}=", get_text("feedback/policy_published/#{attr}"))
+        end
+
+        self.pct = self.pct && !self.pct.empty? ? self.pct.to_i : nil
+      end
+    end
+  end
+end

data/lib/dmarcator/report/reason.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+require_relative '../xml_helper'
+
+module DMARCator
+  class Report
+    #
+    # Represents a `reason` element of a DMARC XML report record.
+    #
+    class Reason
+      include XmlHelper
+
+      ATTRIBUTES = [:type, :comment]
+
+      attr_accessor(*ATTRIBUTES)
+
+      def initialize(node)
+        @node = node
+        self.type = get_text('type')
+        self.comment = get_text('comment')
+      end
+    end
+  end
+end

data/lib/dmarcator/report/record.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require_relative '../xml_helper'
+require_relative 'auth_result'
+require_relative 'reason'
+
+module DMARCator
+  class Report
+    #
+    # Represents a single `record` element of a DMARC XML report.
+    #
+    class Record
+      include XmlHelper
+
+      ATTRIBUTES = [
+        :source_ip, :count, :disposition, :dkim, :spf,
+        :envelope_to, :envelope_from, :header_from,
+        :auth_results, :reasons
+      ]
+
+      attr_accessor(*ATTRIBUTES)
+
+      def initialize(node)
+        @node = node
+        self.source_ip = get_text('row/source_ip')
+        self.count = get_int('row/count')
+        self.disposition = get_text('row/policy_evaluated/disposition')
+        self.dkim = get_text('row/policy_evaluated/dkim')
+        self.spf = get_text('row/policy_evaluated/spf')
+        self.reasons = node.xpath('row/policy_evaluated/reason').map do |reason_node|
+          Reason.new(reason_node)
+        end
+        self.envelope_to = get_text('identifiers/envelope_to')
+        self.envelope_from = get_text('identifiers/envelope_from')
+        self.header_from = get_text('identifiers/header_from')
+        self.auth_results = node.xpath('auth_results/*').map do |auth_results_node|
+          AuthResult.new(auth_results_node)
+        end
+      end
+    end
+  end
+end

data/lib/dmarcator/report.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+require 'nokogiri'
+require 'bigdecimal'
+require 'bigdecimal/util'
+
+require_relative 'xml_helper'
+require_relative 'exceptions'
+require_relative 'report/metadata'
+require_relative 'report/policy'
+require_relative 'report/record'
+
+module DMARCator
+  #
+  # Represents a parsed DMARC aggregate/forensic XML report.
+  #
+  # Nokogiri's default parse options are used, which do not resolve external
+  # entities or fetch network resources; treat report XML as untrusted input.
+  #
+  class Report
+    include XmlHelper
+
+    #
+    # Initializes the report from an XML string.
+    #
+    # @param [String] xml
+    #   The raw DMARC XML report.
+    #
+    def initialize(xml)
+      @xml = xml
+      @node = Nokogiri::XML(xml)
+
+      unless @node.errors.empty?
+        raise InvalidReport, "invalid DMARC XML report: #{@node.errors.first}"
+      end
+
+      @node.remove_namespaces!
+    end
+
+    #
+    # The report version.
+    #
+    # @return [BigDecimal, nil]
+    #
+    def version
+      @version ||= begin
+        value = get_text('feedback/version')
+
+        if value && !value.empty?
+          begin
+            BigDecimal(value)
+          rescue ArgumentError
+            nil
+          end
+        end
+      end
+    end
+
+    #
+    # The report metadata.
+    #
+    # @return [Report::Metadata]
+    #
+    def metadata
+      @metadata ||= Metadata.new(@node)
+    end
+
+    #
+    # The published DMARC policy.
+    #
+    # @return [Report::Policy]
+    #
+    def policy
+      @policy ||= Policy.new(@node)
+    end
+
+    #
+    # The report records.
+    #
+    # @return [Array<Report::Record>]
+    #
+    def records
+      @records ||= @node.xpath('feedback/record').map do |node|
+        Record.new(node)
+      end
+    end
+  end
+end

data/lib/dmarcator/uri.rb

@@ -75,6 +75,27 @@ module DMARCator
       (@unit == other.unit)
     end
 
+    #
+    # Determines if the DMARC URI is equivalent to the other.
+    #
+    # @param [Object] other
+    #   the other DMARC URI to compare against.
+    #
+    # @return [Boolean]
+    #
+    def eql?(other)
+      self == other
+    end
+
+    #
+    # Computes a hash value consistent with {#eql?}.
+    #
+    # @return [Integer]
+    #
+    def hash
+      [self.class, @uri, @size, @unit].hash
+    end
+
     #
     # Converts the DMARC URI back into a String.
     #

data/lib/dmarcator/version.rb

@@ -1,4 +1,4 @@
 module DMARCator
   # dmarcator version
-  VERSION = '0.1.0'
+  VERSION = '0.3.0'
 end

data/lib/dmarcator/xml_helper.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+require 'nokogiri'
+
+module DMARCator
+  #
+  # Internal helper for extracting values from parsed DMARC XML reports.
+  #
+  module XmlHelper
+    #
+    # Returns the text of the first node matching the XPath expression.
+    #
+    # @param [String] xpath
+    #   The XPath expression to match.
+    #
+    # @return [String, nil]
+    #   The node text, or `nil` if no node matched.
+    #
+    def get_text(xpath)
+      @node.at_xpath(xpath)&.text
+    end
+
+    #
+    # Returns a Unix timestamp as a `Time`.
+    #
+    # @param [String] xpath
+    #   The XPath expression to match.
+    #
+    # @return [Time, nil]
+    #
+    def get_timestamp(xpath)
+      value = get_text(xpath)
+      return nil if value.nil? || value.empty?
+
+      digits = value.strip
+      return nil unless digits.match?(/\A\d+\z/)
+
+      Time.at(digits.to_i)
+    end
+
+    #
+    # Returns an integer value.
+    #
+    # @param [String] xpath
+    #   The XPath expression to match.
+    #
+    # @return [Integer, nil]
+    #
+    def get_int(xpath)
+      value = get_text(xpath)
+      value && !value.empty? ? value.to_i : nil
+    end
+  end
+end

data/lib/dmarcator.rb

@@ -2,4 +2,5 @@ require 'dmarcator/exceptions'
 require 'dmarcator/query'
 require 'dmarcator/record'
 require 'dmarcator/parser'
+require 'dmarcator/report'
 require 'dmarcator/version'

data/spec/dmarcator_spec.rb

@@ -59,4 +59,70 @@ describe DMARCator do
       expect { subject.query("foo bar") }.to raise_error(ArgumentError)
     end
   end
+
+  describe ".validate_domain" do
+    it "accepts a valid domain" do
+      expect(subject.validate_domain("example.com")).to eq("example.com")
+    end
+
+    it "rejects a label longer than 63 octets" do
+      expect {
+        subject.validate_domain("#{'a' * 64}.com")
+      }.to raise_error(ArgumentError)
+    end
+
+    it "accepts a 63-octet label" do
+      domain = "#{'a' * 63}.com"
+
+      expect(subject.validate_domain(domain)).to eq(domain)
+    end
+
+    it "rejects a domain longer than 248 octets" do
+      domain = "#{'a' * 62}.#{'a' * 62}.#{'a' * 62}.#{'a' * 60}"
+
+      expect { subject.validate_domain(domain) }.to raise_error(ArgumentError)
+    end
+
+    it "accepts a domain at the 248-octet limit" do
+      domain = "#{'a' * 62}.#{'a' * 62}.#{'a' * 62}.#{'a' * 59}"
+
+      expect(subject.validate_domain(domain)).to eq(domain)
+    end
+
+    it "rejects a non-string domain" do
+      expect { subject.validate_domain(123) }.to raise_error(ArgumentError)
+    end
+  end
+
+  describe ".vulnerable_resolv?" do
+    it "is true for resolv 0.3.1 and earlier" do
+      allow(subject).to receive(:resolv_version).and_return("0.3.1")
+
+      expect(subject.vulnerable_resolv?).to be(true)
+    end
+
+    it "is false for resolv 0.3.2" do
+      allow(subject).to receive(:resolv_version).and_return("0.3.2")
+
+      expect(subject.vulnerable_resolv?).to be(false)
+    end
+
+    it "is true for resolv 0.4.0 through 0.7.1" do
+      allow(subject).to receive(:resolv_version).and_return("0.7.1")
+
+      expect(subject.vulnerable_resolv?).to be(true)
+    end
+
+    it "is false for resolv 0.7.2 and later" do
+      allow(subject).to receive(:resolv_version).and_return("0.7.2")
+
+      expect(subject.vulnerable_resolv?).to be(false)
+    end
+
+    it "is false when the version is unknown" do
+      allow(subject).to receive(:resolv_version).and_return(nil)
+
+      expect(subject.vulnerable_resolv?).to be(false)
+    end
+  end
 end