exarch 0.5.0

Memory-safe archive extraction library with built-in security validation

exarch

Memory-safe archive extraction and creation library for Python.

Important: exarch is designed as a secure replacement for vulnerable archive libraries like Python's tarfile, which has known CVEs with CVSS scores up to 9.4.

This package provides Python bindings for exarch-core, a Rust library with built-in protection against common archive vulnerabilities.

Installation

pip install exarch

Tip: Use uv pip install exarch for faster installation.

Alternative Package Managers

# Poetry
poetry add exarch

# Pipenv
pipenv install exarch

Requirements

• Python >= 3.10

Quick Start

Extraction

import exarch

result = exarch.extract_archive("archive.tar.gz", "/output/path")
print(f"Extracted {result.files_extracted} files")

Creation

import exarch

result = exarch.create_archive("backup.tar.gz", ["src/", "Cargo.toml"])
print(f"Created archive with {result.files_added} files")

Usage

Basic Extraction

import exarch

result = exarch.extract_archive("archive.tar.gz", "/output/path")

print(f"Files extracted: {result.files_extracted}")
print(f"Bytes written: {result.bytes_written}")
print(f"Duration: {result.duration_ms}ms")

With pathlib.Path

from pathlib import Path
import exarch

archive = Path("archive.tar.gz")
output = Path("/output/path")

result = exarch.extract_archive(archive, output)

Custom Security Configuration

import exarch

config = exarch.SecurityConfig()
config = config.with_max_file_size(100 * 1024 * 1024)  # 100 MB

result = exarch.extract_archive("archive.tar.gz", "/output", config)

Error Handling

import exarch

try:
    result = exarch.extract_archive("archive.tar.gz", "/output")
    print(f"Extracted {result.files_extracted} files")
except exarch.PathTraversalError as e:
    print(f"Blocked path traversal: {e}")
except exarch.ZipBombError as e:
    print(f"Zip bomb detected: {e}")
except exarch.SecurityViolationError as e:
    print(f"Security violation: {e}")
except exarch.ArchiveError as e:
    print(f"Extraction failed: {e}")

API Reference

extract_archive(archive_path, output_dir, config=None)

Extract an archive to the specified directory with security validation.

Parameters:

Name	Type	Description
archive_path	str | Path	Path to the archive file
output_dir	str | Path	Directory where files will be extracted
config	SecurityConfig	Optional security configuration

Returns: ExtractionReport

Attribute	Type	Description
files_extracted	int	Number of files extracted
directories_created	int	Number of directories created
symlinks_created	int	Number of symlinks created
bytes_written	int	Total bytes written
duration_ms	int	Extraction duration in milliseconds
files_skipped	int	Number of files skipped (e.g. duplicates)
warnings	list[str]	Warning messages generated during extraction

Raises:

Exception	Description
PathTraversalError	Path traversal attempt detected
SymlinkEscapeError	Symlink points outside extraction directory
HardlinkEscapeError	Hardlink target outside extraction directory
ZipBombError	Potential zip bomb detected
QuotaExceededError	Resource quota exceeded
SecurityViolationError	Security policy violation
UnsupportedFormatError	Archive format not supported
UnknownFormatError	Archive format cannot be determined from path or magic bytes (subclass of UnsupportedFormatError)
InvalidArchiveError	Archive is corrupted
IOError	I/O operation failed

Note: Since v0.4.0, create_archive raises FileNotFoundError for missing sources, FileExistsError when the output already exists without overwrite, and ValueError for invalid compression levels — matching standard Python conventions.

extract_archive_with_progress(archive_path, output_dir, config, progress)

Extract an archive with a progress callback. The GIL is held when a callback is provided and released otherwise.

Parameters:

Name	Type	Description
archive_path	str | Path	Path to the archive file
output_dir	str | Path	Directory where files will be extracted
config	SecurityConfig | None	Optional security configuration
progress	Callable[[str, int, int, int], None] | None	Optional progress callback: (path, total_files, current_file, bytes_written)

import exarch

def on_progress(path: str, total: int, current: int, bytes_written: int) -> None:
    print(f"[{current}/{total}] {path} ({bytes_written} bytes)")

result = exarch.extract_archive_with_progress(
    "archive.tar.gz", "/output", config=None, progress=on_progress
)

SecurityConfig

Builder-style security configuration.

config = exarch.SecurityConfig()
config = config.with_max_file_size(100 * 1024 * 1024)   # 100 MB per file
config = config.with_max_total_size(1024 * 1024 * 1024) # 1 GB total
config = config.with_max_file_count(10_000)              # Max 10k files
config = config.with_max_compression_ratio(50.0)        # Zip bomb threshold
config = config.add_allowed_extension(".txt")            # Extension allowlist
config = config.add_allowed_extension(".md")
config = config.add_banned_component("__MACOSX")         # Skip components
config = config.with_allow_solid_archives(True)          # Allow solid 7z archives

Security Features

The library provides built-in protection against:

Protection	Description
Path traversal	Blocks ../ and absolute paths
Symlink attacks	Prevents symlinks escaping extraction directory
Hardlink attacks	Validates hardlink targets
Zip bombs	Detects high compression ratios
Permission sanitization	Strips setuid/setgid bits
Size limits	Enforces file and total size limits

Caution: Unlike Python's standard tarfile module, exarch applies security validation by default.

Supported Formats

Format	Extensions	Extract	Create	List	Verify
TAR	.tar	✅	✅	✅	✅
TAR+GZIP	.tar.gz, .tgz	✅	✅	✅	✅
TAR+BZIP2	.tar.bz2, .tbz2	✅	✅	✅	✅
TAR+XZ	.tar.xz, .txz	✅	✅	✅	✅
TAR+ZSTD	.tar.zst, .tzst	✅	✅	✅	✅
ZIP	.zip	✅	✅	✅	✅
7z	.7z	✅	—	✅	✅

Note: 7z creation is not yet supported. Solid and encrypted 7z archives are rejected for security reasons. Unix symlinks inside 7z archives are reported as regular files (sevenz-rust2 API limitation).

Comparison with tarfile

# UNSAFE - tarfile has known vulnerabilities (CVE-2007-4559)
import tarfile
with tarfile.open("archive.tar.gz") as tar:
    tar.extractall("/output")  # May extract outside target directory!

# SAFE - exarch validates all paths
import exarch
exarch.extract_archive("archive.tar.gz", "/output")  # Protected by default

Development

This package is built using PyO3 and maturin.

# Clone repository
git clone https://github.com/bug-ops/exarch
cd exarch/crates/exarch-python

# Build with maturin
pip install maturin
maturin develop

# Run tests
pytest tests/

Related Packages

• exarch-core — Core Rust library
• exarch (npm) — Node.js bindings

License

Licensed under either of:

• Apache License, Version 2.0 (LICENSE-APACHE)
• MIT License (LICENSE-MIT)

at your option.