dmarc 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 3b3ddde1f4d2db595acab01a63352cb7a62e9cdf
-  data.tar.gz: 8199be76eb510e8693dc45fe296227ec4a00f9e4
+  metadata.gz: da372737bb262f1d63188a9bfac317660bb8cdb4
+  data.tar.gz: d29823cc84b2e12a8aa6c37d4cfe0c1c0ad95006
 SHA512:
-  metadata.gz: 0a1762477121db2b245d80c5929432850e68727043d019bd272a5fabbe26d766005e25bbc28e872fcfafcd03b7b1e18ec899d8de447b7630310e69cbaab8ae9a
-  data.tar.gz: aaf8c594a50a80c593976dad9d9d532e3abbae5fa7e1d42aa0c2743810588e16e156496650872698cecad50959f7c2b9b22f67e238ee7a56cafff7400a82d9fd
+  metadata.gz: 938905706d15411759c04133451472d0d7d9565982240ed9747e1566b2c450cab830b66ae6edffbfe8e193ea91bd1aae0dab655a4b6c453b181755f549930e21
+  data.tar.gz: 764c5540136f70d7d7abd04a5b28253473c8288d82f934f1ad2f57f93d1bbc85ad832277d967957b568f8a27615007ce472a1d09a002cc7ab6c6bd2523145c41

data/.document

@@ -0,0 +1,3 @@
+- 
+ChangeLog.md
+LICENSE.txt

data/.rspec

@@ -0,0 +1 @@
+--colour --format documentation

data/.travis.yml

@@ -0,0 +1,7 @@
+language: ruby
+rvm:
+  - 1.9.3
+  - 2.0.0
+  - 2.1.0
+  - jruby-19mode
+  - rbx-2

data/.yardopts

@@ -0,0 +1 @@
+--markup markdown --title "DMARC Documentation" --protected

data/ChangeLog.md

@@ -0,0 +1,12 @@
+### 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/Gemfile

@@ -1,3 +1,12 @@
 source 'https://rubygems.org'
 
 gemspec
+
+group :development do
+  gem 'rake'
+  gem 'nokogiri'
+  gem 'rspec', '~> 3.0'
+
+  gem 'kramdown'
+  gem 'yard', '~> 0.8'
+end

data/README.md

@@ -1,17 +1,41 @@
-dmarc
-=====
+# DMARC
 
-[DMARC](http://tools.ietf.org/html/draft-kucherawy-dmarc-base-02) is a
-technical specification intended to solve a couple of long-standing email
-authentication problems. DMARC policies are described in DMARC "records," which
-are stored as DNS TXT records on a subdomain. This library contains a parser
-for DMARC records.
+[![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)
 
-Usage
------
+[DMARC] is a technical specification intended to solve a couple of long-standing
+email authentication problems. DMARC policies are described in DMARC "records," 
+which are stored as DNS TXT records on a subdomain. This library contains a
+parser for DMARC records.
 
-```ruby
-require 'dmarc/record'
-record = DMARC::Record.from_txt(txt) # txt is a DNS TXT record containing the DMARC policy
-```
+## Example
 
+    require 'dmarc'
+
+    record = DMARC::Record.from_txt(txt)
+
+## Requirements
+
+* [parslet] ~> 1.5
+
+## Install
+
+    $ gem install dmarc
+
+## Testing
+
+To run the RSpec tests:
+
+    $ rake spec
+
+To test the parser against the Alexa Top 500:
+
+    $ rake spec:gauntlet
+
+## License
+
+See the {file:LICENSE.txt} file.
+
+[DMARC]: http://tools.ietf.org/html/draft-kucherawy-dmarc-base-02
+[parslet]: http://kschiess.github.io/parslet/

data/Rakefile

@@ -16,9 +16,18 @@ require 'bundler/gem_tasks'
 require 'rspec/core/rake_task'
 RSpec::Core::RakeTask.new
 
+namespace :spec do
+  desc "Tests DMARC::Parser against Alexa Top 500"
+  RSpec::Core::RakeTask.new(:gauntlet) do |t|
+    t.rspec_opts = '--tag gauntlet'
+  end
+end
+
 task :test    => :spec
 task :default => :spec
 
 require 'yard'
 YARD::Rake::YardocTask.new  
 task :doc => :yard
+
+require_relative 'tasks/alexa'

data/dmarc.gemspec

@@ -20,7 +20,4 @@ Gem::Specification.new do |gem|
   gem.add_dependency 'parslet', '~> 1.5'
 
   gem.add_development_dependency 'bundler', '~> 1.0'
-  gem.add_development_dependency 'rake',    '~> 10.0'
-  gem.add_development_dependency 'rspec',   '~> 2.8'
-  gem.add_development_dependency 'yard',    '~> 0.8'
 end

data/lib/dmarc.rb

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

data/lib/dmarc/exceptions.rb

@@ -0,0 +1,19 @@
+module DMARC
+  class Error < StandardError; end
+  class InvalidRecord < Error
+    attr_reader :original
+
+    def initialize(msg = nil, original = $!)
+      super msg
+      @original = original
+    end
+
+    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
+  end
+end

data/lib/dmarc/parser.rb

@@ -3,175 +3,197 @@ require 'parslet'
 module DMARC
   class Parser < Parslet::Parser
 
-    root('dmarc_record')
-    rule('dmarc_record') do
-      dmarc_version >>
-      (dmarc_sep >> (
-        dmarc_request |
-        dmarc_srequest |
-        dmarc_auri |
-        dmarc_furi |
-        dmarc_adkim |
-        dmarc_aspf |
-        dmarc_ainterval |
-        dmarc_rfmt |
-        dmarc_percent
-      )).repeat >>
+    root :dmarc_record
+
+    rule(:dmarc_record) do
+      dmarc_version.repeat(1,1) >> dmarc_sep >>
+      dmarc_request.maybe >>
+      (dmarc_sep >> dmarc_tag).repeat >>
       dmarc_sep.maybe
     end
 
-    rule('dmarc_version') do
-      str('v') >> wsp.repeat >>
-      str('=') >> wsp.repeat >>
+    rule(:dmarc_sep) { wsp? >> str(';') >> wsp? }
+
+    rule(:dmarc_version) do
+      str('v') >> wsp? >>
+      str('=') >> wsp? >>
       str('DMARC1').as(:v)
     end
-    rule('dmarc_sep') { wsp.repeat >> str(';') >> wsp.repeat }
 
-    rule('dmarc_request') do
-      str('p') >> wsp.repeat >> str('=') >> wsp.repeat >> (
+    rule(:dmarc_request) do
+      str('p') >> wsp? >> str('=') >> wsp? >> (
         str('none') |
         str('quarantine') |
         str('reject')
       ).as(:p)
     end
 
-    rule('dmarc_srequest') do
-      str('sp') >> wsp.repeat >> str('=') >> wsp.repeat >> (
-        str('none') |
-        str('quarantine') |
-        str('reject')
-      ).as(:sp)
+    rule(:dmarc_tag) do
+      dmarc_srequest  |
+      dmarc_auri      |
+      dmarc_furi      |
+      dmarc_adkim     |
+      dmarc_aspf      |
+      dmarc_ainterval |
+      dmarc_fo        |
+      dmarc_rfmt      |
+      dmarc_percent   |
+      unknown_tag
     end
 
-    rule('dmarc_auri') do
-      str('rua') >> wsp.repeat >> str('=') >> wsp.repeat >>
-      dmarc_uri.as(:rua) >> (
-        wsp.repeat >> str(',') >> wsp.repeat >> dmarc_uri.as(:rua)
-      ).repeat
+    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
 
-    rule('dmarc_ainterval') do
-      str('ri') >> wsp.repeat >> str('=') >> wsp.repeat >> digit.repeat(1).as(:ri)
+    tag_rule(:srequest,'sp') do
+      str('none') | str('quarantine') | str('reject')
     end
 
-    rule('dmarc_furi') do
-      str('ruf') >> wsp.repeat >> str('=') >> wsp.repeat >>
-      dmarc_uri.as(:ruf) >> (wsp.repeat >> str(',') >> wsp.repeat >> dmarc_uri.as(:ruf)).repeat
+    tag_rule(:auri, 'rua') do
+      dmarc_uri >> (wsp? >> str(',') >> wsp? >> dmarc_uri).repeat
     end
 
-    rule('dmarc_rfmt') do
-      str('rf') >> wsp.repeat >> str('=') >> wsp.repeat >> (
-        str('afrf') |
-        str('iodef')
-      ).as(:rf)
-    end
+    tag_rule(:ainterval,'ri') { digit.repeat(1) }
 
-    rule('dmarc_percent') do
-      str('pct') >> wsp.repeat >> str('=') >> wsp.repeat >> digit.repeat(1, 3).as(:pct)
+    tag_rule(:furi,'ruf') do
+      dmarc_uri >> (wsp? >> str(',') >> wsp? >> dmarc_uri).repeat
     end
 
-    rule('dmarc_adkim') do
-      str('adkim') >> wsp.repeat >> str('=') >> wsp.repeat >> (
-        str('r') |
-        str('s')
-      ).as(:adkim)
+    tag_rule(:fo,'fo') do
+      fo_opt >> (wsp? >> str(':') >> wsp? >> fo_opt).repeat
     end
 
-    rule('dmarc_aspf') do
-      str('aspf') >> wsp.repeat >> str('=') >> wsp.repeat >> (
-        str('r') |
-        str('s')
-      ).as(:aspf)
-    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) }
 
-    rule('dmarc_uri') do
+    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
       uri.as(:uri) >> (
         str('!') >> digit.repeat(1).as(:size) >> (
-          str('k') |
-          str('m') |
-          str('g') |
-          str('t')
+          match['kmgt']
         ).as(:unit).maybe
       ).maybe
     end
 
-    rule('uri') do
+    rule(:uri) do
       ( absoluteURI | relativeURI ).maybe >>
       ( str('#') >> fragment ).maybe
     end
-    rule('absoluteURI') { scheme >> str(':') >> ( hier_part | opaque_part ) }
-    rule('relativeURI') do
+    rule(:absoluteURI) { scheme >> str(':') >> ( hier_part | opaque_part ) }
+    rule(:relativeURI) do
       ( net_path | abs_path | rel_path ) >> ( str('?') >> query ).maybe
     end
 
-    rule('hier_part') do
+    rule(:hier_part) do
       ( net_path | abs_path ) >> ( str('?') >> query )
     end
-    rule('opaque_part') do
+    rule(:opaque_part) do
       uric_no_slash >> uric.repeat
     end
 
-    rule('uric_no_slash') do
+    rule(:uric_no_slash) do
       unreserved | escaped | match('[?:@&=+$]')
     end
 
-    rule('net_path') { str('//') >> authority >> abs_path.maybe }
-    rule('abs_path') { str('/') >> path_segments }
-    rule('rel_path') { rel_segment >> abs_path.maybe }
+    rule(:net_path) { str('//') >> authority >> abs_path.maybe }
+    rule(:abs_path) { str('/') >> path_segments }
+    rule(:rel_path) { rel_segment >> abs_path.maybe }
 
-    rule('rel_segment') { ( unreserved | escaped | match('[@&=+$]') ).repeat(1) }
+    rule(:rel_segment) { ( unreserved | escaped | match('[@&=+$]') ).repeat(1) }
 
-    rule('scheme') { alpha >> ( alpha | digit | match('[+-.]') ).repeat }
+    rule(:scheme) { alpha >> ( alpha | digit | match('[+-.]') ).repeat }
 
-    rule('authority') { server | reg_name }
+    rule(:authority) { server | reg_name }
 
-    rule('reg_name') { ( unreserved | escaped | match('[$:@&=+]') ).repeat(1) }
+    rule(:reg_name) { ( unreserved | escaped | match('[$:@&=+]') ).repeat(1) }
 
-    rule('server') { ( ( userinfo >> str('@') ).maybe >> hostport ).maybe }
-    rule('userinfo') { ( unreserved | escaped | match('[:&=+$]') ).repeat }
+    rule(:server) { ( ( userinfo >> str('@') ).maybe >> hostport ).maybe }
+    rule(:userinfo) { ( unreserved | escaped | match('[:&=+$]') ).repeat }
 
-    rule('hostport') { host >> ( str(':') >> port ).maybe }
-    rule('host') { hostname | ipv4address }
-    rule('hostname') do
+    rule(:hostport) { host >> ( str(':') >> port ).maybe }
+    rule(:host) { hostname | ipv4address }
+    rule(:hostname) do
       ( domainlabel >> str('.') ).repeat >> toplabel >> str('.').maybe
     end
-    rule('domainlabel') do
+    rule(:domainlabel) do
       alphanum | (
         alphanum >> ( alphanum | str('-') ).repeat >> alphanum
       )
     end
-    rule('toplabel') do
+    rule(:toplabel) do
       alpha | (
         alpha >> ( alphanum | str('-') ).repeat >> alphanum
       )
     end
-    rule('ipv4address') do
+    rule(:ipv4address) do
       digit.repeat(1) >> str('.') >>
       digit.repeat(1) >> str('.') >>
       digit.repeat(1) >> str('.') >>
       digit.repeat(1)
     end
-    rule('port') { digit.repeat }
-
-    rule('path') { ( abs_path | opaque_part ).maybe }
-    rule('path_segments') { segment >> ( str('/') >> segment ).repeat }
-    rule('segment') { pchar.repeat >> ( str(';') >> param ).repeat }
-    rule('param') { pchar }
-    rule('pchar') { unreserved | escaped | match('[:@&=+$]') }
-
-    rule('query') { uric.repeat }
-    rule('fragment') { uric.repeat }
-
-    rule('uric') { reserved | unreserved | escaped }
-    rule('reserved') { match('[/?:@&=+$]') }
-    rule('unreserved') { alphanum | mark }
-    rule('mark') { match("[-_.~*'()]") }
-    rule('escaped') { str('%') >> hex >> hex }
-    rule('hex') { digit | match('[a-fA-F]') }
-    rule('alphanum') { alpha | digit }
-    rule('alpha') { match('[a-zA-Z]') }
-    rule('digit') { match('[0-9]') }
-    rule('wsp') { str(' ') | str("\t") }
+    rule(:port) { digit.repeat }
+
+    rule(:path) { ( abs_path | opaque_part ).maybe }
+    rule(:path_segments) { segment >> ( str('/') >> segment ).repeat }
+    rule(:segment) { pchar.repeat >> ( str(';') >> param ).repeat }
+    rule(:param) { pchar }
+    rule(:pchar) { unreserved | escaped | match('[:@&=+$]') }
+
+    rule(:query) { uric.repeat }
+    rule(:fragment) { uric.repeat }
+
+    rule(:uric) { reserved | unreserved | escaped }
+    rule(:reserved) { match('[/?:@&=+$]') }
+    rule(:unreserved) { alphanum | mark }
+    rule(:mark) { match("[-_.~*'()]") }
+    rule(:escaped) { str('%') >> hex >> hex }
+    rule(:hex) { digit | match('[a-fA-F]') }
+    rule(:alphanum) { alpha | digit }
+    rule(:alpha) { match('[a-zA-Z]') }
+    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(: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}  }
+
+    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 parse(record)
+      tags = Transform.new.apply(super(record))
+      hash = {}
+
+      tags.each { |tag| hash.merge!(tag) }
+
+      return hash
+    end
 
   end
 end