README

Shieldon 是一个针对PHP的Web应用程序防火墙（WAF），它具有美观且实用的控制面板，可以帮助您轻松管理防火墙规则和安全设置。

• 网站: https://shieldon.io
• Wiki: https://github.com/terrylinooo/shieldon/wiki
• GitHub仓库: https://github.com/terrylinooo/shieldon
• WordPress插件: https://wordpresstheme.cn/plugins/wp-shieldon/

演示

• 在安装Shieldon之前，您可以尝试防火墙控制面板的在线 DEMO，用户名和密码都是 demo。
• 在 shieldon.io 上尝试使用Shieldon临时阻止，刷新几次后，您将看到一个要求您解决Google ReCaptcha以取消阻止的对话框。

安装

通过PHP Composer安装。

composer require shieldon/shieldon ^2

这将同时安装为Shieldon构建的依赖项

概念

这是关于Shieldon如何工作的基本概念。

• 网络层防火墙，如CloudFlare。
• 系统层防火墙，如iptables模块。
• 要使用Web应用程序层的防火墙软件，您可以在APP的非常早期阶段实现Shieldon，通常是在Composer自动加载之后或中间件管道的第一位。
• Shieldon分析所有您的HTTP和HTTPS请求。
• 一旦Shieldon检测到请求的异常行为，就会将其阻止并提示进行CAPTCHA以取消阻止。
• 如果请求连续多次失败（取决于您的设置），它们将在当前数据圈中永久禁止。
• 如果请求已被永久禁止，但它们仍然访问您的页面，则在系统层防火墙 - iptables中丢弃它们。（您必须正确设置iptables网桥）

如何使用

与框架集成

这里有一些逐步安装指南，帮助您在PHP应用程序上实施Shieldon防火墙。请选择您正在使用的框架。

Laravel	CakePHP 3	Symfony	PHPixie
FatFree	CodeIgniter 3 CodeIgniter 4	Yii 2	Zend MVC Zend Expressive
		-
Slim 3 Slim 4	Fuel	纯PHP项目

列出的框架：Laravel、Symfony、CodeIgniter、CakePHP、Yii、Zend、Slim、Fat-Free、Fuel、PHPixie。找不到您所使用框架的文档？

您可以选择三种方式在应用程序中使用Shieldon。

• 将Shieldon作为PSR-15中间件实施。
• 在应用程序的引导阶段实施Shieldon。
• 在由其他控制器扩展的父控制器中实施Shieldon。

Shieldon 2.x实现了PSR-7，以便与Laravel、Symfony、Slim、Yii等现代框架兼容。

PSR-15中间件

示例：Slim 4框架

在这个示例中，我将向您提供有关如何将Shieldon作为PSR-15中间件实施的一些提示。

我使用Slim 4框架进行演示。这种方法也可以用于支持PSR-15的任何框架，只需稍作修改。

(1) 创建防火墙中间件。

class FirewallMiddleware
{
    /**
     * Example middleware invokable class
     *
     * @param ServerRequest  $request PSR-7 request
     * @param RequestHandler $handler PSR-15 request handler
     *
     * @return Response
     */
    public function __invoke(Request $request, RequestHandler $handler): Response
    {
        $response = $handler->handle($request);

        $firewall = new \Shieldon\Firewall\Firewall($request, $response);

        // The directory in where Shieldon Firewall will place its files.
        $firewall->configure(__DIR__ . '/../cache/shieldon_firewall');

        // The base url for the control panel.
        $firewall->controlPanel('/firewall/panel/');

        $response = $firewall->run();

        if ($response->getStatusCode() !== 200) {
            $httpResolver = new \Shieldon\Firewall\HttpResolver();
            $httpResolver($response);
        }

        return $response;
    }
}

(2) 在您的应用程序中添加防火墙中间件。

例如，如果您使用的是Slim 4框架，代码应如下所示。

$app->add(new FirewallMiddleware());

(3) 创建控制面板的路由。

例如，如果您使用的是Slim 4框架，代码应如下所示。然后您可以通过访问URL https://yourwebsite.com/firewall/panel 登录到控制面板。

$app->any('/firewall/panel[/{params:.*}]', function (Request $request, Response $response, $args) {
    $firewall = new \Shieldon\Firewall\Firewall($request, $response);

    // The directory in where Shieldon Firewall will place its files.
    // Must be the same as firewallMiddleware.
    $firewall->configure(__DIR__ . '/../cache/shieldon_firewall');

    $panel = new \Shieldon\Firewall\Panel();
    $panel->entry();
});

注意

• HTTP方法POST和GET都应该应用于您的网站。
• POST方法用于解决被临时阻止的用户需要解决的CAPTCHA。

引导阶段

示例：Laravel 6框架

在应用程序的引导阶段初始化Shieldon，通常是在composer自动加载器之后。

在这个示例中，我使用Laravel 6进行演示。

(1) 在初始化$app之前

在您的bootstrap/app.php中，在<?php之后，添加以下代码。

/*
|--------------------------------------------------------------------------
| Run The Shieldon Firewall
|--------------------------------------------------------------------------
|
| Shieldon Firewall will watch all HTTP requests coming to your website.
| Running Shieldon Firewall before initializing Laravel will avoid possible
| conflicts with Laravel's built-in functions.
*/
if (isset($_SERVER['REQUEST_URI'])) {

    // This directory must be writable.
    // We put it in the `storage/shieldon_firewall` directory.
    $storage =  __DIR__ . '/../storage/shieldon_firewall';

    $firewall = new \Shieldon\Firewall\Firewall();
    $firewall->configure($storage);

    // The base url for the control panel.
    $firewall->controlPanel('/firewall/panel/');
    $response = $firewall->run();

    if ($response->getStatusCode() !== 200) {
        $httpResolver = new \Shieldon\Firewall\HttpResolver();
        $httpResolver($response);
    }
}

(2) 定义防火墙面板的路由。

Route::any('/firewall/panel/{path?}', function() {

    $panel = new \Shieldon\Firewall\Panel();
    $panel->csrf(['_token' => csrf_token()]);
    $panel->entry();

})->where('path', '(.*)');

父控制器

示例：CodeIgniter 3 框架

如果您使用的是 MVC 框架，在父控制器中实现 Shieldon 也是一个不错的选择。在这个例子中，我使用 CodeIgniter 3 进行演示。

1. 创建父控制器。

让我们在 core 文件夹中创建一个 MY_Controller.php。

class MY_Controller extends CI_Controller
{
    public function __construct()
    {
        parent::__construct();
    }
}

2. 初始化防火墙实例

将初始代码放在构造函数中，以便任何扩展 MY_Controller 的控制器都将有初始化的 Shieldon 防火墙和 $this->firewall() 方法。

class MY_Controller extends CI_Controller
{
    public function __construct()
    {
        parent::__construct();

        // Composer autoloader
        require_once APPPATH . '../vendor/autoload.php';

        // This directory must be writable.
        $storage = APPPATH . 'cache/shieldon_firewall';

        $firewall = new \Shieldon\Firewall\Firewall();
        $firewall->configure($storage);

        // The base url for the control panel.
        $firewall->controlPanel('/firewall/panel/');
        $response = $firewall->run();

        if ($response->getStatusCode() !== 200) {
            $httpResolver = new \Shieldon\Firewall\HttpResolver();
            $httpResolver($response);
        }
    }

    /**
     * Shieldon Firewall protection.
     */
    public function firewall()
    {
        $firewall = \Shieldon\Container::get('firewall');
        $firewall->run();
    }
}

3. 定义控制面板的控制器。

我们需要一个控制器来访问 Shieldon 防火墙控制面板，在这个例子中，我们定义了一个名为 Firewall 的控制器。

class Firewall extends MY_Controller
{
    public function __construct()
    {
        parent::__construct();
    }

    /**
     * This is the entry of our Firewall Panel.
     */
    public function panel()
    {
        $panel = new \Shieldon\Firewall\Panel();
        $panel->entry();
    }
}

最后，无论您选择哪种方式，进入 https://yoursite.com/firewall/panel/，登录页面应该会显示在您的屏幕上。

默认用户名和密码是 shieldon_user 和 shieldon_pass。登录控制面板后，您需要做的第一件事是更改登录名和密码。

贡献

感谢您对我们项目的兴趣！我们欢迎来自每个人的贡献。在开始之前，请花点时间审阅以下指南。

指南

• 从 master 分支创建一个分支。
• 确保您的代码遵循我们的编码风格和约定。
• 保持代码简洁、文档齐全和模块化。
• 编写清晰的提交信息，描述您的更改目的。
• 彻底测试您的更改，以确保它们不会引入任何新问题。
• 确保您的代码在没有任何错误或警告的情况下成功构建。
• 更新相关文档，包括必要的 README 文件。
• 向原始存储库的 master 分支提交一个拉取请求 (PR)。

代码测试

我们使用一个包含各种依赖项的 Docker 镜像来进行代码测试。该镜像基于 /tests/Fixture/docker/Dockerfile。

按照以下步骤运行测试

• 确保您的机器上安装了 Docker。如果没有，您可以从官方 Docker 网站下载并安装它。
• 导航到项目目录，并运行以下命令来构建 Docker 镜像

  composer test:docker:build
  

• 一旦构建了 Docker 镜像，您可以通过执行以下命令来运行测试

  composer test:docker:run
  

• 观察测试结果，并注意任何失败或错误。输出将在终端中显示。

覆盖率报告将在 /tests/report 目录中生成。您可以通过在浏览器中打开 index.html 文件来查看报告。

作者

Shieldon 库是由来自台湾的 Terry L. 提供的。

许可

Shieldon 防火墙是一个开源软件，根据 MIT 许可证授权。