safe_zip 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 7bec069256c55d64e3d1a1e531a8155d3265720004b411e4eff72d631918caa3
+  data.tar.gz: a4cf744f09bb187b005db88b74b8a48e741b3ae37ef91984fbd5e5b26b5bfbdf
+SHA512:
+  metadata.gz: ad1abccda8aebebdad8a668ab03350415e0ccd56fc24c05016328f829d234c1bb1ca37557640f3031d11f948a6e8ec065d02496a6066949776965ce6f4a528bc
+  data.tar.gz: fc0146896ee13019ffa295672b9500caf925f6dc69ab6cda521fb5d680fff157089a10bb15355924933d7a5cceaf61fe0b8bf3af1fe7cc9729d2f59e9a695c5d

data/lib/safe_zip/entry.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+module SafeZip
+  class Entry
+    attr_reader :zip_archive, :zip_entry
+    attr_reader :path, :params
+
+    def initialize(zip_archive, zip_entry, params)
+      @zip_archive = zip_archive
+      @zip_entry = zip_entry
+      @params = params
+      @path = ::File.expand_path(zip_entry.name, params.extract_path)
+    end
+
+    def path_dir
+      ::File.dirname(path)
+    end
+
+    def real_path_dir
+      ::File.realpath(path_dir)
+    end
+
+    def exist?
+      ::File.exist?(path)
+    end
+
+    def extract
+      # do not extract if file is not part of target directory or target file
+      return false unless matching_target_directory || matching_target_file
+
+      # do not overwrite existing file
+      raise SafeZip::Extract::AlreadyExistsError, "File already exists #{zip_entry.name}" if exist?
+
+      create_path_dir
+
+      if zip_entry.file?
+        extract_file
+      elsif zip_entry.directory?
+        extract_dir
+      elsif zip_entry.symlink?
+        extract_symlink
+      else
+        raise SafeZip::Extract::UnsupportedEntryError, "File #{zip_entry.name} cannot be extracted"
+      end
+    rescue SafeZip::Extract::Error
+      raise
+    rescue Zip::EntrySizeError => e
+      raise SafeZip::Extract::EntrySizeError, e.message
+    rescue StandardError => e
+      raise SafeZip::Extract::ExtractError, e.message
+    end
+
+    private
+
+    def extract_file
+      zip_archive.extract(zip_entry, path)
+    end
+
+    def extract_dir
+      FileUtils.mkdir(path)
+    end
+
+    def extract_symlink
+      source_path = read_symlink
+      real_source_path = expand_symlink(source_path)
+
+      # ensure that source path of symlink is within target directories
+      unless real_source_path.start_with?(matching_target_directory)
+        raise SafeZip::Extract::PermissionDeniedError, "Symlink cannot be created targeting: #{source_path}"
+      end
+
+      ::File.symlink(source_path, path)
+    end
+
+    def create_path_dir
+      # Create all directories, but ignore permissions
+      FileUtils.mkdir_p(path_dir)
+
+      # disallow to make path dirs to point to another directories
+      unless path_dir == real_path_dir
+        raise SafeZip::Extract::PermissionDeniedError, "Directory of #{zip_entry.name} points to another directory"
+      end
+    end
+
+    def matching_target_directory
+      params.matching_target_directory(path)
+    end
+
+    def matching_target_file
+      params.matching_target_file(path)
+    end
+
+    def read_symlink
+      zip_archive.read(zip_entry)
+    end
+
+    def expand_symlink(source_path)
+      ::File.realpath(source_path, path_dir)
+    rescue StandardError
+      raise SafeZip::Extract::SymlinkSourceDoesNotExistError, "Symlink source #{source_path} does not exist"
+    end
+  end
+end

data/lib/safe_zip/extract.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+module SafeZip
+  # SafeZip::Extract provides a safe interface
+  # to extract specific directories or files within a `zip` archive.
+  #
+  # @example Extract directories to destination
+  #   SafeZip::Extract.new(archive_file).extract(directories: ['app/', 'test/'], to: destination_path)
+  # @example Extract files to destination
+  #   SafeZip::Extract.new(archive_file).extract(files: ['index.html', 'app/index.js'], to: destination_path)
+  class Extract
+    Error = Class.new(StandardError)
+    PermissionDeniedError = Class.new(Error)
+    SymlinkSourceDoesNotExistError = Class.new(Error)
+    UnsupportedEntryError = Class.new(Error)
+    EntrySizeError = Class.new(Error)
+    AlreadyExistsError = Class.new(Error)
+    NoMatchingError = Class.new(Error)
+    ExtractError = Class.new(Error)
+
+    attr_reader :archive_path
+
+    def initialize(archive_file)
+      @archive_path = archive_file
+    end
+
+    # extract given files or directories from the archive into the destination path
+    #
+    # @param [Hash] opts the options for extraction.
+    # @option opts [Array<String] :files list of files to be extracted
+    # @option opts [Array<String] :directories list of directories to be extracted
+    # @option opts [String] :to destination path
+    #
+    # @raise [PermissionDeniedError]
+    # @raise [SymlinkSourceDoesNotExistError]
+    # @raise [UnsupportedEntryError]
+    # @raise [EntrySizeError]
+    # @raise [AlreadyExistsError]
+    # @raise [NoMatchingError]
+    # @raise [ExtractError]
+    def extract(opts = {})
+      params = SafeZip::ExtractParams.new(**opts)
+
+      extract_with_ruby_zip(params)
+    end
+
+    private
+
+    def extract_with_ruby_zip(params)
+      ::Zip::File.open(archive_path) do |zip_archive| # rubocop:disable Performance/Rubyzip
+        # Extract all files in the following order:
+        # 1. Directories first,
+        # 2. Files next,
+        # 3. Symlinks last (or anything else)
+        extracted = extract_all_entries(zip_archive, params,
+          zip_archive.lazy.select(&:directory?))
+
+        extracted += extract_all_entries(zip_archive, params,
+          zip_archive.lazy.select(&:file?))
+
+        extracted += extract_all_entries(zip_archive, params,
+          zip_archive.lazy.reject(&:directory?).reject(&:file?))
+
+        raise NoMatchingError, 'No entries extracted' unless extracted > 0
+      end
+    end
+
+    def extract_all_entries(zip_archive, params, entries)
+      entries.count do |zip_entry|
+        SafeZip::Entry.new(zip_archive, zip_entry, params)
+          .extract
+      end
+    end
+  end
+end

data/lib/safe_zip/extract_params.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module SafeZip
+  class ExtractParams
+    attr_reader :directories, :files, :extract_path
+
+    def initialize(to:, directories: [], files: [])
+      @directories = directories
+      @files = files
+      @extract_path = ::File.realpath(to)
+      validate!
+    end
+
+    def matching_target_directory(path)
+      target_directories.find do |directory|
+        path.start_with?(directory)
+      end
+    end
+
+    def target_directories
+      @target_directories ||= directories.map do |directory|
+        ::File.join(::File.expand_path(directory, extract_path), '')
+      end
+    end
+
+    def directories_wildcard
+      @directories_wildcard ||= directories.map do |directory|
+        ::File.join(directory, '*')
+      end
+    end
+
+    def matching_target_file(path)
+      target_files.include?(path)
+    end
+
+    private
+
+    def target_files
+      @target_files ||= files.map do |file|
+        ::File.join(extract_path, file)
+      end
+    end
+
+    def validate!
+      raise ArgumentError, 'Either directories or files are required' if directories.empty? && files.empty?
+    end
+  end
+end

data/lib/safe_zip/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module SafeZip
+  VERSION = "0.1.0"
+end

data/lib/safe_zip.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require "zip"
+
+require_relative "safe_zip/version"
+require_relative "safe_zip/extract_params"
+require_relative "safe_zip/entry"
+require_relative "safe_zip/extract"

metadata

@@ -0,0 +1,103 @@
+--- !ruby/object:Gem::Specification
+name: safe_zip
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- GitLab Engineers
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rubyzip
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.4'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.4'
+- !ruby/object:Gem::Dependency
+  name: gitlab-styles
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '14.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '14.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: rspec-parameterized
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+description: Provides a safe interface to extract specific directories or files within
+  a zip archive, preventing path traversal attacks.
+email:
+- engineering@gitlab.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- lib/safe_zip.rb
+- lib/safe_zip/entry.rb
+- lib/safe_zip/extract.rb
+- lib/safe_zip/extract_params.rb
+- lib/safe_zip/version.rb
+homepage: https://gitlab.com/gitlab-org/gitlab/-/tree/master/gems/safe_zip
+licenses:
+- MIT
+metadata:
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.15
+specification_version: 4
+summary: Safe zip archive extraction
+test_files: []