virtual path

RayneVirtualPath

A biblioteca VirtualPath normaliza caminhos e evita ataques de passagem de diretório sem consultar um sistema de arquivos.

Conteúdo

• Instalação
• Dependências
• Uso
• Exemplos
• Detalhes de implementação
• Testes

Instalação

É recomendado usar o gerenciador de dependências Composer para instalar rayne/virtual-path .

composer require rayne/virtual-path

Dependências

• PHP 5.6 ou melhor

Uso

A classe VirtualPath normaliza as entradas para virtual path absolutos sem consultar qualquer sistema de arquivos. Ele também detecta e sinaliza ataques de passagem de diretório.

A classe JailedPath utiliza VirtualPath para construir caminhos seguros que podem ser usados ​​para trabalhar com arquivos reais. A normalização é feita em relação a uma jail chamada path que é usada como raiz virtual para qualquer caminho inserido pelo usuário. Como JailedPath não consulta o sistema de arquivos, ele é adequado para trabalhar com caminhos locais, remotos ou fictícios.

Leia a seção Detalhes da implementação para obter mais detalhes.

DR Use a classe JailedPath em caso de dúvida.

Exemplos

JailedPath

Neste exemplo, os visitantes do site podem baixar qualquer arquivo do diretório local /test especificando o caminho relativo como parâmetro GET . Para evitar que os usuários saiam do diretório com ataques de passagem de diretório, JailedPath é usado com /test como diretório raiz 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 ());
}

A tabela a seguir mostra como os caminhos definidos pelo usuário são normalizados e como são interpretados em relação à raiz virtual.

Entrada do usuário	hasJailbreakAttempt()	getAbsolutePath()	getRelativePath()
String vazia	false	/test	String vazia
.	false	/test	String vazia
a.png/../b.png	false	/test/b.png	b.png
/a/./b	false	/test/a/b	a/b
..	true	/test	String vazia
../example	true	/test/example	example
../etc/passwd	true	/test/etc/passwd	etc/passwd
Variedade	true	/test	String vazia

VirtualPath

Se um prefixo fixo ou o revestimento açucarado de JailedPath não for necessário, então VirtualPath será suficiente, pois é a classe usada para normalizar caminhos. VirtualPath normaliza a entrada e fornece um caminho confiável (normalizado, com um / ) inicial e um caminho não confiável (uma representação de string da entrada do usuário provavelmente maliciosa).

O exemplo anterior pode ser facilmente recriado com VirtualPath quando a instância de VirtualPath (que pode ser convertida em (string) ) é anexada ao diretório raiz virtual.

 <?php

use Rayne  VirtualPath  VirtualPath ;

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

Dependendo do cenário de uso, às vezes é útil trabalhar com o caminho confiável normalizado, mesmo que a entrada original não seja confiável, por exemplo, ao apoiar explicitamente caminhos relativos e dar ao usuário o benefício da dúvida ao tentar acidentalmente acessar arquivos fora do virtual path .

Nota : VirtualPath retorna o caminho normalizado com um / inicial. Ao trabalhar com arquivos, é recomendado adicionar um caminho confiável como prefixo (veja o exemplo de código na seção atual), caso contrário, os arquivos relativos à raiz do sistema de arquivos seriam referenciados. Para não esquecer de adicionar o prefixo, use a classe JailedPath ao trabalhar com arquivos reais.

Entrada	isTrusted()	getTrustedPath()	getUntrustedPath()
Variedade	false	/	String vazia
String vazia	true	/	String vazia
../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

Detalhes de implementação

Usar um caminho normalizado virtual puro tem benefícios diferentes:

• A normalização do caminho é feita sem consultar um sistema de arquivos

• É impossível forjar ataques de temporização para arquivos fora do escopo do virtual path

• Nenhuma comparação complexa é necessária para limitar as travessias de diretório a um diretório específico e seus filhos

• Apenas . , .. , (normalizado para / ) e / são interpretados para normalização de caminho

• Sem expansões inesperadas e com ~ de informações, como visto em outras bibliotecas

A implementação do VirtualPath não interpreta, altera ou remove caracteres de controle e Unicode:

• Os caminhos de diretório e arquivo podem conter caracteres de controle em alguns sistemas

• A remoção de caracteres de controle está fora do escopo da biblioteca

Testes

1. Clonar o repositório

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

2. Instale as dependências de desenvolvimento

   composer install --dev

3. Execute os testes

   composer test