2017 © Pedro Peláez
 

library virtual-path

The VirtualPath library normalises paths and prevents directory traversal attacks without querying a file system.

image

rayne/virtual-path

The VirtualPath library normalises paths and prevents directory traversal attacks without querying a file system.

  • Friday, October 13, 2017
  • by Rayne
  • Repository
  • 2 Watchers
  • 6 Stars
  • 27 Installations
  • PHP
  • 0 Dependents
  • 0 Suggesters
  • 0 Forks
  • 0 Open issues
  • 2 Versions
  • 17 % Grown

The README.md

Rayne\VirtualPath

The VirtualPath library normalises paths and prevents directory traversal attacks without querying a file system., (*1)

Latest Stable Version Code Coverage Scrutinizer Code Quality License, (*2)

Contents

Installation

It's recommended to use the dependency manager Composer to install rayne/virtual-path., (*3)

composer require rayne/virtual-path

Dependencies

  • PHP 5.6 or better

Usage

The VirtualPath class normalises inputs to absolute virtual paths without querying any file system. It also detects and flags directory traversal attacks., (*4)

The JailedPath class utilises VirtualPath to build safe paths which can be used for working with real files. The normalisation is done relative to a jail called path which is used as virtual root for any path entered by the user. As JailedPath does not query the file system it's suited for working with local, remote or fictional paths., (*5)

Please read the Implementation Details section for more details., (*6)

TL;DR Use the JailedPath class when in doubt., (*7)

Examples

JailedPath

In this example website visitors are allowed to download any file from the local directory /test by specifying the relative path as GET parameter. To prevent users from leaving the directory with directory traversal attacks, JailedPath is used with /test as the virtual root directory., (*8)

<?php

use Rayne\VirtualPath\JailedPath;

$jailedPath = new JailedPath('/test', $_GET['path'] ?? '');

if ($jailedPath->hasJailbreakAttempt()) {
    // Log jailbreak attempt, ban user, …
    return;
}

if (is_file($jailedPath->getAbsolutePath())) {
    @readfile($jailedPath->getAbsolutePath());
}

The following table shows how user defined paths are normalised and how they are interpreted relative to the virtual root., (*9)

User Input hasJailbreakAttempt() getAbsolutePath() getRelativePath()
Empty String false /test Empty String
. false /test Empty String
a.png/../b.png false /test/b.png b.png
/a/./b false /test/a/b a/b
.. true /test Empty String
../example true /test/example example
../etc/passwd true /test/etc/passwd etc/passwd
Array true /test Empty String

VirtualPath

If a fixed prefix or the sugar coating of JailedPath isn't required, then VirtualPath is sufficient as it is the class used for normalising paths. VirtualPath normalises the input and provides a trusted (normalised, with a leading /) and an untrusted (a string representation of the probably malicious user input) path., (*10)

The previous example can be easily recreated with VirtualPath when the instance of VirtualPath (which is (string) cast-able) is appended to the virtual root directory., (*11)

<?php

use Rayne\VirtualPath\VirtualPath;

$path = new VirtualPath($_GET['path'] ?? '');
$absolutePath = '/test' . $path;

Depending on the usage scenario it's sometimes useful to work with the normalised trusted path even if the original input is not trustworthy, e.g. when explicitly supporting relative paths and giving the user the benefit of doubt when accidentally trying to access files outside of the virtual path., (*12)

Note: VirtualPath returns the normalised path with a leading /. When working with files it's recommended to add a trusted path as prefix (see code example in the current section) as otherwise files relative to the file system's root would be referenced. To not forget to add the prefix use the JailedPath class instead when working with real files., (*13)

Input isTrusted() getTrustedPath() getUntrustedPath()
Array false / Empty String
Empty String true / Empty String
../articles false /articles ../articles
tags/../../articles false /articles tags/../../articles
tags/../articles true /articles tags/../articles
../etc/passwd false /etc/passwd ../etc/passwd
/etc/passwd true /etc/passwd /etc/passwd
etc/passwd true /etc/passwd etc/passwd

Implementation Details

Using a pure virtual normalised path has different benefits:, (*14)

  • Path normalisation is done without querying a file system, (*15)

  • It's impossible to forge timing attacks for files outside of the scope of the virtual path, (*16)

  • No complex comparisons are required to limit directory traversals to a specific directory and its children, (*17)

  • Only ., .., \ (normalised to /) and / are interpreted for path normalisation, (*18)

  • No unexpected and information leaking ~ expansions as seen in other libraries, (*19)

The implementation of VirtualPath does not interpret, alter or remove control characters and Unicode:, (*20)

  • Directory and file paths are allowed to contain control characters on some systems, (*21)

  • Removing control characters is out of scope for the library, (*22)

Tests

  1. Clone the repository, (*23)

    git clone https://github.com/rayne/virtual-path.git

  2. Install the development dependencies, (*24)

    composer install --dev

  3. Run the tests, (*25)

    composer test

The Versions

13/10 2017

dev-master

9999999-dev

The VirtualPath library normalises paths and prevents directory traversal attacks without querying a file system.

  Sources   Download

MIT

The Requires

  • php >=5.6

 

The Development Requires

by Dennis Meckel

directory path traversal

10/10 2017

1.0.0

1.0.0.0

The VirtualPath library normalises paths and prevents directory traversal attacks without querying a file system.

  Sources   Download

MIT

The Requires

  • php >=5.6

 

The Development Requires

by Dennis Meckel

directory path traversal