Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/rayne/virtual-path
The VirtualPath library normalises paths and prevents directory traversal attacks without querying a file system
https://github.com/rayne/virtual-path
composer-library jailed-path path-normalisation path-normalization php-library
Last synced: 3 months ago
JSON representation
The VirtualPath library normalises paths and prevents directory traversal attacks without querying a file system
- Host: GitHub
- URL: https://github.com/rayne/virtual-path
- Owner: Rayne
- License: mit
- Created: 2017-10-06T19:33:46.000Z (about 7 years ago)
- Default Branch: master
- Last Pushed: 2019-11-10T19:16:33.000Z (about 5 years ago)
- Last Synced: 2024-04-18T18:27:30.083Z (9 months ago)
- Topics: composer-library, jailed-path, path-normalisation, path-normalization, php-library
- Language: PHP
- Size: 38.1 KB
- Stars: 8
- Watchers: 3
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# Rayne\VirtualPath
The `VirtualPath` library normalises paths and
prevents directory traversal attacks
without querying a file system.
[](https://packagist.org/packages/rayne/virtual-path)
[](https://scrutinizer-ci.com/g/rayne/virtual-path/?branch=master)
[](https://scrutinizer-ci.com/g/rayne/virtual-path/?branch=master)
[](https://packagist.org/packages/rayne/virtual-path)
## Contents
* [Installation](#installation)
* [Dependencies](#dependencies)
* [Usage](#usage)
* [Examples](#examples)
* [Implementation Details](#implementation-details)
* [Tests](#tests)
## Installation
It's recommended to use the dependency manager
[Composer](https://getcomposer.org/download)
to install `rayne/virtual-path`.
```bash
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.
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.
Please read the [Implementation Details](#implementation-details) section for more details.
**TL;DR** *Use the `JailedPath` class when in doubt.*
## 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.
```php
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.
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.
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.
```php