Skip to content

safeuploads

Secure file upload validation for Python 3.11+ applications. Catches dangerous filenames, malicious extensions, Windows reserved names, and compression-based attacks before you accept an upload.

Features

  • Framework-agnostic async and sync validation (FastAPI, generic)
  • Filename sanitization and Unicode security checks
  • Extension validation with configurable allow/block lists
  • ZIP bomb detection, nested archive inspection, and recursive structure protection
  • MIME type verification with file signature validation
  • Activity file support (.gpx, .tcx, .fit) with XXE-safe XML parsing and FIT structure validation
  • Gzip archive validation with decompression bomb detection
  • PDF validation that rejects JavaScript, embedded files, launch and remote actions, encryption, ambiguous structure and stream bombs
  • Streaming validation for memory-efficient large file processing
  • Resource monitoring (wall-clock time and memory limits)
  • Content analysis with malware signature and polyglot detection
  • Structured audit logging with correlation IDs
  • Rich exception hierarchy with machine-readable error codes
  • Zero configuration required—secure defaults out of the box

Installation

pip install safeuploads

For FastAPI integration:

pip install safeuploads[fastapi]

Quick Start

from fastapi import FastAPI, UploadFile, HTTPException
from safeuploads import FileValidator
from safeuploads.exceptions import FileValidationError

app = FastAPI()
validator = FileValidator()

@app.post("/upload")
async def upload_image(file: UploadFile):
    try:
        result = await validator.validate_image_file(file)
    except FileValidationError as e:
        raise HTTPException(status_code=400, detail=str(e))

    # Store under a generated name; serve with the detected type
    return {"filename": result.filename, "content_type": result.mime_type}

Every validation method returns a ValidationResult with the sanitized filename and the mime_type detected from the content. A file whose extension is not one allowed for its detected type, such as a WebP named photo.jpg, is rejected with MimeTypeError (EXTENSION_MIME_MISMATCH).

For synchronous code or worker threads, use the *_sync methods. They block the calling thread and return the same result:

from safeuploads import FileValidator

validator = FileValidator()

with open("activity.gpx", "rb") as fh:
    result = validator.validate_activity_file_sync(fh, "activity.gpx")

Calling a *_sync method on a thread running an asyncio event loop raises RuntimeError; await the async method there instead.

Configuration

from safeuploads import FileValidator, FileSecurityConfig

# Use default secure configuration
validator = FileValidator()

# Or customize limits
config = FileSecurityConfig()
config.limits.max_image_size = 10 * 1024 * 1024  # 10 MiB
config.limits.max_image_pixels = 40_000_000  # 40 megapixels
config.limits.max_compression_ratio = 50

# Allowed content: each MIME type maps to the extensions its
# content may carry
config.ALLOWED_IMAGE_TYPES = {
    "image/jpeg": frozenset({".jpg", ".jpeg"}),
    "image/png": frozenset({".png"}),
}

# Opt in to strict ZIP checking: decompress every entry to
# reject archives with forged central-directory metadata
config.limits.verify_zip_decompression = True

validator = FileValidator(config=config)

# Optionally offload blocking inspection to a bounded pool
from concurrent.futures import ThreadPoolExecutor

pooled_validator = FileValidator(
    config=config,
    executor=ThreadPoolExecutor(max_workers=4),
)

Exception Handling

from safeuploads.exceptions import (
    FileValidationError,      # Base exception
    FileSizeError,            # File too large
    ExtensionSecurityError,   # Dangerous extension
    ZipBombError,             # Compression attack
)
# FileProcessingError (internal errors, ResourceLimitError) is not a
# FileValidationError; catch it separately.

try:
    await validator.validate_image_file(file)
except FileSizeError as err:
    return {"error": "File too large", "max_size": err.max_size}
except ExtensionSecurityError as err:
    return {"error": "File type not allowed", "extension": err.extension}
except FileValidationError as err:
    return {"error": str(err), "code": err.error_code}

Current Status

Implemented

  • Filename Security: Unicode normalization, directory traversal prevention, Windows reserved names blocking
  • Extension Validation: Allow/block lists with configurable rules, dangerous extension detection
  • Compression Security: ZIP bomb detection, nested archive inspection, recursive structure and quine detection, size and ratio limits, optional strict decompression verification
  • Content Inspection: Deep ZIP content analysis with configurable depth and entry limits
  • MIME Type Verification: Magic number validation for images, ZIP, activity files, gzip, and PDF, with the extension required to match the detected type
  • Streaming Validation: Memory-efficient processing via SpooledTemporaryFile for large files
  • Resource Monitoring: wall-clock time and memory limits enforced via ResourceMonitor during the work
  • Image Dimension Limits: Header-only pixel count check for PNG, JPEG, WebP and HEIC that rejects decompression (pixel) bombs before the host decodes them
  • Activity File Support: GPX, TCX, and FIT file validation with XXE-safe XML parsing and FIT structure checks
  • Gzip Support: Gzip archive validation with decompression bomb detection
  • PDF Support: Whole-file PDF parsing that rejects names from a configurable block-list (BLOCKED_PDF_NAMES: JavaScript, launch, embedded files, rich media, XFA, form submission, remote documents), also inside object streams and behind #xx escapes; encrypted PDFs; structures readers could parse differently; and Flate streams past a size or ratio limit
  • Content Analysis: Optional malware signature, web shell, and polyglot file detection
  • Audit Logging: Structured security event logging with correlation IDs via contextvars
  • Performance Optimizations: Pre-compiled pattern sets, frozenset lookups
  • Rich Exception System: Machine-readable error codes with detailed context
  • Fuzzing Tests: Hypothesis-based property testing for filenames, ZIP, images, and config

Known Limitations

  • No built-in rate limiting (application-level concern — see Rate Limiting guide)
  • MIME detection covers first 8 KB; advanced polyglot attacks may require enable_content_analysis
  • Images are not decoded: only their dimension headers are checked, so decode and re-encode uploads in an isolated process (see the integration checklist)
  • PDFs are not rendered, so font and image decoder bugs are not caught; encrypted PDFs, LZW or RunLength streams and broken files that readers repair silently are rejected
  • SpooledTemporaryFile uses the system default temp directory

Documentation

License

This project is licensed under the MIT License - see the LICENSE file for details.

Contributing

Contributions welcome! See Contributing Guidelines for guidelines.

Built with ❤️ from Portugal | Part of the Endurain ecosystem