Join our Newsletter — 33% off our NHI Course
Home› Guides› Secure File Upload Handling Guide: Validation, Storage and…
Guide Application Security

Secure File Upload Handling Guide: Validation, Storage and Scanning

PDF for newsletter subscribers · free to read online

← All guides
By NHI Mgmt Group, edited by Lalit Choda Updated 26 October 2026 17 min read
On this page

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 requirementLevelWhat it demandsWhere it lives in the pipeline
V5.2.11Accept only files the application can process without loss of performance or denial of serviceProxy and framework limits
V5.2.21Extension matches an expected extension and content matches the type (magic bytes, image rewriting, specialised libraries); at Level 2 for all filesValidation worker
V5.2.32Check archives against maximum uncompressed size and file count before uncompressingArchive handler
V5.2.43Per-user size quota and maximum number of filesUpload API
V5.2.53Reject archives containing symlinks unless specifically requiredArchive handler
V5.2.63Reject images above a maximum pixel size (pixel flood)Image processor
V5.3.11Uploaded files in public folders are never executed as server-side codeStorage and web server config
V5.3.21File paths built from internal data, not user filenamesStorage key generation
V5.3.33Decompression ignores user-provided path information (zip slip)Archive handler
V5.4.1, V5.4.22Validate or ignore submitted filenames; set and encode the filename in Content-Disposition (RFC 6266)Download service
V5.4.32Scan files from untrusted sources with antivirusScanning 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.

LayerSettingDocumented defaultNotes
nginxclient_max_body_size1mReturns 413 when exceeded; 0 disables the check. Set per location for upload routes
nginxclient_body_timeout60sTime between reads, not total; returns 408. Lower it to limit slow uploads
PHPupload_max_filesize, post_max_size, max_file_uploads2M, 8M, 20upload_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.MaxRequestBodySize30,000,000 bytesOverride per action with [RequestSizeLimit]
ASP.NET CoreFormOptions.MultipartBodyLengthLimit134,217,728 bytesFiles above MemoryBufferThreshold (64 KB) spill to ASPNETCORE_TEMP
IISmaxAllowedContentLength30,000,000 bytesRequest filtering, in web.config
DjangoDATA_UPLOAD_MAX_MEMORY_SIZE, DATA_UPLOAD_MAX_NUMBER_FILES2.5 MB (excludes file data for request.POST), 100FILE_UPLOAD_MAX_MEMORY_SIZE only controls when uploads spool to disk, not whether they are accepted; enforce file size in a validator
Express with Multerlimits.fileSize, limits.files, limits.partsInfinitySet all three; the README warns never to register Multer as global middleware
Spring Bootspring.servlet.multipart.max-file-size, max-request-sizeVersion dependent; set explicitlyAlso 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's memoryStorage.
  • Control temporary directories: PHP upload_tmp_dir, Django FILE_UPLOAD_TEMP_DIR, nginx client_body_temp_path and ASPNETCORE_TEMP should 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.

  1. Authenticate, authorise and check CSRF: the cheat sheet requires uploads to be tied to an identifiable user and protected against cross-site request forgery.
  2. Size and count: enforced at the proxy and framework, re-checked in code.
  3. 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.
  4. Declared Content-Type: a quick consistency check only; the cheat sheet notes it is trivially spoofed.
  5. Magic bytes: confirm the signature matches the extension (for example JPEG begins FF D8 FF). Necessary but, per OWASP, commonly bypassed on its own.
  6. 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.
  7. 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.
  8. 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:

ConditionExamplePurpose
expirationMinutes after issueLimits replay of a leaked policy
bucketExact match on the quarantine bucketUploads can never land in a served bucket
key["starts-with", "$key", "quarantine/<tenant>/<uuid>"] or an exact keyPins 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
aclPrivatePrevents 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.

StateLocationWho can readExit condition
ReceivedQuarantine storeValidation worker onlyStructural checks pass or fail
ValidatedQuarantine storeScanning worker onlyScan returns clean, infected or error
CleanRelease store (rewritten output where applicable)Download service, on behalf of authorised usersRetention expiry or user deletion
Rejected or infectedIsolated evidence store or deletedSecurity teamInvestigation complete
Scan error or limit exceededQuarantine storeNobody until retriedRetry 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-Type from your detected type, X-Content-Type-Options: nosniff, and Content-Disposition: attachment with 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-Policy on 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

  1. 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.
  2. Set limits explicitly: proxy, server and framework values from the table above, deployed as configuration with tests that assert them.
  3. 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.
  4. Introduce quarantine and the state machine: start with new uploads; migrate stored files by rescanning them in the background.
  5. 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.
  6. 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.Exceeded results 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

FrameworkReferenceRelevance
OWASP ASVS 5.0V5.1.1, V5.2.1 to V5.2.6, V5.3.1 to V5.3.3, V5.4.1 to V5.4.3Documentation, validation, storage and download requirements
OWASP WSTGWSTG-BUSL-08, WSTG-BUSL-09Test cases for unexpected and malicious files
MITRE CWECWE-434 Unrestricted Upload of File with Dangerous Type; CWE-22 path traversalCore weaknesses
NIST SP 800-53 Rev. 5SI-10 Information Input Validation, SI-3 Malicious Code ProtectionValidation and scanning controls
CIS Controls v8.1Control 16 Application Software Security; Safeguard 10.1 Deploy and Maintain Anti-Malware SoftwareSecure development and scanning
ISO/IEC 27001:2022 Annex AA.8.28 Secure coding, A.8.7 Protection against malwareManagement system controls
MITRE ATT&CK v20T1505.003 Web Shell, T1190 Exploit Public-Facing ApplicationWhat a failed upload control enables

Common failure patterns

  • Unlimited framework defaults: Multer's file size and count limits default to Infinity, so a missing limits object 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 AlertExceedsMax was 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, nosniff and 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

Related NHI Mgmt Group resources: File Upload Security Guide · Path Traversal Guide · XXE Guide · Secure Error Handling and Logging Guide · Web Shell Response Playbook

PDF for subscribers

Take this guide with you

Every section, table and checklist in one PDF, with links to the sources and related guides. Subscribe to our weekly NHI & AI Identity Journal and we’ll email you a download link.

Free weekly newsletter

Subscribe to the NHI & AI Identity Journal

The latest on NHI and Agentic AI security – articles, research, breaches, news and events every week.

Bonus 33% off our NHI Course when you subscribe.

NHIMG Editorial Note
Researched and written by the NHI Mgmt Group editorial team using AI tools, under the editorial direction of Lalit Choda. Facts are drawn from the sources listed on this page and checked by our automated quality process. Last updated 26 October 2026. Spotted an error? Use our contact page.
NHI Mgmt Group, the independent authority on Non-Human Identity, IAM and Agentic AI security. nhimg.org

PDF Downloads for Newsletter Subscribers

Get the guide

Enter your details and we’ll email you a download link.

The full guide is free to read online. The PDF is a thank you for subscribing.

Fill in all fields marked * and tick the PDF box to continue.