Extract archives without escaping the destination

An archive supplies more than compressed bytes. Each member can name a path, a type, permissions, link target and advertised size. A naive extractor joins its destination with the member name and writes there. For destination /work/import and member ../outside.txt, path resolution leaves the intended root. An absolute member name can ignore the destination entirely. A symlink member can redirect later writes even when every later member name looks relative. Snyk named the pattern Zip Slip in 2018 after finding it in extraction code across many ecosystems.

Define the feature before selecting extraction APIs. The example importer accepts regular files only, with at most three members, at most 1024 bytes per file and 2048 total uncompressed bytes. It does not need symlinks, hard links, devices or archive-preserved ownership. Rejecting unnecessary member types removes complex semantics. Python's tarfile extraction filters provide useful safeguards, and Python 3.14 made filter='data' the default, but the filters themselves have been bypassed: CVE-2025-4517 (CVSS 9.4) and four related CVEs allowed writes and links outside the destination until 3.9.23, 3.10.18, 3.11.13, 3.12.11 and 3.13.4, and CVE-2026-11940, an incomplete fix, until 3.10.21, 3.11.16, 3.12.14, 3.13.15 and 3.14.7. Three more followed in August and September 2026, all fixed in 3.11.17, 3.12.15 and 3.13.16 (30 September and 1 October 2026): CVE-2026-19672 let both filters create empty directories outside the destination for names such as ../evil/../dest/sub/file on POSIX systems (also fixed in 3.14.8); CVE-2026-82049, a hard link to a symlink, let extraction change the permissions or timestamps of a file outside the destination or expose its contents (3.14 is not affected); and CVE-2026-87910 ignored a custom filter's None when a link is extracted as a copy on a system that cannot create it, a fix that is in the 3.14 branch but in no 3.14 release on 11 October 2026. The CVE-2026-19672 record notes that extraction into a randomly named directory is not affected, because the name must contain the destination's own final component, which is one more reason to extract into a fresh tempfile.mkdtemp() directory. Python 3.10 reached end of life on 1 October 2026 with 3.10.22. No filter is a substitute for the application's own file-type and resource policy, and code that relies on the 3.14 default inherits the same bugs. Configure the intended behavior explicitly.

Use a newly created private extraction directory that untrusted local actors cannot modify. Reject absolute paths and parent traversal according to the platform's path rules; normalize names consistently before checking duplicates. A simple string prefix is wrong because /work/import-other starts with /work/import but is not inside it. Use path-component containment or directory-relative filesystem operations designed for this purpose; the fix cards at /fix/path-traversal/ show the component check in seven frameworks.

Checking a resolved path and opening it later can be unsafe if another actor can replace a directory with a symlink between those operations. Restricting the workspace and rejecting links reduces that race; stronger extractors use safe directory handles and no-follow semantics, such as Go's os.Root or Linux openat2 with RESOLVE_BENEATH. Do not overwrite existing files, and reject duplicate normalized destinations rather than allowing an archive's later entry to replace an earlier validated one. Consider platform aliases such as drive paths, separators, case folding and reserved names when moving archives across operating systems. The POSIX-only fixture makes its narrower assumptions explicit.

The Python program below implements the exercise contract with the standard library. It reads tar headers one at a time, rejects any member that is not a regular file before writing it, refuses absolute names, .. components, backslashes and duplicates, and copies each member with its own byte counters into a private staging directory created inside the publish root, opening every file with exclusive create. It never calls extractall, so the filter bugs above cannot affect it. Only when every member succeeds does one os.rename publish the directory under a server-generated import id; any failure removes the staging directory. A test that builds the seven exercise archives plus an absolute path and a hard link publishes A and D, rejects the other seven, leaves the outside sentinel unchanged and leaves no staging directory behind on Python 3.11.17 and 3.14.8.

"""safe_extract.py: import regular files from an untrusted tar archive (Python 3.11+)."""
import os
import shutil
import tarfile
import tempfile
from pathlib import Path, PurePosixPath

MAX_FILES, MAX_FILE_BYTES, MAX_TOTAL_BYTES = 3, 1024, 2048


class Rejected(Exception):
    pass


def member_path(name: str) -> PurePosixPath:
    path = PurePosixPath(name)
    if path.is_absolute() or not path.parts or ".." in path.parts or "\\" in name:
        raise Rejected(f"unsafe name {name!r}")
    return path


def import_archive(archive: Path, publish_root: Path, import_id: str) -> Path:
    """Publishes publish_root/import_id only if every member passes; otherwise writes nothing."""
    staging = Path(tempfile.mkdtemp(prefix=".staging-", dir=publish_root))  # private, 0700
    try:
        seen, total = set(), 0
        with tarfile.open(archive, "r:*") as tar:
            for count, member in enumerate(tar, start=1):  # headers are read one at a time
                if count > MAX_FILES:
                    raise Rejected("too many members")
                if not member.isreg():  # no symlinks, hard links, devices or directories
                    raise Rejected(f"{member.name!r} is not a regular file")
                path = member_path(member.name)
                if path in seen:
                    raise Rejected(f"duplicate {path}")
                seen.add(path)
                target = staging.joinpath(*path.parts)
                target.parent.mkdir(parents=True, exist_ok=True)
                written = 0
                with tar.extractfile(member) as src, open(target, "xb") as dst:  # never overwrite
                    while chunk := src.read(64 * 1024):  # count bytes actually produced
                        written += len(chunk)
                        total += len(chunk)
                        if written > MAX_FILE_BYTES or total > MAX_TOTAL_BYTES:
                            raise Rejected("size limit exceeded")
                        dst.write(chunk)
        final = publish_root / import_id  # a server-generated id, never a caller-supplied path
        os.rename(staging, final)  # publish only after every member succeeded
        return final
    except BaseException:
        shutil.rmtree(staging, ignore_errors=True)
        raise

Go 1.24 added os.Root, which opens a directory once and refuses any path that resolves outside it, including through symbolic links that appear later. The function below combines it with filepath.IsLocal, a regular-file check, exclusive create and byte limits. Its tests, run with Go 1.27, accept A and D, reject the other exercise archives and an absolute path, and prove the containment: when another process plants a symlink inside the staging directory, the extractor fails, while an ordinary os.WriteFile through the same path writes outside.

// Package archive extracts regular files from an untrusted tar stream into one directory.
package archive

import (
	"archive/tar"
	"errors"
	"fmt"
	"io"
	"os"
	"path/filepath"
)

const maxFiles, maxFileBytes, maxTotalBytes = 3, 1024, 2048

// Extract writes the archive's regular files under dir, a fresh private staging directory.
// os.Root (Go 1.24+; MkdirAll needs 1.25) refuses any path that resolves outside dir,
// including through symlinks, so a checked name cannot be redirected later.
func Extract(r io.Reader, dir string) error {
	root, err := os.OpenRoot(dir)
	if err != nil {
		return err
	}
	defer root.Close()
	tr := tar.NewReader(r)
	var total int64
	for n := 1; ; n++ {
		hdr, err := tr.Next()
		if err == io.EOF {
			return nil
		}
		if err != nil {
			return err
		}
		if n > maxFiles {
			return errors.New("too many members")
		}
		if hdr.Typeflag != tar.TypeReg {
			return fmt.Errorf("%q: only regular files are accepted", hdr.Name)
		}
		if !filepath.IsLocal(hdr.Name) { // absolute, "..", empty or reserved names
			return fmt.Errorf("%q: not a local path", hdr.Name)
		}
		name := filepath.Clean(filepath.FromSlash(hdr.Name))
		if err := root.MkdirAll(filepath.Dir(name), 0o700); err != nil {
			return err
		}
		f, err := root.OpenFile(name, os.O_WRONLY|os.O_CREATE|os.O_EXCL, 0o600) // no overwrite
		if err != nil {
			return err
		}
		written, err := io.Copy(f, io.LimitReader(tr, maxFileBytes+1))
		f.Close()
		total += written
		if err != nil {
			return err
		}
		if written > maxFileBytes || total > maxTotalBytes {
			return errors.New("size limit exceeded")
		}
	}
}

An archive header's claimed size is useful for early rejection, but the extractor must count bytes actually produced. Compression ratios can turn a small incoming object into large output; nested archives can multiply that work again if the application recursively opens them. Bound incoming bytes, member count, path depth, decoded output, CPU and time, and avoid automatic recursion unless it is a separately budgeted feature. DOCX, XLSX and ODF files are ZIP archives too: /domains/appsec/secure-features/untrusted-document-conversion/ applies these checks before a document converter opens them.

Define failure semantics before the first write. This exercise treats extraction as an atomic import: any invalid member invalidates the whole archive and private partial output is removed. That prevents callers from receiving a partially accepted directory whose contents depend on member order. If a product intentionally supports partial extraction, it needs an explicit per-member report and must still guarantee that rejected entries caused no outside writes. Neither an exception nor a failed HTTP status proves the filesystem was unchanged.

Keep an outside sentinel in a controlled test workspace and compare its content before and after extraction. Inspect all files created under the destination, including temporary output. The normal archive should publish the expected bytes. A traversal entry, link or duplicate should leave no published output and no changed outside sentinel. A count or byte-limit boundary should fail exactly according to the documented inclusive limit.

The exercise supplies member metadata and actual output sizes, so its decisions require no archive tool or filesystem access. For execution practice, the browser lab at /labs/archive-paths/ and the archive-extraction project below exercise the same rules. Real integrations should test their actual archive library, runtime version and target filesystem because tar, ZIP and platform path rules differ. Diagnose failures using the member index and policy category, with bounded names; do not log unbounded attacker-supplied filenames or retain rejected archives indefinitely.

Extracting into a private directory prevents immediate exposure, but publication can still introduce a path bug. Suppose the caller supplies the final destination name and the importer renames its safe temporary directory to that unchecked location. All member checks pass, yet publication escapes the permitted namespace. Derive the final destination from an authorized import identity and a controlled storage root, then make the publish transition atomic where the filesystem and product contract permit it.

Cleanup must operate only on the private directory the job owns. An error handler that recursively removes a caller-supplied path or follows links can turn a rejection into a destructive action. Retain a trusted directory handle or server-generated path identity throughout processing, and avoid re-resolving untrusted names to decide what to delete. The exercise's cleanup result assumes ownership of its isolated root; it is not permission to recursively delete arbitrary import paths.

Metadata also deserves a policy. Preserving executable bits, ownership or device types may grant capabilities the file-import feature never needed. For a regular-document importer, choose safe permissions for created files and directories and ignore archive-supplied ownership. If executable archives are a legitimate product feature, that requires a separate trust and execution model. A successful path-containment check answers where bytes went; it does not establish that their eventual execution is authorized.

Repair the code

Path traversal lab: Keep archive entries inside their extraction directory

Path traversal lab: Serve an uploaded file without path traversal

Sources & further reading

The standards, specifications and documentation behind the guidance above. Each is the evidence for a claim on this page; consult it for detail beyond the defaults and versions listed here.

1. OWASP File Upload
2. Python tarfile extraction filters. Python 3.15.
3. MITRE CWE-22 path traversal. CWE 4.20.
4. CVE-2025-4517: tarfile realpath overflow (CVE record)
5. CVE-2026-11940: tarfile extraction filter bypass (CVE record)
6. CVE-2026-19672: tarfile extraction filter bypass creates directories outside the destination (CVE record)
7. CVE-2026-82049: tarfile extraction filters and a hard link to a symlink (CVE record)
8. CVE-2026-87910: tarfile link fallback ignores a custom filter's rejection (CVE record)
9. Python 3.14.8, an expedited security release. 30 September 2026.
10. Python 3.11.17 release notes (the same tarfile and zipfile fixes for 3.11). 1 October 2026.
11. Go: os.Root and traversal-resistant file APIs. 12 March 2025.
12. Snyk: Zip Slip vulnerability
13. OWASP ASVS 5.0.0: V5 File Handling

Reference information

Tags

File uploads and archives

SDLC phase

DesignDevelopment

Role

DevelopersAppSec engineers

ASVS 5.0.0 requirements

v5.0.0-5.2.3 · v5.0.0-5.2.5 · v5.0.0-5.3.3

CAPEC attack patterns

• CAPEC-126 at MITRE
• CAPEC-139 at MITRE
• CAPEC-597 at MITRE

Download this guide as Markdown

Continue exploring