function file_munge_filename in Drupal 8

Same name and namespace in other branches

1. 6 includes/file.inc \file_munge_filename()
2. 7 includes/file.inc \file_munge_filename()
3. 9 core/includes/file.inc \file_munge_filename()

Modifies a filename as needed for security purposes.

Munging a file name prevents unknown file extensions from masking exploit files. When web servers such as Apache decide how to process a URL request, they use the file extension. If the extension is not recognized, Apache skips that extension and uses the previous file extension. For example, if the file being requested is exploit.php.pps, and Apache does not recognize the '.pps' extension, it treats the file as PHP and executes it. To make this file name safe for Apache and prevent it from executing as PHP, the .php extension is "munged" into .php_, making the safe file name exploit.php_.pps.

Specifically, this function adds an underscore to all extensions that are between 2 and 5 characters in length, internal to the file name, and either included in the list of unsafe extensions, or not included in $extensions.

Function behavior is also controlled by the configuration 'system.file:allow_insecure_uploads'. If it evaluates to TRUE, no alterations will be made, if it evaluates to FALSE, the filename is 'munged'. *

Parameters

$filename: File name to modify.

$extensions: A space-separated list of extensions that should not be altered. Note that extensions that are unsafe will be altered regardless of this parameter.

$alerts: If TRUE, \Drupal::messenger()->addStatus() will be called to display a message if the file name was changed.

Return value

string The potentially modified $filename.

Related topics

9 calls to file_munge_filename()

FileUploadResource::prepareFilename in core/modules/file/src/Plugin/rest/resource/FileUploadResource.php

Prepares the filename to strip out any malicious extensions.

NameMungingTest::testMungeIgnoreAllowedExtensions in core/tests/Drupal/KernelTests/Core/File/NameMungingTest.php

Tests that allowed extensions are ignored by file_munge_filename().

NameMungingTest::testMungeIgnoreInsecure in core/tests/Drupal/KernelTests/Core/File/NameMungingTest.php

If the system.file.allow_insecure_uploads setting evaluates to true, the file should come out untouched, no matter how evil the filename.

NameMungingTest::testMungeNullByte in core/tests/Drupal/KernelTests/Core/File/NameMungingTest.php

Tests munging with a null byte in the filename.

NameMungingTest::testMungeUnsafe in core/tests/Drupal/KernelTests/Core/File/NameMungingTest.php

Tests unsafe extensions are always munged by file_munge_filename().

... See full list

File

core/includes/file.inc, line 678

API for handling file uploads and server file management.

Code

function file_munge_filename($filename, $extensions, $alerts = TRUE) {
  $original = $filename;

  // Allow potentially insecure uploads for very savvy users and admin
  if (!\Drupal::config('system.file')
    ->get('allow_insecure_uploads')) {

    // Remove any null bytes. See
    // http://php.net/manual/security.filesystem.nullbytes.php
    $filename = str_replace(chr(0), '', $filename);
    $allowed_extensions = array_unique(explode(' ', strtolower(trim($extensions))));

    // Remove unsafe extensions from the allowed list of extensions.
    // @todo https://www.drupal.org/project/drupal/issues/3032390 Make the list
    //   of unsafe extensions a constant. The list is copied from
    //   FILE_INSECURE_EXTENSION_REGEX.
    $allowed_extensions = array_diff($allowed_extensions, explode('|', 'phar|php|pl|py|cgi|asp|js'));

    // Split the filename up by periods. The first part becomes the basename
    // the last part the final extension.
    $filename_parts = explode('.', $filename);

    // Remove file basename.
    $new_filename = array_shift($filename_parts);

    // Remove final extension.
    $final_extension = array_pop($filename_parts);

    // Loop through the middle parts of the name and add an underscore to the
    // end of each section that could be a file extension but isn't in the list
    // of allowed extensions.
    foreach ($filename_parts as $filename_part) {
      $new_filename .= '.' . $filename_part;
      if (!in_array(strtolower($filename_part), $allowed_extensions) && preg_match("/^[a-zA-Z]{2,5}\\d?\$/", $filename_part)) {
        $new_filename .= '_';
      }
    }
    $filename = $new_filename . '.' . $final_extension;
    if ($alerts && $original != $filename) {
      \Drupal::messenger()
        ->addStatus(t('For security reasons, your upload has been renamed to %filename.', [
        '%filename' => $filename,
      ]));
    }
  }
  return $filename;
}