ronin-support 1.0.0 → 1.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b487230c13b8458ad2f063e60e872f35f6262b14921d7f76050647e94aced0a3
-  data.tar.gz: 6bfe1e1bc33c1694070529fe6d622cc745f370cc8afc688fb62bb262cf71e550
+  metadata.gz: 9e7362a5af595979050611362ff0d48ace6148032006e9f05e9d90976b44487c
+  data.tar.gz: a6c6277a8af8169bf8fb374782b65169ae460c8cd6f4cac28a0c82d7ce7648b5
 SHA512:
-  metadata.gz: a928c76fae066768a23621ac2cf1c1c746e034c2d16d141a2f4275bed0dc24ec24556fc8226d3e8fc6cdcf7990528c35850477bf266fa9cfe85d38b3f0898ec4
-  data.tar.gz: 424f6d0b54160808cd43a4dee8f553830182fddb345b80708cc654e2a5df19d0225c1b0076df17fbb64425824a695c72e32f41601625450977b0eea62738df21
+  metadata.gz: f927d978f7af471f00bac7b97cc2bc9244df4b04683af3f6ce89ae6988d8f09cf7b28c16422673414a55b2711c9db05695afa0ffae35b1889b0c35117b7597fa
+  data.tar.gz: 519478e67e3fd01efa02d800d4badb66ce21a867165f300d4310e5a2a4411614ecacd7292c8095b8cef3ae444306b4402cf96e54fb5054f9d4eeb3d19350a335

data/.github/workflows/ruby.yml

@@ -26,3 +26,17 @@ jobs:
         run: bundle install --jobs 4 --retry 3
       - name: Run tests
         run: bundle exec rake test
+
+  # rubocop linting
+  rubocop:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+      - name: Set up Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: 3.0
+      - name: Install dependencies
+        run: bundle install --jobs 4 --retry 3
+      - name: Run rubocop
+        run: bundle exec rubocop --parallel

data/.rubocop.yml

@@ -0,0 +1,109 @@
+AllCops:
+  NewCops: enable
+  SuggestExtensions: false
+  TargetRubyVersion: 3.1
+
+inherit_gem:
+  rubocop-ronin: rubocop.yml
+
+Style/CommentedKeyword: { Enabled: false }
+Style/ArgumentsForwarding: { Enabled: false }
+Style/WhileUntilModifier: { Enabled: false }
+
+#
+# ronin-support specific exceptions
+#
+
+# it makes sense to use octal numbers when testing the file's mode
+Style/NumericLiteralPrefix:
+  Exclude:
+    - 'lib/ronin/support/archive/tar/writer.rb'
+    - 'lib/ronin/support/network/ssl/local_key.rb'
+    - 'lib/ronin/support/network/ssl/local_cert.rb'
+    - 'spec/archive/tar/writer_spec.rb'
+    - 'spec/network/ssl/local_cert_spec.rb'
+    - 'spec/network/ssl/local_key_spec.rb'
+
+# in certain specs we need to use an empty block
+Lint/EmptyBlock:
+  Exclude:
+    - 'spec/archive/zip/reader_spec.rb'
+    - 'spec/network/proxy_spec.rb'
+
+Lint/RaiseException:
+  Exclude:
+    - 'spec/core_ext/kernel_spec.rb'
+
+# the arrays of Floats need to be organized into rows of columns
+Layout/ArrayAlignment:
+  Exclude:
+    - 'spec/binary/unhexdump/parser_spec.rb'
+
+# the arrays of Floats need to be organized into rows of columns
+Layout/ExtraSpacing:
+  Exclude:
+    - 'spec/binary/unhexdump/parser_spec.rb'
+
+# make an exception for required block keyword arguments.
+Layout/SpaceAroundBlockParameters:
+  Exclude:
+    - 'spec/binary/unhexdump/parser_spec.rb'
+
+# robucop mistakes :x86_64 for a "symbol number"
+Naming/VariableNumber:
+  AllowedIdentifiers:
+    - x86_64
+    # OpenSSL TLS version symbols
+    - TLSv1
+    - TLSv1_1
+    - TLSv1_2
+
+# rubocop does not support constants that contain multiple numbers
+Naming/ClassAndModuleCamelCase:
+  AllowedNames:
+    - X86_64
+
+# we need to test Ronin::Support::Binary::CString#+ does not modify itself
+Lint/Void:
+  Exclude:
+    - 'spec/binary/cstring_spec.rb'
+
+Style/Documentation:
+  Exclude:
+    # ignore top-level documentation for core-ext classes
+    - 'lib/ronin/support/**/core_ext/**/*.rb'
+    # BUG: Ronin::Support::Crypto is already documented in lib/ronin/support/crypto.rb
+    - 'lib/ronin/support/crypto/cert.rb'
+    # BUG: Ronin::Support::Binary is already documented in lib/ronin/support/binary.rb
+    - 'lib/ronin/support/binary/struct.rb'
+
+Naming/MethodParameterName:
+  AllowedNames:
+    - n
+    - id
+    - ip
+    - io
+    - iv
+    - os
+    - to
+
+# prefer to keep `self.user_agent` a method
+Style/TrivialAccessors:
+  Exclude:
+    - 'lib/ronin/support/network/http.rb'
+
+# we need to redefine the public-key component methods as public
+Lint/UselessMethodDefinition:
+  Exclude:
+    - 'lib/ronin/support/crypto/key/dh.rb'
+    - 'lib/ronin/support/crypto/key/dsa.rb'
+    - 'lib/ronin/support/crypto/key/rsa.rb'
+
+Naming/BinaryOperatorParameterName:
+  Exclude:
+    - 'lib/ronin/support/binary/memory.rb'
+
+# Kernel#try explicitly rescues all exceptions
+Lint/RescueException:
+  Exclude:
+    - 'lib/ronin/support/core_ext/kernel.rb'

data/ChangeLog.md

@@ -1,4 +1,36 @@
-### 1.0.0 / 2023-XX-XX
+### 1.0.2 / 2023-06-09
+
+* Fixed a bug in {Ronin::Support::Encoding::Base32.decode},
+  {Ronin::Support::Encoding::Hex.unescape},
+  {Ronin::Support::Encoding::C.unescape},
+  {Ronin::Support::Encoding::JS.unescape},
+  {Ronin::Support::Encoding::PowerShell.unescape},
+  {Ronin::Support::Encoding::Ruby.unescape},
+  {Ronin::Support::Encoding::XML.unescape},
+  {Ronin::Support::Path#join}, {String#encode_bytes}, and {String#encode_chars}
+  where ASCII-bit Strings were always being returned instead of UTF-8 Strings.
+* Fixed a bug where {Ronin::Support::Network::IP#address} was being improperly
+  cached.
+* Added missing `require` for {File.tar}, {File.untar}, {File.zip}, and
+  {File.unzip} core-ext methods.
+* Added missing `require` for {Integer#pack} and {Float#pack} core-ext methods.
+* No longer include {Ronin::Support::Mixin} into {Kernel} which caused Mixin
+  methods to be included into *every* Class and object.
+* Added more example code to documentation.
+* Documentation fixes.
+
+### 1.0.1 / 2023-03-01
+
+* {Ronin::Support::Network::HTTP.connect_uri} can now infer when to enable
+  SSL/TLS from the given URI.
+* {Ronin::Support::Network::HTTP.connect_uri} can now use the `user` and
+  `password` information from the given URI.
+* All {Ronin::Support::Network::HTTP} class methods which accept URI objects
+  can now accept URLs with International Domain Names (IDN).
+* Changed {Kernel#try} to not silently ignore `SyntaxError` exceptions.
+* Documentation improvements.
+
+### 1.0.0 / 2023-02-01
 
 * Added {File.aes_encrypt}.
 * Added {File.aes_decrypt}.

data/Gemfile

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 source 'https://rubygems.org'
 
 gemspec
@@ -6,10 +8,10 @@ gem 'jruby-openssl',	'~> 0.7', platforms: :jruby
 
 gem 'net-telnet', '~> 0.1', group: :net
 if RUBY_VERSION >= '3.1.0'
-  gem 'net-ftp',    '~> 0.1', group: :net, platform: :mri
-  gem 'net-smtp',   '~> 0.1', group: :net, platform: :mri
-  gem 'net-pop',    '~> 0.1', group: :net, platform: :mri
-  gem 'net-imap',   '~> 0.1', group: :net, platform: :mri
+  gem 'net-ftp',    '~> 0.1', group: :net
+  gem 'net-smtp',   '~> 0.1', group: :net
+  gem 'net-pop',    '~> 0.1', group: :net
+  gem 'net-imap',   '~> 0.1', group: :net
 end
 
 group :development do
@@ -27,4 +29,6 @@ group :development do
   gem 'dead_end',           require: false
   gem 'sord',               require: false, platform: :mri
   gem 'stackprof',          require: false, platform: :mri
+  gem 'rubocop',            require: false, platform: :mri
+  gem 'rubocop-ronin',      require: false, platform: :mri
 end

data/README.md

@@ -95,7 +95,7 @@ research and development.
     * [Regexs for matching/extracting common types of data][docs-text-patterns].
 * Adds additional methods to many of [Ruby's core classes][docs-core-exts].
 * Small memory footprint (~46Kb).
-* Has 95% documentation coverage.
+* Has 96% documentation coverage.
 * Has 93% test coverage.
 
 ## Synopsis

data/Rakefile

@@ -1,4 +1,4 @@
-require 'rubygems'
+# frozen_string_literal: true
 
 begin
   require 'bundler'
@@ -53,7 +53,7 @@ namespace :public_suffix do
     list = Ronin::Support::Network::PublicSuffix::List.load_file(
       'public_suffix_list.dat'
     )
-    
+
     regex = list.to_regexp
 
     template = 'data/text/patterns/network/public_suffix.rb.erb'

data/examples/ssl_proxy.rb

@@ -1,10 +1,11 @@
 #!/usr/bin/env ruby
+# frozen_string_literal: true
 
 require 'bundler/setup'
 require 'ronin/support/network/ssl/proxy'
 
 Ronin::Support::Network::SSL::Proxy.start(port: 1337, server: ['example.com', 443]) do |proxy|
-  address = lambda { |socket|
+  address = ->(socket) {
     addrinfo = socket.peeraddr
 
     "#{addrinfo[3]}:#{addrinfo[1]}"

data/examples/tcp_proxy.rb

@@ -1,4 +1,5 @@
 #!/usr/bin/env ruby
+# frozen_string_literal: true
 
 require 'bundler/setup'
 
@@ -6,16 +7,17 @@ require 'ronin/support/network/tcp/proxy'
 require 'hexdump'
 
 Ronin::Support::Network::TCP::Proxy.start(port: 1337, server: ['www.wired.com', 80]) do |proxy|
-  address = lambda { |socket|
+  address = ->(socket) {
     addrinfo = socket.peeraddr
 
     "#{addrinfo[3]}:#{addrinfo[1]}"
   }
-  hex = Hexdump::Dumper.new
+
+  hexdump = Hexdump::Dumper.new
 
   proxy.on_client_data do |client,server,data|
     puts "#{address[client]} -> #{proxy}"
-    hex.dump(data)
+    hexdump.dump(data)
   end
 
   proxy.on_client_connect do |client|
@@ -28,7 +30,7 @@ Ronin::Support::Network::TCP::Proxy.start(port: 1337, server: ['www.wired.com',
 
   proxy.on_server_data do |client,server,data|
     puts "#{address[client]} <- #{proxy}"
-    hex.dump(data)
+    hexdump.dump(data)
   end
 
   proxy.on_server_connect do |client,server|

data/lib/ronin/support/archive/core_ext/file.rb

@@ -38,6 +38,22 @@ class File
   # @return [Ronin::Support::Archive::Tar::Reader]
   #   The tar reader object.
   #
+  # @example Enumerating over each entry in the tar archive:
+  #   File.untar('file.tar') do |tar|
+  #     tar.each do |entry|
+  #       puts entry.full_name
+  #       puts '-' * 80
+  #       puts entry.read
+  #       puts '-' * 80
+  #     end
+  #   end
+  #
+  # @example Reads a specific file from the tar archive:
+  #   File.untar('file.tar') do |tar|
+  #     data = tar.read('foo.txt')
+  #     # ...
+  #   end
+  #
   # @api public
   #
   # @since 1.0.0
@@ -61,6 +77,12 @@ class File
   # @return [Ronin::Support::Archive::Tar::Writer]
   #   The tar writer object.
   #
+  # @example
+  #   File.tar('output.tar') do |tar|
+  #     tar.mkdir('foo')
+  #     tar.add_file('foo/bar.txt','Hello World!')
+  #   end
+  #
   # @api public
   #
   # @since 1.0.0
@@ -84,6 +106,22 @@ class File
   # @return [Ronin::Support::Archive::Zip::Reader]
   #   The zip reader object.
   #
+  # @example Enumerating over each file in a zip archive:
+  #   File.unzip('file.zip') do |zip|
+  #     zip.each do |entry|
+  #       puts entry.name
+  #       puts '-' * 80
+  #       puts entry.read
+  #       puts '-' * 80
+  #     end
+  #   end
+  #
+  # @example Reads a specific file from a zip archive:
+  #   File.unzip('file.zip') do |zip|
+  #     data = zip.read('foo.txt')
+  #     # ...
+  #   end
+  #
   # @api public
   #
   # @since 1.0.0
@@ -107,6 +145,11 @@ class File
   # @return [Ronin::Support::Archive::Zip::Writer]
   #   The zip writer object.
   #
+  # @example
+  #   File.zip('output.zip') do |zip|
+  #     zip.add_file('foo/bar.txt','Hello World!')
+  #   end
+  #
   # @api public
   #
   # @since 1.0.0

data/lib/ronin/support/archive/core_ext.rb

@@ -16,4 +16,4 @@
 # along with ronin-support.  If not, see <https://www.gnu.org/licenses/>.
 #
 
-require 'ronin/support/compression/core_ext/file'
+require 'ronin/support/archive/core_ext/file'

data/lib/ronin/support/archive/tar/writer.rb

@@ -122,7 +122,7 @@ module Ronin
           # @return [self]
           #
           # @see https://rubydoc.info/stdlib/rubygems/Gem/Package/TarWriter/RestrictedStream
-          #   
+          #
           def add_file(name,contents=nil, mode: 0644, &block)
             if contents
               super(name,mode) do |io|
@@ -154,7 +154,7 @@ module Ronin
           # @return [self]
           #
           # @see https://rubydoc.info/stdlib/rubygems/Gem/Package/TarWriter/BoundedStream
-          #   
+          #
           def allocate_file(name,size, mode: 0644, &block)
             add_file_simple(name,mode,size,&block)
           end

data/lib/ronin/support/archive/tar.rb

@@ -40,20 +40,20 @@ module Ronin
       #     Tar.new(io, mode: 'w') do |tar|
       #       # add a file
       #       tar.add_file('file1.txt', "...")
-      #     
+      #
       #       # add a file and open an output stream
       #       tar.add_file('file2.txt') do |io|
       #         io.write("...")
       #       end
-      #     
+      #
       #       # add a symlink 'link' pointing to 'file1.txt'
       #       tar.add_symlink('link','file1.txt')
-      #     
+      #
       #       # add a directory
       #       tar.mkdir('foo')
       #     end
       #
-      # Opening 
+      # Opening
       #
       # @api public
       #

data/lib/ronin/support/archive/zip/reader.rb

@@ -183,7 +183,7 @@ module Ronin
           end
 
           private
-          
+
           #
           # Creates an `unzip` command with the additional arguments.
           #
@@ -256,7 +256,7 @@ module Ronin
           #   The parsed statistics.
           #
           def parse_statistics_line(line)
-            length, size, compression, files, _ = line.lstrip.split(/\s+/,5)
+            length, size, compression, files, _rest = line.lstrip.split(/\s+/,5)
 
             return Statistics.new(
               length:      length.to_i,

data/lib/ronin/support/binary/array.rb

@@ -35,7 +35,7 @@ module Ronin
       #
       # Creating an array of `int32`s:
       #
-      #     array = Binary::Array.new(:int32, 4)
+      #     array = Binary::Binary::Array.new(:int32, 4)
       #     # => #<Ronin::Support::Binary::Binary::Array: "\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00">
       #     array[0] = 0x11111111
       #     array[1] = 0x22222222
@@ -172,16 +172,13 @@ module Ronin
         def [](index)
           offset = index * @type.size
 
-          if (index < 0 || offset+@type.size > size)
+          if (index < 0) || ((offset + @type.size) > size)
             raise(IndexError,"index #{index} is out of bounds: 0...#{@length}")
           end
 
           case @type
           when CTypes::ObjectType
-            @cache[index] ||= (
-              slice = byteslice(offset,@type.size)
-              @type.unpack(slice)
-            )
+            @cache[index] ||= @type.unpack(byteslice(offset,@type.size))
           else
             data = super(offset,@type.size)
             @type.unpack(data)
@@ -207,11 +204,11 @@ module Ronin
         #   array[0] = 0x11111111
         #   array[0]
         #   # => 286331153
-        #   
+        #
         def []=(index,value)
           offset = index * @type.size
 
-          if (index < 0 || offset+@type.size > size)
+          if (index < 0) || ((offset + @type.size) > size)
             raise(IndexError,"index #{index} is out of bounds: 0...#{@length}")
           end
 

data/lib/ronin/support/binary/bit_flip.rb

@@ -32,6 +32,9 @@ module Ronin
       # @api semipublic
       #
       module BitFlip
+        #
+        # Methods for bit-flipping Integers.
+        #
         module Integer
           #
           # Enumerates over every bit flip in the integer.
@@ -101,6 +104,9 @@ module Ronin
           end
         end
 
+        #
+        # Methods for bit-flipping Strings.
+        #
         module String
           #
           # Enumerates over every bit flip of every byte in the string.
@@ -127,7 +133,7 @@ module Ronin
 
             bits = (0...8)
 
-            string.each_byte.each_with_index do |byte,index|
+            string.each_byte.with_index do |byte,index|
               Integer.each_bit_flip(byte,bits) do |flipped_byte|
                 new_string = string.dup
                 new_string.force_encoding(Encoding::ASCII_8BIT)

data/lib/ronin/support/binary/buffer.rb

@@ -30,7 +30,7 @@ module Ronin
       #
       # Writing bytes into an empty buffer:
       #
-      #     buffer = Buffer.new(10)
+      #     buffer = Binary::Buffer.new(10)
       #     # => #<Ronin::Support::Binary::Buffer: "\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00">
       #     buffer[0] = 0x41
       #     buffer[1] = 0x42
@@ -40,7 +40,7 @@ module Ronin
       #
       # Writing different types of data to a buffer:
       #
-      #     buffer = Buffer.new(16)
+      #     buffer = Binary::Buffer.new(16)
       #     # => #<Ronin::Support::Binary::Buffer: "\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00">
       #     buffer.put_uint32(0,0x11223344)
       #     buffer.put_int32(4,-1)
@@ -51,7 +51,7 @@ module Ronin
       #
       # Creating a buffer from an existing String:
       #
-      #     buffer = Buffer.new("\x41\x00\x00\x00\x42\x00\x00\x00")
+      #     buffer = Binary::Buffer.new("\x41\x00\x00\x00\x42\x00\x00\x00")
       #     # => #<Ronin::Support::Binary::Buffer: "A\u0000\u0000\u0000B\u0000\u0000\u0000">
       #     buffer.get_uint32(0)
       #     # => 65
@@ -203,8 +203,8 @@ module Ronin
         def get(type,offset)
           type = @type_system[type]
 
-          if (offset < 0 || offset+type.size > size)
-            raise(IndexError,"offset #{offset} is out of bounds: 0...#{size-type.size}")
+          if (offset < 0) || ((offset + type.size) > size)
+            raise(IndexError,"offset #{offset} is out of bounds: 0...#{size - type.size}")
           end
 
           data = @string[offset,type.size]
@@ -270,27 +270,27 @@ module Ronin
         #   The read C string, without the null-byte.
         #
         def get_string(offset,length=nil)
-          if (offset < 0 || offset >= size)
-            raise(IndexError,"offset #{offset} is out of bounds: 0...#{size-1}")
-          elsif (length && offset+length > size)
-            raise(IndexError,"offset #{offset} or length #{length} is out of bounds: 0...#{size-1}")
+          if (offset < 0) || (offset >= size)
+            raise(IndexError,"offset #{offset} is out of bounds: 0...#{size - 1}")
+          elsif (length && (offset + length) > size)
+            raise(IndexError,"offset #{offset} or length #{length} is out of bounds: 0...#{size - 1}")
           end
 
           if length
             substring = @string[offset,length]
 
-            if (null_byte = substring.index("\0"))
-              substring[0...null_byte]
+            if (null_byte_index = substring.index("\0"))
+              substring[0...null_byte_index]
+            else
+              substring
             end
           else
-            if (null_byte = @string.index("\0",offset))
-              substring = @string[offset...null_byte]
+            if (null_byte_index = @string.index("\0",offset))
+              @string[offset...null_byte_index]
             else
-              substring = @string[offset..]
+              @string[offset..]
             end
           end
-
-          return substring
         end
 
         #
@@ -707,8 +707,8 @@ module Ronin
           type       = @type_system[type]
           array_type = type[count]
 
-          if (offset < 0 || offset+array_type.size > size)
-            raise(IndexError,"offset #{offset} or size #{array_type.size} is out of bounds: 0...#{size-type.size}")
+          if (offset < 0) || ((offset + array_type.size) > size)
+            raise(IndexError,"offset #{offset} or size #{array_type.size} is out of bounds: 0...#{size - type.size}")
           end
 
           slice = @string[offset,array_type.size]
@@ -1162,8 +1162,8 @@ module Ronin
         def put(type,offset,value)
           type = @type_system[type]
 
-          if (offset < 0 || offset+type.size > size)
-            raise(IndexError,"offset #{offset} is out of bounds: 0...#{size-type.size}")
+          if (offset < 0) || ((offset + type.size) > size)
+            raise(IndexError,"offset #{offset} is out of bounds: 0...#{size - type.size}")
           end
 
           data = type.pack(value)
@@ -1222,8 +1222,8 @@ module Ronin
           ascii_string = string.encode(Encoding::ASCII_8BIT)
           cstring      = "#{ascii_string}\0"
 
-          if (offset < 0 || offset+cstring.bytesize >= size)
-            raise(IndexError,"offset #{offset} or C string size #{cstring.bytesize} is out of bounds: 0...#{size-1}")
+          if (offset < 0) || ((offset + cstring.bytesize) >= size)
+            raise(IndexError,"offset #{offset} or C string size #{cstring.bytesize} is out of bounds: 0...#{size - 1}")
           end
 
           @string[offset,cstring.bytesize] = cstring
@@ -1605,9 +1605,9 @@ module Ronin
         def put_array_of(type,offset,array)
           type       = @type_system[type]
           array_type = type[array.length]
-          
-          if (offset < 0 || offset+array_type.size > size)
-            raise(IndexError,"offset #{offset} or size #{array_type.size} is out of bounds: 0...#{size-type.size}")
+
+          if (offset < 0) || ((offset + array_type.size) > size)
+            raise(IndexError,"offset #{offset} or size #{array_type.size} is out of bounds: 0...#{size - type.size}")
           end
 
           data = array_type.pack(array)