minitar 1.0.2 → 1.1.0

data/Manifest.txt

@@ -1,22 +1,45 @@
-Code-of-Conduct.md
-Contributing.md
-History.md
-Licence.md
+CHANGELOG.md
+CODE_OF_CONDUCT.md
+CONTRIBUTING.md
+CONTRIBUTORS.md
+LICENCE.md
 Manifest.txt
-README.rdoc
+README.md
 Rakefile
+SECURITY.md
 docs/bsdl.txt
 docs/ruby.txt
 lib/minitar.rb
 lib/minitar/input.rb
 lib/minitar/output.rb
+lib/minitar/pax_header.rb
 lib/minitar/posix_header.rb
 lib/minitar/reader.rb
+lib/minitar/version.rb
 lib/minitar/writer.rb
+licenses/bsdl.txt
+licenses/dco.txt
+licenses/ruby.txt
+test/fixtures/issue_46.tar.gz
+test/fixtures/issue_62.tar.gz
+test/fixtures/tar_input.tgz
+test/fixtures/test_input_non_strict_octal.tgz
+test/fixtures/test_input_relative.tgz
+test/fixtures/test_input_space_octal.tgz
+test/fixtures/test_minitar.tar.gz
 test/minitest_helper.rb
-test/support/tar_test_helpers.rb
+test/support/minitar_test_helpers.rb
+test/support/minitar_test_helpers/fixtures.rb
+test/support/minitar_test_helpers/header.rb
+test/support/minitar_test_helpers/tarball.rb
+test/test_filename_boundary_conditions.rb
+test/test_gnu_tar_compatibility.rb
+test/test_integration_pack_unpack_cycle.rb
 test/test_issue_46.rb
+test/test_issue_62.rb
 test/test_minitar.rb
+test/test_pax_header.rb
+test/test_pax_support.rb
 test/test_tar_header.rb
 test/test_tar_input.rb
 test/test_tar_output.rb

data/README.md

@@ -0,0 +1,70 @@
+# minitar
+
+- code :: <https://github.com/halostatue/minitar>
+- issues :: <https://github.com/halostatue/minitar/issues>
+- changelog :: <https://github.com/halostatue/minitar/blob/main/CHANGELOG.md>
+
+## Description
+
+The minitar library is a pure-Ruby library that operates on POSIX tar(1) archive
+files.
+
+minitar (previously called Archive::Tar::Minitar) is based heavily on code
+originally written by Mauricio Julio Fernández Pradier for the rpa-base project.
+
+## Synopsis
+
+Using minitar is easy. The simplest case is:
+
+```ruby
+require 'minitar'
+
+# Packs everything that matches Find.find('tests').
+# test.tar will automatically be closed by Minitar.pack.
+Minitar.pack('tests', File.open('test.tar', 'wb'))
+
+# Unpacks 'test.tar' to 'x', creating 'x' if necessary.
+Minitar.unpack('test.tar', 'x')
+```
+
+A gzipped tar can be written with:
+
+```ruby
+  require 'zlib'
+  # test.tgz will be closed automatically.
+  Minitar.pack('tests', Zlib::GzipWriter.new(File.open('test.tgz', 'wb'))
+
+  # test.tgz will be closed automatically.
+  Minitar.unpack(Zlib::GzipReader.new(File.open('test.tgz', 'rb')), 'x')
+```
+
+As the case above shows, one need not write to a file. However, it will
+sometimes require that one dive a little deeper into the API, as in the case of
+StringIO objects. Note that I'm not providing a block with Minitar::Output, as
+Minitar::Output#close automatically closes both the Output object and the
+wrapped data stream object.
+
+```ruby
+begin
+  sgz = Zlib::GzipWriter.new(StringIO.new(String.new))
+  tar = Output.new(sgz)
+  Find.find('tests') do |entry|
+    Minitar.pack_file(entry, tar)
+  end
+ensure
+  # Closes both tar and sgz.
+  tar.close
+end
+```
+
+## Minitar and Security
+
+See [SECURITY](./SECURITY.md)
+
+## minitar Semantic Versioning
+
+The minitar library uses a [Semantic Versioning][semver] scheme with one change:
+
+- When PATCH is zero (`0`), it will be omitted from version references.
+
+[semver]: http://semver.org/

data/Rakefile

@@ -1,42 +1,97 @@
-# -*- ruby encoding: utf-8 -*-
+# frozen_string_literal: true
 
 require "rubygems"
 require "hoe"
 require "rake/clean"
+require "rdoc/task"
+require "minitest"
+require "minitest/test_task"
 
-$LOAD_PATH.unshift("support")
-
-Hoe.plugin :doofus
-Hoe.plugin :gemspec2
-Hoe.plugin :git2
-Hoe.plugin :minitest
+Hoe.plugin :halostatue
 Hoe.plugin :rubygems
-Hoe.plugin :cov
 
-Hoe.spec "minitar" do
+Hoe.plugins.delete :debug
+Hoe.plugins.delete :newb
+Hoe.plugins.delete :publish
+Hoe.plugins.delete :signing
+Hoe.plugins.delete :test
+
+hoe = Hoe.spec "minitar" do
   developer("Austin Ziegler", "halostatue@gmail.com")
 
-  self.history_file = "History.md"
-  self.readme_file = "README.rdoc"
+  self.trusted_release = ENV["rubygems_release_gem"] == "true"
 
   require_ruby_version ">= 3.1"
 
   self.licenses = ["Ruby", "BSD-2-Clause"]
 
-  spec_extras[:metadata] = ->(val) { val["rubygems_mfa_required"] = "true" }
+  spec_extras[:metadata] = ->(val) {
+    val["rubygems_mfa_required"] = "true"
+  }
 
-  extra_dev_deps << ["base64", "~> 0.2"]
   extra_dev_deps << ["hoe", "~> 4.0"]
-  extra_dev_deps << ["hoe-doofus", "~> 1.0"]
-  extra_dev_deps << ["hoe-gemspec2", "~> 1.1"]
-  extra_dev_deps << ["hoe-git2", "~> 1.7"]
-  extra_dev_deps << ["hoe-rubygems", "~> 1.0"]
+  extra_dev_deps << ["hoe-halostatue", "~> 2.1", ">= 2.1.1"]
+  extra_dev_deps << ["irb", "~> 1.0"]
   extra_dev_deps << ["minitest", "~> 5.16"]
   extra_dev_deps << ["minitest-autotest", "~> 1.0"]
-  extra_dev_deps << ["minitest-focus", "~> 1.0"]
+  extra_dev_deps << ["minitest-focus", "~> 1.1"]
   extra_dev_deps << ["rake", ">= 10.0", "< 14"]
-  extra_dev_deps << ["rdoc", ">= 0.0"]
+  extra_dev_deps << ["rdoc", ">= 0.0", "< 7"]
+  extra_dev_deps << ["simplecov", "~> 0.22"]
+  extra_dev_deps << ["simplecov-lcov", "~> 0.8"]
   extra_dev_deps << ["standard", "~> 1.0"]
   extra_dev_deps << ["standard-minitest", "~> 1.0"]
   extra_dev_deps << ["standard-thread_safety", "~> 1.0"]
 end
+
+Minitest::TestTask.create :test
+Minitest::TestTask.create :coverage do |t|
+  formatters = <<-RUBY.split($/).join(" ")
+    SimpleCov::Formatter::MultiFormatter.new([
+      SimpleCov::Formatter::HTMLFormatter,
+      SimpleCov::Formatter::LcovFormatter,
+      SimpleCov::Formatter::SimpleFormatter
+    ])
+  RUBY
+  t.test_prelude = <<-RUBY.split($/).join("; ")
+  require "simplecov"
+  require "simplecov-lcov"
+
+  SimpleCov::Formatter::LcovFormatter.config do |config|
+    config.report_with_single_file = true
+    config.lcov_file_name = "lcov.info"
+  end
+
+  SimpleCov.start "test_frameworks" do
+    enable_coverage :branch
+    primary_coverage :branch
+    formatter #{formatters}
+  end
+  RUBY
+end
+
+task default: :test
+
+task :version do
+  require "color/version"
+  puts Color::VERSION
+end
+
+RDoc::Task.new do
+  _1.title = "minitar"
+  _1.main = "lib/minitar.rb"
+  _1.rdoc_dir = "doc"
+  _1.rdoc_files = hoe.spec.require_paths - ["Manifest.txt"] + hoe.spec.extra_rdoc_files
+  _1.markup = "markdown"
+end
+task docs: :rerdoc
+
+task :console do
+  arguments = %w[irb]
+  arguments.push(*hoe.spec.require_paths.map { |dir| "-I#{dir}" })
+  arguments.push("-r#{hoe.spec.name.gsub("-", File::SEPARATOR)}")
+  unless system(*arguments)
+    error "Command failed: #{show_command}"
+    abort
+  end
+end

data/SECURITY.md

@@ -0,0 +1,64 @@
+# Minitar Security Policy
+
+Minitar aims to be secure by default for the data _inside_ of a tar file.
+
+## LLM-Generated Security Report Policy
+
+Absolutely no security reports will be accepted that have been generated by LLM
+agents.
+
+## Supported Versions
+
+Security reports are accepted only for the most recent major release. As of
+December 2024, that is the 1.0 release series. Older releases are no longer
+supported.
+
+## Reporting a Vulnerability
+
+By preference, use the [Tidelift security contact][tidelift]. Tidelift will
+coordinate the fix and disclosure.
+
+Alternatively, Send an email to [minitar@halostatue.ca][email] with the text
+`Minitar` in the subject. Emails sent to this address should be encrypted using
+[age][age] with the following public key:
+
+```
+age1fc6ngxmn02m62fej5cl30lrvwmxn4k3q2atqu53aatekmnqfwumqj4g93w
+```
+
+## Exclusions
+
+There are several classes of potential security issues that will not be accepted
+for Minitar There are several classes of "security" issues which will not be
+accepted for Minitar, because any issues arising from these are a matter of the
+library being used incorrectly.
+
+- [CWE-073](https://cwe.mitre.org/data/definitions/73.html)
+- [CWE-078](https://cwe.mitre.org/data/definitions/78.html)
+- [CWE-088](https://cwe.mitre.org/data/definitions/88.html)
+
+Minitar does _not_ perform validation or sanitization of path names provided to
+the convenience classes `Minitar::Output` and `Minitar::Input`, which use
+`Kernel.open` for their underlying implementations when not given an IO-like
+object.
+
+Improper use of these convenience classes with arbitrary input filenames may
+leave your your software to the same class of vulnerability as reported for
+Net::FTP ([CVE-2017-17405][CVE-2017-17405]). If the input filename argument
+starts with the pipe character (`|`), the command following the pipe character
+is executed.
+
+Additionally, the use of the `open-uri` library (which extends `Kernel.open`
+with transparent implementations of `Net::HTTP`, `Net::HTTPS`, and `Net::FTP`),
+there are other possible vulnerabilities when accepting arbitrary input, as
+[detailed][openuri] by Egor Homakov.
+
+These security vulnerabilities may be avoided, even with the `Minitar::Output`
+and `Minitar::Input` convenience classes, by providing IO-like objects instead
+of pathname-like objects as the source or destination of these classes.
+
+[tidelift]: https://tidelift.com/security
+[email]: mailto:minitar@halostatue.ca
+[age]: https://github.com/FiloSottile/age
+[CVE-2017-17405]: https://nvd.nist.gov/vuln/detail/CVE-2017-17405
+[openuri]: https://sakurity.com/blog/2015/02/28/openuri.html

data/docs/ruby.txt

@@ -44,13 +44,13 @@ You can redistribute it and/or modify it under either the terms of the
      For the list of those files and their copying conditions, see the
      file LEGAL.
 
-  5. The scripts and library files supplied as input to or produced as 
+  5. The scripts and library files supplied as input to or produced as
      output from the software do not automatically fall under the
-     copyright of the software, but belong to whomever generated them, 
+     copyright of the software, but belong to whomever generated them,
      and may be sold commercially, and may be aggregated with this
      software.
 
   6. THIS SOFTWARE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR
      IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED
      WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
-     PURPOSE.
+     PURPOSE.

data/lib/minitar/input.rb

@@ -1,26 +1,42 @@
+# frozen_string_literal: true
+
 require "minitar/reader"
 
 class Minitar
-  # Wraps a Minitar::Reader with convenience methods and wrapped
-  # stream management; Input only works with data streams that can be rewound.
+  # Wraps a Minitar::Reader with convenience methods and wrapped stream management; Input
+  # only works with data streams that can be rewound.
+  #
+  # === Security Notice
+  #
+  # Constructing a Minitar::Input will use Kernel.open if the provided input is not
+  # a readable stream object. Using an untrusted value for input may allow a malicious
+  # user to execute arbitrary system commands. It is the caller's responsibility to ensure
+  # that the input value is safe.
+  #
+  # * {CWE-073}[https://cwe.mitre.org/data/definitions/73.html]
+  # * {CWE-078}[https://cwe.mitre.org/data/definitions/78.html]
+  # * {CWE-088}[https://cwe.mitre.org/data/definitions/88.html]
+  #
+  # This notice applies to Minitar::Input.open, Minitar::Input.each_entry, and
+  # Minitar::Input.new.
   class Input
     include Enumerable
 
-    # With no associated block, +Input.open+ is a synonym for +Input.new+. If
-    # the optional code block is given, it will be given the new Input as an
-    # argument and the Input object will automatically be closed when the block
-    # terminates (this also closes the wrapped stream object). In this
-    # instance, +Input.open+ returns the value of the block.
+    # With no associated block, +Input.open+ is a synonym for +Input.new+.
+    #
+    # If a block is given, the new Input will be yielded to the block as an argument and
+    # the Input object will automatically be closed when the block terminates (this also
+    # closes the wrapped stream object). The return value will be the value of the block.
     #
-    # call-seq:
+    # :call-seq:
     #    Minitar::Input.open(io) -> input
     #    Minitar::Input.open(io) { |input| block } -> obj
     def self.open(input)
       stream = new(input)
 
       if block_given?
-        # This exception context must remain, otherwise the stream closes on
-        # open even if a block is not given.
+        # This exception context must remain, otherwise the stream closes on open even if
+        # a block is not given.
         begin
           yield stream
         ensure
@@ -31,8 +47,7 @@ class Minitar
       end
     end
 
-    # Iterates over each entry in the provided input. This wraps the common
-    # pattern of:
+    # Iterates over each entry in the provided input. This wraps the common pattern of:
     #
     #     Minitar::Input.open(io) do |i|
     #       inp.each do |entry|
@@ -40,10 +55,9 @@ class Minitar
     #       end
     #     end
     #
-    # If a block is not provided, an enumerator will be created with the same
-    # behaviour.
+    # If a block is not provided, an enumerator will be created with the same behaviour.
     #
-    # call-seq:
+    # :call-seq:
     #    Minitar::Input.each_entry(io) -> enumerator
     #    Minitar::Input.each_entry(io) { |entry| block } -> obj
     def self.each_entry(input)
@@ -56,33 +70,31 @@ class Minitar
       end
     end
 
-    # Creates a new Input object. If +input+ is a stream object that responds
-    # to #read, then it will simply be wrapped. Otherwise, one will be created
-    # and opened using Kernel#open. When Input#close is called, the stream
-    # object wrapped will be closed.
+    # Creates a new Input object. If +input+ is a stream object that responds to #read,
+    # then it will simply be wrapped. Otherwise, one will be created and opened using
+    # Kernel#open. When Input#close is called, the stream object wrapped will be closed.
     #
-    # An exception will be raised if the stream that is wrapped does not
-    # support rewinding.
+    # An exception will be raised if the stream that is wrapped does not support
+    # rewinding.
     #
-    # call-seq:
+    # :call-seq:
     #    Minitar::Input.new(io) -> input
     #    Minitar::Input.new(path) -> input
     def initialize(input)
-      @io = if input.respond_to?(:read)
-        input
-      else
-        ::Kernel.open(input, "rb")
-      end
+      @io =
+        if input.respond_to?(:read)
+          input
+        else
+          ::Kernel.open(input, "rb")
+        end
 
-      unless Minitar.seekable?(@io, :rewind)
-        raise Minitar::NonSeekableStream
-      end
+      raise Minitar::NonSeekableStream unless Minitar.seekable?(@io, :rewind)
 
       @tar = Reader.new(@io)
     end
 
-    # When provided a block, iterates through each entry in the archive. When
-    # finished, rewinds to the beginning of the stream.
+    # When provided a block, iterates through each entry in the archive. When finished,
+    # rewinds to the beginning of the stream.
     #
     # If not provided a block, creates an enumerator with the same semantics.
     def each_entry
@@ -96,39 +108,38 @@ class Minitar
     end
     alias_method :each, :each_entry
 
-    # Extracts the current +entry+ to +destdir+. If a block is provided, it
-    # yields an +action+ Symbol, the full name of the file being extracted
-    # (+name+), and a Hash of statistical information (+stats+).
+    # Extracts the current +entry+ to +destdir+. If a block is provided, it yields an
+    # +action+ Symbol, the full name of the file being extracted (+name+), and a Hash of
+    # statistical information (+stats+).
     #
     # The +action+ will be one of:
+    #
     # <tt>:dir</tt>::           The +entry+ is a directory.
-    # <tt>:file_start</tt>::    The +entry+ is a file; the extract of the
-    #                           file is just beginning.
-    # <tt>:file_progress</tt>:: Yielded every 4096 bytes during the extract
-    #                           of the +entry+.
+    # <tt>:file_start</tt>::    The +entry+ is a file; the extract of the file is just
+    #                           beginning.
+    # <tt>:file_progress</tt>:: Yielded every 4096 bytes during the extract of the
+    #                           +entry+.
     # <tt>:file_done</tt>::     Yielded when the +entry+ is completed.
     #
     # The +stats+ hash contains the following keys:
-    # <tt>:current</tt>:: The current total number of bytes read in the
-    #                     +entry+.
-    # <tt>:currinc</tt>:: The current number of bytes read in this read
-    #                     cycle.
-    # <tt>:entry</tt>::   The entry being extracted; this is a
-    #                     Reader::EntryStream, with all methods thereof.
-    def extract_entry(destdir, entry, options = {}, &) # :yields action, name, stats:
+    #
+    # <tt>:current</tt>:: The current total number of bytes read in the +entry+.
+    # <tt>:currinc</tt>:: The current number of bytes read in this read cycle.
+    # <tt>:entry</tt>::   The entry being extracted; this is a Reader::EntryStream, with
+    #                     all methods thereof.
+    def extract_entry(destdir, entry, options = {}, &) # :yields: action, name, stats
       stats = {
         current: 0,
         currinc: 0,
         entry: entry
       }
 
-      # extract_entry is not vulnerable to prefix '/' vulnerabilities, but it
-      # is vulnerable to relative path directories. This code will break this
-      # vulnerability. For this version, we are breaking relative paths HARD by
-      # throwing an exception.
+      # extract_entry is not vulnerable to prefix '/' vulnerabilities, but it is
+      # vulnerable to relative path directories. This code will break this vulnerability.
+      # For this version, we are breaking relative paths HARD by throwing an exception.
       #
-      # Future versions may permit relative paths as long as the file does not
-      # leave +destdir+.
+      # Future versions may permit relative paths as long as the file does not leave
+      # +destdir+.
       #
       # However, squeeze consecutive '/' characters together.
       full_name = entry.full_name.squeeze("/")
@@ -145,9 +156,7 @@ class Minitar
     end
 
     # Returns false if the wrapped data stream is open.
-    def closed?
-      @io.closed?
-    end
+    def closed? = @io.closed?
 
     # Returns the Reader object for direct access.
     attr_reader :tar
@@ -203,7 +212,11 @@ class Minitar
       File.unlink(destfile) if File.symlink?(destfile)
 
       # Errno::ENOENT
-      FileUtils.chmod(0o600, destfile) rescue nil # standard:disable Style/RescueModifier
+      begin
+        FileUtils.chmod(0o600, destfile)
+      rescue
+        nil
+      end
 
       yield :file_start, full_name, stats if block_given?
 

data/lib/minitar/output.rb

@@ -1,18 +1,33 @@
+# frozen_string_literal: true
+
 require "minitar/writer"
 
 class Minitar
-  # Wraps a Minitar::Writer with convenience methods and wrapped
-  # stream management. If the stream provided to Output does not support random
-  # access, only Writer#add_file_simple and Writer#mkdir are guaranteed to
-  # work.
+  # Wraps a Minitar::Writer with convenience methods and wrapped stream management. If the
+  # stream provided to Output does not support random access, only Writer#add_file_simple
+  # and Writer#mkdir are guaranteed to work.
+  #
+  # === Security Notice
+  #
+  # Constructing a Minitar::Output will use Kernel.open if the provided output is not
+  # a readable stream object. Using an untrusted value for output may allow a malicious
+  # user to execute arbitrary system commands. It is the caller's responsibility to ensure
+  # that the output value is safe.
+  #
+  # * {CWE-073}[https://cwe.mitre.org/data/definitions/73.html]
+  # * {CWE-078}[https://cwe.mitre.org/data/definitions/78.html]
+  # * {CWE-088}[https://cwe.mitre.org/data/definitions/88.html]
+  #
+  # This notice applies to Minitar::Output.open, Minitar::Output.tar, and
+  # Minitar::Output.new.
   class Output
-    # With no associated block, +Output.open+ is a synonym for +Output.new+. If
-    # the optional code block is given, it will be given the new Output as an
-    # argument and the Output object will automatically be closed when the
-    # block terminates (this also closes the wrapped stream object). In this
-    # instance, +Output.open+ returns the value of the block.
+    # With no associated block, +Output.open+ is a synonym for +Output.new+.
+    #
+    # If a block is given, the new Output will be yielded to the block as an argument and
+    # the Output object will automatically be closed when the block terminates (this also
+    # closes the wrapped stream object). The return value will be the value of the block.
     #
-    # call-seq:
+    # :call-seq:
     #    Minitar::Output.open(io) -> output
     #    Minitar::Output.open(io) { |output| block } -> obj
     def self.open(output)
@@ -28,11 +43,11 @@ class Minitar
       end
     end
 
-    # Output.tar is a wrapper for Output.open that yields the owned tar object
-    # instead of the Output object. If a block is not provided, an enumerator
-    # will be created with the same behaviour.
+    # Output.tar is a wrapper for Output.open that yields the owned tar object instead of
+    # the Output object. If a block is not provided, an enumerator will be created with
+    # the same behaviour.
     #
-    # call-seq:
+    # :call-seq:
     #    Minitar::Output.tar(io) -> enumerator
     #    Minitar::Output.tar(io) { |tar| block } -> obj
     def self.tar(output)
@@ -43,12 +58,11 @@ class Minitar
       end
     end
 
-    # Creates a new Output object. If +output+ is a stream object that responds
-    # to #write, then it will simply be wrapped. Otherwise, one will be created
-    # and opened using Kernel#open. When Output#close is called, the stream
-    # object wrapped will be closed.
+    # Creates a new Output object. If +output+ is a stream object that responds to #write,
+    # then it will simply be wrapped. Otherwise, one will be created and opened using
+    # Kernel#open. When Output#close is called, the stream object wrapped will be closed.
     #
-    # call-seq:
+    # :call-seq:
     #    Minitar::Output.new(io) -> output
     #    Minitar::Output.new(path) -> output
     def initialize(output)
@@ -64,9 +78,7 @@ class Minitar
     attr_reader :tar
 
     # Returns false if the wrapped data stream is open.
-    def closed?
-      @io.closed?
-    end
+    def closed? = @io.closed?
 
     # Closes the Writer object and the wrapped data stream.
     def close