ronin-support 0.5.1 → 1.0.0.beta1

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

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

@@ -0,0 +1,155 @@
+# 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'
+
+module Ronin
+  module Support
+    module Archive
+      #
+      # Handles tar archive reading/writing.
+      #
+      # ## Examples
+      #
+      # Create a tar reader stream around an existing IO object:
+      #
+      #     Tar.new(io) do |tar|
+      #       file = tar['file.txt']
+      #       puts "#{file.full_name} (#{file.header.umode})"
+      #       puts file.read
+      #     end
+      #
+      # Opening a tar writer stream around an existing IO object:
+      #
+      #     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 
+      #
+      # @api public
+      #
+      # @since 1.0.0
+      #
+      module Tar
+        #
+        # Creates a tar stream around the IO object.
+        #
+        # @param [IO, StringIO, String] 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 [Reader, Writer] tar
+        #   The tar reader or writer object.
+        #
+        # @return [Reader, Writer]
+        #   The gzip reader or writer object.
+        #
+        # @raise [ArgumentError]
+        #   The mode must include either `r`, `w`, or `a`.
+        #
+        # @example Creates a tar reader stream around an existing IO object:
+        #   Tar.new(io) do |tar|
+        #     # ...
+        #   end
+        #
+        # @example Creates a tar writer stream around an existing IO object:
+        #   Tar.new(io, mode: 'w') do |tar|
+        #     # ...
+        #   end
+        #
+        # @api public
+        #
+        def self.new(io, mode: 'r', &block)
+          tar_class = if mode.include?('w') || mode.include?('a')
+                        Writer
+                      elsif mode.include?('r')
+                        Reader
+                      else
+                        raise(ArgumentError,"mode argument must include either 'r', 'w', or 'a': #{mode.inspect}")
+                      end
+
+          return tar_class.new(io, mode: mode, &block)
+        end
+
+        #
+        # Opens the 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 [gz]
+        #   If a block is given, it will be passed the gzip writer object.
+        #
+        # @yieldparam [Reader, Writer] tar
+        #   The tar writer object.
+        #
+        # @return [Reader, Writer]
+        #   The tar writer object.
+        #
+        # @raise [ArgumentError]
+        #   The mode must include either `r`, `w`, or `a`.
+        #
+        # @example Open a tar file for reading:
+        #   Tar.open(path) do |tar|
+        #     # ...
+        #   end
+        #
+        # @example Open a tar file for writing:
+        #   Tar.open(path, mode: 'w') do |tar|
+        #     # ...
+        #   end
+        #
+        # @api public
+        #
+        def self.open(path, mode: 'r', &block)
+          tar_class = if mode.include?('w') || mode.include?('a')
+                        Writer
+                      elsif mode.include?('r')
+                        Reader
+                      else
+                        raise(ArgumentError,"mode argument must include either 'r', 'w', or 'a': #{mode.inspect}")
+                      end
+
+          return tar_class.open(path,&block)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,134 @@
+# 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 'date'
+
+module Ronin
+  module Support
+    module Archive
+      module Zip
+        class Reader
+
+          #
+          # Represents an entry in a zip archive.
+          #
+          # @since 1.0.0
+          #
+          class Entry
+
+            # The length of the file.
+            #
+            # @return [Integer]
+            attr_reader :length
+
+            # The compression method used.
+            #
+            # @return [:stored, :deflate]
+            attr_reader :method
+
+            # The size of the file.
+            #
+            # @return [Integer]
+            attr_reader :size
+
+            # The compression ratio of the file.
+            #
+            # @return [Integer]
+            attr_reader :compression
+
+            # The date of the file.
+            #
+            # @return [Date]
+            attr_reader :date
+
+            # The time of the file.
+            #
+            # @return [Time]
+            attr_reader :time
+
+            # The CRC32 checksum (in hex encoding).
+            #
+            # @return [String]
+            attr_reader :crc32
+
+            # The name of the file.
+            #
+            # @return [String]
+            attr_reader :name
+
+            #
+            # Initializes the zip archive entry.
+            #
+            # @param [Reader] reader
+            #
+            # @param [Integer] length
+            #
+            # @param [:stored, :deflate] method
+            #
+            # @param [Integer] size
+            #
+            # @param [Integer] compression
+            #
+            # @param [Date] date
+            #
+            # @param [Time] time
+            #
+            # @param [String] crc32
+            #
+            # @param [String] name
+            #
+            # @api private
+            #
+            def initialize(reader, length: ,
+                                   method: ,
+                                   size:   ,
+                                   compression: ,
+                                   date: ,
+                                   time: ,
+                                   crc32: ,
+                                   name: )
+              @reader      = reader
+              @length      = length
+              @method      = method
+              @size        = size
+              @compression = compression
+              @date        = date
+              @time        = time
+              @crc32       = crc32
+              @name        = name
+            end
+
+            #
+            # Reads the contents of the entry.
+            #
+            # @param [Integer, nil] length
+            #   Optional number of bytes to read.
+            #
+            # @return [String]
+            #   The read data.
+            #
+            def read(length=nil)
+              @reader.read(@name, length: length)
+            end
+
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,76 @@
+# 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 'date'
+
+module Ronin
+  module Support
+    module Archive
+      module Zip
+        class Reader
+          #
+          # Represents the overall statistics for the zip archive.
+          #
+          class Statistics
+
+            # The total zip archive length.
+            #
+            # @return [Integer]
+            attr_reader :length
+
+            # The total zip archive size.
+            #
+            # @return [Integer]
+            attr_reader :size
+
+            # The total compression ratio of the zip archive.
+            #
+            # @return [Integer]
+            attr_reader :compression
+
+            # The total number of files in the zip archive.
+            #
+            # @return [Integer]
+            attr_reader :files
+
+            #
+            # Initializes the statistics object.
+            #
+            # @param [Integer] length
+            #
+            # @param [Integer] size
+            #
+            # @param [Integer] compression
+            #
+            # @param [Integer] files
+            #
+            # @api private
+            #
+            def initialize(length: , size: , compression: , files: )
+              @length      = length
+              @size        = size
+              @compression = compression
+              @files       = files
+            end
+
+          end
+        end
+      end
+    end
+  end
+end