puppetlabs/puppet · error · Puppet::ModuleTool::Errors::InvalidPathInPackageError

Attempt to install file with an invalid path into %{path} un

Error message

Attempt to install file with an invalid path into %{path} under %{dir}

What it means

While unpacking a module tarball, the Mini backend validates every entry path before extraction. validate_entry first rejects entries whose path is absolute (Pathname#absolute? — leading '/' or a Windows drive root) with InvalidPathInPackageError, because joining an absolute path with the destination would write outside the module directory. This is a security control against hostile or malformed packages, not a Puppet bug.

Source

Thrown at lib/puppet/module_tool/tar/mini.rb:109

  # This check was mainly added to ignore 'x' and 'g' flags from the PAX
  # standard but will also ignore any other non-standard tar flags.
  # tar format info: https://pic.dhe.ibm.com/infocenter/zos/v1r13/index.jsp?topic=%2Fcom.ibm.zos.r13.bpxa500%2Ftaf.htm
  # pax format info: https://pic.dhe.ibm.com/infocenter/zos/v1r13/index.jsp?topic=%2Fcom.ibm.zos.r13.bpxa500%2Fpxarchfm.htm
  def find_valid_files(tarfile)
    Archive::Tar::Minitar.open(tarfile).collect do |entry|
      flag = entry.typeflag
      if flag.nil? || flag =~ /[[:digit:]]/ && (0..7).cover?(flag.to_i)
        entry.full_name
      else
        Puppet.debug "Invalid tar flag '#{flag}' will not be extracted: #{entry.name}"
        next
      end
    end
  end

  def validate_entry(destdir, path)
    if Pathname.new(path).absolute?
      raise Puppet::ModuleTool::Errors::InvalidPathInPackageError, :entry_path => path, :directory => destdir
    end

    path = Pathname.new(File.join(destdir, path)).cleanpath.to_path

    if path !~ /\A#{Regexp.escape destdir}/
      raise Puppet::ModuleTool::Errors::InvalidPathInPackageError, :entry_path => path, :directory => destdir
    end
  end
end

View on GitHub (pinned to e227c27540)

Solutions

1. Rebuild the package with relative paths from inside the module root (cd mymod && tar czf ../author-mymod-1.0.0.tar.gz metadata.json manifests lib), or better, use 'puppet module build'.
2. Inspect the archive first: tar tzf pkg.tar.gz — any leading '/' or drive letter is a red flag.
3. If the module came unmodified from a third party, treat it as hostile and report it; do not force extraction.
4. Keep puppet-agent current so the hardened validators (absolute paths, traversal, symlinks) all run.

Example fix

# before — absolute entry names
$ tar czf mymod.tar.gz /home/me/src/mymod/metadata.json /home/me/src/mymod/manifests

# after — relative entries from the module root
$ cd /home/me/src/mymod && tar czf /tmp/author-mymod-1.0.0.tar.gz metadata.json manifests lib

require 'minitar'
require 'pathname'
# reject packages whose entries are absolute before attempting install
def safe_package?(tarball)
  Minitar::Input.open(File.open(tarball, 'rb')) do |inp|
    inp.each { |entry| return false if Pathname.new(entry.name).absolute? }
  end
  true
end

begin
  Puppet::ModuleTool::Tar.instance.unpack(pkg, target_dir, module_name)
rescue Puppet::ModuleTool::Errors::InvalidPathInPackageError => e
  # entry_path/directory in the message identify the offender — quarantine the package
  quarantine(pkg)
end

When it happens

Trigger: 'puppet module install' of a tarball containing at least one entry with an absolute name — typically packages created with 'tar czf mod.tar.gz /abs/path/to/files', or malicious archives attempting to overwrite system files.

Common situations: Hand-packaged modules built with wrong tar flags from outside the module root; CI pipelines archiving absolute paths; hostile third-party modules; archives converted from Windows zips with drive-letter paths.

Related errors

• No suitable tar implementation found
• invalid key
• invalid key
• invalid key
• Could not extract contents of module archive: %{message}

AI-assisted analysis of puppetlabs/puppet@e227c27540 (2026-08-21). Data as JSON: /api/errors/c14d906398ee3399. Report an issue: GitHub.