Reject archive members that escape the extraction directory

[jaraco]

Summary

setuptools.archive_util guarded against traversal with:

if name.startswith('/') or '..' in name.split('/'):
    continue
target = os.path.join(extract_dir, *name.split('/'))

Both the tar and zip formats specify / as the only path separator, so splitting on / alone is the natural reading — but a backslash is then carried into a single path component and handed to os.path.join, where Windows treats it as a separator after all:

member name	old guard blocked?	resolved destination
..\escaped.txt	no	C:\escaped.txt
safe\..\escaped.txt	no	C:\dest\escaped.txt
C:evil.txt	no	C:\evil.txt
\\server\share\x	no	\\server\share\x

The drive-qualified and UNC cases are not traversal at all — os.path.join discards extract_dir outright, giving a fully attacker-chosen destination.

This affects the zip driver as well as the tar driver: _unpack_zipfile_obj carries a byte-identical guard. A zipfile-built PoC hides this, because ZipInfo.__init__ rewrites os.sep to / when os.sep != "/", so an archive built on Windows has its backslashes normalized away; one built on Linux (or written directly) preserves them.

Ref GHSA-grgh-hr87-3jpw, reported by @Faze-up.

Impact

Low, hence a public PR rather than a private fix.

The tar driver has had no in-tree caller since easy_install and package_index were removed — install_egg_info passes a locally built .egg-info directory, which dispatches to unpack_directory. So the reported vector is third-party callers of the public API only.

The zip driver is still reachable in-tree, via installer._fetch_build_egg_no_warn → Wheel.install_as_egg → _unpack_zipfile_obj, on the deprecated setup_requires path. Even there the escalation is slight: a wheel unpacked by that path is about to be imported anyway.

Approach

Both drivers now share one _resolve_dest(), so the two copies of the guard cannot drift apart again. It rejects names containing a backslash, .. components, a leading /, or a drive/UNC prefix, and then — belt and braces — confirms the resolved destination really does fall under the resolved extraction directory.

Two details worth flagging for review:

• The containment check is applied to the preliminary destination, before progress_filter. The callback is documented as free to rewrite the destination, so asserting on the post-filter path would break filters that legitimately relocate files.
• Zip directory members keep their trailing separator. ensure_directory only creates the parent of its argument, so dropping it would leave empty directories uncreated — there is now a regression test pinning that.

Tests

Traversal cases are parametrized over both drivers and asserted through unpack_archive, so they are meaningful on Linux CI rather than Windows-only: on POSIX the old code created a file literally named ..\escaped.txt inside the target, so "the target contains only the control member" fails before the fix on every platform. Archive members are written with the name assigned after ZipInfo construction, so the backslash cases survive being built on Windows too.

There is also a symlink case covering the containment check specifically: a member name that is harmless in isolation still must not escape through a symlink already present in the extraction directory.

🤖 Generated with Claude Code

[mergify]

Tick the box to add this pull request to the merge queue (same as @mergifyio queue).

• Queue this pull request

[jaraco]

Switched _resolve_dest from returning None to raising a new UnsafeMember, per review. Rationale, since it changes public behavior:

Skipping made a malicious or malformed archive indistinguishable from a clean one — the caller got a quietly incomplete extraction with no signal that anything was dropped. For the one remaining in-tree caller that is an unpacked wheel, i.e. a corrupt install that is then imported. The stdlib made the same call in PEP 706: data_filter raises OutsideDestinationError rather than skipping, leaving "skip it" to callers who write their own filter.

UnsafeMember is deliberately not a subclass of UnrecognizedFormat. unpack_archive catches that one to fall through to the next driver, so inheriting from it would have converted an unsafe zip into an attempt to parse the same file as a tar, and ultimately into a misleading "Not a recognized archive type".

Two consequences worth a look before merge:

• This is a breaking change, so there is now a removal fragment alongside the bugfix one. Previously an archive containing a .. or absolute member extracted everything else and returned normally; it now aborts.
• The blast radius is wider than the traversal cases. Some non-conforming Windows archivers write dir\file.txt as a member name. Under the old code that extracted as a literal backslash-named file on POSIX, and as dir/file.txt on Windows — i.e. it "worked" there. Those archives now raise. I think that is correct, since we cannot distinguish a buggy archiver from an attacker by the name alone, but it is a real behavior change for benign inputs and worth your call.

Also added a positive test that ordinary members — nested and ./-prefixed — still extract, so the guard is pinned against over-rejection in both directions.

[jaraco]

Correcting my previous comment: the removal fragment is gone, replaced by a feature one. Silently skipping members that escape the extraction directory was never intended behavior, so nothing supported is being removed.

Backslash-separated member names are likewise staying rejected on every platform, with no removal marker, on the reasoning that no good-faith use case could have depended on them:

• Both formats specify / as the only separator (ZIP APPNOTE 4.4.17.1, POSIX ustar), so such a name is malformed by specification rather than an alternative convention.
• The old handling was already inconsistent across platforms — the same archive yielded a nested tree on Windows and a single literal backslash-named file on POSIX — so no portable code could have relied on it.
• The only in-tree consumer is unpacked wheels, and zipfile rewrites os.sep to / at write time, so conforming tooling cannot produce such a wheel in the first place.
• Nothing in the module's history — no issue, PR, or changelog entry across its ~20 years — mentions backslash or separator handling.

Rejecting uniformly also removes the platform-dependent behavior rather than entrenching it, which is the outcome we want.

[jaraco]

Split out the two things noted during review but left out of scope here:

• archive_util bypasses tarfile's PEP 706 extraction filters by calling private APIs #5328 — archive_util extracts via tarfile's private _extract_member/_getmember, so PEP 706 filters never run and the containment check added in this PR is a partial hand-rolled substitute for data_filter.
• CI: test (pypy3.11, ubuntu-latest, stdlib) fails because PyPy's bundled distutils calls sysconfig.is_python_build(True) #5327 — the standing test (pypy3.11, ubuntu-latest, stdlib) CI failure, which is a PyPy bundled-distutils bug rather than ours, and which currently masks real regressions on every PR.