virtual path

RayneRutaVirtual

La biblioteca VirtualPath normaliza las rutas y evita ataques de cruce de directorios sin consultar un sistema de archivos.

Contenido

• Instalación
• Dependencias
• Uso
• Ejemplos
• Detalles de implementación
• Pruebas

Instalación

Se recomienda utilizar el administrador de dependencias Composer para instalar rayne/virtual-path .

composer require rayne/virtual-path

Dependencias

• PHP 5.6 o mejor

Uso

La clase VirtualPath normaliza las entradas a virtual path absolutas sin consultar ningún sistema de archivos. También detecta y marca ataques de cruce de directorios.

La clase JailedPath utiliza VirtualPath para crear rutas seguras que pueden usarse para trabajar con archivos reales. La normalización se realiza en relación con una jail llamada ruta que se utiliza como raíz virtual para cualquier ruta ingresada por el usuario. Como JailedPath no consulta el sistema de archivos, es adecuado para trabajar con rutas locales, remotas o ficticias.

Lea la sección Detalles de implementación para obtener más detalles.

TL;DR Utilice la clase JailedPath en caso de duda.

Ejemplos

JailedPath

En este ejemplo, los visitantes del sitio web pueden descargar cualquier archivo del directorio local /test especificando la ruta relativa como parámetro GET . Para evitar que los usuarios abandonen el directorio con ataques transversales de directorio, se utiliza JailedPath con /test como directorio raíz virtual.

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

La siguiente tabla muestra cómo se normalizan las rutas definidas por el usuario y cómo se interpretan en relación con la raíz virtual.

Entrada del usuario	hasJailbreakAttempt()	getAbsolutePath()	getRelativePath()
Cadena vacía	false	/test	Cadena vacía
.	false	/test	Cadena vacía
a.png/../b.png	false	/test/b.png	b.png
/a/./b	false	/test/a/b	a/b
..	true	/test	Cadena vacía
../example	true	/test/example	example
../etc/passwd	true	/test/etc/passwd	etc/passwd
Formación	true	/test	Cadena vacía

VirtualPath

Si no se requiere un prefijo fijo o la capa de azúcar de JailedPath , entonces VirtualPath es suficiente ya que es la clase utilizada para normalizar rutas. VirtualPath normaliza la entrada y proporciona una ruta confiable (normalizada, con un / inicial) y una ruta no confiable (una representación de cadena de la entrada probablemente maliciosa del usuario).

El ejemplo anterior se puede recrear fácilmente con VirtualPath cuando la instancia de VirtualPath (que se puede convertir (string) ) se agrega al directorio raíz virtual.

 <?php

use Rayne  VirtualPath  VirtualPath ;

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

Dependiendo del escenario de uso, a veces es útil trabajar con la ruta confiable normalizada incluso si la entrada original no es confiable, por ejemplo, cuando se admiten explícitamente rutas relativas y se le brinda al usuario el beneficio de la duda cuando accidentalmente intenta acceder a archivos fuera de la virtual path .

Nota : VirtualPath devuelve la ruta normalizada con un / inicial. Cuando se trabaja con archivos, se recomienda agregar una ruta confiable como prefijo (consulte el ejemplo de código en la sección actual), ya que de lo contrario se haría referencia a los archivos relativos a la raíz del sistema de archivos. Para no olvidar agregar el prefijo, use la clase JailedPath cuando trabaje con archivos reales.

Aporte	isTrusted()	getTrustedPath()	getUntrustedPath()
Formación	false	/	Cadena vacía
Cadena vacía	true	/	Cadena vacía
../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

Detalles de implementación

Usar una ruta normalizada virtual pura tiene diferentes beneficios:

• La normalización de rutas se realiza sin consultar un sistema de archivos.

• Es imposible falsificar ataques de sincronización para archivos fuera del alcance de la virtual path

• No se requieren comparaciones complejas para limitar los recorridos de directorio a un directorio específico y sus hijos.

• Solo . , .. , (normalizado a / ) y / se interpretan para la normalización de ruta

• Sin imprevistos ni fugas de información ~ expansiones como se ve en otras bibliotecas

La implementación de VirtualPath no interpreta, altera ni elimina caracteres de control y Unicode:

• Las rutas de directorios y archivos pueden contener caracteres de control en algunos sistemas.

• La eliminación de caracteres de control está fuera del alcance de la biblioteca

Pruebas

1. Clonar el repositorio

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

2. Instalar las dependencias de desarrollo.

   composer install --dev

3. ejecutar las pruebas

   composer test