ronin-support 0.5.2 → 1.0.0.beta2

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,7 +1,6 @@
+# frozen_string_literal: true
 #
-# Copyright (c) 2006-2021 Hal Brodigan (postmodern.mod3 at gmail.com)
-#
-# This file is part of ronin-support.
+# 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
@@ -17,4 +16,4 @@
 # 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

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

@@ -0,0 +1,197 @@
+# 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
+        #
+        # Handles writing tar encoded archive data.
+        #
+        # @see https://rubydoc.info/stdlib/rubygems/Gem/Package/TarWriter
+        #
+        # @api public
+        #
+        # @since 1.0.0
+        #
+        class Writer < Gem::Package::TarWriter
+
+          #
+          # Initializes the tar writer.
+          #
+          # @param [IO, StringIO, String] io_or_buffer
+          #   The IO object or buffer to write to. 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 writer object.
+          #
+          # @yieldparam [Writer] tar
+          #   The tar writer object.
+          #
+          # @return [Writer]
+          #   The gzip writer object.
+          #
+          # @example Initializing with an IO object:
+          #   tar = Archive::Tar::Writer.new(io)
+          #
+          # @example Initializing with a buffer:
+          #   buffer = ""
+          #   tar   = Archive::Tar::Writer.new(buffer)
+          #
+          # @example Initializin with a buffer and append mode:
+          #   buffer = "foo"
+          #   tar   = Archive::Tar::Writer.new(buffer, mode: 'a')
+          #
+          def self.new(io_or_buffer, mode: 'w', &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 writing.
+          #
+          # @param [String] path
+          #   The path to the tar archive.
+          #
+          # @yield [tar]
+          #   If a block is given, then it will be passed the new tar writer
+          #   object.
+          #
+          # @yieldparam [Writer] tar
+          #   The newly created tar writer object.
+          #
+          # @return [Writer]
+          #   If no block is given, than the tar writer object will be returned.
+          #
+          def self.open(path,&block)
+            if block
+              File.open(path,'wb') do |file|
+                new(file,&block)
+              end
+            else
+              return new(File.new(path,'wb'))
+            end
+          end
+
+          #
+          # Adds a file to the tar archive.
+          #
+          # @param [String] name
+          #   The name or relative path of the new file.
+          #
+          # @param [String, nil] contents
+          #   The optional contents of the file.
+          #
+          # @param [Integer] mode
+          #   The permission mode for the new file.
+          #
+          # @yield [file]
+          #   If a block is given, it will be yielded an output stream for the
+          #   file that can be written to.
+          #
+          # @yieldparam [Gem::Package::TarWriter::RestrictedStream] file
+          #
+          # @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|
+                io.write(contents)
+              end
+            else
+              super(name,mode,&block)
+            end
+          end
+
+          #
+          # Adds a file, with the exact size, to the tar archive.
+          #
+          # @param [String] name
+          #   The name or relative path of the new file.
+          #
+          # @param [Integer] size
+          #   The size of the file in bytes.
+          #
+          # @param [Integer] mode
+          #   The permission mode for the new file.
+          #
+          # @yield [file]
+          #   If a block is given, it will be yielded an output stream for the
+          #   file that can be written to.
+          #
+          # @yieldparam [Gem::Package::TarWriter::BoundedStream] file
+          #
+          # @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
+
+          #
+          # Adds a symlink to the tar archive.
+          #
+          # @param [String] name
+          #   The name or relative path of the new symlink.
+          #
+          # @param [String] target
+          #   The destination of the new symlink.
+          #
+          # @param [Integer] mode
+          #   The permission mode of the new symlink.
+          #
+          def add_symlink(name,target, mode: 0777)
+            super(name,target,mode)
+          end
+
+          #
+          # Adds a directory to the tar archive.
+          #
+          # @param [String] name
+          #   The name or relative path of the new directory.
+          #
+          # @param [Integer] mode
+          #   The permission mode of the new directory.
+          #
+          # @return [self]
+          #
+          def mkdir(name, mode: 0755)
+            super(name,mode)
+          end
+
+        end
+      end
+    end
+  end
+end