dmarc 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: da372737bb262f1d63188a9bfac317660bb8cdb4
-  data.tar.gz: d29823cc84b2e12a8aa6c37d4cfe0c1c0ad95006
+  metadata.gz: 9a12630bf22487064d3d35386f55e7af00f6b542
+  data.tar.gz: 35f68803f6820445c7e38d9e37078737075807e4
 SHA512:
-  metadata.gz: 938905706d15411759c04133451472d0d7d9565982240ed9747e1566b2c450cab830b66ae6edffbfe8e193ea91bd1aae0dab655a4b6c453b181755f549930e21
-  data.tar.gz: 764c5540136f70d7d7abd04a5b28253473c8288d82f934f1ad2f57f93d1bbc85ad832277d967957b568f8a27615007ce472a1d09a002cc7ab6c6bd2523145c41
+  metadata.gz: 3214787e24b80ce2eb162473d43e9e77f152d8e1ff6cfcf1fbbb2fadfe8d565b27c4e0b97c3c17180783e10ff6c62a18714c8be3925a97309a886f79a7d2eee4
+  data.tar.gz: f7ed4b603e8541e97c7d29d733f45d5b7f93ee1d737f9cc70916c1459098a570a01e1cdece1b2b182dd683c8b2322d279ed4db2c3fbe5187ec8be9eb2389d7fe

data/.travis.yml

@@ -1,7 +1,17 @@
 language: ruby
 rvm:
-  - 1.9.3
-  - 2.0.0
-  - 2.1.0
-  - jruby-19mode
-  - rbx-2
+- 1.9.3
+- 2.0
+- 2.1
+- 2.2
+- jruby
+- rbx-2
+matrix:
+  allow_failures:
+  - rvm: rbx-2
+addons:
+  code_climate:
+    repo_token: 27519af871c1d9576b91e6f264e841eb7b7babbdcda315bf94fcbd095c202949
+notifications:
+  slack:
+    secure: Jqj30lwH2fnyu8adMI2nXa7rfF70o5JSrL0ZOe425XVu3YMMpfIp8J4DD0Ks/nCxgGRhJpq35oAHXjKmJAEHyda9oxx7GV9QwOuu2oviUrW3VUQQj9UsXPQP0sc0GD9BPI+KVNp4dbGki1ik90I6HVVsqDauek/z5MWt6MJY+tA=

data/ChangeLog.md

@@ -1,6 +1,18 @@
+### 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::Error`.
 * Added {DMARC::InvalidRecord}.
 * Add support for parsing `fo` tokens.
 * Ignore unknown tags instead of raising a parser exception.

data/Gemfile

@@ -10,3 +10,8 @@ group :development do
   gem 'kramdown'
   gem 'yard', '~> 0.8'
 end
+
+group :test do
+  gem 'json'
+  gem 'codeclimate-test-reporter', require: nil
+end

data/README.md

@@ -3,6 +3,7 @@
 [![Code Climate](https://codeclimate.com/github/trailofbits/dmarc.png)](https://codeclimate.com/github/trailofbits/dmarc) [![Build Status](https://travis-ci.org/trailofbits/dmarc.svg)](https://travis-ci.org/trailofbits/dmarc)
 [![Gem Version](https://badge.fury.io/rb/dmarc.svg)](http://badge.fury.io/rb/dmarc)
 [![YARD Docs](http://img.shields.io/badge/yard-docs-blue.svg)](http://rubydoc.info/gems/dmarc)
+[![Test Coverage](https://codeclimate.com/github/trailofbits/dmarc/badges/coverage.svg)](https://codeclimate.com/github/trailofbits/dmarc)
 
 [DMARC] is a technical specification intended to solve a couple of long-standing
 email authentication problems. DMARC policies are described in DMARC "records," 
@@ -11,9 +12,49 @@ parser for DMARC records.
 
 ## Example
 
+Parse a SPF record:
+
     require 'dmarc'
 
-    record = DMARC::Record.from_txt(txt)
+    record = DMARC::Record.parse("v=DMARC1; p=reject; rua=mailto:d@rua.agari.com; ruf=mailto:d@ruf.agari.com; fo=1")
+
+    record.v
+    # => :DMARC1
+
+    record.adkim
+    # => :r
+
+    record.aspf
+    # => :r
+
+    record.fo
+    # => ["0"]
+
+    record.p
+    # => :reject
+
+    record.pct
+    # => 100
+
+    record.rf
+    # => :afrf
+
+    record.ri
+    # => 86400
+
+    record.rua
+    # => [#<URI::MailTo:0x000000034a1cc8 URL:mailto:d@rua.agari.com>]
+
+    record.ruf
+    # => [#<URI::MailTo:0x000000034a02b0 URL:mailto:d@ruf.agari.com>]
+
+    record.sp
+    # => :reject
+
+Query the SPF record for a domain:
+
+    record = DMARC::Record.query('twitter.com')
+    # => #<DMARC::Record:0x0000000313bd90 @adkim=:r, @aspf=:r, @fo=["1"@79], @p=:reject, @pct=100, @rf=:afrf, @ri=86400, @rua=[#<URI::MailTo:0x00000003124e38 URL:mailto:d@rua.agari.com>], @ruf=[#<URI::MailTo:0x00000003132678 URL:mailto:d@ruf.agari.com>], @sp=:reject, @v=:DMARC1>
 
 ## Requirements
 
@@ -37,5 +78,5 @@ To test the parser against the Alexa Top 500:
 
 See the {file:LICENSE.txt} file.
 
-[DMARC]: http://tools.ietf.org/html/draft-kucherawy-dmarc-base-02
+[DMARC]: https://tools.ietf.org/html/rfc7489
 [parslet]: http://kschiess.github.io/parslet/

data/dmarc.gemspec

@@ -16,6 +16,7 @@ Gem::Specification.new do |gem|
   gem.files         = `git ls-files`.split($/)
   gem.test_files    = gem.files.grep(%r{^(test|spec|features)/})
   gem.require_paths = ["lib"]
+  gem.required_ruby_version = '>= 1.9.1'
 
   gem.add_dependency 'parslet', '~> 1.5'
 

data/lib/dmarc.rb

@@ -1,4 +1,5 @@
 require 'dmarc/exceptions'
+require 'dmarc/dmarc'
 require 'dmarc/record'
 require 'dmarc/parser'
 require 'dmarc/version'

data/lib/dmarc/dmarc.rb

@@ -0,0 +1,30 @@
+require 'resolv'
+
+module DMARC
+  #
+  # 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)
+    host = "_dmarc.#{domain}"
+
+    begin
+      return resolver.getresource(
+        host, Resolv::DNS::Resource::IN::TXT
+      ).strings.join
+    rescue Resolv::ResolvError
+    end
+  end
+end

data/lib/dmarc/exceptions.rb

@@ -1,19 +1,6 @@
-module DMARC
-  class Error < StandardError; end
-  class InvalidRecord < Error
-    attr_reader :original
-
-    def initialize(msg = nil, original = $!)
-      super msg
-      @original = original
-    end
+require 'parslet'
 
-    def ascii_tree
-      # `cause` is a method defined by parslet on the ParseFailed error
-      # Not to be confused with ruby 2.1's Exception#cause method
-      if self.original != nil
-        self.original.cause.ascii_tree
-      end
-    end
+module DMARC
+  class InvalidRecord < Parslet::ParseFailed
   end
 end

data/lib/dmarc/parser.rb

@@ -1,13 +1,19 @@
 require 'parslet'
 
+require 'uri'
+
 module DMARC
+  #
+  # 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_request.maybe >>
+      dmarc_version.repeat(1,1) >>
       (dmarc_sep >> dmarc_tag).repeat >>
       dmarc_sep.maybe
     end
@@ -20,15 +26,8 @@ module DMARC
       str('DMARC1').as(:v)
     end
 
-    rule(:dmarc_request) do
-      str('p') >> wsp? >> str('=') >> wsp? >> (
-        str('none') |
-        str('quarantine') |
-        str('reject')
-      ).as(:p)
-    end
-
     rule(:dmarc_tag) do
+      dmarc_request   |
       dmarc_srequest  |
       dmarc_auri      |
       dmarc_furi      |
@@ -48,6 +47,10 @@ module DMARC
       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
@@ -167,13 +170,22 @@ module DMARC
 
     class Transform < Parslet::Transform
 
-      rule(:fo_opt => simple(:fo_opt)) { fo_opt }
+      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(:p  => simple(:p))  { {p:  p.to_sym } }
-      rule(:sp => simple(:sp)) { {sp: sp.to_sym} }
+      rule(pct: simple(:pct)) { {pct: pct.to_i} }
+      rule(ri:  simple(:ri))  { {ri:  ri.to_i}  }
 
-      rule(:pct => simple(:pct)) { {pct: pct.to_i} }
-      rule(:ri  => simple(:ri))  { {ri:  ri.to_i}  }
+      rule(uri: simple(:uri)) { URI.parse(uri) }
+      rule(rua: subtree(:uris)) { {rua: Array(uris)} }
+      rule(ruf: subtree(:uris)) { {ruf: Array(uris)} }
 
     end
 
@@ -186,8 +198,8 @@ module DMARC
     # @return [Hash{Symbol => Object}]
     #   The Hash of tags within the record.
     #
-    def parse(record)
-      tags = Transform.new.apply(super(record))
+    def self.parse(record)
+      tags = Transform.new.apply(new.parse(record))
       hash = {}
 
       tags.each { |tag| hash.merge!(tag) }

data/lib/dmarc/record.rb

@@ -1,30 +1,203 @@
+require 'dmarc/dmarc'
 require 'dmarc/parser'
 require 'dmarc/exceptions'
 
+require 'resolv'
+
 module DMARC
-  class Record < Struct.new(:adkim, :aspf, :fo, :p, :pct, :rf, :ri, :rua, :ruf, :sp, :v)
+  class Record
 
-    def self.from_txt(rec)
-      new(Parser.new.parse(rec))
-    rescue Parslet::ParseFailed
-      raise InvalidRecord
-    end
+    # `p` field.
+    # 
+    # @return [:none, :quarantine, :reject]
+    attr_reader :p
+
+    # `rua` field.
+    #
+    # @return [Array<URI::MailTo>]
+    attr_reader :rua
 
-    DEFAULTS = {
-      adkim: 'r',
-      aspf:  'r',
-      fo:    '0',
-      pct:   100,
-      rf:    'afrf',
-      ri:    86400,
-    }
+    # `rua` field.
+    #
+    # @return [Array<URI::MailTo>]
+    attr_reader :ruf
 
+    # `sp` field.
+    # 
+    # @return [:none, :quarantine, :reject]
+    attr_reader :sp
+
+    # `v` field.
+    #
+    # @return [:DMARC1]
+    attr_reader :v
+
+    #
+    # Initializes the record.
+    #
+    # @param [Hash{Symbol => Object}] attributes
+    #   Attributes for the record.
+    #
+    # @option attributes [:r, :s] :adkim (:r)
+    #
+    # @option attributes [:r, :s] :aspf (:r)
+    #
+    # @option attributes [Array<'0', '1', 'd', 's'>] :fo ('0')
+    #
+    # @option attributes [:none, :quarantine, :reject] :p
+    #
+    # @option attributes [Integer] :pct (100)
+    #
+    # @option attributes [:afrf, :iodef] :rf (:afrf)
+    #
+    # @option attributes [Integer] :ri (86400)
+    #
+    # @option attributes [Array<URI::MailTo>] :rua
+    #
+    # @option attributes [Array<URI::MailTo>] :ruf
+    #
+    # @option attributes [:none, :quarantine, :reject] :sp
+    #
+    # @option attributes [:DMARC1] :v
+    #
     def initialize(attributes={})
-      attributes.merge(DEFAULTS).each_pair do |k,v|
-        self[k] = v
+      @adkim, @aspf, @fo, @p, @pct, @rf, @ri, @rua, @ruf, @sp, @v = attributes.values_at(:adkim, :aspf, :fo, :p, :pct, :rf, :ri, :rua, :ruf, :sp, :v)
+    end
+
+    def sp
+      @sp || @p
+    end
+
+    #
+    # `adkim=` field.
+    #
+    # @return [:r, :s]
+    #
+    def adkim
+      @adkim || :r
+    end
+
+    #
+    # `aspf` field.
+    #
+    # @return [:r, :s]
+    #
+    def aspf
+      @aspf || :r
+    end
+
+    #
+    # `fo` field.
+    #
+    # @return [Array<'0', '1', 'd', 's'>]
+    #
+    def fo
+      @fo || %w[0]
+    end
+
+    #
+    # `pct` field.
+    #
+    # @return [Integer]
+    #
+    def pct
+      @pct || 100
+    end
+
+    #
+    # `rf` field.
+    # 
+    # @return [:afrf, :iodef]
+    #
+    def rf
+      @rf || :afrf
+    end
+
+    #
+    # `ri` field.
+    #
+    # @return [Integer]
+    #
+    def ri
+      @ri || 86400
+    end
+
+    #
+    # Parses a DMARC record.
+    #
+    # @param [String] record
+    #   The raw DMARC record.
+    #
+    # @return [Record]
+    #   The parsed DMARC record.
+    #
+    # @raise [InvalidRecord]
+    #   The DMARC record could not be parsed.
+    #
+    # @since 0.3.0
+    #
+    # @api public
+    #
+    def self.parse(record)
+      new(Parser.parse(record))
+    rescue Parslet::ParseFailed => error
+      raise(InvalidRecord.new(error.message,error.cause))
+    end
+
+    #
+    # @deprecated use {parse} instead.
+    #
+    def self.from_txt(rec)
+      parse(rec)
+    end
+
+    #
+    # Queries and parses the DMARC record for a domain.
+    #
+    # @param [String] domain
+    #   The domain to query DMARC for.
+    #
+    # @param [Resolv::DNS] resolver
+    #   The resolver to use.
+    #
+    # @return [Record, nil]
+    #   The parsed DMARC record. If no DMARC record was found, `nil` will be
+    #   returned.
+    #
+    # @raise [InvalidRecord]
+    #   The DMARC record could not be parsed.
+    #
+    # @since 0.3.0
+    #
+    # @api public
+    #
+    def self.query(domain,resolver=Resolv::DNS.new)
+      if (dmarc = DMARC.query(domain,resolver))
+        parse(dmarc)
       end
+    end
+
+    #
+    # Converts the record back to a DMARC String.
+    #
+    # @return [String]
+    #
+    def to_s
+      tags = []
+
+      tags << "v=#{@v}" if @v
+      tags << "p=#{@p}" if @p
+      tags << "sp=#{@sp}" if @sp
+      tags << "rua=#{@rua.join(',')}" if @rua
+      tags << "ruf=#{@ruf.join(',')}" if @ruf
+      tags << "adkim=#{@adkim}" if @adkim
+      tags << "aspf=#{@aspf}" if @aspf
+      tags << "ri=#{@ri}" if @ri
+      tags << "fo=#{@fo.join(':')}" if @fo
+      tags << "rf=#{@rf}" if @rf
+      tags << "pct=#{@pct}" if @pct
 
-      self.sp ||= p
+      return tags.join('; ')
     end
 
   end