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
SpooledTemporaryFilefor large files - Resource Monitoring: wall-clock time and memory limits enforced via
ResourceMonitorduring 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#xxescapes; 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,
frozensetlookups - 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
SpooledTemporaryFileuses the system default temp directory
Documentation
- API Reference — full public API documentation
- Rate Limiting — production rate limiting guide
- Threat Model — threat categories and mitigations
- Architecture — validation pipeline and data flow
- Integration Checklist — production deployment checklist
License
This project is licensed under the MIT License - see the LICENSE file for details.
Contributing
Contributions welcome! See Contributing Guidelines for guidelines.