README

(基于AOP-PHP/AOP)

PHPWatchDog 允许您为函数与方法调用创建细粒度的访问策略，并限制文件访问。尽管您始终可以在操作系统级别设置文件权限，并使用 disable_functions 在整个 PHP 环境中禁用某些函数，但此库允许您复制此行为，但按作用域进行控制。例如，您可以通过在代码中尽可能早地包含以下行来限制对 CustomJSONEncoder 类中 encode() 方法的 json_encode() 的访问。

        \OutCompute\PHPWatchDog\Main::configure(
                array(
                    'functions' => array(
                        'json_encode()' => array(
                            'default' => 'block',
                            'except' => array(
                                array(
                                    'scope' => 'CustomJSONEncoder->encode()'
                                )
                            )
                        )
                    )
                )
        );

上面的代码块会将 PHPWatchDog 配置为在从 CustomJSONEncoder->encode() 方法作用域之外访问 json_encode 时抛出异常。同样，您也可以限制特定作用域对特定文件的读写访问，如下所示

        \OutCompute\PHPWatchDog\Main::configure(
                array(
                    'files' => array(
                        'licenceKeys' => array(
                            'default' => 'block',
                            'except' => array(
                                array(
                                    'scope' => 'Licence->get()'
                                )
                            )
                        )
                    )
                )
        );

注意：此库会监视任何执行代码或启用当前上下文执行代码的函数（例如：eval()），而不会监视跳出当前执行过程上下文执行的代码（例如：exec()）。

什么是面向切面编程（AOP）？

上述功能是通过此AOP 库实现的，该库在 PHP 中实现了AOP。强烈建议您从提供的链接中了解 AOP，但这里提供了一个简化说明。AOP 允许程序员指定在执行过程中发生特定事件时要执行的功能，事件可以是任何函数或方法调用。此处提供的 PHPWatchDog 库使用 AOP，并允许库用户将访问策略指定为 PHP 关联数组，并根据数组设置切入点。在上面的第一个示例中，库将监视每个 json_encode 调用，并检查调用来源的作用域和文件名是否与任何 'except' 规则匹配，然后咨询每个 except 和默认过滤器，决定是阻止还是允许执行。此处使用的 AOP 库本身是一个非常好的工具，具有比此处使用的更多功能。您可以在这里了解更多信息。

如何使用

以下是一些使用此库的建议

您需要为 PHP 安装安装 AOP 扩展，安装步骤在此提供。建议不要使用 pecl install 路由，而是在自己的系统上编译。主分支已在 RedHat/Debian 上针对 PHP 版本 5.4、5.5 和 5.6 进行了测试，并且它们可以无问题编译。以下文档还列出了获取预安装和配置有 AOP 扩展、PHP 和 PHPUnit 的 Docker 图像的步骤。
不要将 configure 调用的结果分配给变量。这将防止任何恶意代码删除它。主类实现为单例，因此，当您使用有效的参数调用 configure() 时，属性就会设置一次。
尽可能早地调用 Main::configure，以防止任何代码禁用 AOP、尝试阻止执行或安装规避此库效果的措施。完全限定的类名和参数如下所示

    /*
     * @var array $watchlist        An array of the following format.
     *                              array(
     *                                  'functions' => array(
     *                                      'targetFunction()' => array(
     *                                          'default' => 'block', # Mandatory Key, can be either 'allow' or 'block'
     *                                          # If default is block, the below combinations in 'except' will allow targetFunction().
     *                                          # If default is allow, then the below combinations will block targetFunction().
     *                                          'except' => array(
     *                                              array(
     *                                                  'file' => 'AllowedFile.php',
     *                                                  'scope' => 'AllowedClass->AllowedMethod()'
     *                                              ),
     *                                              ... # You can specify more combinations here targeting targetFunction()
     *                                          )
     *                                      )
     *                                  ),
     *                                  'files' => array(
     *                                      'logs.log' => array(
     *                                          'default' => 'allow',
     *                                          'except' => array(
     *                                              array(
     *                                                  'file' => 'upload.php'
     *                                              ),
     *                                              ...
     *                                          )
     *                                      )
     *                                  )
     *                              )
     * @var boolean $haltOnIncident Specifies if the library should call die() after throwing the Exception() anytime a policy violation incident happens
     */
    \OutCompute\PHPWatchDog\Main::configure($watchlist, $haltOnIncident)

创建方法监视列表时请谨慎，因为可能创建一个访问策略，该策略可能会干扰到库的执行，因为该库使用了某些PHP函数。

注意：这仍然处于概念验证状态，不建议在生产系统中使用。然而，鼓励大家使用它，通过实际验证来推翻这个概念，寻找错误或扩展它。

预构建的Docker镜像

基于Debian的3个不同版本的PHP（5.4、5.5和5.6）的Docker镜像，以及AOP扩展和PHPUnit，也在这里提供。您可以使用这些Docker镜像，例如运行PHPUnit测试，如下所示

$ git clone https://github.com/outcompute/PHPWatchDog.git
$ docker pull outcompute/php-phpunit-aop

PHP5.6:

 $ docker run -itv <absolute path to PHPWatchDog directory>:/app outcompute/php-phpunit-aop:php56 phpunit

PHP5.5:

 $ docker run -itv <absolute path to PHPWatchDog directory>:/app outcompute/php-phpunit-aop:php55 phpunit

PHP5.4:

 $ docker run -itv <absolute path to PHPWatchDog directory>:/app outcompute/php-phpunit-aop:php54 phpunit

用例

几个攻击向量通过上传恶意文件或执行任意代码来注入代码，用他们的攻击向量覆盖有效代码。PHPWatchDog可以用来防止这种情况，并限制执行任何未明确允许的代码。您可以通过在.htaccess或VirtualHost块中使用auto_prepend_file配置来加载PHPWatchDog，并默认对所有脚本执行访问策略。

待办事项

收集反馈并验证概念

许可证

MIT

outcompute / phpwatchdog

维护者

详细信息