tzst/SECURITY.md

Security Policy

Overview

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.

Supported Versions

Version	Supported
1.x.x	✅ Yes
< 1.0	❌ No

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

Security Features

Built-in Security by Default

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

🔒 Secure Extraction Filters

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

⚡ Atomic Operations

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)

🛡️ Path Traversal Protection

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

🔍 Input Validation

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

Best Practices for Users

1. Always Use Secure Defaults

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")

2. Choose Appropriate Security Filters

# 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")

3. Validate Archive Sources

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

4. Use Safe Extraction Practices

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

5. Error Handling

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")

Security Considerations for Different Use Cases

Processing Untrusted Archives

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

Enterprise/Internal Use

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

Development/Testing

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

Reporting Security Vulnerabilities

We take security vulnerabilities seriously and appreciate responsible disclosure.

How to Report

DO NOT report security vulnerabilities through public GitHub issues.

Instead, please report security vulnerabilities via email to:

📧 i@xi-xu.me

Information to Include

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

What to Expect

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)

Response Timeline

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

Security Updates and Advisories

How We Communicate Security Issues

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

Staying Informed

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

Development Security Practices

Code Review Process

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

Testing

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

Dependencies

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

Known Security Considerations

Archive Bombs

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.

Symbolic Links

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.

File Permissions

Extracted file permissions depend on:

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

Recommendation: Review and validate extracted file permissions.

Contact

For security-related questions or concerns:

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

Acknowledgments

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.