dmarcator 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: e13144ffc39b0f47db1c26f65201c05db51af4701cf51ffd2398dcab8011a791
+  data.tar.gz: 7560c54eb55c97de2a841e22f5c1ff4469741b23a2bd3f593934eb24b21c3582
+SHA512:
+  metadata.gz: f7966f69b4b9741fad6a84c6f502631137f32891955d81a3f94e3b83fe01810fca1a8a94544dbb4f81f6adbc361b6d6d89374377d435e46f8df44a82e247a37a
+  data.tar.gz: 016b57445827a1c297870e079a148be4c0ce786dabc3f0cb2574a09beb00c8d91742a117b0d03e8095c3b4f4aeeb46a22a88431c3c4b781df948021a77f1bab4

data/ChangeLog.md

@@ -0,0 +1,55 @@
+### 0.1.0 / 2026-10-13
+
+* Forked from the Trail of Bits `dmarc` gem and published as `dmarcator`.
+* Renamed the `DMARC` module to `DMARCator` (`require "dmarcator"`).
+* Hardened parsing and DNS querying; see the README for details.
+
+### 0.6.0 / 2024-01-24
+
+Entries below this point refer to the original `dmarc` gem.
+
+
+* {DMARC::Record.parse} now allows trailing whitespace, per DMARC spec.
+
+### 0.5.0 / 2016-06-16
+
+* Added {DMARC::Uri} to represent `mailto:dmarc@example.com!10m` URIs.
+
+### 0.4.0 / 2016-06-10
+
+* Added {DMARC::Record#to_h}.
+* Added {DMARC::Record#adkim?}.
+* Added {DMARC::Record#aspf?}.
+* Added {DMARC::Record#fo?}.
+* Added {DMARC::Record#p?}.
+* Added {DMARC::Record#pct?}.
+* Added {DMARC::Record#rf?}.
+* Added {DMARC::Record#ri?}.
+* Added {DMARC::Record#rua?}.
+* Added {DMARC::Record#ruf?}.
+* Added {DMARC::Record#sp?}.
+
+### 0.3.0 / 2015-07-01
+
+* Added {DMARC::Record.query}.
+* Added {DMARC::Record#to_s}.
+* Added {DMARC::InvalidRecord}.
+* Deprecate {DMARC::Record.from_txt}.
+* {DMARC::Record#v} now returns `:DMARC1`.
+* {DMARC::Record#p} and {DMARC::Record#sp} now return Symbols
+* {DMARC::Record#rua} and {DMARC::Record#ruf} will always return Arrays.
+* Fixed a bug in {DMARC::Parser} with respect to order of tags.
+* {DMARC::Parser::Transform} now coerces URIs into URI objects.
+
+### 0.2.0 / 2014-10-20
+
+* Added `DMARC::Error`.
+* Added {DMARC::InvalidRecord}.
+* Add support for parsing `fo` tokens.
+* Ignore unknown tags instead of raising a parser exception.
+* Ignore tags with invalid values instead of raising a parser exception.
+
+### 0.1.0 / 2014-04-25
+
+* Initial release.
+

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2014-2016 Trail of Bits
+Copyright (c) 2026 Noah Berman
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+the Software, and to permit persons to whom the Software is furnished to do so,
+subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,137 @@
+# DMARCator
+
+[![Gem Version](https://badge.fury.io/rb/dmarcator.svg)](https://badge.fury.io/rb/dmarcator)
+[![YARD Docs](https://img.shields.io/badge/yard-docs-blue.svg)](https://rubydoc.info/gems/dmarcator)
+
+DMARCator is a Ruby library for parsing and querying [DMARC] records.
+
+> **DMARCator is a fork of the [`dmarc`][dmarc-gem] gem, originally created by
+> Davis Gallinghouse at [Trail of Bits].** It keeps the original MIT license and
+> credits its authors, but ships under a new name with additional hardening and
+> 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.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem "dmarcator"
+```
+
+And then execute:
+
+```sh
+bundle install
+```
+
+Or install it yourself:
+
+```sh
+gem install dmarcator
+```
+
+The gem is loaded via:
+
+```ruby
+require "dmarcator"
+```
+
+## Example
+
+Parse a DMARC record:
+
+```ruby
+require "dmarcator"
+
+record = DMARCator::Record.parse(
+  "v=DMARC1; p=reject; rua=mailto:d@rua.agari.com; ruf=mailto:d@ruf.agari.com; fo=1"
+)
+
+record.v
+# => :DMARC1
+
+record.p
+# => :reject
+
+record.adkim
+# => :r
+
+record.aspf
+# => :r
+
+record.fo
+# => ["0"]
+
+record.pct
+# => 100
+
+record.rf
+# => :afrf
+
+record.ri
+# => 86400
+
+record.rua
+# => [#<DMARCator::Uri ... @uri=#<URI::MailTo mailto:d@rua.agari.com>, @size=nil, @unit=nil>]
+
+record.ruf
+# => [#<DMARCator::Uri ... @uri=#<URI::MailTo mailto:d@ruf.agari.com>, @size=nil, @unit=nil>]
+
+record.sp
+# => :reject
+```
+
+Query the DMARC record for a domain:
+
+```ruby
+record = DMARCator::Record.query("twitter.com")
+# => #<DMARCator::Record ... @p=:reject, @rua=[...], ...>
+```
+
+## Requirements
+
+* [Ruby] >= 3.0.0
+* [parslet] >= 1.0.0, < 3.0.0
+
+## Testing
+
+To run the RSpec tests:
+
+```sh
+rake spec
+```
+
+To test the parser against the bundled Alexa Top 500 fixture:
+
+```sh
+rake spec:gauntlet
+```
+
+## License
+
+This project is released under the MIT License. See the [LICENSE.txt] file for
+details.
+
+## Acknowledgments
+
+DMARCator is a fork of [`dmarc`][dmarc-gem], a DMARC record parser created by
+Davis Gallinghouse at [Trail of Bits] and released under the MIT License.
+
+This fork renames the `DMARC` module to `DMARCator` (loaded via
+`require "dmarcator"`) while keeping the original API shape, and adds:
+
+* strict `mailto:`-only handling for `rua`/`ruf` report URIs,
+* validation for required and ranged tags (`p`, `pct`, `ri`) and duplicate tags,
+* a DNS query path that selects the `v=DMARC1` TXT record per RFC 7489,
+* hardened packaging and test fixtures.
+
+[DMARC]: https://www.rfc-editor.org/rfc/rfc7489
+[dmarc-gem]: https://rubygems.org/gems/dmarc
+[Trail of Bits]: https://www.trailofbits.com
+[Ruby]: https://www.ruby-lang.org
+[parslet]: https://kschiess.github.io/parslet/
+[LICENSE.txt]: LICENSE.txt

data/lib/dmarcator/exceptions.rb

@@ -0,0 +1,6 @@
+require 'parslet'
+
+module DMARCator
+  class InvalidRecord < Parslet::ParseFailed
+  end
+end

data/lib/dmarcator/parser.rb

@@ -0,0 +1,221 @@
+require 'dmarcator/exceptions'
+require 'dmarcator/uri'
+
+require 'parslet'
+require 'uri'
+
+module DMARCator
+  #
+  # DMARC parser.
+  #
+  # @see https://tools.ietf.org/html/rfc7489#section-6.4
+  #
+  class Parser < Parslet::Parser
+
+    root :dmarc_record
+
+    rule(:dmarc_record) do
+      dmarc_version.repeat(1,1) >>
+      (dmarc_sep >> dmarc_tag).repeat >>
+      dmarc_sep.maybe >>
+      wsp?.maybe
+    end
+
+    rule(:dmarc_sep) { wsp? >> str(';') >> wsp? }
+
+    rule(:dmarc_version) do
+      str('v') >> wsp? >>
+      str('=') >> wsp? >>
+      str('DMARC1').as(:v)
+    end
+
+    rule(:dmarc_tag) do
+      dmarc_request   |
+      dmarc_srequest  |
+      dmarc_auri      |
+      dmarc_furi      |
+      dmarc_adkim     |
+      dmarc_aspf      |
+      dmarc_ainterval |
+      dmarc_fo        |
+      dmarc_rfmt      |
+      dmarc_percent   |
+      unknown_tag
+    end
+
+    def self.tag_rule(name,tag,&block)
+      rule(:"dmarc_#{name}") do
+        str(tag) >> wsp? >> str('=') >> wsp? >>
+        (instance_eval(&block).as(tag.to_sym) | unknown_value)
+      end
+    end
+
+    tag_rule(:request,'p') do
+      str('none') | str('quarantine') | str('reject')
+    end
+
+    tag_rule(:srequest,'sp') do
+      str('none') | str('quarantine') | str('reject')
+    end
+
+    tag_rule(:auri, 'rua') do
+      dmarc_uri >> (wsp? >> str(',') >> wsp? >> dmarc_uri).repeat
+    end
+
+    tag_rule(:ainterval,'ri') { digit.repeat(1, 10) >> digit.absent? }
+
+    tag_rule(:furi,'ruf') do
+      dmarc_uri >> (wsp? >> str(',') >> wsp? >> dmarc_uri).repeat
+    end
+
+    tag_rule(:fo,'fo') do
+      fo_opt >> (wsp? >> str(':') >> wsp? >> fo_opt).repeat
+    end
+
+    rule(:fo_opt) { match['01ds'].as(:fo_opt) }
+
+    tag_rule(:rfmt,'rf') { str('afrf') | str('iodef') }
+
+    tag_rule(:percent,'pct') { digit.repeat(1,3) >> digit.absent? }
+
+    tag_rule(:adkim, 'adkim') { match['rs'] }
+    tag_rule(:aspf, 'aspf')   { match['rs'] }
+
+    rule(:unknown_tag) { match["^; \t"].repeat(1) }
+    rule(:unknown_value) { match["^; \t"].repeat(1) }
+
+    rule(:dmarc_uri) do
+      mailto_uri.as(:uri) >> (
+        str('!') >> digit.repeat(1, 10).as(:size) >> digit.absent? >> (
+          match['kmgt']
+        ).as(:unit).maybe
+      ).maybe >> str('!').absent?
+    end
+
+    rule(:mailto_uri) do
+      str('mailto:') >> mailto_address
+    end
+
+    rule(:mailto_address) do
+      mailto_local >> str('@') >> mailto_domain
+    end
+
+    rule(:mailto_local)  { mailto_char.repeat(1) }
+    rule(:mailto_domain) { mailto_char.repeat(1) }
+    rule(:mailto_char)   { match["^;,! \t@"] }
+
+    rule(:digit) { match('[0-9]') }
+    rule(:wsp) { str(' ') | str("\t") }
+    rule(:wsp?) { wsp.repeat }
+
+    class Transform < Parslet::Transform
+
+      rule(fo_opt: simple(:fo_opt)) { fo_opt }
+      rule(fo: simple(:fo_opt)) { {fo: [fo_opt]} }
+
+      rule(v: simple(:version)) { {v: version.to_sym} }
+      rule(p:  simple(:p))  { {p:  p.to_sym } }
+      rule(sp: simple(:sp)) { {sp: sp.to_sym} }
+      rule(rf: simple(:rf)) { {rf: rf.to_sym} }
+      rule(adkim: simple(:adkim)) { {adkim: adkim.to_sym} }
+      rule(aspf:  simple(:aspf))  { {aspf: aspf.to_sym} }
+
+      rule(pct: simple(:pct)) { {pct: pct.to_i} }
+      rule(ri:  simple(:ri))  { {ri:  ri.to_i}  }
+
+      rule(uri: simple(:uri), size: simple(:size), unit: simple(:unit)) do
+        Uri.new(
+          Transform.parse_uri(uri),
+          size.to_i,
+          unit.to_sym
+        )
+      end
+      rule(uri: simple(:uri), size: simple(:size)) do
+        Uri.new(
+          Transform.parse_uri(uri),
+          size.to_i
+        )
+      end
+      rule(uri: simple(:uri)) { Uri.new(Transform.parse_uri(uri)) }
+      rule(rua: subtree(:uris)) { {rua: Array(uris)} }
+      rule(ruf: subtree(:uris)) { {ruf: Array(uris)} }
+
+      MAX_ERROR_MESSAGE_LENGTH = 300
+
+      def self.parse_uri(value)
+        uri = value.to_s
+
+        begin
+          parsed = URI.parse(uri)
+        rescue URI::Error => error
+          raise InvalidRecord, truncate(error.message)
+        end
+
+        unless parsed.is_a?(URI::MailTo)
+          raise InvalidRecord, "invalid DMARC report URI (expected mailto): #{truncate(uri)}"
+        end
+
+        parsed
+      end
+
+      def self.truncate(message)
+        message = message.to_s
+
+        if message.length > MAX_ERROR_MESSAGE_LENGTH
+          message[0, MAX_ERROR_MESSAGE_LENGTH] + "..."
+        else
+          message
+        end
+      end
+
+    end
+
+    #
+    # Parses a DMARC record.
+    #
+    # @param [String] record
+    #   The raw DMARC record to parse.
+    #
+    # @return [Hash{Symbol => Object}]
+    #   The Hash of tags within the record.
+    #
+    def self.parse(record)
+      tags = Transform.new.apply(new.parse(record))
+      hash = {}
+
+      tags.each do |tag|
+        tag.each_key do |key|
+          if hash.key?(key)
+            raise InvalidRecord, "duplicate DMARC tag: #{key}"
+          end
+        end
+
+        hash.merge!(tag)
+      end
+
+      validate!(hash)
+
+      return hash
+    end
+
+    #
+    # Validates the parsed tags.
+    #
+    # @param [Hash{Symbol => Object}] tags
+    #   The parsed tags.
+    #
+    # @raise [InvalidRecord]
+    #   One of the tags has an invalid value.
+    #
+    def self.validate!(tags)
+      if tags[:pct] && !(tags[:pct].is_a?(Integer) && tags[:pct].between?(0, 100))
+        raise InvalidRecord, "pct must be an integer between 0 and 100"
+      end
+
+      if tags[:ri] && !(tags[:ri].is_a?(Integer) && tags[:ri].between?(0, 2**32 - 1))
+        raise InvalidRecord, "ri must be an integer between 0 and 4294967295"
+      end
+    end
+
+  end
+end

data/lib/dmarcator/query.rb

@@ -0,0 +1,63 @@
+require 'resolv'
+
+module DMARCator
+  #
+  # Validates a domain before using it in a DNS query.
+  #
+  # @param [String] domain
+  #   The domain to validate.
+  #
+  # @return [String]
+  #   The validated domain.
+  #
+  # @raise [ArgumentError]
+  #   The domain is not a syntactically valid DNS name.
+  #
+  def self.validate_domain(domain)
+    unless domain.is_a?(String) && !domain.empty? &&
+           domain.length <= 253 &&
+           !domain.start_with?('.') &&
+           !domain.include?('..') &&
+           !domain.match?(/[^A-Za-z0-9._-]/)
+      raise ArgumentError, "invalid domain: #{domain.inspect}"
+    end
+
+    domain
+  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.
+  #
+  # @return [String, nil]
+  #   The domain's DMARC record or `nil` if none exists.
+  #
+  # @api semipublic
+  #
+  # @since 0.3.0
+  #
+  def self.query(domain,resolver=Resolv::DNS.new)
+    validate_domain(domain)
+
+    host = "_dmarc.#{domain}"
+
+    begin
+      records = resolver.getresources(host, Resolv::DNS::Resource::IN::TXT)
+    rescue Resolv::ResolvError
+      return nil
+    end
+
+    # Per RFC 7489 §6.6.3, use the TXT record beginning with "v=DMARC1".
+    # If multiple DMARC records exist, treat the domain as having none.
+    dmarc_records = records.map { |record| record.strings.join }
+                           .select { |text| text.start_with?('v=DMARC1') }
+
+    return dmarc_records.first if dmarc_records.one?
+    nil
+  end
+end