exarch

Command-line utility for secure archive extraction and creation. Built on exarch-core, providing memory-safe archive handling with built-in protection against path traversal, zip bombs, and symlink escape attacks.

Features

• Secure by default - All security checks enabled out of the box
• Path traversal protection - Blocks ../ escape attempts
• Zip bomb detection - Configurable compression ratio limits
• Symlink/hardlink validation - Prevents symlink escape attacks
• Quota enforcement - File count, total size, and per-file limits
• Multiple formats - TAR (gz, bz2, xz, zstd), ZIP, and 7z support
• Multiple output modes - Human-readable and JSON output

Installation

From crates.io

cargo install exarch-cli

From source

git clone https://github.com/bug-ops/exarch
cd exarch
cargo install --path crates/exarch-cli

[!TIP] Use cargo binstall exarch-cli for faster installation without compilation.

# Linux/macOS
tar -xzf exarch-*.tar.gz
chmod +x exarch
sudo mv exarch /usr/local/bin/

# Windows - extract zip and add to PATH

[!IMPORTANT] Requires Rust 1.89.0 or later for building from source.

Usage

exarch [OPTIONS] <COMMAND>

Commands

Global Options

Extract Command

exarch extract [OPTIONS] <ARCHIVE> [OUTPUT_DIR]

Examples

# Extract archive to current directory
exarch extract archive.tar.gz

# Extract to specific directory
exarch extract archive.zip /tmp/output

# Extract with JSON output for scripting
exarch extract --json archive.tar.xz | jq '.data.files_extracted'

# Extract with verbose output
exarch extract --verbose archive.tar.gz

# Increase security limits for large archives
exarch extract --max-files 50000 --max-total-size 50G large-archive.tar.gz

# Allow symlinks for trusted archives
exarch extract --allow-symlinks trusted-source.tar

Security Options

[!CAUTION] Only use --allow-symlinks and --allow-hardlinks with archives from trusted sources. These options can be exploited by malicious archives.

Create Command

Create archives from files and directories:

exarch create [OPTIONS] <OUTPUT> <SOURCES>...

Examples

# Create tar.gz from directory
exarch create backup.tar.gz ./src

# Create from multiple sources
exarch create project.tar.gz src/ Cargo.toml README.md

# Create ZIP with maximum compression
exarch create -l 9 archive.zip ./data

# Exclude patterns
exarch create backup.tar.gz ./project --exclude "*.log" --exclude "target/"

# Include hidden files
exarch create backup.tar.gz ./project --include-hidden

# Overwrite existing archive
exarch create -f backup.tar.gz ./src

Create Options

[!TIP] Archive format is detected from the output file extension. Supported formats: .tar, .tar.gz, .tar.bz2, .tar.xz, .tar.zst, .zip

Output Modes

Human-readable (default)

Extraction complete
  Files extracted: 1,523
  Directories: 87
  Total size: 42.3 MB

JSON output (--json)

{
  "operation": "extract",
  "status": "success",
  "data": {
    "files_extracted": 1523,
    "directories_created": 87,
    "symlinks_created": 0,
    "bytes_written": 44396032
  }
}

[!TIP] Use JSON output with jq for scripting: exarch extract --json archive.tar.gz | jq '.data.files_extracted'

Security

exarch is designed with security as a primary concern, protecting against common archive vulnerabilities:

[!NOTE] All security checks are enabled by default. Use --allow-* flags only for trusted archives.

Supported Formats

[!NOTE] 7z creation is not yet supported. Solid and encrypted 7z archives are rejected for security reasons.

Development

# Build
cargo build -p exarch-cli

# Run tests
cargo nextest run -p exarch-cli

# Run CLI directly
cargo run -p exarch-cli -- extract tests/fixtures/sample.tar.gz

# Check formatting and lints
cargo +nightly fmt --all -- --check
cargo clippy -p exarch-cli -- -D warnings

Roadmap

• Phase 1: Foundation - CLI parsing, error handling, output formatting
• Phase 2: Archive creation functionality
• Phase 3: List and verify commands
• Phase 4: Progress bars, shell completions
• Phase 5: Distribution (Homebrew, apt, releases)

Related Crates

• exarch-core - Core extraction library
• exarch-python - Python bindings
• exarch-node - Node.js bindings

License

Licensed under MIT OR Apache-2.0 - see LICENSE-MIT or LICENSE-APACHE.