safe_unzip

Secure archive extraction. Supports ZIP (core), TAR, and 7z (optional features).

The Problem

Zip files can contain malicious paths that escape the extraction directory:

import zipfile
zipfile.ZipFile("evil.zip").extractall("/var/uploads")
# Extracts ../../etc/cron.d/pwned → /etc/cron.d/pwned 💀

This is Zip Slip, and Python's default behavior is still vulnerable.

"But didn't Python fix this?"

Sort of. Python added warnings and ZipInfo.filename sanitization in 2014. In Python 3.12+, there's a filter parameter:

# The "safe" way — but who knows this exists?
zipfile.ZipFile("evil.zip").extractall("/var/uploads", filter="data")

The problem: the safe option is opt-in. The default is still vulnerable. Most developers don't read the docs carefully enough to discover filter="data".

safe_unzip makes security the default, not an afterthought.

The Solution

use safe_unzip::extract_file;

extract_file("/var/uploads", "evil.zip")?;
// Err(PathEscape { entry: "../../etc/cron.d/pwned", ... })

# Python bindings — same safety
from safe_unzip import extract_file

extract_file("/var/uploads", "evil.zip")
# Raises: PathEscapeError

Security is the default. No special flags, no opt-in safety. Every path is validated. Malicious archives are rejected, not extracted.

Why Not Just Use zip / tar / zipfile?

Because archive extraction is a security boundary, and most libraries treat it as a convenience function.

If you're extracting untrusted archives, you need a library designed for that threat model.

Who Should Use This

• Backend services handling user-uploaded zip files
• CI/CD systems unpacking third-party artifacts
• SaaS platforms with file import features
• Forensics / malware analysis pipelines
• Anything running as a privileged user

If your zip files only come from trusted sources you control, the standard zip crate is fine. If users can upload archives, use safe_unzip.

Features

• CLI Tool — safe_unzip command with --list, --verify, limits, and filtering
• Archive Verification — Check CRC32 integrity without extracting
• Multi-Format Support — ZIP (core), TAR, and 7z (feature flags)
• Partial Extraction — Extract specific files with only() or glob patterns
• Progress Callbacks — Monitor extraction progress (Rust API)
• Async API — Optional tokio-based async extraction (feature flag)
• Zip Slip Protection — Path traversal attacks blocked via path_jail
• Zip Bomb Protection — Configurable limits on size, file count, and path depth
• Strict Size Enforcement — Catches files that decompress larger than declared
• Filename Sanitization — Blocks control characters and Windows reserved names
• Symlink Handling — Skip or reject symlinks (no symlink-based escapes)
• Secure Overwrite — Removes symlinks before overwriting to prevent symlink attacks
• Atomic File Creation — TOCTOU-safe file creation using O_EXCL
• Overwrite Policies — Error, skip, or overwrite existing files
• Filter Callback — Extract only the files you want
• Two-Pass Mode — Validate everything before writing anything
• Permission Stripping — Removes setuid/setgid bits on Unix

Installation

CLI:

cargo install safe_unzip --features cli

Rust:

[dependencies]
safe_unzip = "0.1"

Python:

pip install safe-unzip

Feature Flags

# ZIP only (smallest, ~30 deps)
safe_unzip = "0.1"

# With TAR support (~40 deps)
safe_unzip = { version = "0.1", features = ["tar"] }

# With async API
safe_unzip = { version = "0.1", features = ["async"] }

# Kitchen sink (~85 deps)
safe_unzip = { version = "0.1", features = ["tar", "async", "sevenz"] }

Note: Python bindings always include TAR support.

Python Bindings

The Python bindings are thin wrappers over the Rust implementation via PyO3. This means:

• ✅ Identical security guarantees — same code path, same validation
• ✅ Identical limits — same defaults (1GB total, 10K files, 100MB per file)
• ✅ Identical semantics — same error conditions, same behavior
• ✅ No re-implementation — Python calls Rust directly, no logic duplication

Security reviewers: the Python API is a direct binding, not a port.

CLI Usage

# Extract archive to destination
safe_unzip archive.zip -d /var/uploads

# List contents without extracting
safe_unzip archive.zip --list

# Verify integrity (CRC32 check)
safe_unzip archive.zip --verify

# With limits
safe_unzip archive.zip -d /var/uploads --max-size 100M --max-files 1000

# Glob filtering
safe_unzip archive.zip -d /var/uploads --include "**/*.py" --exclude "**/test_*"

# Partial extraction
safe_unzip archive.zip -d /var/uploads --only README.md --only LICENSE

# Verbose output
safe_unzip archive.zip -d /var/uploads -v

Quick Start

use safe_unzip::extract_file;

// Extract with safe defaults
let report = extract_file("/var/uploads", "archive.zip")?;
println!("Extracted {} files ({} bytes)", 
    report.files_extracted, 
    report.bytes_written
);

Usage Examples

Basic Extraction

use safe_unzip::Extractor;

let report = Extractor::new("/var/uploads")?
    .extract_file("archive.zip")?;

Create Destination if Missing

use safe_unzip::Extractor;

// Extractor::new() errors if destination doesn't exist (catches typos)
// Extractor::new_or_create() creates it automatically
let report = Extractor::new_or_create("/var/uploads/new_folder")?
    .extract_file("archive.zip")?;

// The convenience functions (extract_file, extract) also create automatically
use safe_unzip::extract_file;
extract_file("/var/uploads/new_folder", "archive.zip")?;

Custom Limits (Prevent Zip Bombs)

use safe_unzip::{Extractor, Limits};

let report = Extractor::new("/var/uploads")?
    .limits(Limits {
        max_total_bytes: 500 * 1024 * 1024,  // 500 MB total
        max_file_count: 1_000,                // Max 1000 files
        max_single_file: 50 * 1024 * 1024,   // 50 MB per file
        max_path_depth: 10,                   // No deeper than 10 levels
    })
    .extract_file("archive.zip")?;

Filter by Extension

use safe_unzip::Extractor;

// Only extract images
let report = Extractor::new("/var/uploads")?
    .filter(|entry| {
        entry.name.ends_with(".png") || 
        entry.name.ends_with(".jpg") ||
        entry.name.ends_with(".gif")
    })
    .extract_file("archive.zip")?;

println!("Extracted {} images, skipped {} other files",
    report.files_extracted,
    report.entries_skipped
);

Partial Extraction (New in v0.1.5)

Extract specific files by name or glob pattern:

use safe_unzip::Extractor;

// Extract only specific files
let report = Extractor::new("/var/uploads")?
    .only(&["README.md", "LICENSE"])
    .extract_file("archive.zip")?;

// Include by glob pattern
let report = Extractor::new("/var/uploads")?
    .include_glob(&["**/*.py", "**/*.rs"])
    .extract_file("archive.zip")?;

// Exclude by glob pattern
let report = Extractor::new("/var/uploads")?
    .exclude_glob(&["**/__pycache__/**", "**/*.pyc"])
    .extract_file("archive.zip")?;

Python:

from safe_unzip import Extractor

# Extract only specific files
report = Extractor("/var/uploads").only(["README.md", "LICENSE"]).extract_file("archive.zip")

# Include by pattern
report = Extractor("/var/uploads").include_glob(["**/*.py"]).extract_file("archive.zip")

# Exclude by pattern  
report = Extractor("/var/uploads").exclude_glob(["**/__pycache__/**"]).extract_file("archive.zip")

Progress Callbacks

Monitor extraction progress:

use safe_unzip::Extractor;

let report = Extractor::new("/var/uploads")?
    .on_progress(|p| {
        println!("[{}/{}] {} ({} bytes)",
            p.entry_index + 1,
            p.total_entries,
            p.entry_name,
            p.entry_size
        );
    })
    .extract_file("archive.zip")?;

Python:

from safe_unzip import Extractor

def show_progress(p):
    print(f"[{p['entry_index']+1}/{p['total_entries']}] {p['entry_name']}")

Extractor("/var/uploads").on_progress(show_progress).extract_file("archive.zip")

# Or with tqdm for a progress bar
from tqdm import tqdm
entries = list_zip_entries("archive.zip")
pbar = tqdm(total=len(entries))
def update_bar(p):
    pbar.update(1)
    pbar.set_description(p['entry_name'])
Extractor("/var/uploads").on_progress(update_bar).extract_file("archive.zip")
pbar.close()

Archive Verification

Check archive integrity without extracting:

use safe_unzip::verify_file;

// Verify CRC32 for all entries
let report = verify_file("archive.zip")?;
println!("Verified {} entries ({} bytes)", 
    report.entries_verified, 
    report.bytes_verified
);

Or with the Extractor (useful if you want to verify then extract):

use safe_unzip::Extractor;

let extractor = Extractor::new("/var/uploads")?;

// First verify
extractor.verify_file("archive.zip")?;

// Then extract (re-reads archive, but guarantees integrity)
extractor.extract_file("archive.zip")?;

Overwrite Policies

use safe_unzip::{Extractor, OverwritePolicy};

// Skip files that already exist
let report = Extractor::new("/var/uploads")?
    .overwrite(OverwritePolicy::Skip)
    .extract_file("archive.zip")?;

// Or overwrite them
let report = Extractor::new("/var/uploads")?
    .overwrite(OverwritePolicy::Overwrite)
    .extract_file("archive.zip")?;

// Default: Error if file exists
let report = Extractor::new("/var/uploads")?
    .overwrite(OverwritePolicy::Error)  // This is the default
    .extract_file("archive.zip")?;

Symlink Policies

use safe_unzip::{Extractor, SymlinkPolicy};

// Default: silently skip symlinks
let report = Extractor::new("/var/uploads")?
    .symlinks(SymlinkPolicy::Skip)
    .extract_file("archive.zip")?;

// Or reject archives containing symlinks
let report = Extractor::new("/var/uploads")?
    .symlinks(SymlinkPolicy::Error)
    .extract_file("archive.zip")?;

Extraction Modes

⚠️ Neither mode is truly atomic. If extraction fails mid-write (e.g., disk full), partial files remain regardless of mode. ValidateFirst only prevents writes when validation fails (bad paths, limits exceeded), not when I/O fails during extraction.

use safe_unzip::{Extractor, ExtractionMode};

// Two-pass extraction:
// 1. Validate ALL entries (no disk writes)
// 2. Extract (only if validation passed)
let report = Extractor::new("/var/uploads")?
    .mode(ExtractionMode::ValidateFirst)
    .extract_file("untrusted.zip")?;

Use ValidateFirst when you can't tolerate partial state from malicious archives. Use Streaming (default) when speed matters and you can clean up on error.

Extracting from Memory

use safe_unzip::Extractor;
use std::io::Cursor;

let zip_bytes: Vec<u8> = download_zip_somehow();
let cursor = Cursor::new(zip_bytes);

let report = Extractor::new("/var/uploads")?
    .extract(cursor)?;

TAR Extraction (New in v0.1.2)

use safe_unzip::{Driver, TarAdapter};

// Extract a .tar file
let report = Driver::new("/var/uploads")?
    .extract_tar_file("archive.tar")?;

// Extract a .tar.gz file
let report = Driver::new("/var/uploads")?
    .extract_tar_gz_file("archive.tar.gz")?;

// With options
let report = Driver::new("/var/uploads")?
    .filter(|entry| entry.name.ends_with(".txt"))
    .validation(safe_unzip::ValidationMode::ValidateFirst)
    .extract_tar_file("archive.tar")?;

The new Driver API provides a unified interface for all archive formats with the same security guarantees.

7z Extraction (Requires sevenz Feature)

Enable the sevenz feature:

[dependencies]
safe_unzip = { version = "0.1", features = ["sevenz"] }

use safe_unzip::{Driver, SevenZAdapter};

// Extract a .7z file
let report = Driver::new("/var/uploads")?
    .extract_7z_file("archive.7z")?;

// Or from bytes
let report = Driver::new("/var/uploads")?
    .extract_7z_bytes(&seven_z_bytes)?;

Note: 7z archives are fully decompressed into memory before extraction, so large archives may use significant RAM.

Python:

from safe_unzip import extract_7z_file, Extractor

# Simple extraction
report = extract_7z_file("/var/uploads", "archive.7z")

# With options
report = Extractor("/var/uploads").extract_7z_file("archive.7z")

Async Extraction (New)

Enable the async feature for tokio-based async extraction:

[dependencies]
safe_unzip = { version = "0.1", features = ["async"] }

use safe_unzip::r#async::{extract_file, extract_tar_file, AsyncExtractor};

#[tokio::main]
async fn main() -> Result<(), safe_unzip::Error> {
    // Simple async extraction
    let report = extract_file("/var/uploads", "archive.zip").await?;
    
    // TAR extraction
    let report = extract_tar_file("/var/uploads", "archive.tar").await?;
    
    // With options
    let report = AsyncExtractor::new("/var/uploads")?
        .max_total_bytes(500 * 1024 * 1024)
        .max_file_count(1000)
        .extract_file("archive.zip")
        .await?;
    
    Ok(())
}

Concurrent extraction of multiple archives:

use safe_unzip::r#async::{extract_file, extract_tar_bytes};

let (zip_result, tar_result) = tokio::join!(
    extract_file("/uploads/a", "first.zip"),
    extract_tar_bytes("/uploads/b", tar_data),
);

The async API uses spawn_blocking internally, so extraction runs in a thread pool without blocking the async runtime.

Python Async API

Python async support uses asyncio.to_thread() to run extraction in a thread pool:

import asyncio
from safe_unzip import async_extract_file, AsyncExtractor

async def main():
    # Simple async extraction
    report = await async_extract_file("/var/uploads", "archive.zip")
    
    # TAR extraction
    from safe_unzip import async_extract_tar_file
    report = await async_extract_tar_file("/var/uploads", "archive.tar")
    
    # With options
    report = await (
        AsyncExtractor("/var/uploads")
        .max_total_mb(500)
        .max_files(1000)
        .extract_file("archive.zip")
    )

asyncio.run(main())

Concurrent extraction:

async def extract_all(archives):
    tasks = [
        async_extract_file(f"/uploads/{i}", path)
        for i, path in enumerate(archives)
    ]
    return await asyncio.gather(*tasks)

Security Model

Default Limits

Error Handling

use safe_unzip::{extract_file, Error};

match extract_file("/var/uploads", "archive.zip") {
    Ok(report) => {
        println!("Success: {} files", report.files_extracted);
    }
    Err(Error::PathEscape { entry, detail }) => {
        eprintln!("Blocked path traversal in '{}': {}", entry, detail);
    }
    Err(Error::TotalSizeExceeded { limit, would_be }) => {
        eprintln!("Archive too large: {} bytes (limit: {})", would_be, limit);
    }
    Err(Error::FileTooLarge { entry, size, limit }) => {
        eprintln!("File '{}' too large: {} bytes (limit: {})", entry, size, limit);
    }
    Err(Error::FileCountExceeded { limit }) => {
        eprintln!("Too many files (limit: {})", limit);
    }
    Err(Error::AlreadyExists { path }) => {
        eprintln!("File already exists: {}", path);
    }
    Err(Error::InvalidFilename { entry, .. }) => {
        eprintln!("Invalid filename: {}", entry);
    }
    Err(Error::EncryptedEntry { entry }) => {
        eprintln!("Encrypted entry not supported: {}", entry);
    }
    Err(e) => {
        eprintln!("Extraction failed: {}", e);
    }
}

Limitations

Format Limitations

• ZIP, TAR, 7z only — RAR not supported
• Requires seekable input for ZIP — ZIP format requires reading the central directory at the end
• TAR is sequential — TAR files are read in order; ValidateFirst mode caches entries in memory
• No encrypted archives — See below

Encrypted Archives

safe_unzip does not support password-protected zip files. Encrypted entries are rejected with Error::EncryptedEntry.

If you need to extract encrypted archives:

1. Decrypt first using the zip crate directly
2. Then extract with safe_unzip

This is intentional—encryption handling is outside our security scope. Password management, key derivation, and cryptographic validation are complex domains that deserve dedicated tooling.

Extraction Behavior

• Partial state in Streaming mode — If extraction fails mid-way, already-extracted files remain on disk. Use ExtractionMode::ValidateFirst to validate before writing.
• Filters not applied during validation — In ValidateFirst mode, limits are checked against ALL entries. Filtered entries still count toward limits. This is conservative: validation may reject archives that would succeed with filtering.

Security Scope

These threats are not fully addressed (by design or complexity):

TOCTOU Mitigations

For OverwriteMode::Error and OverwriteMode::Skip, we use atomic file creation (O_CREAT | O_EXCL) instead of check-then-create. This eliminates race conditions between checking if a file exists and creating it.

For OverwriteMode::Overwrite, symlinks are removed before writing to prevent symlink-following attacks, but there's a brief window between removal and creation.

Filename Restrictions

These filenames are rejected for security:

• Control characters (including null bytes)
• Backslashes (\) — prevents Windows path separator confusion
• Paths longer than 1024 bytes
• Path components longer than 255 bytes
• Windows reserved names: CON, PRN, AUX, NUL, COM1-9, LPT1-9

Development

Fuzzing

We use cargo-fuzz with two targets:

# Install cargo-fuzz (requires nightly)
cargo install cargo-fuzz

# Run the main extraction fuzzer
cargo +nightly fuzz run fuzz_extract

# Run the adapter fuzzer (tests parsing layer)
cargo +nightly fuzz run fuzz_zip_adapter

Fuzzing targets are in fuzz/fuzz_targets/. Run fuzzing before releases to catch parsing edge cases.

License

MIT OR Apache-2.0