A flexible, production-ready ColdFusion module for secure file uploads and robust validation can save hours of development, reduce Security risk, and standardize how your application accepts user-generated content. This downloadable package gives you a tested CFML implementation for handling multipart/form-data, server-side checks, storage strategies, and optional integrations such as S3 and antivirus scanning—without reinventing the wheel.
Overview
This resource is a complete ColdFusion File upload & Validation Module designed to plug into Adobe ColdFusion (2018/2021/2023) or Lucee (5/6) applications. It wraps Best practices for accepting files, validating types and sizes, sanitizing filenames, and persisting uploads in a safe, maintainable way. In addition to a straightforward cffile-based flow, you get optional presigned S3 uploads, Image processing hooks, and a test harness.
The module aims to:
- Make secure file uploads easy to implement.
- Provide a consistent API for CFML apps.
- Enforce validation and sanitization out of the box.
- Support both classic form posts and modern async uploads.
What You’ll Get
Download the ZIP and you’ll find:
- /modules/cf-upload/
- /components/
- UploadService.cfc (core logic: cffile, validation, renaming, storage)
- Validation.cfc (MIME, extension, size validation; filename sanitization)
- StorageLocal.cfc (stores files outside webroot)
- StorageS3.cfc (optional S3 Storage using presigned URLs or server-side upload)
- ImageService.cfc (optional: resize/thumbnail with cfimage)
- VirusScan.cfc (optional: ClamAV/ICAP hook)
- /handlers/
- apiUpload.cfc (REST-style endpoint for AJAX uploads)
- /ui/
- formUpload.cfm (simple form-based upload)
- dropzone.cfm (drag-and-drop demo using a lightweight JS library)
- /config/
- config.json (centralized settings: size limits, allowed types, storage paths)
- mime-allowlist.json (common safe MIME types)
- /db/
- schema.sql (example table for stored file metadata)
- /tests/
- upload-tests.cfm (manual test harness and fixtures)
- /components/
- /docs/
- QuickStart.pdf (8 pages, step-by-step install and usage)
- API-Guide.pdf (methods, arguments, examples, error codes)
- /ops/
- docker-compose.clamav.yml (optional on-demand virus scanning)
- PostmanCollection.json (ready-to-use API calls)
- LICENSE (Apache-2.0)
- CHANGELOG.md
- README.md
Supported Environments and Requirements
- Adobe ColdFusion: 2018, 2021, 2023
- Lucee: 5.x, 6.x
- OS: Windows, Linux, or macOS
- Java: JRE compatible with your CF engine
- Optional:
- AWS credentials (for S3 Storage)
- ClamAV or ICAP server (for antivirus)
- ImageMagick/GD support if using advanced Image processing
How to Install
Download and Unpack
- Download the ZIP and extract it to your project root.
- Ensure the module lives at: /modules/cf-upload/
- Verify that /modules/cf-upload/config/config.json is readable by the ColdFusion server.
Configure the Module
Edit /modules/cf-upload/config/config.json. Common keys:
- storageProvider: “local” or “s3”
- local.storagePath: Absolute path outside webroot (e.g., D:/data/uploads or /var/app/uploads)
- allowList: Extension and MIME allowlist file references
- maxFileSizeMB: Numeric limit per file
- renameStrategy: “uuid”, “timestamp”, or “original_sanitized”
- sanitizeFilenames: true/false
- createThumbnails: true/false
- virusScan.enabled: true/false
- csrf.enforce: true/false
- rateLimit.maxPerMinute: Number per IP/session
- logging.level: “info”, “debug”, “error”
Important platform settings:
- ColdFusion Administrator
- Request Size Limits: increase “Maximum size of post data” to your needs.
- Request Timeout: ensure enough time for Large uploads.
- Lucee Server Admin
- Request size (POST), upload temp directory, and timeouts.
Tip: Use an absolute path for local.storagePath. Keeping uploaded files outside the webroot is a critical Security control.
Wire It Into Your App
Add a mapping or import in Application.cfc:
- If you use CF mappings, add a mapping for /modules to the extracted directory.
- Or reference relative paths directly when creating components.
Example Application.cfc snippet (simplified):
- Ensure sessionManagement is true if you plan to use CSRF tokens and Rate limiting.
- Consider setting this.requestTimeout to support larger uploads.
How to Use
Simple Form Example
Front-end form (formUpload.cfm):
- Use enctype=”multipart/form-data”.
- Include a CSRF token if csrf.enforce is enabled.
Example:
- A form with a file input named “upload”.
Best practice: never trust “accept” attributes alone; rely on server-side validation.
Server-Side Upload Handler
Example handler logic (script-style summary):
- Generate or verify a CSRF token.
- Call UploadService to process the file field “upload”.
- The service will: save to temp, validate MIME/extension, enforce size limits, sanitize, rename, and then move to final storage (local or S3). It returns a structured result containing fileId, originalName, size, mime, storagePath or URL, checksum, and createdAt.
Key validations performed:
- MIME verification using fileGetMimeType
- Extension allowlist check
- Double-extension and control-character checks
- Size enforcement (rejects oversize gracefully)
- Filename sanitization and randomization
- Optional virus scan and thumbnail creation
REST API Endpoint (AJAX/Chunked)
The provided /handlers/apiUpload.cfc exposes:
- POST /api/upload (multipart/form-data) for standard AJAX uploads
- Optional “init” endpoints to obtain S3 presigned POST or PUT URLs
This allows direct-to-cloud uploads from the browser, reducing application server load and improving throughput.
Best practices
- Store files outside the webroot
- Prevent direct HTTP execution of uploaded content.
- Prefer renaming strategies
- Use uuid or timestamp to avoid collisions and information leakage.
- Verify content type, not just extension
- Trust fileGetMimeType over user-supplied names.
- Enforce size limits at multiple layers
- Web server Reverse proxy, CF Admin, and application-level maxFileSizeMB.
- Sanitize aggressively
- Replace unsafe characters; block double extensions and hidden files.
- Enable antivirus scanning in regulated environments
- Use ClamAV/ICAP hooks for defense-in-depth.
- Image safety
- Re-encode images using cfimage to strip dangerous metadata, if needed.
- CSRF and Rate limiting
- Require a CSRF token and limit uploads per IP/session to prevent abuse.
- Logging and auditing
- Log all accepted and rejected uploads with reason codes.
- Cloud storage offload
- For large files or high-traffic, use presigned S3 workflows.
- Test on staging with realistic files
- Validate Performance and edge cases (corrupt files, slow clients).
Benefits and Use Cases
- Saves time
- A ready-made uploader with cffile and Validation logic means fewer bugs and faster delivery.
- Security by default
- Content-based MIME validation, allowlists, sanitization, and CSRF controls reduce risk from malicious uploads.
- Scalability
- Optional direct-to-S3 reduces load on your ColdFusion server and speeds up large transfers.
- Observability
- Structured results, consistent logging, and error codes simplify Troubleshooting.
- Flexibility
- Works with Adobe ColdFusion and Lucee; plugs into legacy forms or Modern JS uploaders.
Common scenarios:
- CMS image library with thumbnails
- HR portals accepting PDF resumes only
- Customer support attachments (PDF, PNG, JPG)
- Engineering portals uploading CAD/PDF with strict allowlists
- SaaS backends providing an upload API endpoint to third parties
Key Takeaways
- A production-ready ColdFusion upload module with end-to-end validation and storage options.
- Enforces MIME checks, size limits, and filename sanitization to block risky files.
- Supports local storage outside webroot and cloud storage via S3 presigned workflows.
- Optional antivirus scanning, image processing, CSRF protection, and rate limiting.
- Works on Adobe ColdFusion 2018/2021/2023 and Lucee 5/6 with clear, documented APIs.
FAQ
How is this different from a basic cffile upload?
The module adds layered security and operational Features missing from a raw cffile implementation: MIME allowlists, size enforcement, filename sanitization, optional virus scanning, CSRF/rate limiting, logging, and structured responses. It also includes UI samples and REST endpoints for AJAX/drag-and-drop uploads.
Does it support Amazon S3 or Azure Blob Storage?
Yes. It ships with an S3 provider for server-side uploads or presigned URL flows. Azure Blob is supported via a provider interface (example adapter included), so you can add Azure by configuring credentials and endpoints.
How do I limit file types securely?
Use a strict allowlist for both MIME and extension. The Validation.cfc verifies the actual file content (via fileGetMimeType) and the declared extension. Double extensions and hidden files are rejected. Never rely on client-side checks alone.
Can I use it on Lucee?
Absolutely. The same code runs on Lucee 5/6. Be sure to configure POST size and temp directories in the Lucee Server Admin, and confirm that fileGetMimeType is enabled for your environment.
How do I enable virus scanning?
Set virusScan.enabled to true and bring up the optional ClamAV service via the provided docker-compose file, or point to an existing ICAP server. The module will submit files for scanning and reject infected content with a clear error message.
