ronin-support 0.5.1 → 1.0.0.beta1

data/gemspec.yml

@@ -1,26 +1,36 @@
 name: ronin-support
-summary: A support library for Ronin.
-description:
-  Ronin Support is a support library for Ronin. Ronin Support contains many
-  of the convenience methods used by Ronin and additional libraries.
+summary: A support library for ronin-rb.
+description: |
+  ronin-support is a support library for ronin-rb. ronin-support provides
+  many Core Extensions to Ruby's built-in classes as well as it's own
+  Classes/Modules. ronin-support can be used by other Ruby libraries, tools, or
+  scripts.
+  
+  It's like pwntools combined with activesupport.
+  
+  Ronin is a Ruby toolkit for security research and development.
 
-license: LGPL-3
+license: LGPL-3.0
 authors: Postmodern
 email: postmodern.mod3@gmail.com
-homepage: http://ronin-ruby.github.com/
+homepage: https://ronin-rb.dev
 has_yard: true
 
-required_ruby_version: ">= 1.8.7"
+metadata:
+  documentation_uri: https://ronin-rb.dev/docs/ronin-support/frames
+  source_code_uri:   https://github.com/ronin-rb/ronin-support
+  bug_tracker_uri:   https://github.com/ronin-rb/ronin-support/issues
+  changelog_uri:     https://github.com/ronin-rb/ronin-support/blob/master/ChangeLog.md
+  rubygems_mfa_required: 'true'
+
+required_ruby_version: ">= 3.0.0"
 
 dependencies:
-  chars: ~> 0.2
-  hexdump: ~> 0.1
+  chars: ~> 0.3, >= 0.3.2
+  hexdump: ~> 1.0
   combinatorics: ~> 0.4
-  uri-query_params: ~> 0.6
-  data_paths: ~> 0.3
-  parameters: ~> 0.4
+  addressable: ~> 2.0
+  uri-query_params: ~> 0.8
 
 development_dependencies:
-  bundler: ~> 1.0
-  yard: ~> 0.8
-  yard-parameters: ~> 0.1
+  bundler: ~> 2.0

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

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+#
+# Copyright (c) 2006-2022 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
+# by the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# ronin-support is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Lesser General Public License for more details.
+#
+# You should have received a copy of the GNU Lesser General Public License
+# along with ronin-support.  If not, see <https://www.gnu.org/licenses/>.
+#
+
+require 'ronin/support/archive/tar/reader'
+require 'ronin/support/archive/tar/writer'
+require 'ronin/support/archive/zip/reader'
+require 'ronin/support/archive/zip/writer'
+
+class File
+
+  #
+  # Opens the tar archive file for reading.
+  #
+  # @param [String] path
+  #   The path to the file to read.
+  #
+  # @yield [tar]
+  #   If a block is given, it will be passed the tar reader object.
+  #
+  # @yieldparam [Ronin::Support::Archive::Tar::Reader] tar
+  #   The tar reader object.
+  #
+  # @return [Ronin::Support::Archive::Tar::Reader]
+  #   The tar reader object.
+  #
+  # @api public
+  #
+  # @since 1.0.0
+  #
+  def self.untar(path,&block)
+    Ronin::Support::Archive::Tar::Reader.open(path,&block)
+  end
+
+  #
+  # Opens the tar archive file for writing.
+  #
+  # @param [String] path
+  #   The path to the file to write to.
+  #
+  # @yield [tar]
+  #   If a block is given, it will be passed the tar writer object.
+  #
+  # @yieldparam [Ronin::Support::Archive::Tar::Writer] tar
+  #   The tar writer object.
+  #
+  # @return [Ronin::Support::Archive::Tar::Writer]
+  #   The tar writer object.
+  #
+  # @api public
+  #
+  # @since 1.0.0
+  #
+  def self.tar(path,&block)
+    Ronin::Support::Archive::Tar::Writer.open(path,&block)
+  end
+
+  #
+  # Opens the zip archive file for reading.
+  #
+  # @param [String] path
+  #   The path to the file to read.
+  #
+  # @yield [zip]
+  #   If a block is given, it will be passed the zip reader object.
+  #
+  # @yieldparam [Ronin::Support::Archive::Zip::Reader] zip
+  #   The zip reader object.
+  #
+  # @return [Ronin::Support::Archive::Zip::Reader]
+  #   The zip reader object.
+  #
+  # @api public
+  #
+  # @since 1.0.0
+  #
+  def self.unzip(path,&block)
+    Ronin::Support::Archive::Zip::Reader.open(path,&block)
+  end
+
+  #
+  # Opens the zip archive file for writing.
+  #
+  # @param [String] path
+  #   The path to the file to write to.
+  #
+  # @yield [zip]
+  #   If a block is given, it will be passed the zip writer object.
+  #
+  # @yieldparam [Ronin::Support::Archive::Zip::Writer] zip
+  #   The zip writer object.
+  #
+  # @return [Ronin::Support::Archive::Zip::Writer]
+  #   The zip writer object.
+  #
+  # @api public
+  #
+  # @since 1.0.0
+  #
+  def self.zip(path,&block)
+    Ronin::Support::Archive::Zip::Writer.open(path,&block)
+  end
+
+end

data/lib/ronin/{formatting/sql.rb → support/archive/core_ext.rb}

@@ -1,20 +1,19 @@
+# frozen_string_literal: true
 #
-# Copyright (c) 2006-2012 Hal Brodigan (postmodern.mod3 at gmail.com)
+# Copyright (c) 2006-2022 Hal Brodigan (postmodern.mod3 at gmail.com)
 #
-# This file is part of Ronin Support.
-#
-# Ronin Support is free software: you can redistribute it and/or modify
+# 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
 # by the Free Software Foundation, either version 3 of the License, or
 # (at your option) any later version.
 #
-# Ronin Support is distributed in the hope that it will be useful,
+# ronin-support is distributed in the hope that it will be useful,
 # but WITHOUT ANY WARRANTY; without even the implied warranty of
 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 # GNU Lesser General Public License for more details.
 #
 # You should have received a copy of the GNU Lesser General Public License
-# along with Ronin Support.  If not, see <http://www.gnu.org/licenses/>.
+# along with ronin-support.  If not, see <https://www.gnu.org/licenses/>.
 #
 
-require 'ronin/formatting/extensions/sql'
+require 'ronin/support/compression/core_ext/file'

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

@@ -0,0 +1,213 @@
+# frozen_string_literal: true
+#
+# Copyright (c) 2006-2022 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
+# by the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# ronin-support is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Lesser General Public License for more details.
+#
+# You should have received a copy of the GNU Lesser General Public License
+# along with ronin-support.  If not, see <https://www.gnu.org/licenses/>.
+#
+
+require 'ronin/support/archive'
+
+module Ronin
+  module Support
+    module Archive
+      #
+      # Provides helper methods for reading/writing archives.
+      #
+      # @api public
+      #
+      # @since 1.0.0
+      #
+      module Mixin
+        #
+        # Creates a tar stream around the IO object.
+        #
+        # @param [IO, StringIO] io
+        #   The IO object to read or write data to.
+        #
+        # @param [String] mode
+        #   The mode to open the tar stream with.
+        #
+        # @yield [tar]
+        #   If a block is given, it will be passed the tar stream object.
+        #
+        # @yieldparam [Tar::Reader, Tar::Writer] tar
+        #   The tar reader or writer object.
+        #
+        # @return [Tar::Reader, Tar::Writer]
+        #   The tar reader or writer object.
+        #
+        # @raise [ArgumentError]
+        #   The mode must include either `r`, `w`, or `a`.
+        #
+        # @see Tar.new
+        #
+        # @api public
+        #
+        def tar_stream(io, mode: 'r', &block)
+          Archive.tar_stream(io, mode: mode, &block)
+        end
+
+        #
+        # Opens a tar file for reading or writing.
+        #
+        # @param [String] path
+        #   The path to the tar file.
+        #
+        # @param [String] mode
+        #   The mode to open the file as.
+        #
+        # @yield [tar]
+        #   If a block is given, it will be passed the tar writer object.
+        #
+        # @yieldparam [Tar::Writer] tar
+        #   The tar writer object.
+        #
+        # @return [Tar::Writer]
+        #   The tar writer object.
+        #
+        # @raise [ArgumentError]
+        #   The mode must include either `r`, `w`, or `a`.
+        #
+        # @see Tar.open
+        #
+        # @api public
+        #
+        def tar_open(path, mode: 'r', &block)
+          Archive.tar_open(path, mode: mode, &block)
+        end
+
+        #
+        # Opens the tarped file for reading.
+        #
+        # @param [String] path
+        #   The path to the file to read.
+        #
+        # @yield [tar]
+        #   If a block is given, it will be passed the tar reader object.
+        #
+        # @yieldparam [Tar::Reader] tar
+        #   The tar reader object.
+        #
+        # @return [Tar::Reader]
+        #   The tar reader object.
+        #
+        # @see tar_open
+        #
+        # @api public
+        #
+        def untar(path,&block)
+          Archive.untar(path,&block)
+        end
+
+        #
+        # Opens the tar file for writing.
+        #
+        # @param [String] path
+        #   The path to the file to write to.
+        #
+        # @yield [tar]
+        #   If a block is given, it will be passed the tar writer object.
+        #
+        # @yieldparam [Tar::Writer] tar
+        #   The tar writer object.
+        #
+        # @return [Tar::Writer]
+        #   The tar writer object.
+        #
+        # @see tar_open
+        #
+        # @api public
+        #
+        def tar(path,&block)
+          Archive.tar(path,&block)
+        end
+
+        #
+        # Opens a zip file for reading or writing.
+        #
+        # @param [String] path
+        #   The path to the zip file.
+        #
+        # @param [String] mode
+        #   The mode to open the file as.
+        #
+        # @yield [zip]
+        #   If a block is given, it will be passed the zip writer object.
+        #
+        # @yieldparam [Zip::Writer] zip
+        #   The zip writer object.
+        #
+        # @return [Zip::Writer]
+        #   The zip writer object.
+        #
+        # @raise [ArgumentError]
+        #   The mode must include either `r`, `w`, or `a`.
+        #
+        # @see Zip.open
+        #
+        # @api public
+        #
+        def zip_open(path, mode: 'r', &block)
+          Archive.zip_open(path, mode: mode, &block)
+        end
+
+        #
+        # Opens the zipped file for reading.
+        #
+        # @param [String] path
+        #   The path to the file to read.
+        #
+        # @yield [zip]
+        #   If a block is given, it will be passed the zip reader object.
+        #
+        # @yieldparam [Zip::Reader] zip
+        #   The zip reader object.
+        #
+        # @return [Zip::Reader]
+        #   The zip reader object.
+        #
+        # @see zip_open
+        #
+        # @api public
+        #
+        def unzip(path,&block)
+          Archive.unzip(path,&block)
+        end
+
+        #
+        # Opens the zip file for writing.
+        #
+        # @param [String] path
+        #   The path to the file to write to.
+        #
+        # @yield [zip]
+        #   If a block is given, it will be passed the zip writer object.
+        #
+        # @yieldparam [Zip::Writer] zip
+        #   The zip writer object.
+        #
+        # @return [Zip::Writer]
+        #   The zip writer object.
+        #
+        # @see zip_open
+        #
+        # @api public
+        #
+        def zip(path,&block)
+          Archive.zip(path,&block)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,135 @@
+# frozen_string_literal: true
+#
+# Copyright (c) 2006-2022 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
+# by the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# ronin-support is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Lesser General Public License for more details.
+#
+# You should have received a copy of the GNU Lesser General Public License
+# along with ronin-support.  If not, see <https://www.gnu.org/licenses/>.
+#
+
+require 'rubygems/package'
+require 'stringio'
+
+module Ronin
+  module Support
+    module Archive
+      module Tar
+        #
+        # Handling reading tar encoded archive data.
+        #
+        # @see https://rubydoc.info/stdlib/rubygems/Gem/Package/TarReader
+        #
+        # @api public
+        #
+        # @since 1.0.0
+        #
+        class Reader < Gem::Package::TarReader
+
+          #
+          # Initializes the tar writer.
+          #
+          # @param [IO, StringIO, String] io_or_buffer
+          #   The IO object or buffer to read from. If a `String` is given, then
+          #   it will be wrapped in a `StringIO` object using the optional
+          #   `mode` argument.
+          #
+          # @param [String] mode
+          #   The optional mode to initialize the `StringIO` object to wrap
+          #   around the given buffer `String`.
+          #
+          # @yield [tar]
+          #   If a block is given, it will be passed the new tar reader object.
+          #
+          # @yieldparam [Reader] tar
+          #   The tar reader object.
+          #
+          # @return [Reader]
+          #   The gzip reader object.
+          #
+          # @example Initializing with an IO object:
+          #   tar = Archive::Tar::Reader.new(io)
+          #
+          # @example Initializing with a buffer:
+          #   buffer = "..."
+          #   tar   = Archive::Tar::Reader.new(buffer)
+          #
+          def self.new(io_or_buffer, mode: 'r', &block)
+            io = case io_or_buffer
+                 when String then StringIO.new(io_or_buffer,mode)
+                 else             io_or_buffer
+                 end
+
+            return super(io,&block)
+          end
+
+          #
+          # Opens the tar archive file for reading.
+          #
+          # @param [String] path
+          #   The path to the tar archive.
+          #
+          # @yield [tar]
+          #   If a block is given, then it will be passed the new tar reader
+          #   object.
+          #
+          # @yieldparam [Reader] tar
+          #   The newly created tar reader object.
+          #
+          # @return [Reader]
+          #   If no block is given, than the tar reader object will be returned.
+          #
+          def self.open(path,&block)
+            if block
+              File.open(path,'rb') do |file|
+                new(file,&block)
+              end
+            else
+              new(File.new(path,'rb'))
+            end
+          end
+
+          #
+          # Finds an entry in the tar archive with the matching name.
+          #
+          # @param [String] name
+          #   The entry name to search for.
+          #
+          # @return [Entry, nil]
+          #   The matching entry or `nil` if none could be found.
+          #
+          def [](name)
+            find { |entry| entry.full_name == name }
+          end
+
+          #
+          # Reads the contents of an entry from the tar archive.
+          #
+          # @param [String] name
+          #   The name of the entry to read.
+          #
+          # @param [Integer, nil] length
+          #   Optional number of bytes to read.
+          #
+          # @return [String]
+          #   The read data.
+          #
+          def read(name, length: nil)
+            if (entry = self[name])
+              entry.read(length)
+            end
+          end
+
+        end
+      end
+    end
+  end
+end