Most upload vulnerabilities are not exotic: they come from default size limits nobody set, client filenames written straight to disk, storage the application can execute, and scanners bolted on after files are already served. This guide is the engineering companion to the File Upload Security Guide, which explains the threats (web shells, polyglots, zip slip, parser exploits). Here the focus is how to build the handling pipeline: the concrete limits in common web servers and frameworks, direct-to-storage uploads with signed policies, an asynchronous quarantine and scanning design, scanner configuration, serving files back, and how to test and measure the result. It is for developers, platform engineers and AppSec teams who own upload features, and maps each step to OWASP ASVS 5.0 chapter V5 File Handling.
Key takeaways
- Set every limit explicitly, at every layer. Proxy, server, framework and application each have their own body and file limits, and several framework defaults are unlimited.
- Never let the client name the file. Generate the storage key server-side; keep the original name as encoded display metadata only.
- Quarantine before release. Uploads land in a non-served, non-executable area and move to clean storage only after validation and scanning pass.
- Signed direct uploads need tight policies. A pre-signed URL or POST policy without key prefix, size range and short expiry is an open write door.
- The pipeline's identities are attack surface. Upload, scanning and publishing services each need their own narrowly scoped credentials, and no one else may write to the buckets they use.
Requirements first: what ASVS 5.0 expects
ASVS 5.0 starts with documentation: V5.1.1 (Level 2) requires that each upload feature defines permitted file types, expected extensions and maximum size including unpacked size, plus how files are made safe for download and what happens when malware is detected. Writing this per feature turns vague "secure uploads" into testable rules.
| ASVS 5.0 requirement | Level | What it demands | Where it lives in the pipeline |
|---|---|---|---|
| V5.2.1 | 1 | Accept only files the application can process without loss of performance or denial of service | Proxy and framework limits |
| V5.2.2 | 1 | Extension matches an expected extension and content matches the type (magic bytes, image rewriting, specialised libraries); at Level 2 for all files | Validation worker |
| V5.2.3 | 2 | Check archives against maximum uncompressed size and file count before uncompressing | Archive handler |
| V5.2.4 | 3 | Per-user size quota and maximum number of files | Upload API |
| V5.2.5 | 3 | Reject archives containing symlinks unless specifically required | Archive handler |
| V5.2.6 | 3 | Reject images above a maximum pixel size (pixel flood) | Image processor |
| V5.3.1 | 1 | Uploaded files in public folders are never executed as server-side code | Storage and web server config |
| V5.3.2 | 1 | File paths built from internal data, not user filenames | Storage key generation |
| V5.3.3 | 3 | Decompression ignores user-provided path information (zip slip) | Archive handler |
| V5.4.1, V5.4.2 | 2 | Validate or ignore submitted filenames; set and encode the filename in Content-Disposition (RFC 6266) | Download service |
| V5.4.3 | 2 | Scan files from untrusted sources with antivirus | Scanning worker |
For the wider standard see the OWASP ASVS Guide.
Size and count limits at every layer
An upload passes through several components, each with its own limit. The smallest wins, but if an inner layer has no limit, an attacker who reaches it directly (for example on an internal route or a misrouted host) faces none. The table lists limits documented by each project; defaults are from official documentation at the time of writing and change between versions, so set values explicitly rather than trusting them.
| Layer | Setting | Documented default | Notes |
|---|---|---|---|
| nginx | client_max_body_size | 1m | Returns 413 when exceeded; 0 disables the check. Set per location for upload routes |
| nginx | client_body_timeout | 60s | Time between reads, not total; returns 408. Lower it to limit slow uploads |
| PHP | upload_max_filesize, post_max_size, max_file_uploads | 2M, 8M, 20 | upload_max_filesize must be smaller than post_max_size; both are INI_PERDIR, so per-directory files can change them |
| ASP.NET Core (Kestrel) | KestrelServerOptions.Limits.MaxRequestBodySize | 30,000,000 bytes | Override per action with [RequestSizeLimit] |
| ASP.NET Core | FormOptions.MultipartBodyLengthLimit | 134,217,728 bytes | Files above MemoryBufferThreshold (64 KB) spill to ASPNETCORE_TEMP |
| IIS | maxAllowedContentLength | 30,000,000 bytes | Request filtering, in web.config |
| Django | DATA_UPLOAD_MAX_MEMORY_SIZE, DATA_UPLOAD_MAX_NUMBER_FILES | 2.5 MB (excludes file data for request.POST), 100 | FILE_UPLOAD_MAX_MEMORY_SIZE only controls when uploads spool to disk, not whether they are accepted; enforce file size in a validator |
| Express with Multer | limits.fileSize, limits.files, limits.parts | Infinity | Set all three; the README warns never to register Multer as global middleware |
| Spring Boot | spring.servlet.multipart.max-file-size, max-request-size | Version dependent; set explicitly | Also set spring.servlet.multipart.location to a dedicated temporary directory |
- Stream large files: Microsoft's guidance is that buffering many concurrent uploads can exhaust memory or disk; stream with
MultipartReader(or the equivalent) where size or frequency is high, and the same applies to Multer'smemoryStorage. - Control temporary directories: PHP
upload_tmp_dir, DjangoFILE_UPLOAD_TEMP_DIR, nginxclient_body_temp_pathandASPNETCORE_TEMPshould point to a dedicated, size-capped, non-executable volume, not a shared/tmp. - Add quotas and rate limits: per-user bytes and file counts (ASVS V5.2.4) and per-client request rates stop storage exhaustion that individual size limits cannot. See the OWASP API Top 10 API4 Unrestricted Resource Consumption Guide.
- Release resources on failure: OWASP's A10:2025 example is an upload path that leaks resources whenever an upload fails, until the service locks up. Clean up partial and temporary files in every error path. See the Secure Error Handling and Logging Guide.
Names, keys and metadata
ASVS V5.3.2 requires file paths built from internally generated or trusted data. Microsoft's documentation says the same in framework terms: never trust IFormFile.FileName, generate a name with Path.GetRandomFileName(), and HTML-encode the original if you display it.
- Storage key: a random identifier (UUID or 128-bit random value) plus, optionally, a tenant prefix you derive from the authenticated session, never from the request body. No user-supplied characters reach the path. See the Path Traversal Guide.
- Metadata record: store original filename, declared type, detected type, size, SHA-256 hash, uploader principal, tenant, timestamps and scan state in a database row keyed by the storage ID.
- Original names, if kept: the OWASP File Upload Cheat Sheet recommends a maximum length and a safe character subset, and rejecting leading periods, consecutive periods and leading hyphens or spaces. Treat it as display text, encode it on output (V5.4.2) and never use it in a path, shell command or SQL statement.
- Hash for decisions: the content hash lets you deduplicate, block known-bad files and find every copy after an incident.
- Strip embedded metadata: image re-encoding removes EXIF data such as GPS coordinates, which protects the uploader's privacy as well as removing a place to hide content.
Content validation in order
Run cheap checks first so expensive parsers only see plausible files. Each step narrows what the next must handle.
- Authenticate, authorise and check CSRF: the cheat sheet requires uploads to be tied to an identifiable user and protected against cross-site request forgery.
- Size and count: enforced at the proxy and framework, re-checked in code.
- Extension allowlist: on the decoded name, lower-cased, matching the feature's documented list (V5.1.1). Reject double extensions and names containing a colon.
- Declared
Content-Type: a quick consistency check only; the cheat sheet notes it is trivially spoofed. - Magic bytes: confirm the signature matches the extension (for example JPEG begins
FF D8 FF). Necessary but, per OWASP, commonly bypassed on its own. - Parse or rewrite: decode images and re-encode them to an allowed format with resource limits and pixel caps (V5.2.6); validate Office files with a strict parser (the cheat sheet names Apache POI); apply content disarm and reconstruction to supported document types.
- Archive checks: before extraction, read the directory to enforce total uncompressed size and entry count (V5.2.3), reject symlinks (V5.2.5) and ignore stored paths (V5.3.3). Prefer not accepting archives at all; the cheat sheet does not recommend ZIP uploads.
- Scan: antivirus and, for higher-risk flows, sandbox analysis (V5.4.3).
XML-based formats (SVG, DOCX, XLSX) need parsers with DTDs and external entities disabled; see the XXE Guide.
Direct-to-storage uploads with signed policies
Large files are often sent straight from the browser to object storage using a pre-signed URL or POST policy, so the application never handles the bytes. That moves enforcement into the policy document, and the validation pipeline must then be triggered by storage events instead of the request.
Amazon S3 POST policies show what a tight policy contains. Each condition is enforced by the service at upload time:
| Condition | Example | Purpose |
|---|---|---|
expiration | Minutes after issue | Limits replay of a leaked policy |
bucket | Exact match on the quarantine bucket | Uploads can never land in a served bucket |
key | ["starts-with", "$key", "quarantine/<tenant>/<uuid>"] or an exact key | Pins the object to a server-generated location |
content-length-range | ["content-length-range", 1, 10485760] | Enforces minimum and maximum size in bytes |
Content-Type | ["starts-with", "$Content-Type", "image/"] | Consistency only; content is still verified after upload |
acl | Private | Prevents uploads made public by the client |
- Every form field needs a condition: AWS documents that fields without a matching condition are rejected (with named exemptions such as
x-ignore-prefixed fields), and that a missing policy places no limit on writes. - Prefer exact keys: issue one signed policy per upload with an exact, server-generated key rather than a broad prefix.
- Validate on arrival: a storage event (object created) triggers the validation and scanning worker. Until it records a clean result, the object is unreachable by users.
- Lock down the bucket itself: block public access, deny writes from any principal other than the signing role, and alert on policy changes that widen access. Other providers offer equivalent controls (for example shared access signatures in Azure and signed URLs in Google Cloud Storage); check each one's way of constraining size and expiry.
The Twilio TaskRouter SDK compromise shows why: a bucket policy granted write access to any AWS principal after a troubleshooting change that was never reverted, and an unknown party replaced a JavaScript SDK file served to customers. See the Cloud Storage Exposure Playbook.
Quarantine, scanning and release
Microsoft's upload guidance recommends scanning before files are stored or made available and, at high volume, moving scanning to a background service that holds files in quarantine and tracks scan status in a database record. Model this as a state machine so every file has exactly one state.
| State | Location | Who can read | Exit condition |
|---|---|---|---|
| Received | Quarantine store | Validation worker only | Structural checks pass or fail |
| Validated | Quarantine store | Scanning worker only | Scan returns clean, infected or error |
| Clean | Release store (rewritten output where applicable) | Download service, on behalf of authorised users | Retention expiry or user deletion |
| Rejected or infected | Isolated evidence store or deleted | Security team | Investigation complete |
| Scan error or limit exceeded | Quarantine store | Nobody until retried | Retry succeeds; otherwise treat as rejected |
Scanner configuration
Treat the scanner's own limits as security settings. ClamAV's clamd.conf sample documents StreamMaxLength (default 100M), MaxScanSize (400M), MaxFileSize (100M), MaxRecursion (17), MaxFiles (10000) and MaxScanTime (120000 ms). A file that exceeds them may be only partly scanned, so set AlertExceedsMax yes (default no), which flags such files with names starting Heuristics.Limits.Exceeded, and treat that result as a rejection. Keep the upload size limit below the scanner's limits so nothing reaches the scanner that it cannot fully inspect. ClamAV also notes that the LocalSocket is world accessible unless LocalSocketMode is set.
- Fail closed: a scanner timeout, crash or signature update failure must leave the file in quarantine, not release it.
- Isolate the workers: run validators, image libraries and scanners in containers with no network egress except signature updates, read-only access to quarantine, and write access only to their output location. Parsers are the code most likely to be exploited by a malicious file.
- Rescan on signature updates: for files kept long term, periodic rescans catch malware that was unknown at upload time.
Serving files back safely
- No execution, ever: ASVS V5.3.1 requires that uploaded files are never executed as server-side code. Serve from object storage or a separate host, never from a directory the application server interprets, and disable per-directory overrides (
.htaccess,web.config) on any filesystem location. - Authorise every download: check the requester against the metadata record, then issue a short-lived signed URL or stream the file. Object identifiers alone are not authorisation.
- Set headers server-side:
Content-Typefrom your detected type,X-Content-Type-Options: nosniff, andContent-Disposition: attachmentwith an encoded filename (V5.4.1, V5.4.2) for anything not meant to render inline. - Use a separate origin for user content: a cookieless domain stops uploaded HTML or SVG from running script in your application's origin. A strict
Content-Security-Policyon that origin adds a second layer; see the Content Security Policy Guide.
Where identity fits
An upload pipeline is a small system of non-human identities: the API that signs policies, the validation and scanning workers, the publisher that moves clean files, and any CDN origin identity. Give each its own role with the narrowest action set (the signing role can create objects only under the quarantine prefix; the scanner can read quarantine and write a result; only the publisher can write to the release store). Use short-lived workload credentials rather than static keys, and keep scanners away from production data stores. See the OWASP NHI Top 10 NHI5 Overprivileged NHI Guide.
Implementation and testing
- Inventory every upload path: forms, APIs, chunked and resumable uploads, signed direct uploads, email ingestion and import features. Each needs a V5.1.1 definition.
- Set limits explicitly: proxy, server and framework values from the table above, deployed as configuration with tests that assert them.
- Run new validation in log-only mode: record what would be rejected for two to four weeks, review false positives with product owners, then enforce one endpoint at a time behind a feature flag so it can be rolled back without a redeploy.
- Introduce quarantine and the state machine: start with new uploads; migrate stored files by rescanning them in the background.
- Test with standard cases: OWASP WSTG-BUSL-08 (unexpected file types) and WSTG-BUSL-09 (malicious files) cover extension tricks, signature changes and XML attacks. Use the EICAR test file to confirm scanning and quarantine end to end. WSTG notes that decompression bomb tests need written approval because they can disrupt service and raise cloud costs.
- Add regression tests to CI: a corpus of rejected samples (renamed executables, oversized images, archives with traversal paths) that must fail, and clean samples that must pass.
Decision guidance
- Proxy through the application or upload direct to storage: proxy for small files and simple apps where synchronous validation is enough; go direct with signed policies when files are large or volumes high, accepting that validation becomes asynchronous and the user sees a "processing" state.
- Synchronous or asynchronous scanning: synchronous scanning gives immediate feedback but ties request time to scanner latency; asynchronous quarantine scales and fails closed more cleanly.
- Rewrite or scan: rewriting images and disarming documents removes active content that scanners may not recognise; scanning catches known malware in formats you cannot rewrite. Higher-risk flows (files opened by staff from unknown senders) justify both.
- Small versus large organisations: a small team can use the framework's limits, generated names, private object storage with signed downloads and a managed scanning service. Large estates should offer a shared upload service with the state machine built in, so product teams do not each rebuild it.
Detection and measurement
Log upload events with the OWASP Logging Vocabulary names (upload_complete, upload_validation with the check and result, upload_delete), the uploader principal, hash and detected type. On hosts, watch for new files in web-served directories and web server processes spawning shells, the behaviour behind ATT&CK T1505.003 Web Shell that often follows T1190 Exploit Public-Facing Application.
- Pipeline coverage: share of upload paths (including direct and chunked) that pass through quarantine and scanning. Target 100%.
- Executable upload locations: count of storage locations where uploaded content could be interpreted by a server. Target zero.
- Explicit limits: share of services with size, count and timeout limits set in configuration rather than defaults.
- Rejection and scan outcomes: rejection reasons, infected counts and
Heuristics.Limits.Exceededresults per week; sudden changes indicate probing or a broken check. - Time in quarantine: median and 95th percentile time from upload to clean; growth means scanner capacity problems that teams will be tempted to bypass.
Framework mapping
| Framework | Reference | Relevance |
|---|---|---|
| OWASP ASVS 5.0 | V5.1.1, V5.2.1 to V5.2.6, V5.3.1 to V5.3.3, V5.4.1 to V5.4.3 | Documentation, validation, storage and download requirements |
| OWASP WSTG | WSTG-BUSL-08, WSTG-BUSL-09 | Test cases for unexpected and malicious files |
| MITRE CWE | CWE-434 Unrestricted Upload of File with Dangerous Type; CWE-22 path traversal | Core weaknesses |
| NIST SP 800-53 Rev. 5 | SI-10 Information Input Validation, SI-3 Malicious Code Protection | Validation and scanning controls |
| CIS Controls v8.1 | Control 16 Application Software Security; Safeguard 10.1 Deploy and Maintain Anti-Malware Software | Secure development and scanning |
| ISO/IEC 27001:2022 Annex A | A.8.28 Secure coding, A.8.7 Protection against malware | Management system controls |
| MITRE ATT&CK v20 | T1505.003 Web Shell, T1190 Exploit Public-Facing Application | What a failed upload control enables |
Common failure patterns
- Unlimited framework defaults: Multer's file size and count limits default to Infinity, so a missing
limitsobject leaves the service open to storage and memory exhaustion. - Global upload middleware: registering a multipart parser on every route lets attackers upload to endpoints that never expected files.
- Broad signed policies: pre-signed uploads with no size range, a wide key prefix and long expiry, pointed at the bucket that also serves content.
- Scanner limits silently exceeded: files larger or deeper than the scanner's limits are passed as clean because
AlertExceedsMaxwas left off. - Temporary changes to storage permissions that become permanent: as in the Twilio TaskRouter case, a write grant added for troubleshooting stays for years.
- Fail-open scanning: when the scanner is down, a fallback releases files "to avoid user impact".
Practitioner checklist
- Document types, extensions, maximum and unpacked sizes and malware behaviour for every upload feature (ASVS V5.1.1).
- Set body, file, count and timeout limits explicitly at proxy, server and framework layers, and test them in CI.
- Generate storage keys server-side; keep original names as encoded metadata only.
- Validate in order: extension allowlist, magic bytes, strict parsing or rewriting, archive limits, then scanning.
- Route every upload, including signed direct uploads, through a quarantine state machine that fails closed.
- Constrain signed policies with exact keys, size ranges, private ACLs and short expiry; block other writers to the bucket.
- Configure scanner limits above upload limits and treat limit-exceeded results as rejections.
- Serve files from a separate, cookieless origin with server-set
Content-Type,nosniffand attachment disposition, after an authorisation check. - Give upload, scanning and publishing services separate least-privilege identities with short-lived credentials.
- Run WSTG-BUSL-08 and BUSL-09 tests and an EICAR end-to-end check before each major release.
Standards and references
- OWASP: Application Security Verification Standard 5.0
- OWASP: File Upload Cheat Sheet
- OWASP: WSTG-BUSL-09 Test Upload of Malicious Files
- Amazon Web Services: Creating a POST Policy
- Microsoft Learn: Upload files in ASP.NET Core
- Django: Settings reference
- nginx: Module ngx_http_core_module
- Cisco Talos: ClamAV clamd.conf sample
Related NHI Mgmt Group resources: File Upload Security Guide · Path Traversal Guide · XXE Guide · Secure Error Handling and Logging Guide · Web Shell Response Playbook