Class List

FastSitePHP\FileSystem\Security

File System Security

Source Code

GitHub

Example Code

File System Security

// The FileSystem Security Class contains functions for validating files.

// Prevent Path Traversal Attacks by verifying if a file name exists in a
// specified directory. Path Traversal Attacks can happen if a user is
// allowed to specify a file on a file system through input and uses a
// pattern such as '/../' to obtain files from another directory.

// Examples:

// Assume both files exist and would return [true] from built-in function
// [is_file()]. [false] would be returned for the 2nd file when using
// [Security::dirContainsFile()].
$file1 = 'user_image.jpg';
$file2 = '../../index.php';
$file_exists_1 = \FastSitePHP\FileSystem\Security::dirContainsFile($dir, $file1);
$file_exists_2 = \FastSitePHP\FileSystem\Security::dirContainsFile($dir, $file2);

// The function [dirContainsFile()] only allows for files directly under the root
// folder so another function exists to search sub-directories [dirContainsPath()].
$path1 = 'icons/clipboard.svg'; // Returns [true]
$path2 = '../../app/index.php'; // Returns [false]
$path_exists_1 = \FastSitePHP\FileSystem\Security::dirContainsPath($dir, $path1);
$path_exists_2 = \FastSitePHP\FileSystem\Security::dirContainsPath($dir, $path2);

// [dirContainsPath()] contains an optional 3rd parameter [$type] which defaults
// to 'file' and allows for one of the following options ['file', 'dir', 'all'].
$path3 = 'icons';
$exists = \FastSitePHP\FileSystem\Security::dirContainsPath($dir, $path3, 'dir');

// [dirContainsDir()] can be used to check directories/folders.
$dir1 = 'icons';
$dir2 = '../../app';
$dir_exists_1 = \FastSitePHP\FileSystem\Security::dirContainsDir($dir, $file1);
$dir_exists_2 = \FastSitePHP\FileSystem\Security::dirContainsDir($dir, $file2);

// Validate Image Files
// The [fileIsValidImage()] function can be used to verify if image files
// created from user input are valid. For example a malicious user may try
// to rename a PHP script or executable file as an image and upload it to
// a site. Returns [true] if an image file [jpg, gif, png, webp, svg]
// is valid and the file's extension matches the image type.
$is_image = \FastSitePHP\FileSystem\Security::fileIsValidImage($image_file);

Methods

dirContainsFile($dir, $file)

Static Function

Prevent Path Traversal Attacks by verifying if a file name exists in a specified directory. Path Traversal Attacks can happen if a user is allowed to specify a file on a file system through input and uses a pattern such as '/../' to obtain files from another directory.

This function returns [true] if the file exists in the directory and the file name matches exactly to the [$file] parameter. The [$dir] parameter can be a relative path with '../' characters so it should not come from a user. The [$dir] parameter is required to be a valid directory otherwise an exception is thrown as it indicates a logic or permissions error in the app.

Example:
    // Assume both files exist and would return [true] from built-in function [is_file()].
    // False is returned for the 2nd file because a '/' character was used.
    $dir = __DIR__ . '/../img';
    true  = Security::dirContainsFile($dir, 'user_image.jpg')
    false = Security::dirContainsFile($dir, '../../index.php')

Returns: bool

dirContainsPath($dir, $path, $type = 'file')

Static Function

Prevent Path Traversal Attacks by verifying if a file or directory exists under the specified directory. Sub-directories can be specified, however path traversal using '../' or '..\' is not allowed for the [$path] paramater.

See additional comments and links in [dirContainsFile()].

Example:
    // Assume both files exist and would return [true] from built-in function [is_file()].
    // False is returned for the 2nd file because a '../' was used.
    $dir  = __DIR__ . '/../img';
    true  = Security::dirContainsPath($dir, 'icons/clipboard.svg')
    false = Security::dirContainsPath($dir, '../../app/app.php')

    // An optional parameter [$type] can be used with one of values: ['file', 'dir', 'all'].
    // The defaut value is 'file'. Example:
    false = Security::dirContainsPath($dir, 'icons')
    true  = Security::dirContainsPath($dir, 'icons', 'dir')
    true  = Security::dirContainsPath($dir, 'icons', 'all')

Returns: bool

dirContainsDir($root_dir, $dir_name)

Static Function

Prevent Path Traversal Attacks by verifying if a directory exists in a specified directory.

This function returns [true] if the directory exists in the directory and the directory name matches exactly to the [$dir_name] parameter.

See additional comments and links in [dirContainsFile()].

Example:
    // Assume both directories exist and would return [true] from built-in function [is_dir()].
    // False is returned for the 2nd file because a '/' character was used.
    $dir = __DIR__ . '/../img';
    true  = Security::dirContainsDir($dir, 'icons')
    false = Security::dirContainsDir($dir, '../../app')

Returns: bool

fileIsValidImage($full_path)

Static Function

Returns [true] if a image file (jpg, jpeg, gif, png, webp, svg) is valid and the file's extension matches the image type.

This function can be used to verify if image files created from user input are valid. For example a malicious user may try to rename a PHP Script or executable file as an image and upload it to a site.

For SVG Files this function simply verifies that the file is a valid XML file with [svg] as the root element.

For other images types such as JPG or PNG this function uses the [FastSitePHP\Media\Image] class to check if a file is valid. If you intended on using the [Image] class from the same calling function then using this function is not needed as it would open the same image file twice.

If your app or site needs to resize an image after a user upload then the [Image] class is recommend, however if you simply need to verify an image then this helper function allows for simple and clear code.

Returns: bool