ronin-support 1.0.6 → 1.1.0.rc1

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

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 #
-# Copyright (c) 2006-2023 Hal Brodigan (postmodern.mod3 at gmail.com)
+# Copyright (c) 2006-2024 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
@@ -86,6 +86,46 @@ module Ronin
             unlock:    Net::HTTP::Unlock
           }
 
+          # Common MIME types.
+          #
+          # @since 1.1.0
+          MIME_TYPES = {
+            text: 'text/plain',
+            xml:  'text/xml',
+            html: 'text/html',
+            json: 'application/json'
+          }
+
+          #
+          # Resolves the MIME type.
+          #
+          # @param [String, :text, :xml, :html, :json, nil] mime_type
+          #   The MIME type String or Symbol.
+          #   If a Symbol is given it will be resolved to a common MIME type:
+          #   * `:text` - `text/plain`
+          #   * `:xml` - `text/xml`
+          #   * `:html` - `text/html`
+          #   * `:json` - `application/json`
+          #
+          # @return [String]
+          #   The resolved MIME type String.
+          #
+          # @raise [ArgumentError]
+          #   An unknown Symbol is given.
+          #
+          # @since 1.1.0
+          #
+          def self.mime_type_for(mime_type)
+            case mime_type
+            when Symbol
+              MIME_TYPES.fetch(mime_type) do
+                raise(ArgumentError,"unsupported MIME type: #{mime_type.inspect}")
+              end
+            else
+              mime_type
+            end
+          end
+
           #
           # Creates a new `Net::HTTP` request.
           #
@@ -111,6 +151,22 @@ module Ronin
           # @param [Hash{Symbol => String}, Hash{String => String}, nil] headers
           #   Additional HTTP header names and values to add to the request.
           #
+          # @param [String, :text, :xml, :html, :json, nil] content_type
+          #   The `Content-Type` header value for the request.
+          #   If a Symbol is given it will be resolved to a common MIME type:
+          #   * `:text` - `text/plain`
+          #   * `:xml` - `text/xml`
+          #   * `:html` - `text/html`
+          #   * `:json` - `application/json`
+          #
+          # @param [String, :text, :xml, :html, :json, nil] accept
+          #   The `Accept` header value for the request.
+          #   If a Symbol is given it will be resolved to a common MIME type:
+          #   * `:text` - `text/plain`
+          #   * `:xml` - `text/xml`
+          #   * `:html` - `text/html`
+          #   * `:json` - `application/json`
+          #
           # @param [String, :random, :chrome, :chrome_linux, :chrome_macos,
           #         :chrome_windows, :chrome_iphone, :chrome_ipad,
           #         :chrome_android, :firefox, :firefox_linux, :firefox_macos,
@@ -131,6 +187,11 @@ module Ronin
           # @param [Hash, String, nil] form_data
           #   The form data that may be sent in the body of the request.
           #
+          # @param [#to_json, nil] json
+          #   The JSON data that will be sent in the body of the request.
+          #   Will also default the `Content-Type` header to `application/json`,
+          #   unless already set.
+          #
           # @return [Net::HTTP::Copy,
           #          Net::HTTP::Delete,
           #          Net::HTTP::Get,
@@ -155,12 +216,15 @@ module Ronin
                                       user:     nil,
                                       password: nil,
                                       # Header keyword arguments
-                                      headers:    nil,
-                                      user_agent: nil,
-                                      cookie:     nil,
+                                      headers:      nil,
+                                      content_type: nil,
+                                      accept:       nil,
+                                      user_agent:   nil,
+                                      cookie:       nil,
                                       # request body keyword arguments
                                       body:      nil,
-                                      form_data: nil)
+                                      form_data: nil,
+                                      json:      nil)
             request_class = METHODS.fetch(method) do
               raise(ArgumentError,"unknown HTTP request method: #{method.inspect}")
             end
@@ -177,6 +241,14 @@ module Ronin
               request.basic_auth(user,password)
             end
 
+            if content_type
+              request['Content-Type'] = mime_type_for(content_type)
+            end
+
+            if accept
+              request['Accept'] = mime_type_for(accept)
+            end
+
             if user_agent
               request['User-Agent'] = case user_agent
                                       when Symbol then UserAgents[user_agent]
@@ -191,13 +263,18 @@ module Ronin
                                   end
             end
 
-            if form_data
+            if json
+              request['Content-Type'] ||= 'application/json'
+
+              request.body = json.to_json
+            elsif form_data
               case form_data
               when String
-                request.content_type = 'application/x-www-form-urlencoded'
-                request.body         = form_data
+                request['Content-Type'] ||= 'application/x-www-form-urlencoded'
+
+                request.body = form_data
               else
-                request.form_data    = form_data
+                request.form_data = form_data
               end
             elsif body
               case body

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

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 #
-# Copyright (c) 2006-2023 Hal Brodigan (postmodern.mod3 at gmail.com)
+# Copyright (c) 2006-2024 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

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

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 #
-# Copyright (c) 2006-2023 Hal Brodigan (postmodern.mod3 at gmail.com)
+# Copyright (c) 2006-2024 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

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

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 #
-# Copyright (c) 2006-2023 Hal Brodigan (postmodern.mod3 at gmail.com)
+# Copyright (c) 2006-2024 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
@@ -365,7 +365,21 @@ module Ronin
           @http.key              = key              if key
 
           @http.ssl_timeout = timeout if timeout
-          @http.ssl_version = SSL::VERSIONS.fetch(version,version) if version
+
+          if version
+            version = SSL::VERSIONS.fetch(version,version)
+
+            @http.min_version = @http.max_version = version
+          else min_version || max_version
+            if min_version
+              @http.min_version = SSL::VERSIONS.fetch(min_version,min_version)
+            end
+
+            if max_version
+              @http.max_version = SSL::VERSIONS.fetch(max_version,max_version)
+            end
+          end
+
           @http.min_version = min_version if min_version
           @http.max_version = max_version if max_version
 
@@ -641,6 +655,22 @@ module Ronin
         # @param [Hash{Symbol,String => String}, nil] headers
         #   Additional HTTP header names and values to add to the request.
         #
+        # @param [String, :text, :xml, :html, :json, nil] content_type
+        #   The `Content-Type` header value for the request.
+        #   If a Symbol is given it will be resolved to a common MIME type:
+        #   * `:text` - `text/plain`
+        #   * `:xml` - `text/xml`
+        #   * `:html` - `text/html`
+        #   * `:json` - `application/json`
+        #
+        # @param [String, :text, :xml, :html, :json, nil] accept
+        #   The `Accept` header value for the request.
+        #   If a Symbol is given it will be resolved to a common MIME type:
+        #   * `:text` - `text/plain`
+        #   * `:xml` - `text/xml`
+        #   * `:html` - `text/html`
+        #   * `:json` - `application/json`
+        #
         # @param [String, Hash{String => String}, nil] cookie
         #   Additional `Cookie` header. If a `Hash` is given, it will be
         #   converted to a `String` using {Cookie}.
@@ -651,6 +681,11 @@ module Ronin
         # @param [Hash, String, nil] form_data
         #   The form data that may be sent in the body of the request.
         #
+        # @param [#to_json, nil] json
+        #   The JSON data that will be sent in the body of the request.
+        #   Will also default the `Content-Type` header to `application/json`,
+        #   unless already set.
+        #
         # @param [Hash{Symbol => String}] additional_headers
         #   Additional headers to add to the request.
         #
@@ -701,18 +736,23 @@ module Ronin
                                  query:        nil,
                                  query_params: nil,
                                  # header keyword arguments
-                                 headers:    nil,
-                                 user_agent: @user_agent,
-                                 cookie:     @cookie,
+                                 headers:      nil,
+                                 content_type: nil,
+                                 accept:       nil,
+                                 user_agent:   @user_agent,
+                                 cookie:       @cookie,
                                  # Basic-Auth keyword arguments
                                  user:     @user,
                                  password: @password,
                                  # request body keyword arguments
                                  body:      nil,
                                  form_data: nil,
+                                 json:      nil,
                                  **additional_headers,
                                  &block)
           request = Request.build(method,path, headers:      @headers,
+                                               content_type: content_type,
+                                               accept:       accept,
                                                user_agent:   user_agent,
                                                cookie:       cookie,
                                                user:         user,
@@ -720,7 +760,8 @@ module Ronin
                                                query:        query,
                                                query_params: query_params,
                                                body:         body,
-                                               form_data:    form_data)
+                                               form_data:    form_data,
+                                               json:         json)
 
           if headers
             # populate any arbitrary headers
@@ -759,6 +800,22 @@ module Ronin
         #   @option kwargs [Hash{Symbol,String => String}, nil] :headers
         #     Additional HTTP header names and values to add to the request.
         #
+        #   @option kwargs [String, :text, :xml, :html, :json, nil] :content_type
+        #     The `Content-Type` header value for the request.
+        #     If a Symbol is given it will be resolved to a common MIME type:
+        #     * `:text` - `text/plain`
+        #     * `:xml` - `text/xml`
+        #     * `:html` - `text/html`
+        #     * `:json` - `application/json`
+        #
+        #   @option kwargs [String, :text, :xml, :html, :json, nil] :accept
+        #     The `Accept` header value for the request.
+        #     If a Symbol is given it will be resolved to a common MIME type:
+        #     * `:text` - `text/plain`
+        #     * `:xml` - `text/xml`
+        #     * `:html` - `text/html`
+        #     * `:json` - `application/json`
+        #
         #   @option kwargs [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
@@ -770,6 +827,11 @@ module Ronin
         #   @option kwargs [Hash, String, nil] :form_data
         #     The form data that may be sent in the body of the request.
         #
+        #   @option kwargs [#to_json, nil] :json
+        #     The JSON data that will be sent in the body of the request.
+        #     Will also default the `Content-Type` header to
+        #     `application/json`, unless already set.
+        #
 
         #
         # Sends an arbitrary HTTP request and returns the response status.
@@ -1023,6 +1085,29 @@ module Ronin
           end
         end
 
+        #
+        # Sends an HTTP request and returns the parsed `Set-Cookie` header(s).
+        #
+        # @param [String] path
+        #   The path to to make the request for.
+        #
+        # @!macro request_kwargs
+        #
+        # @return [Array<SetCookie>, nil]
+        #   The parsed `Cookie` headers.
+        #
+        # @since 1.1.0
+        #
+        def post_cookies(path, **kwargs)
+          response = request(:post,path,**kwargs)
+
+          if (set_cookies = response.get_fields('Set-Cookie'))
+            set_cookies.map do |cookie|
+              SetCookie.parse(cookie)
+            end
+          end
+        end
+
         #
         # Sends a `GET` HTTP request and returns the response body.
         #
@@ -2821,6 +2906,53 @@ module Ronin
 
           http.unlock(path,**kwargs,&block)
         end
+
+        #
+        # Sends an HTTP request and returns the parsed `Set-Cookie` header(s).
+        #
+        # @param [URI::HTTP, Addressable::URI, String] url
+        #   Optional URL to create the HTTP request for.
+        #
+        # @!macro request_kwargs
+        # @!macro initialize_kwargs
+        #
+        # @return [Array<SetCookie>, nil]
+        #   The parsed `Cookie` header(s).
+        #
+        # @see connect_uri
+        # @see #post_cookies
+        #
+        # @since 1.1.0
+        #
+        def self.post_cookies(url, proxy:      self.proxy,
+                                   ssl:        nil,
+                                   headers:    {},
+                                   user_agent: nil,
+                                   cookie:     nil,
+                                   user:       nil,
+                                   password:   nil,
+                                   **kwargs,
+                                   &block)
+          uri = case url
+                when Addressable::URI, URI::HTTP
+                  url
+                when String
+                  Addressable::URI.parse(url)
+                else
+                  raise(ArgumentError,"URL argument must be either a Addressable::URI, URI::HTTP, or a String: #{url.inspect}")
+                end
+
+          path = uri.request_uri
+          http = connect_uri(url, proxy:      proxy,
+                                  ssl:        ssl,
+                                  headers:    headers,
+                                  user_agent: user_agent,
+                                  cookie:     cookie,
+                                  user:       user,
+                                  password:   password)
+
+          http.post_cookies(path,**kwargs)
+        end
       end
     end
   end

data/lib/ronin/support/network/imap/mixin.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 #
-# Copyright (c) 2006-2023 Hal Brodigan (postmodern.mod3 at gmail.com)
+# Copyright (c) 2006-2024 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

data/lib/ronin/support/network/ip/mixin.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 #
-# Copyright (c) 2006-2023 Hal Brodigan (postmodern.mod3 at gmail.com)
+# Copyright (c) 2006-2024 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

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

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 #
-# Copyright (c) 2006-2023 Hal Brodigan (postmodern.mod3 at gmail.com)
+# Copyright (c) 2006-2024 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
@@ -66,6 +66,11 @@ module Ronin
       #
       class IP < IPAddr
 
+        # A regular expression for matching IP addresses.
+        #
+        # @since 1.1.0
+        REGEX = /#{RE_IPV4ADDRLIKE}|#{RE_IPV6ADDRLIKE_FULL}|#{RE_IPV6ADDRLIKE_COMPRESSED}/
+
         #
         # Initializes the IP address.
         #
@@ -549,6 +554,42 @@ module Ronin
           DNS.get_ptr_names(@address,**kwargs)
         end
 
+        #
+        # Converts the IP address to it's IPv4 version.
+        #
+        # @note [IP]
+        #   If the IP address is an IPv4-mapped IPv6 address then the IPv6
+        #   address will be extracted from the IPv6 address. If the IP address
+        #   is a regular IPv4 address, then the IP address will be returned.
+        #
+        # @raise [InvalidIP]
+        #   The IP address was a regular IPv6 address and cannot be converted to
+        #   a smaller IPv4 address.
+        #
+        # @example Converting an IPv4-mapped IPv6 address to an IPv4 address:
+        #   ip = Network::IP.new('::ffff:127.0.0.1')
+        #   ip.ipv4
+        #   # => #<Ronin::Support::Network::IP: 127.0.0.1>
+        #
+        # @example When the IP address is already an IPv4 address:
+        #   ip = Network::IP.new('127.0.0.1')
+        #   ip.ipv4
+        #   # => #<Ronin::Support::Network::IP: 127.0.0.1>
+        #
+        # @since 1.1.0
+        #
+        def ipv4
+          if ipv6?
+            if ipv4_mapped?
+              self.class.new(to_i & 0xffffffff,Socket::AF_INET)
+            else
+              raise(InvalidIP,"cannot convert a regular IPv6 address to an IPv4 address: #{inspect}")
+            end
+          else
+            self
+          end
+        end
+
         alias canonical to_string
         alias to_str to_s
         alias to_uint to_i

data/lib/ronin/support/network/ip_range/cidr.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 #
-# Copyright (c) 2006-2023 Hal Brodigan (postmodern.mod3 at gmail.com)
+# Copyright (c) 2006-2024 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
@@ -43,6 +43,49 @@ module Ronin
 
           include Enumerable
 
+          ipv4_octet = /(?:\d{1,2}|1\d{2}|2[1-4]\d|25[0-5])/
+          ipv4_addr  = /#{ipv4_octet}(?:\.#{ipv4_octet}){3}/
+
+          # Regular expression that matches IPv4 CIDR ranges.
+          #
+          # @api private
+          #
+          # @since 1.1.0
+          IPV4_REGEX = %r{\A#{ipv4_addr}(?:/(?:\d|[12]\d|3[0-2]))?\z}
+
+          # Regular expression that matches IPv6 CIDR ranges.
+          #
+          # @api private
+          #
+          # @since 1.1.0
+          IPV6_REGEX = %r{\A(?:
+            (?:[0-9a-fA-F]{1,4}:){6}#{ipv4_addr}|
+            (?:[0-9a-fA-F]{1,4}:){5}[0-9a-fA-F]{1,4}:#{ipv4_addr}|
+            (?:[0-9a-fA-F]{1,4}:){5}:[0-9a-fA-F]{1,4}:#{ipv4_addr}|
+            (?:[0-9a-fA-F]{1,4}:){1,1}(?::[0-9a-fA-F]{1,4}){1,4}:#{ipv4_addr}|
+            (?:[0-9a-fA-F]{1,4}:){1,2}(?::[0-9a-fA-F]{1,4}){1,3}:#{ipv4_addr}|
+            (?:[0-9a-fA-F]{1,4}:){1,3}(?::[0-9a-fA-F]{1,4}){1,2}:#{ipv4_addr}|
+            (?:[0-9a-fA-F]{1,4}:){1,4}(?::[0-9a-fA-F]{1,4}){1,1}:#{ipv4_addr}|
+            :(?::[0-9a-fA-F]{1,4}){1,5}:#{ipv4_addr}|
+            (?:(?:[0-9a-fA-F]{1,4}:){1,5}|:):#{ipv4_addr}|
+            (?:[0-9a-fA-F]{1,4}:){1,1}(?::[0-9a-fA-F]{1,4}){1,6}|
+            (?:[0-9a-fA-F]{1,4}:){1,2}(?::[0-9a-fA-F]{1,4}){1,5}|
+            (?:[0-9a-fA-F]{1,4}:){1,3}(?::[0-9a-fA-F]{1,4}){1,4}|
+            (?:[0-9a-fA-F]{1,4}:){1,4}(?::[0-9a-fA-F]{1,4}){1,3}|
+            (?:[0-9a-fA-F]{1,4}:){1,5}(?::[0-9a-fA-F]{1,4}){1,2}|
+            (?:[0-9a-fA-F]{1,4}:){1,6}(?::[0-9a-fA-F]{1,4}){1,1}|
+            [0-9a-fA-F]{1,4}(?::[0-9a-fA-F]{1,4}){7}|
+            :(?::[0-9a-fA-F]{1,4}){1,7}|
+            (?:(?:[0-9a-fA-F]{1,4}:){1,7}|:):
+          )(?:/(?:\d{1,2}|1[0-1]\d+|12[0-8]))?\z}x
+
+          # Regular expression to match IP-glob ranges.
+          #
+          # @api private
+          #
+          # @since 1.1.0
+          REGEX = /#{IPV4_REGEX}|#{IPV6_REGEX}/
+
           # The CIDR IP range string.
           #
           # @return [String]
@@ -58,12 +101,21 @@ module Ronin
           #   The address family for the CIDR range. This is mainly for
           #   backwards compatibility with `IPAddr#initialize`.
           #
+          # @raise [ArgumentError]
+          #   The CIDR range string was not a valid IPv4 or IPv6 CIDR range.
+          #
           def initialize(string,family=Socket::AF_UNSPEC)
+            unless (string =~ IPV4_REGEX || string =~ IPV6_REGEX)
+              raise(ArgumentError,"invalid CIDR range: #{string.inspect}")
+            end
+
             super(string,family)
 
             @string = string
           end
 
+          alias prefix_address to_string
+
           #
           # Alias for {#initialize new}.
           #
@@ -160,6 +212,65 @@ module Ronin
             new(string).each(&block)
           end
 
+          #
+          # Determines if the given IP belongs to the IP CIDR range.
+          #
+          # @param [IP, IPAddr, String] ip
+          #   The IP to test.
+          #
+          # @return [Boolean]
+          #   Specifies whether the IP is or is not within the IP CIDR range.
+          #
+          # @since 1.1.0
+          #
+          def include?(ip)
+            ip = IPAddr.new(ip) unless ip.kind_of?(IPAddr)
+
+            family_mask = MASKS[@family]
+            start_addr  = @addr
+            end_addr    = @addr | (~@mask_addr & family_mask)
+            ip_addr     = ip.to_i
+
+            return (ip_addr >= start_addr) && (ip_addr <= end_addr)
+          end
+
+          #
+          # Compares the CIDR range to another IP range.
+          #
+          # @param [Object] other
+          #   The other IP range.
+          #
+          # @return [Boolean]
+          #
+          # @since 1.1.0
+          #
+          def ==(other)
+            other.kind_of?(self.class) &&
+              family == other.family &&
+              to_i   == other.to_i
+          end
+
+          #
+          # Determines if the given IP range is a sub-set of the IP CIDR range.
+          #
+          # @param [CIDR, Glob, Enumerable<String>] other
+          #   The other IP range.
+          #
+          # @return [Boolean]
+          #
+          # @since 1.1.0
+          #
+          def ===(other)
+            case other
+            when CIDR
+              include?(other.first) && include?(other.last)
+            when Enumerable
+              other.all? { |ip| include?(ip) }
+            else
+              false
+            end
+          end
+
           #
           # Iterates over each IP address that is included in the addresses
           # netmask. Supports both IPv4 and IPv6 addresses.
@@ -212,6 +323,17 @@ module Ronin
             _to_string(@addr | ~@mask_addr)
           end
 
+          #
+          # Calculates the size of the CIDR range.
+          #
+          # @return [Integer]
+          #
+          # @since 1.1.0
+          #
+          def size
+            2**(SIZES.fetch(family) - prefix)
+          end
+
           #
           # Converts the CIDR range back into a String.
           #