ronin-support 1.0.1 → 1.0.3

data/lib/ronin/support/crypto/core_ext/string.rb

@@ -54,10 +54,10 @@ class String
 
   #
   # @return [String]
-  #   The SHA2 checksum of the String.
+  #   The SHA256 checksum of the String.
   #
   # @example
-  #   "hello".sha2
+  #   "hello".sha256
   #   # => "2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824"
   #
   # @api public
@@ -152,6 +152,10 @@ class String
   # @return [String]
   #   The encrypted String.
   #
+  # @example
+  #   "top secret".encrypt('aes-256-cbc', password: 's3cr3t')
+  #   # => "\xF0[\x17\xDA\xA2\x82\x93\xF4\xB6s\xB5\xD8\x1F\xF2\xC6\\"
+  #
   # @see http://rubydoc.info/stdlib/openssl/OpenSSL/Cipher
   #
   # @since 0.6.0
@@ -191,6 +195,10 @@ class String
   # @return [String]
   #   The decrypted String.
   #
+  # @example
+  #  "\xF0[\x17\xDA\xA2\x82\x93\xF4\xB6s\xB5\xD8\x1F\xF2\xC6\\".decrypt('aes-256-cbc', password: 's3cr3t')
+  #  # => "top secret"
+  #
   # @see http://rubydoc.info/stdlib/openssl/OpenSSL/Cipher
   #
   # @since 0.6.0
@@ -236,6 +244,10 @@ class String
   # @raise [ArgumentError]
   #   Either the the `key:` or `password:` keyword argument must be given.
   #
+  # @example
+  #   "top secret".aes_encrypt(key_size: 256, password: 's3cr3t')
+  #   # => "\xF0[\x17\xDA\xA2\x82\x93\xF4\xB6s\xB5\xD8\x1F\xF2\xC6\\"
+  #
   # @since 1.0.0
   #
   def aes_encrypt(**kwargs)
@@ -275,6 +287,10 @@ class String
   # @raise [ArgumentError]
   #   Either the the `key:` or `password:` keyword argument must be given.
   #
+  # @example
+  #   "\xF0[\x17\xDA\xA2\x82\x93\xF4\xB6s\xB5\xD8\x1F\xF2\xC6\\".aes_decrypt(key_size: 256, password: 's3cr3t')
+  #   # => "top secret"
+  #
   # @since 1.0.0
   #
   def aes_decrypt(**kwargs)
@@ -311,6 +327,10 @@ class String
   # @raise [ArgumentError]
   #   Either the the `key:` or `password:` keyword argument must be given.
   #
+  # @example
+  #   "top secret".aes128_encrypt(password: 's3cr3t')
+  #   # => "\x88\xA53\xE9|\xE2\x8E\xA0\xABv\xCF\x94\x17\xBB*\xC5"
+  #
   # @since 1.0.0
   #
   def aes128_encrypt(**kwargs)
@@ -347,6 +367,10 @@ class String
   # @raise [ArgumentError]
   #   Either the the `key:` or `password:` keyword argument must be given.
   #
+  # @example
+  #   "\x88\xA53\xE9|\xE2\x8E\xA0\xABv\xCF\x94\x17\xBB*\xC5".aes128_decrypt(password: 's3cr3t')
+  #   # => "top secret"
+  #
   # @since 1.0.0
   #
   def aes128_decrypt(**kwargs)
@@ -383,6 +407,10 @@ class String
   # @raise [ArgumentError]
   #   Either the the `key:` or `password:` keyword argument must be given.
   #
+  # @example
+  #   "top secret".aes256_encrypt(password: 's3cr3t')
+  #   # => "\xF0[\x17\xDA\xA2\x82\x93\xF4\xB6s\xB5\xD8\x1F\xF2\xC6\\"
+  #
   # @since 1.0.0
   #
   def aes256_encrypt(**kwargs)
@@ -419,6 +447,10 @@ class String
   # @raise [ArgumentError]
   #   Either the the `key:` or `password:` keyword argument must be given.
   #
+  # @example
+  #   "\xF0[\x17\xDA\xA2\x82\x93\xF4\xB6s\xB5\xD8\x1F\xF2\xC6\\".aes256_decrypt(password: 's3cr3t')
+  #   # => "top secret"
+  #
   # @since 1.0.0
   #
   def aes256_decrypt(**kwargs)

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

@@ -71,7 +71,7 @@ module Ronin
         #   # => "hello"
         #
         def self.decode(data)
-          decoded = String.new
+          decoded = String.new(encoding: Encoding::ASCII_8BIT)
 
           data.scan(/../).each do |hex_char|
             decoded << hex_char.to_i(16).chr

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

@@ -63,7 +63,7 @@ module Ronin
         #   The Base32 decoded String.
         #
         def self.decode(data)
-          decoded = String.new
+          decoded = String.new(encoding: Encoding::UTF_8)
 
           each_chunk(data,8) do |chunk|
             chunk.decode(decoded)

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

@@ -47,7 +47,7 @@ class String
   #   The unescaped C String.
   #
   # @example
-  #   "\x68\x65\x6c\x6c\x6f\x20\x77\x6f\x72\x6c\x64".c_unescape
+  #   "\\x68\\x65\\x6c\\x6c\\x6f\\x20\\x77\\x6f\\x72\\x6c\\x64".c_unescape
   #   # => "hello world"
   #
   # @see Ronin::Support::Encoding::C.unescape

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

@@ -213,11 +213,11 @@ module Ronin
         #   The unescaped C String.
         #
         # @example
-        #   Encoding::C.unescape("\x68\x65\x6c\x6c\x6f\x20\x77\x6f\x72\x6c\x64")
+        #   Encoding::C.unescape("\\x68\\x65\\x6c\\x6c\\x6f\\x20\\x77\\x6f\\x72\\x6c\\x64")
         #   # => "hello world"
         #
         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/core_ext/string.rb

@@ -48,7 +48,7 @@ class String
   def encode_bytes(include: nil, exclude: nil)
     included  = (Chars::CharSet.new(*include) if include)
     excluded  = (Chars::CharSet.new(*exclude) if exclude)
-    formatted = String.new
+    formatted = String.new(encoding: ::Encoding::UTF_8)
 
     each_byte do |b|
       formatted << if (included.nil? || included.include_byte?(b)) &&
@@ -90,7 +90,7 @@ class String
   def encode_chars(include: nil, exclude: nil)
     included  = (Chars::CharSet.new(*include) if include)
     excluded  = (Chars::CharSet.new(*exclude) if exclude)
-    formatted = String.new
+    formatted = String.new(encoding: ::Encoding::UTF_8)
 
     each_char do |c|
       formatted << if (included.nil? || included.include_char?(c)) &&

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,33 @@ 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.
+        #
+        # @return [self]
+        #
+        # @api private
+        #
+        def set(addr,*family)
+          super(addr,*family)
+
+          # unset the cached IP address since the numeric address has changed
+          @address = nil
+          return self
         end
 
+        public
+
         # The URI for https://ipinfo.io/ip
         IPINFO_URI = URI::HTTPS.build(host: 'ipinfo.io', path: '/ip')
 
@@ -286,6 +307,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 +550,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.
@@ -529,7 +560,7 @@ module Ronin
         #   The inspected IP object.
         #
         def inspect
-          "#<#{self.class}: #{@address}>"
+          "#<#{self.class}: #{address}>"
         end
 
       end

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/network/ssl/mixin.rb

@@ -267,6 +267,8 @@ module Ronin
             socket     = tcp_connect(host,port,bind_host: bind_host,
                                                bind_port: bind_port)
             ssl_socket = ssl_socket(socket,**kwargs)
+
+            ssl_socket.hostname = host
             ssl_socket.connect
 
             if block_given?

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.
         #