ronin-support 1.0.0 → 1.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b487230c13b8458ad2f063e60e872f35f6262b14921d7f76050647e94aced0a3
-  data.tar.gz: 6bfe1e1bc33c1694070529fe6d622cc745f370cc8afc688fb62bb262cf71e550
+  metadata.gz: e4a9cca292661aabc9b8b8360bef73af12a140bac7b80bbe969671a78d5c4cb8
+  data.tar.gz: cb8920fa647c56bcf03c9a4b5796f6e58fd732d82ea79027bce10d77246f1af6
 SHA512:
-  metadata.gz: a928c76fae066768a23621ac2cf1c1c746e034c2d16d141a2f4275bed0dc24ec24556fc8226d3e8fc6cdcf7990528c35850477bf266fa9cfe85d38b3f0898ec4
-  data.tar.gz: 424f6d0b54160808cd43a4dee8f553830182fddb345b80708cc654e2a5df19d0225c1b0076df17fbb64425824a695c72e32f41601625450977b0eea62738df21
+  metadata.gz: '04831026ac5813990e5db208ac229f707f24cfb0bcff277ff0da70eecdce58b379925ed944b5377ead08ac63f7e6fce0a323bcfe05a4a617a6d0cfa5987ec90b'
+  data.tar.gz: ed25a967fe35242afdb9a9d2e3dc8dff096de0e7737494100b6a54c96f67c4288d2ff21ab2e6eadce4f07fe6284037e454e37498ae1b108dfeda024b115bf26b

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,15 @@
-### 1.0.0 / 2023-XX-XX
+### 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/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

@@ -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

@@ -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)

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

@@ -69,15 +69,15 @@ module Ronin
 
           case string
           when ByteSlice
-            if (offset < 0) || (offset+length > string.bytesize)
+            if (offset < 0) || ((offset + length) > string.bytesize)
               raise(IndexError,"offset #{offset} or length #{length} is out of bounds: 0...#{string.bytesize}")
             end
 
             @string = string.string
-            @offset = string.offset+offset
+            @offset = string.offset + offset
             @length = length
           when String
-            if (offset < 0) || (offset+length > string.bytesize)
+            if (offset < 0) || ((offset + length) > string.bytesize)
               raise(IndexError,"offset #{offset} or length #{length} is out of bounds: 0...#{string.bytesize}")
             end
 
@@ -109,17 +109,17 @@ module Ronin
           when Range
             range = index_or_range
 
-            @string[@offset+range.begin,range.end-range.begin]
+            @string[@offset + range.begin,range.end - range.begin]
           when Integer
             index = index_or_range
 
             case length
             when Integer
-              @string[@offset+index,length]
+              @string[@offset + index,length]
             when nil
-              @string[@offset+index]
+              @string[@offset + index]
             when Float::INFINITY
-              @string[@offset+index,@length-index]
+              @string[@offset + index,@length - index]
             else
               raise(ArgumentError,"invalid length (#{length.inspect}) must be an Integer, nil, or Float::INFINITY")
             end
@@ -151,17 +151,17 @@ module Ronin
           when Range
             range = index_or_range
 
-            @string[@offset+range.begin,range.end-range.begin] = value
+            @string[@offset + range.begin,range.end - range.begin] = value
           when Integer
             index = index_or_range
 
             case length
             when Integer
-              @string[@offset+index,length] = value
+              @string[@offset + index,length] = value
             when nil
-              @string[@offset+index] = value
+              @string[@offset + index] = value
             when Float::INFINITY
-              @string[@offset+index,@length-index] = value
+              @string[@offset + index,@length - index] = value
             else
               raise(ArgumentError,"invalid length (#{length.inspect}) must be an Integer, nil, or Float::INFINITY")
             end
@@ -200,7 +200,7 @@ module Ronin
         #   found.
         #
         def index(substring,offset=0)
-          if (index = @string.index(substring,@offset+offset))
+          if (index = @string.index(substring,@offset + offset))
             if index < (@offset + @length)
               index - @offset
             end
@@ -211,13 +211,13 @@ module Ronin
         # Gets the byte at the given index within the byte slice.
         #
         # @param [Integer] index
-        # 
+        #
         # @return [Integer, nil]
         #   The byte at the given index, or nil if the index is out of bounds.
         #
         def getbyte(index)
           if index < @length
-            @string.getbyte(@offset+index)
+            @string.getbyte(@offset + index)
           end
         end
 
@@ -235,7 +235,7 @@ module Ronin
         #
         def setbyte(index,byte)
           if index < @length
-            @string.setbyte(@offset+index,byte)
+            @string.setbyte(@offset + index,byte)
           else
             raise(IndexError,"index #{index.inspect} is out of bounds")
           end
@@ -257,7 +257,7 @@ module Ronin
         def each_byte
           return enum_for(__method__) unless block_given?
 
-          (@offset...(@offset+@length)).each do |index|
+          (@offset...(@offset + @length)).each do |index|
             yield @string.getbyte(index)
           end
         end
@@ -288,7 +288,7 @@ module Ronin
         def each_char
           return enum_for(__method__) unless block_given?
 
-          (@offset...(@offset+@length)).each do |index|
+          (@offset...(@offset + @length)).each do |index|
             yield @string[index]
           end
         end

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

@@ -101,14 +101,15 @@ module Ronin
         # @return [self]
         #
         def concat(value)
-          value = case value
-                  when Integer then value.chr
-                  else              value.to_s
-                  end
+          value      = case value
+                       when Integer then value.chr
+                       else              value.to_s
+                       end
           value_size = value.bytesize
 
           unless value.include?(NULL)
             value = "#{value}#{NULL}"
+
             value_size += 1
           end
 
@@ -153,6 +154,7 @@ module Ronin
 
           @string.each_char do |char|
             break if char == NULL
+
             yield char
           end
         end
@@ -185,6 +187,7 @@ module Ronin
 
           @string.each_byte do |byte|
             break if byte == 0x00
+
             yield byte
           end
         end

data/lib/ronin/support/binary/ctypes/arch/arm/big_endian.rb

@@ -24,6 +24,10 @@ module Ronin
       module CTypes
         module Arch
           module ARM
+            #
+            # Represents the C types for the ARM architecture, in big-endian
+            # mode.
+            #
             module BigEndian
               include CTypes::BigEndian
 

data/lib/ronin/support/binary/ctypes/arch/arm.rb

@@ -23,6 +23,9 @@ module Ronin
     module Binary
       module CTypes
         module Arch
+          #
+          # Represents the C types for the ARM architecture.
+          #
           module ARM
             include LittleEndian
 

data/lib/ronin/support/binary/ctypes/arch/arm64/big_endian.rb

@@ -24,6 +24,10 @@ module Ronin
       module CTypes
         module Arch
           module ARM64
+            #
+            # Represents the C types for the ARM64 architecture, in big-endian
+            # mode.
+            #
             module BigEndian
               include CTypes::BigEndian