ronin-support 0.5.1 → 1.0.0.beta1

data/lib/ronin/support/network/domain.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+#
+# Copyright (c) 2006-2022 Hal Brodigan (postmodern.mod3 at gmail.com)
+#
+# ronin-support is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Lesser General Public License as published
+# by the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# ronin-support is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Lesser General Public License for more details.
+#
+# You should have received a copy of the GNU Lesser General Public License
+# along with ronin-support.  If not, see <https://www.gnu.org/licenses/>.
+#
+
+require 'ronin/support/network/host'
+
+module Ronin
+  module Support
+    module Network
+      #
+      # Represents a domain.
+      #
+      # ## Examples
+      #
+      #     domain = Domain.new('github.com')
+      #     domain.ips
+      #     # => [#<Ronin::Support::Network::IP: 192.30.255.113>]
+      #     domain.ip
+      #     # => #<Ronin::Support::Network::IP: 192.30.255.113>
+      #     domain.mailservers
+      #     # => ["aspmx.l.google.com",
+      #           "alt3.aspmx.l.google.com",
+      #           "alt4.aspmx.l.google.com",
+      #           "alt1.aspmx.l.google.com",
+      #           "alt2.aspmx.l.google.com"]
+      #     domain.nameservers
+      #     # => ["dns1.p08.nsone.net",
+      #           "dns2.p08.nsone.net",
+      #           "dns3.p08.nsone.net",
+      #           "dns4.p08.nsone.net",
+      #           "ns-1283.awsdns-32.org",
+      #           "ns-1707.awsdns-21.co.uk",
+      #           "ns-421.awsdns-52.com",
+      #           "ns-520.awsdns-01.net"]
+      #     domain.txt_strings
+      #     # => ["v=spf1 ip4:192.30.252.0/22 include:_netblocks.google.com include:_netblocks2.google.com include:_netblocks3.google.com include:spf.protection.outlook.com include:mail.zendesk.com include:_spf.salesforce.com include:servers.mcsv.net ip4:166.78.69.169 ip4:1",
+      #           "66.78.69.170 ip4:166.78.71.131 ip4:167.89.101.2 ip4:167.89.101.192/28 ip4:192.254.112.60 ip4:192.254.112.98/31 ip4:192.254.113.10 ip4:192.254.113.101 ip4:192.254.114.176 ip4:62.253.227.114 ~all",
+      #           "MS=6BF03E6AF5CB689E315FB6199603BABF2C88D805",
+      #           "MS=ms44452932",
+      #           "atlassian-domain-verification=jjgw98AKv2aeoYFxiL/VFaoyPkn3undEssTRuMg6C/3Fp/iqhkV4HVV7WjYlVeF8",
+      #           "stripe-verification=f88ef17321660a01bab1660454192e014defa29ba7b8de9633c69d6b4912217f",
+      #           "google-site-verification=UTM-3akMgubp6tQtgEuAkYNYLyYAvpTnnSrDMWoDR3o",
+      #           "MS=ms58704441",
+      #           "docusign=087098e3-3d46-47b7-9b4e-8a23028154cd",
+      #           "adobe-idp-site-verification=b92c9e999aef825edc36e0a3d847d2dbad5b2fc0e05c79ddd7a16139b48ecf4b",
+      #           "apple-domain-verification=RyQhdzTl6Z6x8ZP4"]
+      #
+      # @api public
+      #
+      # @since 1.0.0
+      #
+      class Domain < Host
+      end
+    end
+  end
+end

data/lib/ronin/support/network/email_address.rb

@@ -0,0 +1,574 @@
+# frozen_string_literal: true
+#
+# Copyright (c) 2006-2022 Hal Brodigan (postmodern.mod3 at gmail.com)
+#
+# ronin-support is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Lesser General Public License as published
+# by the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# ronin-support is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Lesser General Public License for more details.
+#
+# You should have received a copy of the GNU Lesser General Public License
+# along with ronin-support.  If not, see <https://www.gnu.org/licenses/>.
+#
+
+require 'ronin/support/network/exceptions'
+
+module Ronin
+  module Support
+    module Network
+      #
+      # Represents an email address.
+      #
+      # ## Features
+      #
+      # * Supports normalizing tagged emails.
+      # * Supports {EmailAddress.deobfuscate deobfuscating} email addresses.
+      # * Supports {EmailAddress#obfuscate obfuscating} email addresses.
+      #
+      # ## Examples
+      #
+      # Builds a new email address:
+      #
+      #     email = EmailAddress.new(mailbox: 'john.smith', domain: 'example.com')
+      #
+      # Parses an email address:
+      #
+      #     email = EmailAddress.parse("John Smith <john.smith@example.com>")
+      #     # => #<Ronin::Support::Network::EmailAddress:0x00007f49586d6a20
+      #           @address=nil,
+      #           @domain="example.com",
+      #           @mailbox="john.smith",
+      #           @name="John Smith",
+      #           @routing=nil,
+      #           @tag=nil>
+      #
+      # Deobfuscate an obfuscated email address:
+      #
+      #     EmailAddress.deobfuscate("john[dot]smith [at] example[dot]com")
+      #     # => "john.smith@example.com"
+      #
+      # Obfuscate an email address:
+      #
+      #     email = EmailAddress.parse("john.smith@example.com")
+      #     email.obfuscate
+      #     # => "john <dot> smith <at> example <dot> com"
+      #
+      # Get every obfuscation of an email address:
+      #
+      #      email.obfuscations
+      #      # => ["john.smith AT example.com",
+      #      #     "john.smith at example.com",
+      #      #     "john.smith[AT]example.com",
+      #      #     "john.smith[at]example.com",
+      #      #     "john.smith [AT] example.com",
+      #      #     "john.smith [at] example.com",
+      #      #     "john.smith<AT>example.com",
+      #      #     "john.smith<at>example.com",
+      #      #     "john.smith <AT> example.com",
+      #      #     "john.smith <at> example.com",
+      #      #     "john.smith{AT}example.com",
+      #      #     "john.smith{at}example.com",
+      #      #     "john.smith {AT} example.com",
+      #      #     "john.smith {at} example.com",
+      #      #     "john.smith(AT)example.com",
+      #      #     "john.smith(at)example.com",
+      #      #     "john.smith (AT) example.com",
+      #      #     "john.smith (at) example.com",
+      #      #     "john DOT smith AT example DOT com",
+      #      #     "john dot smith at example dot com",
+      #      #     "john[DOT]smith[AT]example[DOT]com",
+      #      #     "john[dot]smith[at]example[dot]com",
+      #      #     "john [DOT] smith [AT] example [DOT] com",
+      #      #     "john [dot] smith [at] example [dot] com",
+      #      #     "john<DOT>smith<AT>example<DOT>com",
+      #      #     "john<dot>smith<at>example<dot>com",
+      #      #     "john <DOT> smith <AT> example <DOT> com",
+      #      #     "john <dot> smith <at> example <dot> com",
+      #      #     "john{DOT}smith{AT}example{DOT}com",
+      #      #     "john{dot}smith{at}example{dot}com",
+      #      #     "john {DOT} smith {AT} example {DOT} com",
+      #      #     "john {dot} smith {at} example {dot} com",
+      #      #     "john(DOT)smith(AT)example(DOT)com",
+      #      #     "john(dot)smith(at)example(dot)com",
+      #      #     "john (DOT) smith (AT) example (DOT) com",
+      #      #     "john (dot) smith (at) example (dot) com"]
+      #
+      # @see https://datatracker.ietf.org/doc/html/rfc2822#section-3.4
+      #
+      # @api public
+      #
+      # @since 1.0.0
+      #
+      class EmailAddress
+
+        # The optional name associated with the email address
+        # (ex: `John Smith <john.smith@example.com`).
+        #
+        # @return [String, nil]
+        attr_reader :name
+
+        # The mailbox or username of the email address.
+        #
+        # @return [String]
+        attr_reader :mailbox
+
+        alias username mailbox
+
+        # The optional sorting tag of the email address
+        # (ex: `john.smith+tag@example.com`).
+        #
+        # @return [String, nil]
+        attr_reader :tag
+
+        # Additional hosts to route sent emails through; aka the "percent hack"
+        # (ex: `john.smith%host3.com%host2.com@host1.com`).
+        #
+        # @return [Array<String>, nil]
+        attr_reader :routing
+
+        # The domain of the email address (ex: `john.smith@example.com`).
+        #
+        # @return [String, nil]
+        attr_reader :domain
+
+        # The IP address of the email address (ex: `john.smith@[1.2.3.4]`).
+        #
+        # @return [String, nil]
+        attr_reader :address
+
+        #
+        # Initializes the email address.
+        #
+        # @param [String, nil] name
+        #   The optional name associated with the email address
+        #   (ex: `John Smith <john.smith@example.com`).
+        #
+        # @param [String] mailbox
+        #   The mailbox or username of the email address.
+        #
+        # @param [String, nil] tag
+        #   The optional sorting tag of the email address
+        #   (ex: `john.smith+tag@example.com`).
+        #
+        # @param [Array<String>, nil] routing
+        #   Additional hosts to route sent emails through; aka the
+        #   "percent hack" (ex: `john.smith%host3.com%host2.com@host1.com`).
+        #
+        # @param [String, nil] domain
+        #   The domain of the email address (ex: `john.smith@example.com`).
+        #
+        # @param [String, nil] address
+        #   The IP address of the email address (ex: `john.smith@[1.2.3.4]`).
+        #
+        # @raise [ArgumentError]
+        #   Must specify either the `domain:` or `address:` keyword arguments.
+        #
+        # @example Initializing a basic email address.
+        #   email = EmailAddress.new(mailbox: 'john.smith', domain: 'example.com')
+        #
+        # @example Initializing an email address with a name:
+        #   email = EmailAddress.new(name: 'John Smith', mailbox: 'john.smith', domain: 'example.com')
+        #
+        # @example Initializing an email address with a sorting tag:
+        #   email = EmailAddress.new(mailbox: 'john.smith', tag: 'spam', domain: 'example.com')
+        #
+        def initialize(name: nil, mailbox: , tag: nil, routing: nil, domain: nil, address: nil)
+          @name    = name
+          @mailbox = mailbox
+          @tag     = tag
+          @routing = routing
+
+          unless (domain.nil? ^ address.nil?)
+            raise(ArgumentError,"must specify domain: or address: keyword arguments")
+          end
+
+          @domain  = domain
+          @address = address
+        end
+
+        #
+        # Parses an email address.
+        #
+        # @param [String] string
+        #   The email string to parse.
+        #
+        # @return [EmailAddress]
+        #   The parsed email address.
+        #
+        # @raise [InvalidEmailAddress]
+        #   The string is not a valid formatted email address.
+        #
+        # @example
+        #   email = EmailAddress.parse("John Smith <john.smith@example.com>")
+        #   # => #<Ronin::Support::Network::EmailAddress:0x00007f49586d6a20
+        #         @address=nil,
+        #         @domain="example.com",
+        #         @mailbox="john.smith",
+        #         @name="John Smith",
+        #         @routing=nil,
+        #         @tag=nil>
+        #
+        # @see https://datatracker.ietf.org/doc/html/rfc2822#section-3.4
+        #
+        def self.parse(string)
+          if string.include?('<') && string.end_with?('>')
+            # Name <local-part@domain.com>
+            if (match = string.match(/^([^<]+)\s+<([^>]+)>$/))
+              name    = match[1]
+              address = match[2]
+            else
+              raise(InvalidEmailAddress,"invalid email address: #{string.inspect}")
+            end
+          else
+            name    = nil
+            address = string
+          end
+
+          return new(name: name, **parse_address(address))
+        end
+
+        private
+
+        #
+        # Parses the address portion of an email address.
+        #
+        # @param [String] string
+        #   the email address string to parse.
+        #
+        # @return [Hash{Symbol => Object}]
+        #   Keyword arguments for {#initialize}.
+        #
+        # @raise [InvalidEmailAddress]
+        #   The string did not contain a `@` character.
+        #
+        # @api private
+        #
+        def self.parse_address(string)
+          unless string.include?('@')
+            raise(InvalidEmailAddress,"invalid email address: #{string.inspect}")
+          end
+
+          # local-part@domain.com
+          local_part, domain = string.split('@',2)
+
+          return {**parse_local_part(local_part), **parse_domain(domain)}
+        end
+
+        #
+        # Parses the local-part portion of an email address.
+        #
+        # @param [String] string
+        #   the local-part string to parse.
+        #
+        # @return [Hash{Symbol => Object}]
+        #   Keyword arguments for {#initialize}.
+        #
+        # @api private
+        #
+        def self.parse_local_part(string)
+          routing = nil
+
+          if string.include?('%')
+            mailbox, *routing = string.split('%')
+          else
+            mailbox = string
+            routing = nil
+          end
+
+          return {routing: routing, **parse_mailbox(mailbox)}
+        end
+
+        #
+        # Parses the mailbox portion of an email address.
+        #
+        # @param [String] string
+        #   The mailbox string to parse.
+        #
+        # @return [Hash{Symbol => Object}]
+        #   Keyword arguments for {#initialize}.
+        #
+        # @api private
+        #
+        def self.parse_mailbox(string)
+          # extract any sorting-tags (ex: `user+service@domain.com`)
+          mailbox, tag = string.split('+',2)
+
+          return {mailbox: mailbox, tag: tag}
+        end
+
+        #
+        # Parses the domain portion of an email address.
+        #
+        # @param [String] string
+        #   The domain portion to parse.
+        #
+        # @return [Hash{Symbol => Object}]
+        #   Keyword arguments for {#initialize}.
+        #
+        # @api private
+        #
+        def self.parse_domain(string)
+          domain  = nil
+          address = nil
+
+          # extract IP addresses from the domain part (ex: `user@[1.2.3.4]`)
+          if string.start_with?('[') && string.end_with?(']')
+            address = string[1..-2]
+          else
+            domain  = string
+          end
+
+          return {domain: domain, address: address}
+        end
+
+        public
+
+        # Email address de-obfuscation rules.
+        DEOBFUSCATIONS = {
+          /\s+@\s+/                 => '@',
+          /\s+(?:at|AT)\s+/         => '@',
+          /\s+(?:dot|DOT)\s+/       => '.',
+          /\s*\[(?:at|AT)\]\s*/     => '@',
+          /\s*\[(?:dot|DOT)\]\s*/   => '.',
+          /\s*\<(?:at|AT)\>\s*/     => '@',
+          /\s*\<(?:dot|DOT)\>\s*/   => '.',
+          /\s*\{(?:at|AT)\}\s*/     => '@',
+          /\s*\{(?:dot|DOT)\}\s*/   => '.',
+          /\s*\((?:at|AT)\)\s*/     => '@',
+          /\s*\((?:dot|DOT)\)\s*/   => '.'
+        }
+
+        #
+        # Deobfuscates an obfuscated email address.
+        #
+        # @param [String] string
+        #   The obfuscated email address to deobfuscate.
+        #
+        # @return [String]
+        #   The deobfuscated email address.
+        #
+        # @example
+        #   EmailAddress.deobfuscate("john[dot]smith [at] example[dot]com")
+        #   # => "john.smith@example.com"
+        #
+        def self.deobfuscate(string)
+          DEOBFUSCATIONS.each do |pattern,replace|
+            string = string.gsub(pattern,replace)
+          end
+
+          return string
+        end
+
+        #
+        # Creates a new email address without the {#tag} or {#routing}
+        # attribute.
+        #
+        # @return [EmailAddress]
+        #   The new normalized email address object.
+        #
+        # @example
+        #   email = EmailAddress.parse("John Smith <john.smith+spam@example.com>")
+        #   email.normalize.to_s
+        #   # => "john.smith@example.com"
+        #
+        def normalize
+          EmailAddress.new(
+            mailbox: mailbox,
+            domain:  domain,
+            address: address
+          )
+        end
+
+        #
+        # The hostname to connect to.
+        #
+        # @return [String]
+        #   The {#domain} or {#address}.
+        #
+        def hostname
+          @domain || @address
+        end
+
+        #
+        # Converts the email address back into a string.
+        #
+        # @return [String]
+        #   The string representation of the email address.
+        #
+        # @example
+        #   email = EmailAddress.parse("John Smith <john.smith+spam@example.com>")
+        #   email.to_s
+        #   # => "John Smith <john.smith+spam@example.com>"
+        #
+        def to_s
+          string = "#{@mailbox}"
+          string << "+#{@tag}"               if @tag
+          string << "%#{@routing.join('%')}" if @routing
+          string << "@"
+          string << if @address then "[#{@address}]"
+                    else             @domain
+                    end
+          string = "#{@name} <#{string}>" if @name
+          return string
+        end
+
+        alias to_str to_s
+
+        #
+        # @group Obfuscation Methods
+        #
+
+        # Email address obfuscation rules.
+        OBFUSCATIONS = [
+          [/\@/, {'@' => ' @ '  }],
+          [/\@/, {'@' => ' AT '  }],
+          [/\@/, {'@' => ' at '  }],
+          [/\@/, {'@' => '[AT]'  }],
+          [/\@/, {'@' => '[at]'  }],
+          [/\@/, {'@' => ' [AT] '}],
+          [/\@/, {'@' => ' [at] '}],
+          [/\@/, {'@' => '<AT>'  }],
+          [/\@/, {'@' => '<at>'  }],
+          [/\@/, {'@' => ' <AT> '}],
+          [/\@/, {'@' => ' <at> '}],
+          [/\@/, {'@' => '{AT}'  }],
+          [/\@/, {'@' => '{at}'  }],
+          [/\@/, {'@' => ' {AT} '}],
+          [/\@/, {'@' => ' {at} '}],
+          [/\@/, {'@' => '(AT)'  }],
+          [/\@/, {'@' => '(at)'  }],
+          [/\@/, {'@' => ' (AT) '}],
+          [/\@/, {'@' => ' (at) '}],
+          [/[\.\@]/, {'.' => ' DOT ',   '@' => ' AT '  }],
+          [/[\.\@]/, {'.' => ' dot ',   '@' => ' at '  }],
+          [/[\.\@]/, {'.' => '[DOT]',   '@' => '[AT]'  }],
+          [/[\.\@]/, {'.' => '[dot]',   '@' => '[at]'  }],
+          [/[\.\@]/, {'.' => ' [DOT] ', '@' => ' [AT] '}],
+          [/[\.\@]/, {'.' => ' [dot] ', '@' => ' [at] '}],
+          [/[\.\@]/, {'.' => '<DOT>',   '@' => '<AT>'  }],
+          [/[\.\@]/, {'.' => '<dot>',   '@' => '<at>'  }],
+          [/[\.\@]/, {'.' => ' <DOT> ', '@' => ' <AT> '}],
+          [/[\.\@]/, {'.' => ' <dot> ', '@' => ' <at> '}],
+          [/[\.\@]/, {'.' => '{DOT}',   '@' => '{AT}'  }],
+          [/[\.\@]/, {'.' => '{dot}',   '@' => '{at}'  }],
+          [/[\.\@]/, {'.' => ' {DOT} ', '@' => ' {AT} '}],
+          [/[\.\@]/, {'.' => ' {dot} ', '@' => ' {at} '}],
+          [/[\.\@]/, {'.' => '(DOT)',   '@' => '(AT)'  }],
+          [/[\.\@]/, {'.' => '(dot)',   '@' => '(at)'  }],
+          [/[\.\@]/, {'.' => ' (DOT) ', '@' => ' (AT) '}],
+          [/[\.\@]/, {'.' => ' (dot) ', '@' => ' (at) '}]
+        ]
+
+        #
+        # Obfuscates the email address.
+        #
+        # @return [String]
+        #   A randomly obfuscated version of the email address.
+        #
+        # @see OBFUSCATIONS
+        #
+        # @example
+        #   email = EmailAddress.parse("john.smith@example.com")
+        #   email.obfuscate
+        #   # => "john.smith [AT] example.com"
+        #   email.obfuscate
+        #   # => "john <dot> smith <at> example <dot> com"
+        #
+        def obfuscate
+          string = to_s
+          string.gsub!(*OBFUSCATIONS.sample)
+          return string
+        end
+
+        #
+        # Enumerates over each obfuscation of the email address.
+        #
+        # @yield [obfuscated]
+        #   If a block is given, it will be passed every obfuscation of the
+        #   email address.
+        #
+        # @yieldparam [String] obfuscated
+        #   An obfuscated version of the email address.
+        #
+        # @return [Enumerator]
+        #   If no block is given, an Enumerator will be returned.
+        #
+        # @example
+        #   email = EmailAddress.parse("john.smith@example.com")
+        #   email.each_obfuscation { |obfuscated_email| ... }
+        #
+        # @see OBFUSCATIONS
+        #
+        def each_obfuscation
+          return enum_for(__method__) unless block_given?
+
+          string = to_s
+
+          OBFUSCATIONS.each do |gsub_args|
+            yield string.gsub(*gsub_args)
+          end
+
+          return nil
+        end
+
+        #
+        # Returns every obfuscation of the email address.
+        #
+        # @return [Array<String>]
+        #   The Array containing every obfuscation of the email address.
+        #
+        # @example
+        #   email = EmailAddress.parse("john.smith@example.com")
+        #   email.obfuscations
+        #   # => ["john.smith AT example.com",
+        #   #     "john.smith at example.com",
+        #   #     "john.smith[AT]example.com",
+        #   #     "john.smith[at]example.com",
+        #   #     "john.smith [AT] example.com",
+        #   #     "john.smith [at] example.com",
+        #   #     "john.smith<AT>example.com",
+        #   #     "john.smith<at>example.com",
+        #   #     "john.smith <AT> example.com",
+        #   #     "john.smith <at> example.com",
+        #   #     "john.smith{AT}example.com",
+        #   #     "john.smith{at}example.com",
+        #   #     "john.smith {AT} example.com",
+        #   #     "john.smith {at} example.com",
+        #   #     "john.smith(AT)example.com",
+        #   #     "john.smith(at)example.com",
+        #   #     "john.smith (AT) example.com",
+        #   #     "john.smith (at) example.com",
+        #   #     "john DOT smith AT example DOT com",
+        #   #     "john dot smith at example dot com",
+        #   #     "john[DOT]smith[AT]example[DOT]com",
+        #   #     "john[dot]smith[at]example[dot]com",
+        #   #     "john [DOT] smith [AT] example [DOT] com",
+        #   #     "john [dot] smith [at] example [dot] com",
+        #   #     "john<DOT>smith<AT>example<DOT>com",
+        #   #     "john<dot>smith<at>example<dot>com",
+        #   #     "john <DOT> smith <AT> example <DOT> com",
+        #   #     "john <dot> smith <at> example <dot> com",
+        #   #     "john{DOT}smith{AT}example{DOT}com",
+        #   #     "john{dot}smith{at}example{dot}com",
+        #   #     "john {DOT} smith {AT} example {DOT} com",
+        #   #     "john {dot} smith {at} example {dot} com",
+        #   #     "john(DOT)smith(AT)example(DOT)com",
+        #   #     "john(dot)smith(at)example(dot)com",
+        #   #     "john (DOT) smith (AT) example (DOT) com",
+        #   #     "john (dot) smith (at) example (dot) com"]
+        #
+        # @see #each_obfuscation
+        #
+        def obfuscations
+          each_obfuscation.to_a
+        end
+
+      end
+    end
+  end
+end