Secure File Uploads: Validation, Storage, Preventing Execution

1. Why naive upload validation fails

From an attacker's perspective, an upload form is not an edge case, it is one of the most direct ways to get their own code onto a server. The naive assumption held by many developers is: if the file extension is correct and the content type matches, the file is safe. That exact assumption is what attackers exploit. An attacker systematically tries alternative PHP extensions such as .phtml, .php5, .pht, or .phar, manipulates the Content-Type header inside the multipart request, and packs executable code into a file that looks like a harmless image at first glance.

Effective file upload protection only works as a layered system, never as a single check. Each layer covers a different attack variant: whitelisting allowed extensions blocks the obvious cases, magic byte checks detect spoofed file types, storage outside the webroot prevents execution even after a successful bypass, and re-encoding fully destroys embedded code inside image files. Implementing just one of these layers builds a security measure that collapses under the first targeted attack. The following sections walk through each layer individually.

2. MIME-type spoofing: why extension and Content-Type checks alone are insufficient

The Content-Type header of a multipart upload is set entirely by the client, making it a mere suggestion, not a reliable signal. An attacker can send any value they like using curl or a manipulated form, for example image/jpeg for a file that actually contains PHP code. Server-side applications that accept $_FILES['file']['type'] in PHP or similar client metadata without verification aren't really validating anything, they're blindly trusting the attacker's own claim.

The file extension is equally unreliable. Double extensions like shell.php.jpg get incorrectly executed as PHP by some server configurations, when Apache's AddHandler checks every extension in the filename instead of only the last one. Null byte injection in older PHP versions allowed attackers to bypass checks using shell.php%00.jpg. Case variations like .PhP or alternative executable extensions like .phtml are frequently missed by incomplete blacklists. The takeaway: extension and content type are hints for the user interface, never a security boundary.

3. Magic-byte validation done right

Magic bytes are the first bytes of a file that identify its actual format independent of the filename. A genuine PNG always starts with the byte sequence 89 50 4E 47, a JPEG with FF D8 FF. PHP's fileinfo extension and the finfo_file() function provide a reliable way to determine the real MIME type from this signature, instead of trusting client-supplied data. This check must happen server-side immediately after receiving the temporary upload file, before any further processing takes place.

Magic byte validation is necessary but not sufficient, because so-called polyglot files are simultaneously valid images and valid scripts. A GIF file can start with a valid GIF header and still contain PHP code that executes as soon as the file lands with a .php extension on a PHP-enabled server. That's why magic byte validation always has to be combined with a strict extension whitelist and a storage strategy that prevents execution altogether, regardless of file content.

<?php

declare(strict_types=1);

namespace Mironsoft\Security\Model\Upload;

/**
 * Validates uploaded files by inspecting their real file signature (magic bytes)
 * instead of trusting the client supplied extension or Content-Type header.
 */
final class MagicByteValidator
{
    /**
     * Maps allowed MIME types to their expected binary signatures (magic bytes).
     *
     * @var array<string, string>
     */
    private const ALLOWED_SIGNATURES = [
        'image/jpeg' => "\xFF\xD8\xFF",
        'image/png'  => "\x89\x50\x4E\x47\x0D\x0A\x1A\x0A",
        'image/gif'  => "\x47\x49\x46\x38",
        'application/pdf' => "\x25\x50\x44\x46",
    ];

    /**
     * Determines the real MIME type of a file using its binary signature,
     * never trusting $_FILES['type'] which is fully client controlled.
     *
     * @param string $tmpFilePath Path to the temporary uploaded file.
     * @return string Detected MIME type or 'application/octet-stream' if unknown.
     * @throws \RuntimeException If the fileinfo extension is unavailable.
     */
    public function detectRealMimeType(string $tmpFilePath): string
    {
        $finfo = finfo_open(FILEINFO_MIME_TYPE);
        if ($finfo === false) {
            throw new \RuntimeException('fileinfo extension is not available');
        }

        $mimeType = finfo_file($finfo, $tmpFilePath);
        finfo_close($finfo);

        return $mimeType !== false ? $mimeType : 'application/octet-stream';
    }

    /**
     * Verifies that a file's real MIME type is on the allowed list.
     *
     * @param string $tmpFilePath Path to the temporary uploaded file.
     * @param array<int, string> $allowedMimeTypes Whitelist of accepted MIME types.
     * @return bool True if the file's real signature matches an allowed type.
     */
    public function isAllowed(string $tmpFilePath, array $allowedMimeTypes): bool
    {
        $realMimeType = $this->detectRealMimeType($tmpFilePath);

        return in_array($realMimeType, $allowedMimeTypes, true);
    }
}

4. Storing uploads outside the webroot and in non-executable directories

The single most effective measure against file upload attacks is not validation, it is storage: if an uploaded file can never be interpreted by the web server, it doesn't matter whether an attacker bypassed validation. Uploads should always be stored outside the document root, for instance in a directory like /var/app-storage/uploads/ instead of public/uploads/. Access then happens exclusively through a PHP script that checks permissions, reads the file from the protected directory, and serves it with the correct headers.

If storing files outside the webroot isn't possible for architectural reasons, the upload directory must be explicitly configured as non-executable. On Apache, an .htaccess file with disabled handlers prevents PHP files in that directory from being interpreted. On nginx, the same result is achieved by having the location block for upload paths explicitly exclude PHP processing, rather than relying on a global PHP handler. File permissions should additionally be set to 644 without the execute bit, so that even a direct call at the operating system level cannot trigger script execution.

5. Filename sanitization against path traversal

A filename submitted by the user must never be used unchecked in filesystem operations. An attacker can submit names like ../../etc/cron.d/malicious or ..\..\config\settings.php to break out of the intended upload directory using path traversal sequences and overwrite arbitrary files on the system. Special characters, null bytes, and excessively long filenames are equally dangerous, and can lead to unexpected behavior depending on the filesystem and framework in use.

The robust solution generates a completely new, random filename server-side, for example based on a UUID or a cryptographically secure random value, and discards the original name entirely except for its validated extension. If the original filename is needed for display purposes, it is stored separately in the database, never used as an actual filesystem path. basename() alone is not sufficient, since it doesn't reliably strip path traversal sequences; combining a whitelist of allowed characters with a full regeneration of the name is the only robust approach.

<?php

declare(strict_types=1);

namespace Mironsoft\Security\Model\Upload;

/**
 * Generates safe, unpredictable filenames for uploaded files and rejects
 * any path traversal attempt in the originally submitted filename.
 */
final class FilenameSanitizer
{
    /**
     * Whitelist of file extensions that may be persisted after validation.
     *
     * @var array<int, string>
     */
    private const ALLOWED_EXTENSIONS = ['jpg', 'jpeg', 'png', 'gif', 'pdf'];

    /**
     * Builds a completely new, random filename and keeps only the validated
     * extension of the original file. The original name is never reused
     * as part of the filesystem path.
     *
     * @param string $originalFilename Filename as submitted by the client.
     * @return string Safe filename, e.g. "3f2a9c1e8b7d4a10.jpg".
     * @throws \InvalidArgumentException If the extension is not on the whitelist.
     */
    public function generateSafeFilename(string $originalFilename): string
    {
        $extension = strtolower(pathinfo($originalFilename, PATHINFO_EXTENSION));

        if (!in_array($extension, self::ALLOWED_EXTENSIONS, true)) {
            throw new \InvalidArgumentException(sprintf('Extension "%s" is not allowed', $extension));
        }

        // Cryptographically secure random name, no relation to user input
        $randomName = bin2hex(random_bytes(16));

        return sprintf('%s.%s', $randomName, $extension);
    }

    /**
     * Rejects filenames containing path traversal sequences or null bytes.
     * Use this only as a defensive check before generateSafeFilename();
     * it must never be the sole protection against path traversal.
     *
     * @param string $filename Filename to inspect.
     * @return bool True if the filename contains no traversal indicators.
     */
    public function isFreeOfTraversalSequences(string $filename): bool
    {
        if (str_contains($filename, "\0")) {
            return false;
        }

        if (str_contains($filename, '..') || str_contains($filename, '/') || str_contains($filename, '\\')) {
            return false;
        }

        return true;
    }
}

6. Image re-encoding against embedded scripts and polyglot payloads

Even after a file passes magic byte validation, an image can still contain extra data irrelevant to displaying the image, data that gets executed by some vulnerable component of the infrastructure. EXIF metadata can carry script fragments, and polyglot files are deliberately constructed to be interpretable simultaneously as a valid image and a valid script. The most reliable countermeasure is re-encoding: the uploaded image is fully decoded again using an image library like GD or Imagick and written into a brand new image, discarding every byte that isn't part of the actual pixel data.

Re-encoding automatically strips EXIF data, embedded comment fields, and any code that sits outside the pure image data, because the target library only re-encodes the decoded pixels when writing the new file. Re-encoding is not sufficient for SVG files, since SVG is an XML format that can contain active content like <script> tags or external references; strict XML sanitization with a library that specifically strips active content, or an outright ban on SVG uploads, is the safer choice here.

<?php

declare(strict_types=1);

namespace Mironsoft\Security\Model\Upload;

/**
 * Re-encodes an uploaded image through GD to strip any embedded scripts,
 * EXIF payloads, or polyglot content that is not part of the actual pixels.
 */
final class ImageReencoder
{
    /**
     * Decodes the source image and writes a brand new JPEG file,
     * discarding every byte that is not part of the decoded pixel data.
     *
     * @param string $sourcePath Path to the validated temporary upload.
     * @param string $destinationPath Path the clean, re-encoded file is written to.
     * @param int $quality JPEG quality between 0 and 100.
     * @return bool True on success.
     * @throws \RuntimeException If the source image cannot be decoded.
     */
    public function reencodeAsJpeg(string $sourcePath, string $destinationPath, int $quality = 85): bool
    {
        $imageInfo = getimagesize($sourcePath);
        if ($imageInfo === false) {
            throw new \RuntimeException('Source file is not a decodable image');
        }

        $image = match ($imageInfo['mime']) {
            'image/jpeg' => imagecreatefromjpeg($sourcePath),
            'image/png'  => imagecreatefrompng($sourcePath),
            'image/gif'  => imagecreatefromgif($sourcePath),
            default => throw new \RuntimeException('Unsupported source image type'),
        };

        if ($image === false) {
            throw new \RuntimeException('Failed to decode source image');
        }

        // Flatten transparency onto a white background before writing JPEG
        $width = imagesx($image);
        $height = imagesy($image);
        $flattened = imagecreatetruecolor($width, $height);
        imagefill($flattened, 0, 0, imagecolorallocate($flattened, 255, 255, 255));
        imagecopy($flattened, $image, 0, 0, 0, 0, $width, $height);

        $result = imagejpeg($flattened, $destinationPath, $quality);

        imagedestroy($image);
        imagedestroy($flattened);

        return $result;
    }
}

7. Webserver hardening for upload directories

Beyond application logic, the web server configuration itself must guarantee that files in the upload directory are never interpreted as a script, even if every other safeguard fails. On nginx, this is achieved with a dedicated location block that explicitly disables forwarding to the PHP-FPM handler for the upload path and permits only static file delivery instead. On Apache, an .htaccess file inside the upload directory with RemoveHandler and RemoveType for PHP extensions handles the same task, provided AllowOverride is enabled for that directory.

This configuration should be treated as an independent, standalone security layer that doesn't depend on application logic, and therefore still applies even if a deployment mistake disables validation in the code. It's also worth setting the X-Content-Type-Options: nosniff header for served uploads, so browsers don't guess the declared content type on their own and inadvertently execute HTML or JavaScript from what appears to be an image file. Regular automated tests that attempt to fetch a test file with a PHP extension from the upload directory catch configuration mistakes early.

# nginx: deny PHP execution inside the upload directory
location /media/uploads/ {
    location ~ \.php$ {
        deny all;
        return 403;
    }

    # Serve only static files, no fastcgi_pass to php-fpm here
    try_files $uri =404;
}

# Apache: .htaccess placed inside the upload directory
<FilesMatch "\.(php|phtml|php3|php4|php5|php7|pht|phar)$">
    # Disable execution regardless of AddHandler in a parent context
    SetHandler none
    RemoveHandler .php .phtml .php3 .php4 .php5 .php7 .pht .phar
    RemoveType .php .phtml .php3 .php4 .php5 .php7 .pht .phar
    Require all denied
</FilesMatch>

Options -ExecCGI
AddType text/plain .php .phtml .php3 .php4 .php5 .php7 .pht .phar

8. Magento-specific media upload security

Magento ships with baseline validation via Magento\Framework\File\Uploader, but developers still have to configure it correctly. The setAllowedExtensions() method defines a whitelist of allowed file extensions and should never be left empty, nor extended with far-reaching extensions like .svg without additional checks. Uploader::checkMimeType() adds a MIME type check, but as described in section two, that check is no substitute for magic byte validation. The media storage path pub/media/ lives inside the webroot and is intended by default for catalog images, which is why user-generated uploads from customer areas or custom modules should deliberately land in a separate path that isn't directly browser-accessible.

Admin uploads and storefront uploads call for different trust levels: an administrator with ACL permission for the product catalog is inherently more trusted than an anonymous storefront visitor uploading, say, attachments in a contact form or custom product images. Storefront uploads should generally use a narrower whitelist, mandatory re-encoding for images, and storage outside pub/media/. Magento modules that implement their own upload functionality should consistently configure the Uploader with setAllowRenameFiles(true) and setFilesDispersion(true) to avoid predictable filenames and directory structures.

<?php

declare(strict_types=1);

namespace Mironsoft\Security\Model\Upload;

use Magento\Framework\File\Uploader;
use Magento\Framework\File\UploaderFactory;
use Magento\Framework\Filesystem;
use Magento\Framework\Filesystem\DirectoryList;

/**
 * Wraps Magento's native Uploader with a strict extension whitelist,
 * randomized filenames, and dispersed directory storage.
 */
final class SecureMediaUploader
{
    /**
     * Constructor with promoted dependencies.
     *
     * @param UploaderFactory $uploaderFactory Factory for Magento\Framework\File\Uploader.
     * @param Filesystem $filesystem Filesystem abstraction to resolve the target directory.
     */
    public function __construct(
        private readonly UploaderFactory $uploaderFactory,
        private readonly Filesystem $filesystem
    ) {
    }

    /**
     * Uploads a file from a form field into a non public storage path,
     * enforcing a strict extension whitelist and randomized naming.
     *
     * @param string $formFieldName Name of the multipart form field.
     * @return array<string, mixed> Result data returned by Magento\Framework\File\Uploader::save().
     * @throws \Exception If validation or the upload itself fails.
     */
    public function upload(string $formFieldName): array
    {
        /** @var Uploader $uploader */
        $uploader = $this->uploaderFactory->create(['fileId' => $formFieldName]);

        // Strict whitelist, never leave this empty or add .svg without extra checks
        $uploader->setAllowedExtensions(['jpg', 'jpeg', 'png', 'gif']);
        $uploader->setAllowRenameFiles(true);
        $uploader->setFilesDispersion(true);
        $uploader->checkMimeType(['image/jpeg', 'image/png', 'image/gif']);

        // var/storage is outside pub/, never directly reachable via HTTP
        $targetDir = $this->filesystem->getDirectoryWrite(DirectoryList::VAR_DIR)
            ->getAbsolutePath('storage/uploads');

        return $uploader->save($targetDir);
    }
}

9. Comparison of validation approaches

The preceding sections show that individual validation steps vary widely in effectiveness, and some only create an illusion of security. The table below contrasts insecure, widely used approaches with the recommended, robust alternatives, and makes clear why layered protection is essential in practice.

10. Summary

Secure file uploads don't come from a single clever check, they come from several independent security layers, each covering a different attack vector. MIME type and file extension are mere hints, not a security boundary, because both are fully controlled by the client. Magic byte validation with finfo_file() reliably detects spoofed file types, but doesn't prevent polyglot files that are simultaneously a valid image and a valid script.

The single most effective measure remains storing files outside the webroot, or in a directory the web server explicitly excludes from PHP execution, combined with randomly generated filenames against path traversal and re-encoding against embedded code in images. In Magento, Magento\Framework\File\Uploader with a correctly configured extension whitelist complements these layers, but doesn't replace them. Combining all layers makes a successful bypass of any single check practically useless.

11. FAQ: Secure File Uploads