README

File upload security for Laravel: content-type validation with magic-byte sniffing, filename sanitization, pluggable malware scanning (ClamAV / VirusTotal), secure signed-URL storage, upload rate limiting, and quarantine workflows.

This package is part of the ArtisanPack UI Security 2.0 split — the upload-focused features previously bundled inside artisanpack-ui/security (1.x) live here in 2.0+.

Features

• File validation pipeline (FileValidationService) — MIME sniffing against actual file content, magic-byte verification, extension allowlists / blocklists, per-type and absolute size limits, double-extension and null-byte trick detection, EXIF stripping for images
• Validation rules — SafeFilename, SecureFile (drop-in Rule classes for Form Requests)
• Pluggable malware scanning — ClamAvScanner (Unix socket or binary), VirusTotalScanner (API + by-hash short-circuit), NullScanner (dev / CI default)
• Secure storage (SecureFileStorageService) — files stored outside the public root, served only via signed URLs through the bundled SecureFileController
• Quarantine workflow — files flagged by async scanning live in a quarantine area until cleared by security:scan-quarantine
• Upload rate limiting (FileUploadRateLimiter)
• Middleware — validate.upload, scan.upload
• Eloquent concern — HasSecureFiles adds attachSecureFile, secureImages, secureDocuments, etc. to any model that owns uploaded files
• Events — FileUploaded, FileUploadRejected, FileServed, MalwareDetected (subscribed to by artisanpack-ui/security-analytics for audit trail)
• Artisan commands — security:cleanup-files, security:scan-quarantine

Installation

composer require artisanpack-ui/secure-uploads
php artisan migrate

(Optional) Publish the config:

php artisan vendor:publish --tag=secure-uploads-config

Quick start

use ArtisanPackUI\SecureUploads\Concerns\HasSecureFiles;

class Post extends Model
{
    use HasSecureFiles;
}

$post = Post::find(1);
$stored = $post->attachSecureFile($request->file('attachment'));

return redirect()->route('secure-file.show', ['identifier' => $stored->identifier]);

The attachSecureFile() call runs validation, optionally scans for malware, sanitizes the filename, and stores the file behind a signed URL.

Configuration

The shipped config covers MIME / extension allow- and block-lists, size limits, EXIF stripping, scanner driver selection (null / clamav / virustotal), and rate limiting. Override any of it after publishing:

php artisan vendor:publish --tag=secure-uploads-config

See config/artisanpack/secure-uploads.php for the full list with inline documentation.

Documentation

• Documentation home — overview + map
• Getting started — 5-minute install + first upload
• Installation — requirements, configuration, scanner setup
• Usage — validation, malware scanning, storage, signed URLs, events, commands
• Advanced — extending validators, custom scanners, quarantine workflow
• FAQ
• Troubleshooting
• Changelog

Requirements

• PHP 8.2+
• Laravel 10 / 11 / 12
• ext-fileinfo (bundled with PHP) for MIME detection
• ClamAV daemon or binary (optional, only if using the ClamAV scanner)
• VirusTotal API key (optional, only if using the VirusTotal scanner)

Sibling packages

License

MIT — see LICENSE.

Contributing

Please read the contributing guidelines before opening an issue or PR.