phisher_phinder 0.1.0

data/lib/phisher_phinder/mail_parser/received_headers/classifier.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module PhisherPhinder
+  module MailParser
+    module ReceivedHeaders
+      class Classifier
+        def classify(header_data)
+          {partial: !complete?(header_data)}
+        end
+
+        private
+
+        def complete?(header_data)
+          (
+            header_data[:advertised_sender] &&
+            header_data[:recipient] &&
+            header_data[:recipient_mailbox] &&
+            (
+              (header_data[:protocol] == 'ESMTPS' && header_data[:starttls]) ||
+              (header_data[:protocol] != 'ESMTPS' && !header_data[:starttls])
+            )
+          )
+        end
+      end
+    end
+  end
+end

data/lib/phisher_phinder/mail_parser/received_headers/for_parser.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module PhisherPhinder
+  module MailParser
+    module ReceivedHeaders
+      class ForParser
+        def parse(component)
+          component =~ /\Afor\s(\S+)\z/
+
+          {
+            recipient_mailbox: strip_angle_brackets($1)
+          }
+        end
+
+        private
+
+        def strip_angle_brackets(email_address_string)
+          email_address_string =~ /\<([^>]+)\>/ ? $1 : email_address_string
+        end
+      end
+    end
+  end
+end

data/lib/phisher_phinder/mail_parser/received_headers/from_parser.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module PhisherPhinder
+  module MailParser
+    module ReceivedHeaders
+      class FromParser
+        def initialize(extended_ip_factory)
+          @extended_ip_factory = extended_ip_factory
+        end
+
+        def parse(component)
+          return {advertised_sender: nil, helo: nil, sender: nil} unless component
+
+          patterns = [
+            /from\s(?<advertised_sender>[\S]+)\s\(HELO\s(?<helo>[^)]+)\)\s\(\[(?<sender_ip>[^\]]+)\]\)/,
+            /from\s(?<advertised_sender>[\S]+)\s\((?<sender_host>\S+?)\.?\s\[(?<sender_ip>[^\]]+)\]\)/,
+            /from\s(?<advertised_sender>\S+)\s\((?<sender_host>\S+?)\.?\s(?<sender_ip>\S+?)\)/,
+            /from\s(?<advertised_sender>\S+)\s\(\[(?<sender_ip>[^\]]+)\]\)/,
+            /from\s(?<advertised_sender>\S+)\s\((?<sender_ip>[^)]+)\)/,
+            /\(from\s(?<advertised_sender>[^)]+)\)/,
+            /from\s(?<advertised_sender>\S+)/,
+          ]
+
+          matches = patterns.inject(nil) do |memo, pattern|
+            memo || component.match(pattern)
+          end
+
+          {
+            advertised_sender: matches[:advertised_sender],
+            helo: matches.names.include?('helo') ? matches[:helo] : nil,
+            sender: {
+              host: matches.names.include?('sender_host') ? matches[:sender_host] : nil,
+              ip: matches.names.include?('sender_ip') ? @extended_ip_factory.build(matches[:sender_ip]) : nil
+            }
+          }
+        end
+      end
+    end
+  end
+end

data/lib/phisher_phinder/mail_parser/received_headers/parser.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+module PhisherPhinder
+  module MailParser
+    module ReceivedHeaders
+      class Parser
+        def initialize(by_parser:, for_parser:, from_parser:, starttls_parser:, timestamp_parser:, classifier:)
+          @parsers = {
+            by: by_parser,
+            for: for_parser,
+            from: from_parser,
+            starttls: starttls_parser,
+            time: timestamp_parser,
+          }
+          @classifier = classifier
+        end
+
+        def parse(header)
+          require 'strscan'
+
+          header_value, timestamp = header.split(';')
+
+          parsers = [@by_parser, @for_parser, @from_parser, @starttls_parser, @timestamp_parser]
+          components = extract_value_components(header_value).merge(time: timestamp)
+
+          output = @parsers.inject({}) do |memo, (component_name, parser)|
+            memo.merge(parser.parse(components[component_name]))
+          end
+
+          output.merge(@classifier.classify(output))
+        end
+
+        private
+
+        def extract_value_components(header_value)
+          require 'strscan'
+
+          scanner = StringScanner.new(header_value)
+
+          output = {}
+
+          if scanner.check(/\(from\s+[^)]+\)/)
+            from_part = scanner.scan(/\(from\s+[^)]+\)/)
+          elsif scanner.check(/from\s.+?\(HELO\s[^)]+\)\s\(\[[^\]]+\]\)/)
+            from_part = scanner.scan(/from.+?(?=by)/)
+          elsif scanner.check(/from\s[^)(]+\sby/)
+            from_part = scanner.scan(/from.+?(?=by)/)
+          else
+            from_part = scanner.scan(/from\s.+?\([^)]+?\)/)
+          end
+
+          if scanner.check(/.+\S+\s+by/)
+            starttls_part = scanner.scan(/.+\s(?=by)/)
+            by_part = scanner.scan(/\s?by.+?\sid\s[\S]+\s?/)
+            for_part = scanner.scan(/for\s+\S+/)
+          elsif scanner.check(/\s?by.+?\s(id|ID)\s[\S]+\s?/)
+            by_part = scanner.scan(/\s?by.+?\s(id|ID)\s[\S]+\s?/) unless scanner.eos?
+            for_part = scanner.scan(/for\s+\S+/) unless scanner.eos?
+            starttls_part = scanner.rest unless scanner.eos?
+          elsif scanner.check(/by.+(?!\sid)/)
+            by_part = scanner.scan(/.+/)
+          end
+
+          {
+            by: by_part,
+            for: for_part,
+            from: from_part,
+            starttls: starttls_part
+          }
+        end
+      end
+    end
+  end
+end

data/lib/phisher_phinder/mail_parser/received_headers/starttls_parser.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module PhisherPhinder
+  module MailParser
+    module ReceivedHeaders
+      class StarttlsParser
+        def parse(component)
+          return {starttls: nil} unless component
+
+          patterns = [
+            /\(version=(?<version>\S+)\scipher=(?<cipher>\S+)\sbits=(?<bits>\S+)\)/,
+            /using\s(?<version>\S+)\swith cipher\s(?<cipher>\S+)\s\((?<bits>.+?) bits\)/
+          ]
+
+          matches = patterns.inject(nil) do |memo, pattern|
+            memo || component.match(pattern)
+          end
+
+          {starttls: {version: matches[:version], cipher: matches[:cipher], bits: matches[:bits]}}
+        end
+      end
+    end
+  end
+end

data/lib/phisher_phinder/mail_parser/received_headers/timestamp_parser.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module PhisherPhinder
+  module MailParser
+    module ReceivedHeaders
+      class TimestampParser
+        def parse(timestamp)
+          return {time: nil} unless timestamp
+
+          require 'time'
+
+          date_formats = [
+            "%a, %d %b %Y %H:%M:%S %z (%Z)",
+            "%a, %d %b %Y %H:%M:%S %z",
+            "%d %b %Y %H:%M:%S %z"
+          ]
+
+          parsed_time = date_formats.inject(nil) do |parsed_time, pattern|
+            begin
+              parsed_time || Time.strptime(timestamp.strip, pattern)
+            rescue ArgumentError
+            end
+          end
+
+          raise "Could not match `#{timestamp}` with the available patterns" unless parsed_time
+
+          {time: parsed_time}
+        end
+      end
+    end
+  end
+end

data/lib/phisher_phinder/simple_ip.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal
+
+module PhisherPhinder
+  class SimpleIp
+    attr_reader :ip_address
+
+    def initialize(ip_address:)
+      @ip_address = ip_address
+    end
+
+    def ==(other)
+      other.is_a?(SimpleIp) && ip_address == other.ip_address
+    end
+  end
+end

data/lib/phisher_phinder/version.rb

@@ -0,0 +1,3 @@
+module PhisherPhinder
+  VERSION = "0.1.0"
+end

data/phisher_phinder.gemspec

@@ -0,0 +1,32 @@
+require_relative 'lib/phisher_phinder/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "phisher_phinder"
+  spec.version       = PhisherPhinder::VERSION
+  spec.authors       = ["Rory McKinley"]
+  spec.email         = ["rorymckinley@gmail.com"]
+
+  spec.summary       = %q{A gem for dissecting phishing emails}
+  spec.description   = %q{A collection of tools to dissect and report on phishing emails}
+  spec.homepage      = "https://capefox.co"
+  spec.license       = "MIT"
+  spec.required_ruby_version = Gem::Requirement.new(">= 2.3.0")
+
+  spec.metadata["allowed_push_host"] = "https://rubygems.org"
+
+  spec.metadata["homepage_uri"] = spec.homepage
+  spec.metadata["source_code_uri"] = "https://github.com/rorymckinley/phisher_phinder"
+  spec.metadata["changelog_uri"] = "https://github.com/rorymckinley/phisher_phinder/blob/master/CHANGELOG.md"
+
+  # Specify which files should be added to the gem when it is released.
+  # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
+  spec.files         = Dir.chdir(File.expand_path('..', __FILE__)) do
+    `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
+  end
+  spec.bindir        = "exe"
+  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  spec.add_development_dependency "pry"
+  spec.add_development_dependency "rspec", "3.9.0"
+end

metadata

@@ -0,0 +1,112 @@
+--- !ruby/object:Gem::Specification
+name: phisher_phinder
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Rory McKinley
+autorequire: 
+bindir: exe
+cert_chain: []
+date: 2020-09-23 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: pry
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 3.9.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 3.9.0
+description: A collection of tools to dissect and report on phishing emails
+email:
+- rorymckinley@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".env.example"
+- ".gitignore"
+- ".rspec"
+- ".ruby-gemset"
+- ".ruby-version"
+- ".travis.yml"
+- CHANGELOG.md
+- Gemfile
+- Gemfile.lock
+- LICENSE
+- LICENSE.txt
+- README.md
+- Rakefile
+- bin/console
+- bin/setup
+- db/migrations/0001_create_geo_ip_cache.rb
+- lib/phisher_phinder.rb
+- lib/phisher_phinder/body_hyperlink.rb
+- lib/phisher_phinder/cached_geoip_client.rb
+- lib/phisher_phinder/expanded_data_processor.rb
+- lib/phisher_phinder/extended_ip.rb
+- lib/phisher_phinder/extended_ip_factory.rb
+- lib/phisher_phinder/geoip_ip_data.rb
+- lib/phisher_phinder/mail.rb
+- lib/phisher_phinder/mail_parser.rb
+- lib/phisher_phinder/mail_parser/body_parser.rb
+- lib/phisher_phinder/mail_parser/header_value_parser.rb
+- lib/phisher_phinder/mail_parser/received_headers/by_parser.rb
+- lib/phisher_phinder/mail_parser/received_headers/classifier.rb
+- lib/phisher_phinder/mail_parser/received_headers/for_parser.rb
+- lib/phisher_phinder/mail_parser/received_headers/from_parser.rb
+- lib/phisher_phinder/mail_parser/received_headers/parser.rb
+- lib/phisher_phinder/mail_parser/received_headers/starttls_parser.rb
+- lib/phisher_phinder/mail_parser/received_headers/timestamp_parser.rb
+- lib/phisher_phinder/simple_ip.rb
+- lib/phisher_phinder/version.rb
+- phisher_phinder.gemspec
+homepage: https://capefox.co
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+  homepage_uri: https://capefox.co
+  source_code_uri: https://github.com/rorymckinley/phisher_phinder
+  changelog_uri: https://github.com/rorymckinley/phisher_phinder/blob/master/CHANGELOG.md
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.3.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.1.2
+signing_key: 
+specification_version: 4
+summary: A gem for dissecting phishing emails
+test_files: []