The tzst project takes security seriously and is committed to providing a secure archive management library. This document outlines our security policies, supported versions, vulnerability reporting procedures, and security best practices.

We provide security updates for the latest major version. Users are strongly encouraged to keep their installations up to date.

tzst is designed with security as a primary concern and implements multiple layers of protection:

tzst provides three security filter levels for extraction operations:

• data (default): Maximum security level

  • Blocks dangerous files (device files, named pipes, etc.)
  • Prevents absolute path extraction
  • Blocks directory traversal attacks (../ sequences)
  • Restricts extraction to the specified directory
  • Recommended for untrusted archives

• tar: Standard tar compatibility

  • Blocks absolute paths
  • Prevents directory traversal
  • Allows Unix-specific features (symlinks, permissions)
  • Use for trusted archives requiring tar features

• fully_trusted: No security restrictions

  • Allows all archive features
  • Only use with completely trusted archives
  • ⚠️ Warning: Can be dangerous with untrusted content

All file creation operations use atomic file operations by default:

• Archives are created in temporary files first, then atomically moved
• Automatic cleanup if the process is interrupted
• Prevents corrupted or incomplete archives
• Cross-platform compatibility
• Use use_temp_file=False only when necessary (not recommended)

• Validates all file paths before extraction
• Normalizes paths to prevent directory traversal
• Blocks extraction outside target directory
• Handles edge cases across different operating systems

• Validates compression levels (1-22)
• Validates archive formats
• Validates file paths and names
• Comprehensive error handling with clear messages

from tzst import extract_archive

# ✅ Good: Uses secure 'data' filter by default
extract_archive("untrusted.tzst", "output/")

# ✅ Good: Explicitly specify secure filter
extract_archive("untrusted.tzst", "output/", filter="data")

# For untrusted archives (recommended)
extract_archive("untrusted.tzst", "output/", filter="data")

# For trusted archives needing tar features
extract_archive("trusted.tzst", "output/", filter="tar")

# Only for completely trusted archives (use with caution)
extract_archive("internal.tzst", "output/", filter="fully_trusted")

• Only process archives from trusted sources
• Verify archive integrity before extraction
• Use appropriate security filters based on trust level
• Consider implementing additional validation layers

import tempfile
from pathlib import Path
from tzst import extract_archive, test_archive

def safe_extract(archive_path, trust_level="untrusted"):
    """Safely extract an archive with appropriate security measures."""
    
    # Test archive integrity first
    if not test_archive(archive_path):
        raise ValueError("Archive integrity check failed")
    
    # Choose security filter based on trust level
    filters = {
        "untrusted": "data",
        "trusted": "tar", 
        "internal": "fully_trusted"
    }
    
    security_filter = filters.get(trust_level, "data")
    
    # Extract to temporary directory first
    with tempfile.TemporaryDirectory() as temp_dir:
        extract_archive(
            archive_path, 
            temp_dir, 
            filter=security_filter
        )
        # Process extracted files safely
        # Move to final destination if validation passes

from tzst import TzstArchiveError, TzstDecompressionError

try:
    extract_archive("archive.tzst", "output/")
except TzstDecompressionError:
    # Handle corrupted or invalid archives
    print("Archive appears to be corrupted")
except TzstArchiveError as e:
    # Handle general archive errors
    print(f"Archive operation failed: {e}")
except PermissionError:
    # Handle permission issues
    print("Insufficient permissions")

When processing archives from untrusted sources (internet downloads, user uploads, etc.):

1. Always use data filter (default behavior)
2. Extract to isolated directory with limited permissions
3. Validate extracted content before use
4. Use resource limits to prevent DoS attacks
5. Run in sandboxed environment when possible

For trusted internal archives:

1. Use tar filter for standard compatibility
2. Implement organizational security policies
3. Use secure transport channels
4. Maintain audit logs of archive operations
5. Regular security assessments

Even in development:

1. Use secure defaults
2. Don't disable security features without understanding implications
3. Test with malicious archives (in isolated environments)
4. Validate security assumptions

We take security vulnerabilities seriously and appreciate responsible disclosure.

DO NOT report security vulnerabilities through public GitHub issues.

Instead, please report security vulnerabilities via email to:

📧 i@xi-xu.me

Please include as much of the following information as possible:

1. Description of the vulnerability
2. Steps to reproduce the issue
3. Potential impact and attack scenarios
4. Affected versions (if known)
5. Suggested fix (if you have one)
6. Your contact information for follow-up

1. Acknowledgment: We'll acknowledge receipt within 48 hours
2. Initial Assessment: We'll provide an initial assessment within 5 business days
3. Communication: We'll keep you informed throughout the investigation
4. Resolution: We'll work to resolve confirmed vulnerabilities promptly
5. Credit: We'll credit you in security advisories (unless you prefer anonymity)

• Critical vulnerabilities: Patch within 7 days
• High-severity vulnerabilities: Patch within 14 days
• Medium/Low-severity vulnerabilities: Patch within 30 days

1. GitHub Security Advisories: For confirmed vulnerabilities
2. Release Notes: Security fixes are prominently mentioned
3. PyPI: Updated packages with security fixes
4. Documentation: Security best practices updates

To stay informed about security updates:

1. Watch the repository for release notifications
2. Subscribe to GitHub Security Advisories
3. Follow our release notes for security mentions
4. Use dependency scanners to identify outdated versions

• All changes undergo security-focused code review
• Security-sensitive changes require additional review
• Automated security scanning in CI/CD pipeline
• Regular dependency vulnerability scanning

• Comprehensive security test suite
• Fuzzing with malformed archives
• Path traversal attack simulations
• Permission and access control testing

• Minimal dependency footprint
• Regular dependency updates
• Automated vulnerability scanning
• Pinned versions for reproducible builds

While tzst includes basic protections, be aware of:

• Zip bombs: Archives with extreme compression ratios
• Memory exhaustion: Very large expanded archives
• Resource consumption: Processing time attacks

Mitigation: Use streaming mode for large archives and implement resource limits.

Different security filters handle symbolic links differently:

• data filter: Generally restricts symbolic links
• tar filter: Preserves symbolic links with basic safety checks
• fully_trusted filter: Allows all symbolic link operations

Recommendation: Use data filter for untrusted content.

Extracted file permissions depend on:

• Source archive permissions
• Extraction filter settings
• Operating system capabilities
• User privileges

Recommendation: Review and validate extracted file permissions.

For security-related questions or concerns:

• Security issues: i@xi-xu.me (private)
• General questions: GitHub Discussions
• Documentation: Project Documentation

We thank the security research community for their responsible disclosure of vulnerabilities and continuous efforts to improve software security.

Last Updated: June 2025
Version: 1.0

For the most current security information, please check our GitHub repository and official documentation.