virtual path

راينVirtualPath

تقوم مكتبة VirtualPath بتطبيع المسارات وتمنع هجمات اجتياز الدليل دون الاستعلام عن نظام الملفات.

محتويات

• تثبيت
• التبعيات
• الاستخدام
• أمثلة
• تفاصيل التنفيذ
• الاختبارات

تثبيت

يوصى باستخدام مدير التبعية Composer لتثبيت rayne/virtual-path .

composer require rayne/virtual-path

التبعيات

• PHP 5.6 أو أفضل

الاستخدام

تقوم فئة VirtualPath بتطبيع المدخلات إلى virtual path المطلق دون الاستعلام عن أي نظام ملفات. كما أنه يكتشف هجمات اجتياز الدليل ويضع علامة عليها.

تستخدم فئة JailedPath VirtualPath لإنشاء مسارات آمنة يمكن استخدامها للعمل مع الملفات الحقيقية. تتم التسوية بالنسبة إلى jail يسمى المسار والذي يستخدم كجذر افتراضي لأي مسار يدخله المستخدم. نظرًا لأن 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 إلى تفسير أو تغيير أو إزالة أحرف التحكم وUnicode:

• يُسمح لمسارات الدليل والملفات بأن تحتوي على أحرف تحكم في بعض الأنظمة

• إزالة أحرف التحكم خارج نطاق المكتبة

الاختبارات

1. استنساخ المستودع

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

2. تثبيت تبعيات التطوير

   composer install --dev

3. قم بإجراء الاختبارات

   composer test