ronin-support 0.5.1 → 1.0.0.beta1

data/lib/ronin/support/network/http/request.rb

@@ -0,0 +1,215 @@
+# 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/http/user_agents'
+require 'ronin/support/network/http/cookie'
+
+require 'net/http'
+require 'uri/query_params'
+
+module Ronin
+  module Support
+    module Network
+      class HTTP
+        #
+        # Handles building HTTP request objects.
+        #
+        # @api private
+        #
+        # @since 1.0.0
+        #
+        module Request
+          #
+          # Builds the [Request-URI], aka path + query string, for a HTTP
+          # request.
+          #
+          # [Request-URI]: https://www.w3.org/Protocols/rfc2616/rfc2616-sec5.html#sec5.1.2
+          #
+          # @param [String] path
+          #   The path of the request.
+          #
+          # @param [String, nil] query
+          #   The optional query string for the request.
+          #
+          # @param [Hash{Symbol => Object},
+          #         Hash{String => Object}, nil] query_params
+          #   Additional query params for the request.
+          #
+          # @return [String]
+          #
+          def self.request_uri(path, query: nil, query_params: nil)
+            if query_params
+              query = URI::QueryParams.dump(query_params)
+            end
+
+            if query
+              # append the query-string onto the path
+              path += if path.include?('?') then "&#{query}"
+                      else                       "?#{query}"
+                      end
+            end
+
+            return path
+          end
+
+          # Request methods and `Net::HTTP` request classes.
+          METHODS = {
+            copy:      Net::HTTP::Copy,
+            delete:    Net::HTTP::Delete,
+            get:       Net::HTTP::Get,
+            head:      Net::HTTP::Head,
+            lock:      Net::HTTP::Lock,
+            mkcol:     Net::HTTP::Mkcol,
+            move:      Net::HTTP::Move,
+            options:   Net::HTTP::Options,
+            patch:     Net::HTTP::Patch,
+            post:      Net::HTTP::Post,
+            propfind:  Net::HTTP::Propfind,
+            proppatch: Net::HTTP::Proppatch,
+            put:       Net::HTTP::Put,
+            trace:     Net::HTTP::Trace,
+            unlock:    Net::HTTP::Unlock
+          }
+
+          #
+          # Creates a new `Net::HTTP` request.
+          #
+          # @param [:copy, :delete, :get, :head, :lock, :mkcol, :move,
+          #         :options, :patch, :post, :propfind, :proppatch, :put,
+          #         :trace, :unlock] method
+          #   The HTTP request method to use.
+          #
+          # @param [String] path
+          #
+          # @param [String, nil] query
+          #   The query-string to append to the request path.
+          #
+          # @param [Hash, nil] query_params
+          #   The query-params to append to the request path.
+          #
+          # @param [String, nil] user
+          #   The user to authenticate as.
+          #
+          # @param [String, nil] password
+          #   The password to authenticate with.
+          #
+          # @param [Hash{Symbol => String}, Hash{String => String}, nil] headers
+          #   Additional HTTP header names and values to add to the request.
+          #
+          # @param [String, :random, :chrome, :chrome_linux, :chrome_macos,
+          #         :chrome_windows, :chrome_iphone, :chrome_ipad,
+          #         :chrome_android, :firefox, :firefox_linux, :firefox_macos,
+          #         :firefox_windows, :firefox_iphone, :firefox_ipad,
+          #         :firefox_android, :safari, :safari_macos, :safari_iphone,
+          #         :safari_ipad, :edge, :linux, :macos, :windows, :iphone,
+          #         :ipad, :android, nil] user_agent
+          #     The `User-Agent` header value for the request.
+          #
+          # @param [String, Hash{String => String}, Cookie, nil] cookie
+          #   Additional `Cookie` header. If a `Hash` is given, it will be
+          #   converted to a `String` using {Cookie}. If the cookie value is
+          #   empty, the `Cookie` header will not be set.
+          #
+          # @param [String, nil] body
+          #   The body of the request.
+          #
+          # @param [Hash, String, nil] form_data
+          #   The form data that may be sent in the body of the request.
+          #
+          # @return [Net::HTTP::Copy,
+          #          Net::HTTP::Delete,
+          #          Net::HTTP::Get,
+          #          Net::HTTP::Head,
+          #          Net::HTTP::Lock,
+          #          Net::HTTP::Mkcol,
+          #          Net::HTTP::Move,
+          #          Net::HTTP::Options,
+          #          Net::HTTP::Patch,
+          #          Net::HTTP::Post,
+          #          Net::HTTP::Propfind,
+          #          Net::HTTP::Proppatch,
+          #          Net::HTTP::Put,
+          #          Net::HTTP::Trace,
+          #          Net::HTTP::Unlock]
+          #   The built HTTP request object.
+          #
+          def self.build(method,path, # query string keyword arguments
+                                      query:        nil,
+                                      query_params: nil,
+                                      # Basic-Auth keyword arguments
+                                      user:     nil,
+                                      password: nil,
+                                      # Header keyword arguments
+                                      headers:    nil,
+                                      user_agent: nil,
+                                      cookie:     nil,
+                                      # request body keyword arguments
+                                      body:      nil,
+                                      form_data: nil)
+            request_class = METHODS.fetch(method) do
+              raise(ArgumentError,"unknown HTTP request method: #{method.inspect}")
+            end
+
+            request = request_class.new(
+              request_uri(path, query: query, query_params: query_params),
+              headers
+            )
+
+            if user
+              user     = user.to_s
+              password = password.to_s if password
+
+              request.basic_auth(user,password)
+            end
+
+            if user_agent
+              request['User-Agent'] = case user_agent
+                                      when Symbol then UserAgents[user_agent]
+                                      else             user_agent
+                                      end
+            end
+
+            if cookie && !cookie.empty?
+              request['Cookie'] = case cookie
+                                  when Hash then HTTP::Cookie.new(cookie).to_s
+                                  else           cookie.to_s
+                                  end
+            end
+
+            if form_data
+              case form_data
+              when String
+                request.content_type = 'application/x-www-form-urlencoded'
+                request.body         = form_data
+              else
+                request.form_data    = form_data
+              end
+            elsif body
+              case body
+              when IO, StringIO then request.body_stream = body
+              else                   request.body        = body
+              end
+            end
+
+            return request
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ronin/support/network/http/set_cookie.rb

@@ -0,0 +1,210 @@
+# 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/http/cookie'
+
+require 'time'
+
+module Ronin
+  module Support
+    module Network
+      class HTTP
+        #
+        # Parses and generates `Set-Cookie` header values.
+        #
+        # @api public
+        #
+        # @since 1.0.0
+        #
+        class SetCookie < Cookie
+
+          # The `Max-Age` cookie attribute.
+          #
+          # @return [Integer, nil]
+          attr_reader :max_age
+
+          # The `Expires` cookie attribute.
+          #
+          # @return [Time, nil]
+          attr_reader :expires
+
+          # The `Domain` cookie attribute.
+          #
+          # @return [String, nil]
+          attr_reader :domain
+
+          # The `Path` cookie attribute.
+          #
+          # @return [String, nil]
+          attr_reader :path
+
+          # The `SameSite` cookie attribute.
+          #
+          # @return [:strict, :lax, :none]
+          attr_reader :same_site
+
+          # The `HttpOnly` flag.
+          #
+          # @return [true, nil]
+          attr_reader :http_only
+
+          # The `Secure` flag.
+          #
+          # @return [true, nil]
+          attr_reader :secure
+
+          #
+          # Initializes the `Set-Cookie` object.
+          #
+          # @param [Hash{String => String}] params
+          #
+          # @param [Time, nil] expires
+          #   The parsed `Expires` value.
+          #
+          # @param [Integer, nil] max_age
+          #   The parsed `Max-Age` value.
+          #
+          # @param [String, nil] path
+          #   The parsed `Path` value.
+          #
+          # @param [String, nil] domain
+          #   The parsed `Domain` value.
+          #
+          # @param [true, nil] http_only
+          #   Indicates the `HttpOnly` flag is enabled.
+          #
+          # @param [true, nil] secure
+          #   Indicates the `Secure` flag is enabled.
+          #
+          # @param [:strict, :lax, :none, nil] same_site
+          #   The parsed `SameSite` value.
+          #
+          def initialize(params, expires:   nil,
+                                 max_age:   nil,
+                                 path:      nil,
+                                 domain:    nil,
+                                 http_only: nil,
+                                 secure:    nil,
+                                 same_site: nil)
+            super(params)
+
+            @expires   = expires
+            @max_age   = max_age
+            @path      = path
+            @domain    = domain
+            @http_only = http_only
+            @secure    = secure
+            @same_site = same_site
+          end
+
+          # Mapping of `SameSite` values to Symbols.
+          SAME_SITE = {
+            'None'   => :none,
+            'Strict' => :strict,
+            'Lax'    => :lax
+          }
+
+          #
+          # Parses a `Set-Cookie` string.
+          #
+          # @param [String] string
+          #   The raw `Set-Cookie` string.
+          #
+          # @return [Cookie]
+          #   The parsed cookie.
+          #
+          # @raise [ArgumentError]
+          #   The string contained an unknown `SameSite` value or flag.
+          #
+          def self.parse(string)
+            kwargs = {}
+            params = {}
+
+            string.split(/;\s+/) do |field|
+              if field.include?('=')
+                key, value = field.split('=',2)
+
+                case key
+                when 'Max-Age' then kwargs[:max_age] = value.to_i
+                when 'Expires' then kwargs[:expires] = Time.parse(value)
+                when 'Path'    then kwargs[:path]    = value
+                when 'Domain'  then kwargs[:domain]  = value
+                when 'SameSite'
+                  kwargs[:same_site] = SAME_SITE.fetch(value) do
+                    raise(ArgumentError,"unrecognized SameSite value: #{value.inspect}")
+                  end
+                else
+                  params[unescape(key)] = unescape(value)
+                end
+              else
+                case field
+                when 'HttpOnly' then kwargs[:http_only] = true
+                when 'Secure'   then kwargs[:secure]    = true
+                else
+                  raise(ArgumentError,"unrecognized Cookie flag: #{field.inspect}")
+                end
+              end
+            end
+
+            return new(params,**kwargs)
+          end
+
+          #
+          # Determines if the `HttpOnly` flag is set.
+          #
+          # @return [Boolean]
+          #
+          def http_only?
+            @http_only == true
+          end
+
+          #
+          # Determines if the `Secure` flag is set.
+          #
+          # @return [Boolean]
+          #
+          def secure?
+            @secure == true
+          end
+
+          #
+          # Converts the cookie back into a `Set-Cookie` value.
+          #
+          # @return [String]
+          #   The formatted cookie.
+          #
+          def to_s
+            string = super()
+            string << "; Max-Age=#{@max_age}"          if @max_age
+            string << "; Expires=#{@expires.httpdate}" if @expires
+            string << "; Path=#{@path}"                if @path
+            string << "; Domain=#{@domain}"            if @domain
+            string << "; SameSite=#{@same_site.to_s.capitalize}" if @same_site
+
+            if    @secure    then string << '; Secure'
+            elsif @http_only then string << '; HttpOnly'
+            end
+
+            string
+          end
+
+        end
+      end
+    end
+  end
+end

data/lib/ronin/support/network/http/user_agents.rb

@@ -0,0 +1,115 @@
+# 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/>.
+#
+
+module Ronin
+  module Support
+    module Network
+      class HTTP
+        #
+        # Contains built-in `User-Agent` strings for {HTTP}.
+        #
+        # @api semipublic
+        #
+        # @since 1.0.0
+        #
+        module UserAgents
+          # Built-in `User-Agent` strings for impersonating various browsers.
+          ALIASES = {
+            chrome_linux: 'Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/102.0.5005.63 Safari/537.36',
+            chrome_macos: 'Mozilla/5.0 (Macintosh; Intel Mac OS X 12_4) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/102.0.5005.63 Safari/537.36',
+            chrome_windows: 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/102.0.5005.63 Safari/537.36',
+            chrome_iphone: 'Mozilla/5.0 (iPhone; CPU iPhone OS 15_5 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) CriOS/102.0.5005.87 Mobile/15E148 Safari/604.1',
+            chrome_ipad: 'Mozilla/5.0 (iPad; CPU OS 15_5 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) CriOS/102.0.5005.87 Mobile/15E148 Safari/604.1',
+            chrome_android: 'Mozilla/5.0 (Linux; Android 10) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/102.0.5005.99 Mobile Safari/537.36',
+
+            firefox_linux: 'Mozilla/5.0 (Linux x86_64; rv:101.0) Gecko/20100101 Firefox/101.0',
+            firefox_macos: 'Mozilla/5.0 (Macintosh; Intel Mac OS X 12.4; rv:101.0) Gecko/20100101 Firefox/101.0',
+            firefox_windows: 'Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:101.0) Gecko/20100101 Firefox/101.0',
+            firefox_iphone: 'Mozilla/5.0 (iPhone; CPU iPhone OS 12_4 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) FxiOS/101.0 Mobile/15E148 Safari/605.1.15',
+            firefox_ipad: 'Mozilla/5.0 (iPad; CPU OS 12_4 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) FxiOS/101.0 Mobile/15E148 Safari/605.1.15',
+
+            firefox_android: 'Mozilla/5.0 (Android 12; Mobile; rv:68.0) Gecko/68.0 Firefox/101.0',
+
+            safari_macos: 'Mozilla/5.0 (Macintosh; Intel Mac OS X 12_4) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/15.4 Safari/605.1.15',
+            safari_iphone: 'Mozilla/5.0 (iPhone; CPU iPhone OS 15_5 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/15.4 Mobile/15E148 Safari/604.1',
+            safari_ipad: 'Mozilla/5.0 (iPad; CPU OS 15_5 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/15.4 Mobile/15E148 Safari/604.1',
+
+            edge: 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/102.0.5005.63 Safari/537.36 Edg/102.0.1245.33'
+          }
+
+          #
+          # Returns a `User-Agent` string for the given ID.
+          #
+          # @param [:random, :chrome, :chrome_linux, :chrome_macos,
+          #         :chrome_windows, :chrome_iphone, :chrome_ipad,
+          #         :chrome_android, :firefox, :firefox_linux, :firefox_macos,
+          #         :firefox_windows, :firefox_iphone, :firefox_ipad,
+          #         :firefox_android, :safari, :safari_macos, :safari_iphone,
+          #         :safari_ipad, :edge, :linux, :macos, :windows, :iphone,
+          #         :ipad, :android] id
+          #   The new `User-Agent` string to use. The acceptable values are:
+          #   * `:random` - a random value from {ALIASES} will be returned.
+          #   * `:chrome` - a random Chrome `User-Agent` from {ALIASES} will be
+          #     returned.
+          #   * `:firefox` - a random Firefox `User-Agent` from {ALIASES} will
+          #     be returned.
+          #   * `:safari` - a random Safari `User-Agent` from {ALIASES} will be
+          #     returned.
+          #   * `:linux` - a random Linux `User-Agent` from {ALIASES} will be
+          #     returned.
+          #   * `:macos` - a random macOS `User-Agent` from {ALIASES} will be
+          #     returned.
+          #   * `:windows` - a random Windows `User-Agent` from {ALIASES} will
+          #     be returned.
+          #   * `:iphone` - a random iPhone `User-Agent` from {ALIASES} will
+          #     be returned.
+          #   * `:ipad` - a random iPad `User-Agent` from {ALIASES} will
+          #     be returned.
+          #   * `:android` - a random Android `User-Agent` from {ALIASES} will
+          #     be returned.
+          #   * Otherwise, the `User-Agent` String in {ALIASES} with the
+          #     matching ID will be returned.
+          #
+          # @return [String]
+          #   The `User-Agent` string for the given `id`.
+          #
+          # @raise [ArgumentError]
+          #   The given `User-Agent` ID was not a known ID or wasn't a Symbol.
+          #
+          def self.[](id)
+            case id
+            when :random
+              ALIASES.values.sample
+            when :chrome, :firefox, :safari # prefix
+              ALIASES.select { |k,v| k =~ /^#{id}_/ }.values.sample
+            when :linux, :macos, :windows,
+                 :iphone, :ipad, :android # suffix
+              ALIASES.select { |k,v| k =~ /_#{id}$/ }.values.sample
+            when Symbol
+              ALIASES.fetch(id) do
+                raise(ArgumentError,"unknown user agent alias: #{id.inspect}")
+              end
+            else
+              raise(ArgumentError,"User-Agent ID must be a Symbol")
+            end
+          end
+        end
+      end
+    end
+  end
+end