Runkit_Sandbox

(PECL runkit >= 0.7.0)

Runkit_Sandbox Класс Runkit Sandbox -- это виртуальная машина PHP

Описание

Экземпляр класса Runkit_Sandbox создает отдельный поток основного процесса с собственным окружением и выделенной областью памяти (стеком). С помощью дополнительных параметров конструктора можно ограничивать функционал интерпретатора в песочнице, создавая таким образом безопасное окружение для выполнения пользовательского кода.

Замечание: Поддержка песочницы (необходима для runkit_lint(), runkit_lint_file(), и класса Runkit_Sandbox) доступна только начиная с версии PHP 5.1.0 или в специально пропатченных версиях PHP 5.0, а также требует потокобезопасной (thread safe) версии PHP. Для более подробной информации смотрите файл README, поставляемый с пакетом runkit.

Конструктор

Runkit_Sandbox::__construct ([ array $options ] ) : void

options ассоциативный массив, содержащий произвольную комбинацию специальных параметров, перечисленных ниже

safe_mode

Если родительский скрипт, в котором создается экземпляр Runkit_Sandbox выполняется с директивой safe_mode = off, то эту опцию можно задействовать в песочнице для включения режима safe_mode. Данный параметр не может быть использован для отключения safe_mode, если он включен во внешнем окружении.

safe_mode_gid

Если родительский скрипт, в котором создается экземпляр Runkit_Sandbox выполняется с директивой safe_mode_gid = on, то данную опцию можно задействовать для отключения safe_mode_gid в песочнице. Этот параметр нельзя использовать для включения safe_mode_gid, если он выключен во внешнем окружении.

safe_mode_include_dir

Если родительский скрипт, в котором создается экземпляр Runkit_Sandbox выполняется c заданной директивой safe_mode_include_dir, то для песочницы может быть указана новая директория, находящаяся внутри заданной. Значение safe_mode_include_dir также может быть очищено для возврата к начальным настройкам. Если директива safe_mode_include_dir не была настроена для родительского скрипта, подразумевается, что задан корневой раздел. В таком случае для песочницы можно указать любую директорию, при включенном режим safe_mode.

open_basedir

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

allow_url_fopen

Подобно safe_mode, этот параметр может быть изменен только в сторону увеличения ограничений. Допускается устанавливать его значение FALSE в случае, если значение в родительском окружении TRUE.

disable_functions

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

disable_classes

Список отключенных в песочнице классов через запятую. В этот список не надо вносить уже отключенные в родительском скрипте классы, они таковыми и останутся вне зависимости от наличия в списке.

runkit.superglobal

Список суперглобальных переменных для песочницы через запятую. Перечисленные переменные будут дополнять список существующих суперглобальных переменных, встроенных и заданных с помощью runkit.superglobal в родительском окружении.

runkit.internal_override

Параметр runkit.internal_override может быть только отключен для песочницы.

Пример #1 Пример создания безопасной песочницы

<?php
$options 
= array(
  
'safe_mode'=>true,
  
'open_basedir'=>'/var/www/users/jdoe/',
  
'allow_url_fopen'=>'false',
  
'disable_functions'=>'exec,shell_exec,passthru,system',
  
'disable_classes'=>'myAppClass');
$sandbox = new Runkit_Sandbox($options);
/* Незащищенные ini-переменные устанавливаются обычным способом */
$sandbox->ini_set('html_errors',true);
?>

Доступ к переменным

Все глобальные переменные внутри песочницы доступны через свойства объекта Runkit_Sandbox. Необходимо учитывать, что из-за особенностей распределения памяти объекты и ресурсы не могут переноситься между родительским процессом и песочницей. Массивы полностью копируются между интерпретаторами и все ссылки внутри массивов удаляются. Это также означает, что ссылки между интерпретаторами невозможны.

Пример #2 Работа с переменными в песочнице

<?php
$sandbox 
= new Runkit_Sandbox();

$sandbox->foo 'bar';
$sandbox->eval('echo "$foo\n"; $bar = $foo . "baz";');
echo 
"{$sandbox->bar}\n";
if (isset(
$sandbox->foo)) unset($sandbox->foo);
$sandbox->eval('var_dump(isset($foo));');
?>

Результат выполнения данного примера:

bar
barbaz
bool(false)

Вызов функций PHP

Любая функция, заданная в песочнице, может быть вызвана через метод объекта Runkit_Sandbox. Также доступны несколько псевдо-функций: eval(), include, include_once, require, require_once, echo, print, die() и exit().

Пример #3 Использование функций песочницы

<?php
$sandbox 
= new Runkit_Sandbox();

echo 
$sandbox->str_replace('a','f','abc');
?>

Результат выполнения данного примера:

fbc

Когда функция песочницы вызывается с параметрами, используются значения этих параметров из родительского скрипта. Если необходимо вызвать функцию со значениями из окружения песочницы, следует передавать их как свойства объекта Runkit_Sandbox. Этот механизм проиллюстрирован на следующем примере.

Пример #4 Передача аргументов функциям в песочнице

<?php
$sandbox 
= new Runkit_Sandbox();

$foo 'bar';
$sandbox->foo 'baz';
echo 
$sandbox->str_replace('a',$foo,'a');
echo 
$sandbox->str_replace('a',$sandbox->foo,'a');
?>

Результат выполнения данного примера:

bar
baz

Изменение параметров песочницы

По состоянию на версию runkit 0.5, большинство параметров песочницы могут быть изменены "на лету" с помощью синтаксиса интерфейса ArrayAccess. Некоторые параметры, например, active, доступны только для чтения. Остальные, например, output_handler, могут быть получены и записаны как обычный элемент массива. В будущем могут появиться параметры, доступные только для записи. На текущий момент таких не существует.

Настройки песочницы. Индикаторы статуса
Настройка Тип Назначение По умолчанию
active Boolean (только чтение) TRUE если песочница функционирует, FALSE если процесс завершен после вызова die() или exit(), или в результате ошибки при выполнении. TRUE (изначально)
output_handler Callback Если указана соответствующая callback-функция, весь вывод песочницы перенаправляется в указанную функцию. Обработчики вывода песочницы работают аналогично системным обработчикам вывода. None
parent_access Boolean Параметр управляет доступом к Runkit_Sandbox_Parent из песочницы. Параметр должен быть включен для работы с функционалом, предоставляемым Runkit_Sandbox_Parent. FALSE
parent_read Boolean Разрешает чтение переменных родительского окружения FALSE
parent_write Boolean Разрешает запись переменных родительского окружения FALSE
parent_eval Boolean Разрешает выполнение кода в родительском окружении DANGEROUS FALSE
parent_include Boolean Разрешает подключать php файлы в родительском окружении DANGEROUS FALSE
parent_echo Boolean Разрешает выводить данные в родительском окружении, в обход output_handler. FALSE
parent_call Boolean Разрешает вызов функций в родительском окружении FALSE
parent_die Boolean Разрешает завершать родительский скрипт (а значит и себя тоже) FALSE
parent_scope Integer Настройка области видимости песочницы для внешнего окружения: 0 == Глобальная область видимости, 1 == область вызова, 2 == область до области вызова, 3 == область до этой области, и т.д. 0 (Global)
parent_scope String В случае, когда параметр parent_scope задан строковым значением, он указывает на массив в глобальной области видимости. Если массива не существует - будет создан пустой массив с указанным именем. Если существует переменная с заданным именем, не являющаяся массивом - будет создан массив, содержащий ссылку на существующую переменную.