Getting Started

This comprehensive guide provides a detailed overview of getting started with Shieldon Firewall for your web application. Let's break it down.

Server Requirements

Before using Shieldon Firewall, ensure that your server meets the following requirements:

• PHP >= 7.1.0
• Ctype PHP Extension
• JSON PHP Extension
• GD PHP Extension (Required for generating Captcha verification code images.)
• PDO PHP Extension (Required only if you would like to use MySQL, SQLite driver.)
• Redis PHP Extension (Required only if you would like to use Redis driver.)

Installation

Shieldon can be installed via PHP Composer:

composer require shieldon/shieldon

Implementing

There are three primary ways to implement Shieldon in your application:

• Implement Shieldon as a PSR-15 middleware.
• Implement Shieldon in the bootstrap stage of your application.
• Implement Shieldon in a parent controller that other controllers extend.

Each implementation method is accompanied by practical examples using popular frameworks like Slim 4, Laravel 6, and CodeIgniter 3.

---

PSR-15 Middleware

Example: Slim 4 framework

Shieldon can be used as a PSR-15 middleware, as shown in the example using Slim 4 framework.

(1) Create a firewall middleware.

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');
        $response = $firewall->run();

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

        return $response;
    }
}

(2) Add the firewall middleware in your application.

For example, if you are using Slim 4 framework, the code should look like this.

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

(3) Create a route for control panel.

For example, if you are using Slim 4 framework, the code should look like this. Then you can access the URL https://yourwebsite.com/firewall/panel to login to control 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();

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

Note:

• The HTTP method POST and GET both should be applied to your website.
• POST method is needed for solving CAPTCHA by users who were temporarily blocked.

---

Bootstrap Stage

Example: Laravel 6 framework

You can initialize Shieldon in the bootstrap stage of your application, shown in the example using Laravel 6 framework.

(1) Before Initializing the $app

In your bootstrap/app.php, after <?php, add the following code.

/*
|--------------------------------------------------------------------------
| 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);
    $response = $firewall->run();

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

(2) Define a route for firewall panel.

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

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

    // The entry point must be the same as the route defined.
    $panel->entry('/firewall/panel/');

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

---

Parent Controller

Example: CodeIgniter 3 framework

Shieldon can also be implemented in a parent controller that is extended by other controllers, demonstrated in the example using the CodeIgniter 3 framework.

1. Create a parent controller.

Create a new file MY_Controller.php in the application/core/ directory. This will be your parent controller.

Here is the basic structure for MY_Controller:

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

2. Initialize Firewall instance

Next, initialize Shieldon Firewall in the constructor of MY_Controller. This will ensure that Shieldon Firewall is initialized for every controller that extends MY_Controller.

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);
        $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. Define a Controller for Controll Panel.

Next, you need to define a controller for the Shieldon Firewall control panel. In this example, you'll create a controller named Firewall.

Create a new file Firewall.php in the application/controllers/ directory and add the following code:

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('/firewall/panel/');
    }
}

Now, Shieldon Firewall is initialized in your MY_Controller, and every controller that extends MY_Controller and runs the firewall method will have access to it. Furthermore, you've defined a Firewall controller with a panel method, which is your entry point to the Shieldon Firewall control panel.

Login

Finally, regardless of the chosen implementation method, accessing https://yoursite.com/firewall/panel/ should display the login page.

The default username and password are shieldon_user and shieldon_pass, respectively. For security reasons, changing the login credentials after the first login is highly recommended.