From bcfb299bfba73b89ae38a619cb8a478dafea178b Mon Sep 17 00:00:00 2001 From: Xi Xu Date: Tue, 17 Jun 2025 21:16:31 +0800 Subject: [PATCH] Add SECURITY.md with security policy and best practices Introduces a SECURITY.md file detailing supported versions, security features, best practices for safe archive extraction, vulnerability reporting procedures, and development security practices for the tzst project. --- SECURITY.md | 313 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 313 insertions(+) create mode 100644 SECURITY.md diff --git a/SECURITY.md b/SECURITY.md new file mode 100644 index 0000000..7ab4349 --- /dev/null +++ b/SECURITY.md @@ -0,0 +1,313 @@ +# 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 + +```python +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 + +```python +# 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 + +```python +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 + +```python +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](mailto: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](mailto:i@xi-xu.me) (private) +- **General questions**: [GitHub Discussions](https://github.com/xixu-me/tzst/discussions) +- **Documentation**: [Project Documentation](https://tzst.xi-xu.me) + +## 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](https://github.com/xixu-me/tzst) and [official documentation](https://tzst.xi-xu.me).