ronin-support 1.0.1 → 1.0.2

data/lib/ronin/support/encoding/hex/core_ext/string.rb

@@ -79,7 +79,7 @@ class String
   #   The hex unescaped version of the String.
   #
   # @example
-  #   "hello\\nworld".hex_escape
+  #   "hello\\nworld".hex_unescape
   #   # => "hello\nworld"
   #
   # @see Ronin::Support::Encoding::Hex.unescape

data/lib/ronin/support/encoding/hex.rb

@@ -188,11 +188,11 @@ module Ronin
         #   the same String if it is not quoted.
         #
         # @example
-        #   Encoding::Hex.unescape("\"hello\\nworld\"")
+        #   Encoding::Hex.unescape("hello\\nworld")
         #   # => "hello\nworld"
         #
         def self.unescape(data)
-          buffer  = String.new
+          buffer  = String.new(encoding: Encoding::UTF_8)
           scanner = StringScanner.new(data)
 
           until scanner.eos?

data/lib/ronin/support/encoding/js.rb

@@ -182,7 +182,7 @@ module Ronin
         #   # => "hello world"
         #
         def self.unescape(data)
-          unescaped = String.new
+          unescaped = String.new(encoding: Encoding::UTF_8)
 
           data.scan(/[\\%]u[0-9a-fA-F]{1,4}|[\\%][0-9a-fA-F]{1,2}|\\[btnfr\'\"\\]|./) do |c|
             unescaped << BACKSLASHED_CHARS.fetch(c) do

data/lib/ronin/support/encoding/powershell.rb

@@ -191,7 +191,7 @@ module Ronin
         #   # => "hello\nworld"
         #
         def self.unescape(data)
-          unescaped = String.new
+          unescaped = String.new(encoding: Encoding::UTF_8)
           scanner   = StringScanner.new(data)
 
           until scanner.eos?

data/lib/ronin/support/encoding/quoted_printable.rb

@@ -22,7 +22,9 @@ module Ronin
   module Support
     class Encoding < ::Encoding
       #
-      # Contains methods for encoding/decoding Quoted Printable data.
+      # Contains methods for encoding/decoding [Quoted Printable] data.
+      #
+      # [Quoted-Printable]: https://en.wikipedia.org/wiki/Quoted-printable
       #
       # ## Core-Ext Methods
       #

data/lib/ronin/support/encoding/ruby.rb

@@ -174,7 +174,7 @@ module Ronin
         #   # => "hello"
         #
         def self.unescape(data)
-          unescaped = String.new
+          unescaped = String.new(encoding: Encoding::UTF_8)
           scanner   = StringScanner.new(data)
 
           until scanner.eos?

data/lib/ronin/support/encoding/uuencoding.rb

@@ -20,7 +20,9 @@ module Ronin
   module Support
     class Encoding < ::Encoding
       #
-      # Contains methods for encoding/decoding UUEncoded data.
+      # Contains methods for encoding/decoding [UUEncoded][uuencoding] data.
+      #
+      # [uuencoding]: https://en.wikipedia.org/wiki/Uuencoding
       #
       # ## Core-Ext Methods
       #

data/lib/ronin/support/encoding/xml.rb

@@ -312,7 +312,7 @@ module Ronin
         # @see http://rubydoc.info/stdlib/cgi/CGI.unescapeHash
         #
         def self.unescape(data)
-          unescaped = String.new
+          unescaped = String.new(encoding: Encoding::UTF_8)
           scanner   = StringScanner.new(data)
 
           until scanner.eos?

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

@@ -25,6 +25,8 @@ module Ronin
         #
         # Provides helper methods for performing DNS queries.
         #
+        # @api public
+        #
         module Mixin
           #
           # Sets the DNS nameservers to query.
@@ -79,8 +81,6 @@ module Ronin
           # @return [Resolv, Resolv::DNS]
           #   The DNS Resolver.
           #
-          # @api public
-          #
           def dns_resolver(nameservers: nil, nameserver: nil)
             if nameserver
               Network::DNS.resolver(nameserver: nameserver)
@@ -111,8 +111,6 @@ module Ronin
           # @return [String, nil]
           #   The address of the hostname.
           #
-          # @api public
-          #
           def dns_get_address(host,**kwargs)
             dns_resolver(**kwargs).get_address(host.to_s)
           end
@@ -137,8 +135,6 @@ module Ronin
           # @return [Array<String>]
           #   The addresses of the hostname.
           #
-          # @api public
-          #
           def dns_get_addresses(host,**kwargs)
             dns_resolver(**kwargs).get_addresses(host.to_s)
           end
@@ -161,8 +157,6 @@ module Ronin
           # @return [String, nil]
           #   The hostname of the address.
           #
-          # @api public
-          #
           def dns_get_name(ip,**kwargs)
             dns_resolver(**kwargs).get_name(ip.to_s)
           end
@@ -187,8 +181,6 @@ module Ronin
           # @return [Array<String>]
           #   The hostnames of the address.
           #
-          # @api public
-          #
           def dns_get_names(ip,**kwargs)
             dns_resolver(**kwargs).get_names(ip.to_s)
           end

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

@@ -33,6 +33,10 @@ module URI
     # @return [Integer]
     #   The HTTP Response Status.
     #
+    # @example
+    #   URI('http://github.com/').status
+    #   # => 301
+    #
     # @see Ronin::Support::Network::HTTP.response_status
     #
     # @since 0.3.0
@@ -53,6 +57,10 @@ module URI
     #
     # @see Ronin::Support::Network::HTTP.ok?
     #
+    # @example
+    #   URI('https://example.com/').ok?
+    #   # => true
+    #
     # @since 0.3.0
     #
     def ok?(**kwargs)

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

@@ -66,11 +66,6 @@ module Ronin
       #
       class IP < IPAddr
 
-        # The address of the IP.
-        #
-        # @return [String]
-        attr_reader :address
-
         #
         # Initializes the IP address.
         #
@@ -92,9 +87,15 @@ module Ronin
         #   the IP address.
         #
         def initialize(address,family=Socket::AF_UNSPEC)
-          # XXX: remove the %iface suffix for ruby < 3.1.0
-          if address.kind_of?(String) && address =~ /%.+$/
-            address = address.sub(/%.+$/,'')
+          case address
+          when String
+            # XXX: remove the %iface suffix for ruby < 3.1.0
+            if address =~ /%.+$/
+              address = address.sub(/%.+$/,'')
+            end
+
+            # pre-cache the given IP address String
+            @address = address
           end
 
           begin
@@ -102,13 +103,30 @@ module Ronin
           rescue IPAddr::InvalidAddressError
             raise(InvalidIP,"invalid IP address: #{address.inspect}")
           end
+        end
 
-          @address = case address
-                     when String then address.to_s
-                     else             to_s
-                     end
+        protected
+
+        #
+        # Sets the IP address using the numeric IP address value.
+        #
+        # @param [Integer] addr
+        #   The new numeric IP address value.
+        #
+        # @param [Integer] family
+        #   Optional IP address family.
+        #
+        # @api private
+        #
+        def set(addr,*family)
+          super(addr,*family)
+
+          # unset the cached IP address since the numeric address has changed
+          @address = nil
         end
 
+        public
+
         # The URI for https://ipinfo.io/ip
         IPINFO_URI = URI::HTTPS.build(host: 'ipinfo.io', path: '/ip')
 
@@ -286,6 +304,16 @@ module Ronin
           ipv4? && (@addr & 0xff) == 0x00
         end
 
+        #
+        # The IP address.
+        #
+        # @return [String]
+        #   The String version of the IP address.
+        #
+        def address
+          @address ||= to_s
+        end
+
         #
         # The Autonomous System Number (ASN) information for the IP address.
         #
@@ -519,8 +547,8 @@ module Ronin
         end
 
         alias canonical to_string
-        alias to_uint to_i
         alias to_str to_s
+        alias to_uint to_i
 
         #
         # Inspects the IP.

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

@@ -40,7 +40,7 @@ module Ronin
       #
       # Enumerating over a IP-glob range:
       #
-      #     IPRange.each('10.0.1-3.*/24') { |ip| puts ip }
+      #     IPRange.each('10.0.1-3.*') { |ip| puts ip }
       #     # 10.0.1.1
       #     # 10.0.1.2
       #     # ...
@@ -75,7 +75,7 @@ module Ronin
         #   ip_range = IPRange.new('10.0.0.1/24')
         #
         # @example Initializing an IP-glob range:
-        #   ip_range = IPRange.new('10.0.1-3.*/24')
+        #   ip_range = IPRange.new('10.0.1-3.*')
         #
         def initialize(string)
           @range = if self.class.glob?(string) then Glob.new(string)
@@ -125,7 +125,7 @@ module Ronin
         #   # 10.0.0.255
         #
         # @example Enumerating over a IP-glob range:
-        #   IPRange.each('10.0.1-3.*/24') { |ip| puts ip }
+        #   IPRange.each('10.0.1-3.*') { |ip| puts ip }
         #   # 10.0.1.1
         #   # 10.0.1.2
         #   # ...
@@ -228,7 +228,7 @@ module Ronin
         #   # 10.0.0.255
         #
         # @example Enumerating over a IP-glob range:
-        #   ip_range = IPRange.new('10.0.1-3.*/24')
+        #   ip_range = IPRange.new('10.0.1-3.*')
         #   ip_range.each { |ip| puts ip }
         #   # 10.0.1.1
         #   # 10.0.1.2

data/lib/ronin/support/path.rb

@@ -115,7 +115,7 @@ module Ronin
       #   # => #<Ronin::Support::Path:../../../../../../../etc/passwd>
       #
       def join(*names)
-        joined_path = if root? then String.new
+        joined_path = if root? then String.new(encoding: Encoding::UTF_8)
                       else          self.to_s
                       end
 

data/lib/ronin/support/text/homoglyph/core_ext/string.rb

@@ -39,6 +39,10 @@ class String
   # @raise [Ronin::Support::Text::Homoglyph::NotViable]
   #   No homoglyph replaceable characters were found in the String.
   #
+  # @example
+  #   "microsoft".homoglyph
+  #   # => "mｉcrosoft"
+  #
   # @see Ronin::Support::Text::Homoglyph.substitute
   #
   # @api public
@@ -68,6 +72,11 @@ class String
   # @return [Enumerator]
   #   If no block is given, an Enumerator object will be returned.
   #
+  # @example
+  #   "microsoft".each_homoglyph do |homoglyph|
+  #     # ...
+  #   end
+  #
   # @see Ronin::Support::Text::Homoglyph.each_substitution
   #
   # @api public
@@ -95,6 +104,30 @@ class String
   # @return [Array<String>]
   #   All variation of the given String.
   #
+  # @example
+  #   "microsoft".homoglyphs
+  #   # =>
+  #   # ["ⅿicrosoft",
+  #   #  "ｍicrosoft",
+  #   #  "mіcrosoft",
+  #   #  "mⅰcrosoft",
+  #   #  "mｉcrosoft",
+  #   #  "miϲrosoft",
+  #   #  "miсrosoft",
+  #   #  "miⅽrosoft",
+  #   #  "miｃrosoft",
+  #   #  "micｒosoft",
+  #   #  "micrοsoft",
+  #   #  "microsοft",
+  #   #  "micrоsoft",
+  #   #  "microsоft",
+  #   #  "micrｏsoft",
+  #   #  "microsｏft",
+  #   #  "microѕoft",
+  #   #  "microｓoft",
+  #   #  "microsoｆt",
+  #   #  "microsofｔ"]
+  #
   # @see Ronin::Support::Text::Homoglyph.each_substitution
   #
   # @api public

data/lib/ronin/support/text/patterns/network.rb

@@ -45,26 +45,26 @@ module Ronin
         # A regular expression for matching IPv6 Addresses.
         #
         # @since 1.0.0
-        IPV6_ADDR = Regexp.union(
-          /(?:[0-9a-f]{1,4}:){6}#{IPV4_ADDR}/,
-          /(?:[0-9a-f]{1,4}:){5}[0-9a-f]{1,4}:#{IPV4_ADDR}/,
-          /(?:[0-9a-f]{1,4}:){5}:[0-9a-f]{1,4}:#{IPV4_ADDR}/,
-          /(?:[0-9a-f]{1,4}:){1,1}(?::[0-9a-f]{1,4}){1,4}:#{IPV4_ADDR}/,
-          /(?:[0-9a-f]{1,4}:){1,2}(?::[0-9a-f]{1,4}){1,3}:#{IPV4_ADDR}/,
-          /(?:[0-9a-f]{1,4}:){1,3}(?::[0-9a-f]{1,4}){1,2}:#{IPV4_ADDR}/,
-          /(?:[0-9a-f]{1,4}:){1,4}(?::[0-9a-f]{1,4}){1,1}:#{IPV4_ADDR}/,
-          /:(?::[0-9a-f]{1,4}){1,5}:#{IPV4_ADDR}/,
-          /(?:(?:[0-9a-f]{1,4}:){1,5}|:):#{IPV4_ADDR}/,
-          %r{(?:[0-9a-f]{1,4}:){1,1}(?::[0-9a-f]{1,4}){1,6}(?:/\d{1,3})?},
-          %r{(?:[0-9a-f]{1,4}:){1,2}(?::[0-9a-f]{1,4}){1,5}(?:/\d{1,3})?},
-          %r{(?:[0-9a-f]{1,4}:){1,3}(?::[0-9a-f]{1,4}){1,4}(?:/\d{1,3})?},
-          %r{(?:[0-9a-f]{1,4}:){1,4}(?::[0-9a-f]{1,4}){1,3}(?:/\d{1,3})?},
-          %r{(?:[0-9a-f]{1,4}:){1,5}(?::[0-9a-f]{1,4}){1,2}(?:/\d{1,3})?},
-          %r{(?:[0-9a-f]{1,4}:){1,6}(?::[0-9a-f]{1,4}){1,1}(?:/\d{1,3})?},
-          %r{[0-9a-f]{1,4}(?::[0-9a-f]{1,4}){7}(?:/\d{1,3})?},
-          %r{:(?::[0-9a-f]{1,4}){1,7}(?:/\d{1,3})?},
-          %r{(?:(?:[0-9a-f]{1,4}:){1,7}|:):(?:/\d{1,3})?}
-        )
+        IPV6_ADDR = %r{
+          (?:[0-9a-f]{1,4}:){6}#{IPV4_ADDR}|
+          (?:[0-9a-f]{1,4}:){5}[0-9a-f]{1,4}:#{IPV4_ADDR}|
+          (?:[0-9a-f]{1,4}:){5}:[0-9a-f]{1,4}:#{IPV4_ADDR}|
+          (?:[0-9a-f]{1,4}:){1,1}(?::[0-9a-f]{1,4}){1,4}:#{IPV4_ADDR}|
+          (?:[0-9a-f]{1,4}:){1,2}(?::[0-9a-f]{1,4}){1,3}:#{IPV4_ADDR}|
+          (?:[0-9a-f]{1,4}:){1,3}(?::[0-9a-f]{1,4}){1,2}:#{IPV4_ADDR}|
+          (?:[0-9a-f]{1,4}:){1,4}(?::[0-9a-f]{1,4}){1,1}:#{IPV4_ADDR}|
+          :(?::[0-9a-f]{1,4}){1,5}:#{IPV4_ADDR}|
+          (?:(?:[0-9a-f]{1,4}:){1,5}|:):#{IPV4_ADDR}|
+          (?:[0-9a-f]{1,4}:){1,1}(?::[0-9a-f]{1,4}){1,6}(?:/\d{1,3})?|
+          (?:[0-9a-f]{1,4}:){1,2}(?::[0-9a-f]{1,4}){1,5}(?:/\d{1,3})?|
+          (?:[0-9a-f]{1,4}:){1,3}(?::[0-9a-f]{1,4}){1,4}(?:/\d{1,3})?|
+          (?:[0-9a-f]{1,4}:){1,4}(?::[0-9a-f]{1,4}){1,3}(?:/\d{1,3})?|
+          (?:[0-9a-f]{1,4}:){1,5}(?::[0-9a-f]{1,4}){1,2}(?:/\d{1,3})?|
+          (?:[0-9a-f]{1,4}:){1,6}(?::[0-9a-f]{1,4}){1,1}(?:/\d{1,3})?|
+          [0-9a-f]{1,4}(?::[0-9a-f]{1,4}){7}(?:/\d{1,3})?|
+          :(?::[0-9a-f]{1,4}){1,7}(?:/\d{1,3})?|
+          (?:(?:[0-9a-f]{1,4}:){1,7}|:):(?:/\d{1,3})?
+        }x
 
         # A regular expression for matching IP Addresses.
         #

data/lib/ronin/support/text/random/mixin.rb

@@ -31,7 +31,7 @@ module Ronin
           #
           # Generates a random String of numeric characters.
           #
-          # @param [Integer] n
+          # @param [Integer, Range<Integer>] n
           #   The desired length of the String.
           #
           # @return [String]
@@ -56,7 +56,7 @@ module Ronin
           #
           # A random octal-digit string.
           #
-          # @param [Integer] n
+          # @param [Integer, Range<Integer>] n
           #   The desired length of the String.
           #
           # @return [String]
@@ -79,7 +79,7 @@ module Ronin
           #
           # The upper-case hexadecimal character set.
           #
-          # @param [Integer] n
+          # @param [Integer, Range<Integer>] n
           #   The desired length of the String.
           #
           # @return [String]
@@ -104,7 +104,7 @@ module Ronin
           #
           # The lower-case hexadecimal character set.
           #
-          # @param [Integer] n
+          # @param [Integer, Range<Integer>] n
           #   The desired length of the String.
           #
           # @return [String]
@@ -129,7 +129,7 @@ module Ronin
           #
           # A random hexadecimal string.
           #
-          # @param [Integer] n
+          # @param [Integer, Range<Integer>] n
           #   The desired length of the String.
           #
           # @return [String]
@@ -152,7 +152,7 @@ module Ronin
           #
           # The upper-case alphabetic character set.
           #
-          # @param [Integer] n
+          # @param [Integer, Range<Integer>] n
           #   The desired length of the String.
           #
           # @return [String]
@@ -177,7 +177,7 @@ module Ronin
           #
           # The lower-case alphabetic character set.
           #
-          # @param [Integer] n
+          # @param [Integer, Range<Integer>] n
           #   The desired length of the String.
           #
           # @return [String]
@@ -202,7 +202,7 @@ module Ronin
           #
           # A random alphabetic string.
           #
-          # @param [Integer] n
+          # @param [Integer, Range<Integer>] n
           #   The desired length of the String.
           #
           # @return [String]
@@ -225,7 +225,7 @@ module Ronin
           #
           # A random alpha-numeric string.
           #
-          # @param [Integer] n
+          # @param [Integer, Range<Integer>] n
           #   The desired length of the String.
           #
           # @return [String]
@@ -248,7 +248,7 @@ module Ronin
           #
           # A random punctuation string.
           #
-          # @param [Integer] n
+          # @param [Integer, Range<Integer>] n
           #   The desired length of the String.
           #
           # @return [String]
@@ -271,7 +271,7 @@ module Ronin
           #
           # A random symbolic string.
           #
-          # @param [Integer] n
+          # @param [Integer, Range<Integer>] n
           #   The desired length of the String.
           #
           # @return [String]
@@ -294,7 +294,7 @@ module Ronin
           #
           # A random whitespace string.
           #
-          # @param [Integer] n
+          # @param [Integer, Range<Integer>] n
           #   The desired length of the String.
           #
           # @return [String]
@@ -319,7 +319,7 @@ module Ronin
           #
           # The set of printable characters, not including spaces.
           #
-          # @param [Integer] n
+          # @param [Integer, Range<Integer>] n
           #   The desired length of the String.
           #
           # @return [String]
@@ -342,7 +342,7 @@ module Ronin
           #
           # The set of printable characters, including spaces.
           #
-          # @param [Integer] n
+          # @param [Integer, Range<Integer>] n
           #   The desired length of the String.
           #
           # @return [String]
@@ -365,7 +365,7 @@ module Ronin
           #
           # A random control-character string.
           #
-          # @param [Integer] n
+          # @param [Integer, Range<Integer>] n
           #   The desired length of the String.
           #
           # @return [String]
@@ -388,7 +388,7 @@ module Ronin
           #
           # The signed ASCII character set.
           #
-          # @param [Integer] n
+          # @param [Integer, Range<Integer>] n
           #   The desired length of the String.
           #
           # @return [String]
@@ -411,7 +411,7 @@ module Ronin
           #
           # A random ASCII string.
           #
-          # @param [Integer] n
+          # @param [Integer, Range<Integer>] n
           #   The desired length of the String.
           #
           # @return [String]