safeuploads 0.1.0__py3-none-any.whl

safeuploads/validators/compression_validator.py

@@ -0,0 +1,286 @@
+"""
+Validates ZIP compression ratios and detects zip bombs.
+"""
+
+from __future__ import annotations
+
+import io
+import time
+import zipfile
+import logging
+
+from typing import TYPE_CHECKING
+from .base import BaseValidator
+from ..exceptions import (
+    ZipBombError,
+    CompressionSecurityError,
+    FileProcessingError,
+    ErrorCode,
+)
+
+if TYPE_CHECKING:
+    from ..config import FileSecurityConfig
+
+
+logger = logging.getLogger(__name__)
+
+
+class CompressionSecurityValidator(BaseValidator):
+    """
+    Validates ZIP uploads against zip bombs and compression attacks.
+
+    Attributes:
+        config: Security configuration for validation limits.
+    """
+
+    def __init__(self, config: FileSecurityConfig):
+        """
+        Initialize the compression validator.
+
+        Args:
+            config: Security configuration with compression limits.
+        """
+        super().__init__(config)
+
+    def validate_zip_compression_ratio(
+        self, file_content: bytes, compressed_size: int
+    ) -> None:
+        """
+        Validate ZIP archive against security limits.
+
+        Args:
+            file_content: Raw bytes of the ZIP archive.
+            compressed_size: Size of the compressed archive in bytes.
+
+        Raises:
+            ZipBombError: If compression ratio exceeds maximum allowed
+                or total uncompressed size is too large.
+            CompressionSecurityError: If ZIP structure is invalid, too
+                many entries, nested archives detected, or individual
+                file too large.
+            FileProcessingError: If unexpected error occurs during
+                validation such as memory errors or I/O errors.
+        """
+        try:
+            # Create a BytesIO object from file content for zipfile analysis
+            zip_bytes = io.BytesIO(file_content)
+
+            # Track analysis metrics
+            total_uncompressed_size = 0
+            total_compressed_size = compressed_size
+            file_count = 0
+            nested_archives = []
+            max_compression_ratio = 0
+            overall_compression_ratio = 0  # Initialize to avoid unbound variable
+
+            # Analyze ZIP file structure with timeout protection
+            start_time = time.time()
+
+            with zipfile.ZipFile(zip_bytes, "r") as zip_file:
+                # Check for excessive number of files
+                zip_entries = zip_file.infolist()
+                file_count = len(zip_entries)
+
+                if file_count > self.config.limits.max_zip_entries:
+                    logger.warning(
+                        "ZIP contains too many files",
+                        extra={
+                            "error_type": "zip_too_many_entries",
+                            "file_count": file_count,
+                            "max_entries": self.config.limits.max_zip_entries,
+                        },
+                    )
+                    raise CompressionSecurityError(
+                        message=f"ZIP contains too many files: {file_count}. "
+                        f"Maximum allowed: {self.config.limits.max_zip_entries}",
+                        error_code=ErrorCode.ZIP_TOO_MANY_ENTRIES,
+                    )
+
+                # Analyze each entry in the ZIP
+                for entry in zip_entries:
+                    # Check for timeout
+                    if (
+                        time.time() - start_time
+                        > self.config.limits.zip_analysis_timeout
+                    ):
+                        logger.error(
+                            "ZIP analysis timeout",
+                            extra={
+                                "error_type": "zip_analysis_timeout",
+                                "timeout": self.config.limits.zip_analysis_timeout,
+                            },
+                        )
+                        raise ZipBombError(
+                            message=f"ZIP analysis timeout after {self.config.limits.zip_analysis_timeout}s - potential zip bomb",
+                            compression_ratio=0,
+                        )
+
+                    # Skip directories
+                    if entry.is_dir():
+                        continue
+
+                    # Track uncompressed size
+                    uncompressed_size = entry.file_size
+                    compressed_size_entry = entry.compress_size
+                    total_uncompressed_size += uncompressed_size
+
+                    # Check individual file compression ratio
+                    if compressed_size_entry > 0:  # Avoid division by zero
+                        compression_ratio = uncompressed_size / compressed_size_entry
+                        max_compression_ratio = max(
+                            max_compression_ratio, compression_ratio
+                        )
+
+                        if compression_ratio > self.config.limits.max_compression_ratio:
+                            logger.error(
+                                "Excessive compression ratio detected",
+                                extra={
+                                    "error_type": "compression_ratio_exceeded",
+                                    "file_name": entry.filename,
+                                    "compression_ratio": compression_ratio,
+                                    "max_ratio": self.config.limits.max_compression_ratio,
+                                },
+                            )
+                            raise ZipBombError(
+                                message=f"Excessive compression ratio detected: {compression_ratio:.1f}:1 for '{entry.filename}'. "
+                                f"Maximum allowed: {self.config.limits.max_compression_ratio}:1",
+                                compression_ratio=compression_ratio,
+                            )
+
+                    # Check for nested archive files
+                    filename_lower = entry.filename.lower()
+                    if any(
+                        filename_lower.endswith(ext)
+                        for ext in [".zip", ".rar", ".7z", ".tar", ".gz", ".bz2"]
+                    ):
+                        nested_archives.append(entry.filename)
+
+                    # Check for excessively large individual files
+                    # Use the configurable max_individual_file_size limit
+                    if uncompressed_size > self.config.limits.max_individual_file_size:
+                        logger.warning(
+                            "Individual file too large",
+                            extra={
+                                "error_type": "file_too_large",
+                                "file_name": entry.filename,
+                                "size_mb": uncompressed_size // (1024 * 1024),
+                                "max_size_mb": self.config.limits.max_individual_file_size
+                                // (1024 * 1024),
+                            },
+                        )
+                        raise CompressionSecurityError(
+                            message=f"Individual file too large: '{entry.filename}' would expand to {uncompressed_size // (1024*1024)}MB. "
+                            f"Maximum allowed: {self.config.limits.max_individual_file_size // (1024*1024)}MB",
+                            error_code=ErrorCode.FILE_TOO_LARGE,
+                        )
+
+                # Check total uncompressed size
+                if total_uncompressed_size > self.config.limits.max_uncompressed_size:
+                    logger.warning(
+                        "Total uncompressed size too large",
+                        extra={
+                            "error_type": "zip_too_large",
+                            "total_size_mb": total_uncompressed_size // (1024 * 1024),
+                            "max_size_mb": self.config.limits.max_uncompressed_size
+                            // (1024 * 1024),
+                        },
+                    )
+                    raise ZipBombError(
+                        message=f"Total uncompressed size too large: {total_uncompressed_size // (1024*1024)}MB. "
+                        f"Maximum allowed: {self.config.limits.max_uncompressed_size // (1024*1024)}MB",
+                        compression_ratio=0,
+                        uncompressed_size=total_uncompressed_size,
+                        max_size=self.config.limits.max_uncompressed_size,
+                    )
+
+                # Check overall compression ratio
+                if total_compressed_size > 0:
+                    overall_compression_ratio = (
+                        total_uncompressed_size / total_compressed_size
+                    )
+                    if (
+                        overall_compression_ratio
+                        > self.config.limits.max_compression_ratio
+                    ):
+                        logger.error(
+                            "Overall compression ratio too high",
+                            extra={
+                                "error_type": "compression_ratio_exceeded",
+                                "overall_ratio": overall_compression_ratio,
+                                "max_ratio": self.config.limits.max_compression_ratio,
+                            },
+                        )
+                        raise ZipBombError(
+                            message=f"Overall compression ratio too high: {overall_compression_ratio:.1f}:1. "
+                            f"Maximum allowed: {self.config.limits.max_compression_ratio}:1",
+                            compression_ratio=overall_compression_ratio,
+                            max_ratio=self.config.limits.max_compression_ratio,
+                        )
+
+                # Reject nested archives (potential security risk)
+                if nested_archives:
+                    logger.warning(
+                        "Nested archives detected",
+                        extra={
+                            "error_type": "zip_nested_archive",
+                            "nested_archives": nested_archives,
+                        },
+                    )
+                    raise CompressionSecurityError(
+                        message=f"Nested archives are not allowed: {', '.join(nested_archives)}",
+                        error_code=ErrorCode.ZIP_NESTED_ARCHIVE,
+                    )
+
+                # Log analysis results
+                logger.debug(
+                    "ZIP analysis: %s files, %sMB uncompressed, max ratio: %.1f:1, overall ratio: %.1f:1",
+                    file_count,
+                    total_uncompressed_size // (1024 * 1024),
+                    max_compression_ratio,
+                    overall_compression_ratio,
+                )
+
+        except zipfile.BadZipFile as err:
+            logger.error("Invalid or corrupted ZIP file", exc_info=True)
+            raise CompressionSecurityError(
+                message="Invalid or corrupted ZIP file",
+                error_code=ErrorCode.ZIP_CORRUPT,
+            ) from err
+        except zipfile.LargeZipFile as err:
+            logger.error("ZIP file too large to process", exc_info=True)
+            raise CompressionSecurityError(
+                message="ZIP file too large to process safely",
+                error_code=ErrorCode.ZIP_TOO_LARGE,
+            ) from err
+        except MemoryError as err:
+            logger.error("ZIP requires excessive memory", exc_info=True)
+            raise ZipBombError(
+                message="ZIP file requires too much memory to process - potential zip bomb",
+                compression_ratio=0,
+            ) from err
+        except (ZipBombError, CompressionSecurityError):
+            # Re-raise our own exceptions
+            raise
+        except Exception as err:
+            logger.error(
+                "Unexpected error during ZIP compression validation",
+                exc_info=True,
+            )
+            raise FileProcessingError(
+                message=f"ZIP validation failed: {str(err)}",
+            ) from err
+
+    def validate(self, file_content: bytes, compressed_size: int) -> None:
+        """
+        Validate the compression ratio of a ZIP file.
+
+        Args:
+            file_content: Raw bytes of the uploaded file.
+            compressed_size: Size of the file after compression in bytes.
+
+        Raises:
+            ZipBombError: If compression ratio exceeds maximum allowed.
+            CompressionSecurityError: If ZIP structure is invalid.
+            FileProcessingError: If unexpected error occurs.
+        """
+        return self.validate_zip_compression_ratio(file_content, compressed_size)

safeuploads/validators/extension_validator.py

@@ -0,0 +1,97 @@
+from __future__ import annotations
+
+import logging
+from typing import TYPE_CHECKING
+
+from .base import BaseValidator
+from ..exceptions import ExtensionSecurityError, ErrorCode
+
+if TYPE_CHECKING:
+    from ..config import FileSecurityConfig
+
+
+logger = logging.getLogger(__name__)
+
+
+class ExtensionSecurityValidator(BaseValidator):
+    """
+    Validates filenames against configured forbidden extensions.
+
+    Attributes:
+        config: File security configuration settings.
+    """
+
+    def __init__(self, config: FileSecurityConfig):
+        """
+        Initialize the validator.
+
+        Args:
+            config: File security configuration settings.
+        """
+        super().__init__(config)
+
+    def validate_extensions(self, filename: str) -> None:
+        """
+        Validate filename against blocked extensions.
+
+        Args:
+            filename: Name of the file to validate.
+
+        Raises:
+            ExtensionSecurityError: If blocked compound or single
+                extension detected in filename.
+        """
+        # Check for compound dangerous extensions first (e.g., .tar.xz, .user.js)
+        filename_lower = filename.lower()
+        for compound_ext in self.config.COMPOUND_BLOCKED_EXTENSIONS:
+            if filename_lower.endswith(compound_ext):
+                logger.warning(
+                    "Dangerous compound extension detected",
+                    extra={
+                        "error_type": "compound_extension_blocked",
+                        "file_name": filename,
+                        "extension": compound_ext,
+                    },
+                )
+                raise ExtensionSecurityError(
+                    message=f"Dangerous compound file extension '{compound_ext}' detected in filename. "
+                    f"Upload rejected for security.",
+                    filename=filename,
+                    extension=compound_ext,
+                    error_code=ErrorCode.COMPOUND_EXTENSION_BLOCKED,
+                )
+
+        # Check ALL extensions in the filename for dangerous ones
+        parts = filename.split(".")
+        if len(parts) > 1:
+            for i in range(1, len(parts)):
+                ext = f".{parts[i].lower()}"
+                if ext in self.config.BLOCKED_EXTENSIONS:
+                    logger.warning(
+                        "Dangerous extension detected",
+                        extra={
+                            "error_type": "extension_blocked",
+                            "file_name": filename,
+                            "extension": ext,
+                        },
+                    )
+                    raise ExtensionSecurityError(
+                        message=f"Dangerous file extension '{ext}' detected in filename. "
+                        f"Upload rejected for security.",
+                        filename=filename,
+                        extension=ext,
+                        error_code=ErrorCode.EXTENSION_BLOCKED,
+                    )
+
+    def validate(self, filename: str) -> None:
+        """
+        Validate the given filename.
+
+        Args:
+            filename: Name of the file to validate.
+
+        Raises:
+            ExtensionSecurityError: If filename extension is not
+                permitted.
+        """
+        return self.validate_extensions(filename)

safeuploads/validators/unicode_validator.py

@@ -0,0 +1,132 @@
+"""Unicode Security Validator Module."""
+
+from __future__ import annotations
+
+import unicodedata
+import logging
+
+from typing import TYPE_CHECKING
+from .base import BaseValidator
+from ..exceptions import UnicodeSecurityError
+
+if TYPE_CHECKING:
+    from ..config import FileSecurityConfig
+
+
+logger = logging.getLogger(__name__)
+
+
+class UnicodeSecurityValidator(BaseValidator):
+    """
+    Validates filenames for Unicode security threats.
+
+    Attributes:
+        config: Runtime configuration for file security rules.
+    """
+
+    def __init__(self, config: FileSecurityConfig):
+        """
+        Initialize the Unicode validator.
+
+        Args:
+            config: Runtime configuration that controls file security rules.
+        """
+        super().__init__(config)
+
+    def validate_unicode_security(self, filename: str) -> str:
+        """
+        Validate filename for unsafe Unicode characters.
+
+        Args:
+            filename: The filename to validate and normalize.
+
+        Returns:
+            The NFC-normalized filename.
+
+        Raises:
+            UnicodeSecurityError: If dangerous Unicode characters are
+                detected in the filename or result from normalization.
+        """
+        if not filename:
+            return filename
+
+        # Check for dangerous Unicode characters
+        dangerous_chars_found = []
+        for i, char in enumerate(filename):
+            char_code = ord(char)
+            if char_code in self.config.DANGEROUS_UNICODE_CHARS:
+                dangerous_chars_found.append((char, char_code, i))
+
+        # If dangerous characters found, reject the file entirely
+        if dangerous_chars_found:
+            char_details = []
+            for char, code, pos in dangerous_chars_found:
+                char_name = unicodedata.name(char, f"U+{code:04X}")
+                char_details.append(
+                    f"'{char}' (U+{code:04X}: {char_name}) at position {pos}"
+                )
+
+            logger.warning(
+                "Dangerous Unicode characters detected",
+                extra={
+                    "error_type": "unicode_security",
+                    "file_name": filename,
+                    "char_codes": [code for _, code, _ in dangerous_chars_found],
+                    "positions": [pos for _, _, pos in dangerous_chars_found],
+                },
+            )
+            raise UnicodeSecurityError(
+                message=f"Dangerous Unicode characters detected in filename: {', '.join(char_details)}. "
+                f"These characters can be used to disguise file extensions or create security vulnerabilities.",
+                filename=filename,
+                dangerous_chars=dangerous_chars_found,
+            )
+
+        # Normalize Unicode to prevent normalization attacks
+        # Use NFC (Canonical Decomposition, followed by Canonical Composition)
+        # This prevents attacks where different Unicode representations of the same text are used
+        normalized_filename = unicodedata.normalize("NFC", filename)
+
+        # Check if normalization changed the filename significantly
+        if normalized_filename != filename:
+            logger.info(
+                "Unicode normalization applied: '%s' -> '%s'",
+                filename,
+                normalized_filename,
+            )
+
+        # Additional check: ensure normalized filename doesn't contain dangerous chars
+        # (some normalization attacks might introduce them)
+        for char in normalized_filename:
+            char_code = ord(char)
+            if char_code in self.config.DANGEROUS_UNICODE_CHARS:
+                char_name = unicodedata.name(char, f"U+{char_code:04X}")
+                logger.error(
+                    "Unicode normalization resulted in dangerous character",
+                    extra={
+                        "error_type": "unicode_normalization_error",
+                        "file_name": filename,
+                        "normalized_filename": normalized_filename,
+                        "char_code": char_code,
+                    },
+                )
+                raise UnicodeSecurityError(
+                    message=f"Unicode normalization resulted in dangerous character: "
+                    f"'{char}' (U+{char_code:04X}: {char_name})",
+                    filename=filename,
+                    dangerous_chars=[(char, char_code, 0)],
+                )
+
+        return normalized_filename
+
+    def validate(self, filename: str) -> str:
+        """
+        Validate a filename for Unicode security issues.
+
+        Args:
+            filename: The name of the file to assess.
+
+        Returns:
+            The validated and normalized filename.
+        """
+        return self.validate_unicode_security(filename)

safeuploads/validators/windows_validator.py

@@ -0,0 +1,95 @@
+"""Windows security validator for filename validation."""
+
+from __future__ import annotations
+
+import os
+import logging
+from typing import TYPE_CHECKING
+
+from .base import BaseValidator
+from ..exceptions import WindowsReservedNameError
+
+if TYPE_CHECKING:
+    from ..config import FileSecurityConfig
+
+
+logger = logging.getLogger(__name__)
+
+
+class WindowsSecurityValidator(BaseValidator):
+    """
+    Validator for Windows reserved device names.
+
+    Attributes:
+        config: File security configuration settings.
+    """
+
+    def __init__(self, config: FileSecurityConfig):
+        """
+        Initialize the validator.
+
+        Args:
+            config: File security configuration settings.
+        """
+        super().__init__(config)
+
+    def validate_windows_reserved_names(self, filename: str) -> None:
+        """
+        Validate filename against Windows reserved device names.
+
+        Args:
+            filename: The filename to validate.
+
+        Raises:
+            WindowsReservedNameError: If filename matches a Windows
+                reserved device name.
+        """
+        # Check iteratively by removing extensions to handle compound extensions
+        # e.g., "CON.tar.gz" -> check "con.tar" and "con"
+        current_name = filename
+
+        while current_name:
+            # Get basename without extension
+            name_without_ext, ext = os.path.splitext(current_name)
+
+            # Normalize: lowercase, strip whitespace
+            name_to_check = name_without_ext.lower().strip()
+            # Remove leading dots to handle hidden files like ".CON.jpg"
+            name_to_check = name_to_check.lstrip(".")
+            # Remove trailing dots to handle cases like "con." or "con.."
+            name_to_check = name_to_check.rstrip(".")
+
+            if name_to_check in self.config.WINDOWS_RESERVED_NAMES:
+                logger.warning(
+                    "Windows reserved name detected",
+                    extra={
+                        "error_type": "windows_reserved_name",
+                        "file_name": filename,
+                        "reserved_name": name_to_check.upper(),
+                    },
+                )
+                raise WindowsReservedNameError(
+                    message=f"Filename '{filename}' uses Windows reserved name '{name_to_check.upper()}'. "
+                    f"Reserved names: {', '.join(sorted(self.config.WINDOWS_RESERVED_NAMES)).upper()}",
+                    filename=filename,
+                    reserved_name=name_to_check.upper(),
+                )
+
+            # If no extension was removed, we're done
+            if not ext or name_without_ext == current_name:
+                break
+
+            current_name = name_without_ext
+
+    def validate(self, filename: str) -> None:
+        """
+        Validate filename against Windows reserved naming rules.
+
+        Args:
+            filename: The filename to validate.
+
+        Raises:
+            WindowsReservedNameError: If filename matches a Windows
+                reserved device name.
+        """
+        return self.validate_windows_reserved_names(filename)