README

一个全功能的PHP 7.4+沙盒类，利用PHP-Parser来防止沙盒代码运行不安全代码。

它还利用FunctionParser来反汇编传递给沙盒的可调用项，这样PHP可调用项也可以在沙盒中运行，而无需先将它们转换为字符串。

手册： https://manual.phpsandbox.org

在线API文档： https://docs.phpsandbox.org

功能

• 细粒度白名单和黑名单，并配置合理的默认设置。
• 包括动态演示系统，允许对自定义沙盒配置进行本地测试。
• 可以重新定义内部PHP和其他函数，使其在沙盒中使用更加安全。
• 可以重新定义超全局变量和魔法常量，以将自定义值暴露给沙盒代码。
• 可以覆盖get_defined_*和get_declared_*函数，只向沙盒代码显示允许的函数、类等。
• 可以选择性地允许和禁止函数创建、类声明、常量定义、关键字等。
• 可以在设置和关闭沙盒时添加和附加可信代码，并自动将它们定义的类、函数、变量等白名单。
• 可以检索生成的沙盒代码以供以后使用。
• 可以通过execute方法直接将参数传递给沙盒代码，以便向沙盒揭示选定的外部变量。
• 可以访问解析的、准备的和生成的代码AST，以供进一步分析或序列化。
• 可以为沙盒的每个元素定义自定义验证函数，以进行细粒度控制。
• 可以指定自定义错误处理程序来拦截PHP错误，并使用自定义逻辑处理它们。
• 可以指定自定义异常处理程序来拦截抛出的异常，并使用自定义逻辑处理它们。
• 可以指定验证错误处理程序来拦截抛出的验证错误，并使用自定义逻辑处理它们。
• 可以拦截回调并验证它们是否与函数白名单和黑名单匹配，即使它们是以字符串形式调用的。

示例用法

function test($string){
    return 'Hello ' . $string;
}

$sandbox = new PHPSandbox\PHPSandbox;
$sandbox->whitelistFunc('test');
$result = $sandbox->execute(function(){
   return test('world');
});

var_dump($result);  //Hello world

自定义验证示例

function custom_func(){
    echo 'I am valid!';
}

$sandbox = new PHPSandbox\PHPSandbox;
//this will mark any function valid that begins with "custom_"
$sandbox->setFuncValidator(function($function_name, PHPSandbox\PHPSandbox $sandbox){
    return (substr($function_name, 0, 7) == 'custom_');  //return true if function is valid, false otherwise
});
$sandbox->execute(function(){
    custom_func();
});
//echoes "I am valid!"

自定义验证错误处理程序示例

$sandbox = new PHPSandbox\PHPSandbox;
//this will intercept parser validation errors and quietly exit, otherwise it will throw the validation error
$sandbox->setValidationErrorHandler(function(PHPSandbox\Error $error, PHPSandbox\PHPSandbox $sandbox){
    if($error->getCode() == PHPSandbox\Error::PARSER_ERROR){ //PARSER_ERROR == 1
        exit;
    }
    throw $error;
});
$sandbox->execute('<?php i am malformed PHP code; ?>');
//does nothing

禁用验证示例

$sandbox = new PHPSandbox\PHPSandbox;
//this will disable function validation
$sandbox->setOption('validate_functions', false); // or $sandbox->validate_functions = false;
$sandbox->execute('<?php echo system("ping google.com"); ?>');
//Pinging google.com. . .

要求

• PHP 7.4+
• PHP-Parser
• FunctionParser（如果您想使用闭包）
• PHP应该使用--enable-tokenizer选项编译（通常是这样）

安装

要使用composer安装，只需将以下内容添加到项目根目录中的composer.json文件中

{
    "require": {
        "corveda/php-sandbox": "3.*"
    }
}

然后运行composer install --dry-run来检查任何潜在问题，并运行composer install进行安装。

许可证

Copyright (c) 2013-2021 by Corveda, LLC.

Some rights reserved.

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are
met:

    * Redistributions of source code must retain the above copyright
      notice, this list of conditions and the following disclaimer.

    * Redistributions in binary form must reproduce the above
      copyright notice, this list of conditions and the following
      disclaimer in the documentation and/or other materials provided
      with the distribution.

    * The names of the contributors may not be used to endorse or
      promote products derived from this software without specific
      prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.