ronin-support 0.5.2 → 1.0.0.beta2

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

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

@@ -0,0 +1,273 @@
+# 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/zip/reader/entry'
+require 'ronin/support/archive/zip/reader/statistics'
+
+require 'time'
+
+module Ronin
+  module Support
+    module Archive
+      module Zip
+        #
+        # Handles reading zip archives.
+        #
+        # @note
+        #   This provides a simple interface for reading zip archives using
+        #   the `unzip` command. If you need something more powerful, use the
+        #   [archive-zip] gem instead.
+        #
+        # [archive-zip]: https://github.com/javanthropus/archive-zip
+        #
+        # @api public
+        #
+        # @since 1.0.0
+        #
+        class Reader
+
+          include Enumerable
+
+          # The path to the zip archive that will be read.
+          #
+          # @return [String]
+          attr_reader :path
+
+          # The optional password to use when reading the zip archive.
+          #
+          # @return [String, nil]
+          attr_reader :password
+
+          #
+          # Initializes the zip archive reader.
+          #
+          # @param [String] path
+          #   The path to the zip archive file.
+          #
+          # @param [String, nil] password
+          #   Optional password to use when reading the zip archive.
+          #
+          # @yield [zip]
+          #   If a block is given, it will be yielded the new zip reader.
+          #
+          # @yieldparam [Reader] zip
+          #   The new zip reacher.
+          #
+          def initialize(path, password: nil)
+            @path     = File.expand_path(path)
+            @password = password
+
+            yield self if block_given?
+          end
+
+          #
+          # Alias to {#initialize new}.
+          #
+          # @param [String] path
+          #   The path to the zip archive file.
+          #
+          # @param [Hash{Symbol => Object}] kwargs
+          #   Additional keyword arguments for {#initialize new}.
+          #
+          # @option kwargs [String, nil] :password
+          #   Optional password to use when reading the zip archive.
+          #
+          # @yield [zip]
+          #   If a block is given, it will be yielded the new zip reader.
+          #
+          # @yieldparam [Reader] zip
+          #   The new zip reacher.
+          #
+          # @see #initialize
+          #
+          def self.open(path,**kwargs,&block)
+            new(path,**kwargs,&block)
+          end
+
+          #
+          # Lists the contents of the zip archive.
+          #
+          # @yield [entry]
+          #   If a block is given it will be passed each parsed entry in the
+          #   zip archive.
+          #
+          # @yieldparam [Entry] entry
+          #   An entry in the zip archive.
+          #
+          # @return [Enumerator, Statistics]
+          #   If no block is given an enumerator will be returned.
+          #   If a block was given, then a statistics object will be returned.
+          #
+          # @note
+          #   This method actually executes the `unzip -v -l ZIP` command
+          #   and parses it's output.
+          #
+          def each
+            return enum_for(__method__) unless block_given?
+
+            io = IO.popen(command_argv('-v','-l',@path))
+
+            # skip lines until the "---------  ---------- -----   ----" line
+            until io.eof?
+              break if io.readline.start_with?('-')
+            end
+
+            until io.eof?
+              line = io.readline(chomp: true)
+
+              unless line.start_with?('-')
+                yield parse_entry_line(line)
+              else
+                # reached the "---------                     -------" line
+                break
+              end
+            end
+
+            last_line = io.readline(chomp: true)
+            return parse_statistics_line(last_line)
+          end
+
+          alias list each
+          alias entries to_a
+
+          #
+          # Finds the entry with the given name.
+          #
+          # @param [String] name
+          #   The file name to search for.
+          #
+          # @return [Entry, nil]
+          #   The matching entry or `nil` if no entry could be found.
+          #
+          def [](name)
+            find { |entry| entry.name == name }
+          end
+
+          #
+          # Reads the contents of an entry from the zip 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.
+          #
+          # @note
+          #   This method actually executes the `unzip -p ZIP FILE` command
+          #   and reads it's output.
+          #
+          def read(name, length: nil)
+            io = IO.popen(command_argv('-p', @path, name))
+
+            if length then io.read(length)
+            else           io.read
+            end
+          end
+
+          private
+          
+          #
+          # Creates an `unzip` command with the additional arguments.
+          #
+          # @param [Array<String>] arguments
+          #   Additional arguments for the `unzip` command.
+          #
+          # @return [Array<String>]
+          #   The `unzip` command argv.
+          #
+          def command_argv(*arguments)
+            argv = ['unzip']
+
+            if @password
+              argv << '-P' << @password
+            end
+
+            argv.concat(arguments)
+          end
+
+          # Translates the Method column in `unzip -v -l` output to Symbols.
+          METHODS = {
+            'Stored' => :stored,
+            'Defl:N' => :deflate
+          }
+
+          #
+          # Parses a entry line from the output of `unzip -v -l ZIP`.
+          #
+          # @param [String] line
+          #   The line to parse.
+          #
+          # @return [Entry]
+          #   The parsed entry.
+          #
+          def parse_entry_line(line)
+            length, method, size, compression, date, time, crc32, name =
+              line.lstrip.split(/\s+/,8)
+
+            time_fmt = case date
+                       when /\A\d{2}-\d{2}-\d{4}\z/ then "%m-%d-%Y %H:%M"
+                       when /\A\d{4}-\d{2}-\d{2}\z/ then "%Y-%m-%d %H:%M"
+                       else
+                         raise(NotImplementedError,"unrecognized date format: #{date.inspect}")
+                       end
+
+            length      = length.to_i
+            method      = METHODS.fetch(method)
+            size        = size.to_i
+            compression = compression.chomp('%').to_i
+            time        = Time.strptime("#{date} #{time}",time_fmt)
+            date        = time.to_date
+
+            return Entry.new(self, length:      length,
+                                   method:      method,
+                                   size:        size,
+                                   compression: compression,
+                                   date:        date,
+                                   time:        time,
+                                   crc32:       crc32,
+                                   name:        name)
+          end
+
+          #
+          # Parses the last line from the output of `unzip -v -l ZIP`.
+          #
+          # @param [String] line
+          #   The line to parse.
+          #
+          # @return [Statistics]
+          #   The parsed statistics.
+          #
+          def parse_statistics_line(line)
+            length, size, compression, files, _ = line.lstrip.split(/\s+/,5)
+
+            return Statistics.new(
+              length:      length.to_i,
+              size:        size.to_i,
+              compression: compression.chomp('%').to_i,
+              files:       files.to_i
+            )
+          end
+
+        end
+      end
+    end
+  end
+end