Integration Checklist
Production deployment checklist for applications using safeuploads. Each item links to the relevant threat in the Threat Model or the safeuploads feature that addresses it.
HTTPS & Transport Security
- [ ] All upload endpoints served over HTTPS.
- [ ]
Strict-Transport-Securityheader set withmax-age=31536000; includeSubDomains. - [ ] HTTP requests redirected to HTTPS at the reverse proxy.
Rate Limiting
- [ ] Per-IP rate limits applied to upload endpoints (see Rate Limiting guide).
- [ ] Per-user rate limits applied after authentication.
- [ ] Reverse proxy layer enforces body size and request rate before traffic reaches the application.
- [ ]
429 Too Many Requestsresponses include aRetry-Afterheader.
File Validation Configuration
- [ ]
FileValidatorinstantiated with explicitFileSecurityConfig(not relying solely on defaults). - [ ]
SecurityLimitstuned for your use case:max_image_size— appropriate for expected upload sizes.max_image_pixels— default 89,478,485 (Pillow'sImage.MAX_IMAGE_PIXELS); lower it to the largest image your application needs. An image whose header declares more pixels is rejected withIMAGE_DIMENSIONS_EXCEEDED, and one whose dimension header is missing or malformed withIMAGE_INVALID_STRUCTURE.max_zip_size— set to the maximum acceptable ZIP size.max_activity_file_size— set if accepting GPX/TCX/FIT. FIT uploads must be structurally valid (headers, CRCs, sections covering the file exactly) or are rejected withFIT_INVALID_STRUCTURE.max_gzip_size— set if accepting gzip files.max_pdf_size— default 50 MB; set if accepting PDFs. The whole PDF is read into memory during inspection.max_pdf_uncompressed_size— default 200 MB, the total Flate output of one PDF's streams; a PDF over it, or overmax_compression_ratiotimes its file size, is rejected withPDF_STREAM_BOMB.max_compression_ratio— default 100:1 is reasonable for most workloads; lower for stricter environments.max_validation_time_seconds— default 30 s wall-clock; lower in latency-sensitive services.max_validation_memory_mb— default 512 MB of peak-RSS growth; adjust based on container memory limits.
- [ ]
allow_nested_archivesleftFalseunless needed. When enabled it requiresscan_zip_content=True(the constructor raisesFileSecurityConfigurationErrorotherwise), and every inner ZIP is inspected like the top level; one that is oversized, corrupt or uninspectable is rejected. - [ ]
ALLOWED_*_TYPESreviewed and narrowed to the MIME types your application accepts and the extensions each may carry. - [ ]
FileSecurityConfigurationErrorfrom theFileValidatorconstructor handled at startup: it is raised for any error-severity configuration issue (a removedALLOWED_*_MIMESorALLOWED_*_EXTENSIONSsetting, invalid limit types, non-positive limits, an empty allowed-types mapping, a MIME type with no extensions, empty or uppercase extension entries, empty block lists or reserved names, reserved names that are not lowercase, an emptyBLOCKED_PDF_NAMESor an entry that is not a bare PDF name, a content scan window smaller than an image, activity or PDF size limit), including sets overridden on the instance; warnings are only logged.
Content Analysis
- [ ]
enable_content_analysisset toTrueif accepting files from untrusted users. It covers image, activity and PDF uploads; ZIP contents are scanned entry by entry by the ZIP inspector. - [ ]
content_scan_max_sizeat leastmax_image_size,max_activity_file_sizeandmax_pdf_size(default 50 MB). With content analysis on, a smaller window is a configuration error. - [ ] Consider supplemental antivirus scanning (ClamAV or similar) for high-risk environments.
Image Processing
safeuploads checks the dimensions an image header declares but does not decode pixel data, so decoder bugs and corrupt image bodies are not caught (see Image Decompression Bombs).
- [ ] Images are decoded, resized or re-encoded in an isolated worker process or container with its own memory and time limits, not in the process that serves requests.
- [ ] The decoder's own pixel limit stays set at or below
max_image_pixels(with Pillow, keepImage.MAX_IMAGE_PIXELS; never set it toNone). - [ ] A re-encoded copy is stored or served instead of the uploaded bytes, so metadata (EXIF, GPS), data appended to the image and secondary images are dropped.
- [ ] Image decoder libraries (Pillow, libjpeg-turbo, libpng, libwebp, and libheif with libde265 for HEIC) kept up to date.
- [ ] A host that cannot decode HEIC removes
image/heicandimage/heiffromALLOWED_IMAGE_TYPES. - [ ] HEIC is decoded with the decoder's own limits on, such as libheif's security limits, which also bound the HEVC bitstream size that safeuploads does not read.
PDF Handling
safeuploads rejects PDFs with active content, encryption, ambiguous structure or oversized streams, but does not render them (see PDF Active Content and PDF Parser Differentials).
- [ ]
BLOCKED_PDF_NAMESreviewed. AddURIwhen PDFs are opened by other users on Windows readers, which may followfile:or UNC links and leak NTLM credentials. - [ ] PDFs are rendered, thumbnailed or text-extracted in an isolated worker process or container with its own memory and time limits, since font and image decoder bugs are triggered by rendering.
- [ ] PDFs are served with
Content-Disposition: attachment, or shown in a sandboxed viewer from a separate origin, never inline from the application's origin. - [ ] PDF libraries and viewers (pdf.js, PDFium, Poppler, MuPDF) kept up to date.
- [ ] Users are told how to resubmit a rejected document: encrypted PDFs (including owner-password ones), LZW or RunLength streams and broken files that readers repair silently are rejected; printing to a new PDF usually produces an accepted file.
Audit Logging
- [ ]
enable_audit_loggingset toTruein production. - [ ] Log handler attached to
safeuploads.auditlogger (or parentsafeuploadslogger). - [ ] Structured log output configured (JSON formatter recommended for log aggregation).
- [ ] Log storage retention policy defined (minimum 90 days recommended for security incident investigation).
- [ ] Alerting configured for
THREAT_DETECTEDandRESOURCE_LIMITaudit event types.
Error Handling
- [ ] Application catches specific exception types
(
FileSizeError,ExtensionSecurityError, etc.) and returns user-appropriate messages. Malformed or forbidden XML (XmlSecurityError), rejected PDFs (PdfSecurityError), content threats (ContentThreatError) and images over the pixel limit (ImageDimensionError) areFileValidationErrorsubclasses. - [ ]
FileProcessingError(includingResourceLimitError) is caught as well: it is not aFileValidationError, and it is raised only for internal errors and exceeded resource limits. - [ ] Internal error details from exceptions are not forwarded to API responses.
- [ ]
ErrorCodevalues used for machine-readable API error responses, not raw exception messages. AZipContentErrorcarries the code of the first threat found (for exampleZIP_DIRECTORY_TRAVERSAL), not alwaysZIP_CONTENT_THREAT, andthreatslists all messages. - [ ] Generic 500 errors for unexpected failures — no stack traces in production responses.
File Storage Security
- [ ] Uploaded files stored outside the web-accessible document root.
- [ ] Uploaded files renamed to random identifiers (UUIDs);
original filenames stored in metadata only. If the stored name
needs an extension, take it from
ValidationResult.filename, not from the uploaded name: it is sanitized, and its extension is one the configuration lists for the detected MIME type.mime_typealone cannot choose it, since GPX and TCX share their XML types. Content is not checked as GPX rather than TCX, so an importer must still handle XML that does not match its extension. - [ ] Storage directory permissions restrict access to the
application user only (
0700or equivalent). - [ ] If serving uploaded files back to users, use:
Content-Disposition: attachmentto force download.Content-Typeset fromValidationResult.mime_type, not from the filename.X-Content-Type-Options: nosniffheader.
Security Headers (for serving uploaded content)
- [ ]
Content-Security-Policyconfigured to prevent inline script execution if serving HTML/SVG content. - [ ]
X-Content-Type-Options: nosniffon all responses. - [ ]
X-Frame-Options: DENYorSAMEORIGINas appropriate. - [ ]
Cache-Control: no-storefor sensitive uploaded content.
Resource Limits
- [ ] Container or process memory limits set — safeuploads
max_validation_memory_mbshould be below the container limit. The monitor measures the increase in process-wide peak RSS, so it cannot bound validation memory by itself (an earlier, higher peak hides later allocations) and other work in the same process can also trip it; the container limit stays the hard bound. On Windows memory accounting is disabled and only the time limit applies. - [ ] Both limits are checked at loop boundaries (upload
streaming, ZIP entry loops, gzip decompression, each XML
chunk, each JPEG segment before the frame header, each HEIC
box and item entry, PDF tokenizing and stream inflation) and on exit; a single blocking call, such as one
zipfilecentral-directory parse or one libmagic call, is not interrupted mid-call. AResourceLimitErrorkeeps its ownRESOURCE_TIME_EXCEEDEDorRESOURCE_MEMORY_EXCEEDEDcode. - [ ] Request timeout configured at the reverse proxy and
application level — should be above
max_validation_time_seconds. - [ ] Disk space monitored for temporary file spill
(
SpooledTemporaryFileuses the system temp directory). - [ ] Consider setting
TMPDIRenvironment variable to a dedicated partition with quota enforcement.
Dependency Management
- [ ]
safeuploadspinned to a specific version inrequirements.txtorpyproject.toml. - [ ]
pip-auditorsafetyrun in CI to detect known vulnerabilities in dependencies. - [ ]
defusedxmlandpython-magicdependencies kept up to date. - [ ]
libmagicsystem library installed and up to date on the deployment target. Without itimport safeuploadsfails withImportError. If the detector fails to initialize, every upload is rejected withMIME_DETECTION_FAILED; there is no extension-based fallback.
Testing
- [ ] Unit tests verify validation rejects known-bad payloads for each file type your app accepts.
- [ ] Integration tests confirm error responses match the expected format and status codes.
- [ ] Fuzz tests run periodically (
pytest -m fuzz) to catch edge cases. - [ ] Penetration testing includes crafted uploads: ZIP bombs, polyglot files, XXE payloads, PDFs with JavaScript or obfuscated names, traversal filenames.
Monitoring & Incident Response
- [ ] Upload validation metrics tracked (success rate, failure rate, latency).
- [ ] Anomaly detection on upload volume and failure rate.
- [ ] Incident response runbook covers: detected malware upload, resource exhaustion, and audit log review procedures.
- [ ] Contact information for security reports published
(
SECURITY.mdor equivalent).