virtual path

Рейнвиртуалпуть

Библиотека VirtualPath нормализует пути и предотвращает атаки обхода каталогов без запроса файловой системы.

Содержание

• Установка
• Зависимости
• Использование
• Примеры
• Детали реализации
• Тесты

Установка

Для установки rayne/virtual-path рекомендуется использовать диспетчер зависимостей Composer.

composer require rayne/virtual-path

Зависимости

• PHP 5.6 или выше

Использование

Класс VirtualPath нормализует входные данные до абсолютных virtual path без запроса какой-либо файловой системы. Он также обнаруживает и помечает атаки с обходом каталога.

Класс JailedPath использует VirtualPath для создания безопасных путей, которые можно использовать для работы с реальными файлами. Нормализация выполняется относительно jail под названием path, которая используется в качестве виртуального корня для любого пути, введенного пользователем. Поскольку JailedPath не запрашивает файловую систему, он подходит для работы с локальными, удаленными или вымышленными путями.

Пожалуйста, прочитайте раздел «Детали реализации» для получения более подробной информации.

TL;DR Используйте класс JailedPath если сомневаетесь.

Примеры

JailedPath

В этом примере посетителям веб-сайта разрешено загружать любой файл из локального каталога /test , указав относительный путь в качестве параметра GET . Чтобы пользователи не могли покинуть каталог с помощью атак обхода каталога, JailedPath используется с /test в качестве виртуального корневого каталога.

 <?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 ());
}

В следующей таблице показано, как нормализуются определяемые пользователем пути и как они интерпретируются относительно виртуального корня.

Пользовательский ввод	hasJailbreakAttempt()	getAbsolutePath()	getRelativePath()
Пустая строка	false	/test	Пустая строка
.	false	/test	Пустая строка
a.png/../b.png	false	/test/b.png	b.png
/a/./b	false	/test/a/b	a/b
..	true	/test	Пустая строка
../example	true	/test/example	example
../etc/passwd	true	/test/etc/passwd	etc/passwd
Множество	true	/test	Пустая строка

VirtualPath

Если фиксированный префикс или «сахарное покрытие» JailedPath не требуется, достаточно VirtualPath , поскольку это класс, используемый для нормализации путей. VirtualPath нормализует входные данные и предоставляет доверенный (нормализованный, с ведущим / ) и недоверенный (строковое представление вероятно вредоносного пользовательского ввода) путь.

Предыдущий пример можно легко воссоздать с помощью VirtualPath когда экземпляр VirtualPath (который допускает приведение (string) приведение) добавляется к виртуальному корневому каталогу.

 <?php

use Rayne  VirtualPath  VirtualPath ;

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

В зависимости от сценария использования иногда полезно работать с нормализованным доверенным путем, даже если исходные входные данные не заслуживают доверия, например, когда явная поддержка относительных путей и предоставление пользователю преимущества сомнения при случайной попытке доступа к файлам за пределами virtual path .

Примечание . VirtualPath возвращает нормализованный путь с начальным символом / . При работе с файлами рекомендуется добавлять в качестве префикса доверенный путь (см. пример кода в текущем разделе), так как в противном случае будут ссылаться на файлы, относящиеся к корню файловой системы. Чтобы не забыть добавить префикс, используйте вместо него класс JailedPath при работе с реальными файлами.

Вход	isTrusted()	getTrustedPath()	getUntrustedPath()
Множество	false	/	Пустая строка
Пустая строка	true	/	Пустая строка
../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

Детали реализации

Использование чистого виртуального нормализованного пути имеет различные преимущества:

• Нормализация пути выполняется без запроса файловой системы.

• Невозможно организовать временную атаку для файлов за пределами virtual path

• Никаких сложных сравнений не требуется, чтобы ограничить обход каталогов определенным каталогом и его дочерними элементами.

• Только . , .. , (нормализованные к / ) и / интерпретируются для нормализации пути.

• Никаких неожиданных ~ и утечек информации, как в других библиотеках.

Реализация VirtualPath не интерпретирует, не изменяет и не удаляет управляющие символы и Юникод:

• В некоторых системах пути к каталогам и файлам могут содержать управляющие символы.

• Удаление управляющих символов выходит за рамки библиотеки.

Тесты

1. Клонировать репозиторий

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

2. Установите зависимости разработки

   composer install --dev

3. Запустите тесты

   composer test