Runkit Sandbox クラス -- PHP バーチャルマシン

説明

Runkit_Sandbox クラスをインスタンス化すると、独自のスコープとプログラムスタックを持つ新しいスレッドが生成されます。コンストラクタに渡すオプションを設定することで、この環境ではインタプリタの機能を制限することが可能す。そのため、ユーザから渡されたコードを実行する場合などに、より安全な環境を提供可能です。

注意: サンドボックスのサポート (runkit_lint(), runkit_lint_file(), および Runkit_Sandbox クラスで使用)は、 PHP 5.1.0 以降または特別なパッチを適用した PHP 5.0 でのみ利用可能であり、スレッドセーフを有効にしておく必要があります。詳細については、runkit パッケージに含まれる README ファイルを参照してください。

コンストラクタ

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

options は連想配列で、その中に以下の ini オプションの組み合わせを格納します。

safe_mode: Runkit_Sandbox クラスをインスタンス化した外部スクリプトが safe_mode = off と設定されている場合、サンドボックス内の safe_mode を on にすることが可能です。外部スクリプトで safe_mode が有効になっている場合に、サンドボックス内でそれを無効にすることはできません。
safe_mode_gid: Runkit_Sandbox クラスをインスタンス化した外部スクリプトが safe_mode_gid = on と設定されている場合、サンドボックス内の safe_mode_gid を off にすることが可能です。外部スクリプトで safe_mode_gid が無効になっている場合に、サンドボックス内でそれを有効にすることはできません。
safe_mode_include_dir: Runkit_Sandbox クラスをインスタンス化した外部スクリプトが safe_mode_include_dir を組み込んで configure されていた場合、サンドボックス内の safe_mode_include_dir を定義されているディレクトリ以下に指定することが可能です。この機能を無効にすることを示すため、safe_mode_include_dir をクリアすることも可能です。外部スクリプトで safe_mode_include_dir が空白になっているが safe_mode は有効でない場合、任意の safe_mode_include_dir を指定して safe_mode を on にすることが可能です。
open_basedir: open_basedir は、カレントの open_basedir 以下の任意のパスを指定可能です。グローバルスコープで open_basedir が指定されていない場合、それはルートディレクトリと判断され、どの場所でも指定可能となります。
allow_url_fopen: safe_mode と同様、より厳しくする方向にのみ指定可能です。この場合は TRUE と指定されている場合に FALSE を指定することが可能となります。
disable_functions: サンドボックス内のインタプリタで無効とする関数を、カンマ区切りのリストで指定します。現在すでに無効になっている関数名を含める必要はありません。それらはリストに載っているか否かにかかわらず無効となります。
disable_classes: サンドボックス内のインタプリタで無効とするクラスを、カンマ区切りのリストで指定します。現在すでに無効になっているクラス名を含める必要はありません。それらはリストに載っているか否かにかかわらず無効となります。
runkit.superglobal: サンドボックス内のインタプリタでスーパーグローバルとして扱う変数を、カンマ区切りのリストで指定します。これらの変数は、既に内部で定義されている変数やグローバルの runkit.superglobal 設定に追加して使用されます。
runkit.internal_override: Ini オプション 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);
?>

変数へのアクセス

サンドボックス環境内のすべてのグローバル変数は、サンドボックスオブジェクトのプロパティとしてアクセス可能です。しかし、オブジェクト変数やリソース変数はインタプリタ越しに利用することができないことに注意しましょう。これは、これらの 2 つのスレッドのメモリ管理が仮想マシン上で行われていることが原因です。さらに、配列はすべてディープコピーされ、参照渡しのデータは失われます。つまり、参照渡しのデータをインタプリタ越しに使用することはできないということです。

例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 関数のコール

サンドボックス内で定義されている関数は、すべてサンドボックスオブジェクトのメソッドとしてコールできます。これには、擬似関数として扱われる以下のような言語構造も含みます。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

サンドボックス内の関数への引数は、外部の PHP インスタンスから渡されます。もしサンドボックスのスコープから引数を渡したい場合は、上で示したようにサンドボックスのプロパティとしてそれにアクセスするようにしてください。

例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 以降では、配列へのアクセスと同じ構文で、実行時にサンドボックスの一部の設定を変更することが可能です。 active は読み込み専用で、現在の状態についての情報を提供します。output_handler は通常の配列オフセットと同様に読み書きが可能です。将来的には書き込み専用の設定項目も現れるかもしれませんが、今のところはそのような項目はありません。

**サンドボックス設定 / 状態のインジケータ**
設定	型	目的	デフォルト
active	Boolean (Read Only)	サンドボックスが使用可能な状態である場合に `TRUE` 、 die() や exit() のコールもしくは致命的なエラーなどでリクエストから抜けた状態である場合に `FALSE` 。	`TRUE` (Initial)
output_handler	Callback	有効なコールバックを指定すると、サンドボックスインスタンスの生成するすべての出力に対してその関数が適用されます。サンドボックス出力ハンドラは、システム全体の出力ハンドラと同じ呼び出し規約に従います。	なし
parent_access	Boolean	サンドボックスが Runkit_Sandbox_Parent クラスのインスタンスを使用するかどうか。使用するには、その他の Runkit_Sandbox_Parent 関連の設定を有効にする必要があります。	`FALSE`
parent_read	Boolean	サンドボックスが親コンテキストの変数を読み込むかどうか。	`FALSE`
parent_write	Boolean	サンドボックスが親コンテキストの変数を変更するかどうか。	`FALSE`
parent_eval	Boolean	サンドボックスが親コンテキストの任意のコードを評価する（evaluate）かどうか。危険です。	`FALSE`
parent_include	Boolean	サンドボックスが親コンテキストの php ファイルを include するかどうか。危険です。	`FALSE`
parent_echo	Boolean	サンドボックスが親コンテキストのデータを表示する際に、それ自身の出力ハンドラを回避するかどうか。	`FALSE`
parent_call	Boolean	サンドボックスが親コンテキストの関数をコールするかどうか。	`FALSE`
parent_die	Boolean	サンドボックスが親コンテキスト（そして自分自身）を終了させるかどうか。	`FALSE`
parent_scope	Integer	親のプロパティに対してどのようなスコープでアクセスするか。 0 == Global scope, 1 == Calling scope, 2 == Scope preceeding calling scope, 3 == The scope before that, etc..., etc...	0 (Global)
parent_scope	String	parent_scope に文字列値が設定されている場合は、グローバルスコープの配列変数名を表します。アクセス時にその名前の変数が存在しない場合は、空の配列が作成されます。変数が存在するが配列ではない場合は、その変数への参照を含むダミー配列が作成されます。