Introdução

Este guia abrangente fornece uma visão detalhada de como começar com o Firewall Shieldon para sua aplicação web. Vamos detalhar.

Requisitos do servidor

Antes de usar o Firewall Shieldon, verifique se o seu servidor atende aos seguintes requisitos:

• PHP >= 7.1.0
• Extensão PHP Ctype
• Extensão PHP JSON

Extensão PHP - Extensão PHP GD *(Necessária para gerar imagens de códigos de verificação Captcha.)

• Extensão PHP PDO (Necessário apenas se você quiser usar o driver MySQL ou SQLite)
• Extensão PHP Redis (Necessário apenas se você quiser usar o driver Redis)

Instalação

O Shieldon pode ser instalado via Composer para PHP:

composer require shieldon/shieldon

Implementação

Existem três formas principais de implementar o Shieldon em sua aplicação:

• Implementar o Shieldon como um middleware PSR-15.
• Implementar o Shieldon na fase de inicialização da aplicação.
• Implementar o Shieldon em um controlador pai que é estendido por outros controladores.

Cada método de implementação é acompanhado de exemplos práticos usando frameworks populares como Slim 4, Laravel 6 e CodeIgniter 3.

---

Middleware PSR-15

Exemplo: Framework Slim 4

O Shieldon pode ser usado como um middleware PSR-15, conforme mostrado no exemplo usando o framework Slim 4.

(1) Crie um middleware de firewall.

class FirewallMiddleware
{
    /**
     * Classe invocável do middleware de exemplo
     *
     * @param ServerRequest  $request  Requisição PSR-7
     * @param RequestHandler $handler  Manipulador de requisição PSR-15
     *
     * @return Response
     */
    public function __invoke(Request $request, RequestHandler $handler): Response
    {
        $response = $handler->handle($request);

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

        // O diretório em que o Firewall Shieldon irá armazenar seus arquivos.
        $firewall->configure(__DIR__ . '/../cache/shieldon_firewall');
        $response = $firewall->run();

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

        return $response;
    }
}

(2) Adicione o middleware de firewall em sua aplicação.

Por exemplo, se você estiver usando o framework Slim 4, o código deve ser assim.

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

(3) Crie uma rota para o painel de controle.

Por exemplo, se você estiver usando o framework Slim 4, o código deve ser assim. Em seguida, você pode acessar a URL https://seusite.com/firewall/panel para fazer login no painel de controle.

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

    // O diretório em que o Firewall Shieldon irá armazenar seus arquivos.
    // Deve ser o mesmo do FirewallMiddleware.
    $firewall->configure(__DIR__ . '/../cache/shieldon_firewall');

    $panel = new \Shieldon\Firewall\Panel();

    // A URL base para o painel de controle.
    $panel->entry('/firewall/panel/');
});

Nota:

• O método HTTP POST e GET devem ser aplicados ao seu site.
• O método POST é necessário para resolver o CAPTCHA pelos usuários que foram temporariamente bloqueados.

---

Fase de inicialização

Exemplo: Framework Laravel 6

Você pode inicializar o Shieldon na fase de inicialização da sua aplicação, como mostrado no exemplo usando o framework Laravel 6.

(1) Antes de inicializar $app

No seu arquivo bootstrap/app.php, após <?php, adicione o seguinte código.

/*
|--------------------------------------------------------------------------
| Executar o Firewall Shieldon
|--------------------------------------------------------------------------
|
| O Firewall Shieldon irá monitorar todas as solicitações HTTP que chegam ao seu site.
| Executar o Firewall Shieldon antes de inicializar o Laravel evitará possíveis
| conflitos com as funções internas do Laravel.
*/
if (isset($_SERVER['REQUEST_URI'])) {

    // Este diretório deve ter permissão de escrita.
    // Colocamos em um diretório `storage/shieldon_firewall`.
    $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) Defina uma rota para o painel de controle do firewall.

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

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

    // O ponto de entrada deve ser o mesmo da rota definida.
    $panel->entry('/firewall/panel/');

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

---

Controlador pai

Exemplo: Framework CodeIgniter 3

O Shieldon também pode ser implementado em um controlador pai que é estendido por outros controladores, como demonstrado no exemplo usando o framework CodeIgniter 3.

1. Crie um controlador pai.

Crie um novo arquivo MY_Controller.php no diretório application/core/. Este será o seu controlador pai.

Aqui está a estrutura básica do MY_Controller:

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

2. Inicialize uma instância do Firewall

Em seguida, inicialize o Firewall Shieldon no construtor do MY_Controller. Isso garantirá que o Firewall Shieldon seja inicializado para todos os controladores que estendem o MY_Controller.

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

        // Autoloader do Composer
        require_once APPPATH . '../vendor/autoload.php';

        // Este diretório deve ter permissão de escrita.
        $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);
        }
    }

    /**
     * Proteção do Firewall Shieldon.
     */
    public function firewall()
    {
        $firewall = \Shieldon\Container::get('firewall');
        $firewall->run();
    }
}

3. Defina um controlador para o painel de controle.

Em seguida, você precisa definir um controlador para o painel de controle do Firewall Shieldon. Neste exemplo, você criará um controlador chamado Firewall.

Crie um novo arquivo Firewall.php no diretório application/controllers/ e adicione o seguinte código:

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

    /**
     * Este é o ponto de entrada para o nosso painel de controle do Firewall.
     */
    public function panel()
    {
        $panel = new \Shieldon\Firewall\Panel();
        $panel->entry('/firewall/panel/');
    }
}

Agora, o Firewall Shieldon é inicializado no seu MY_Controller, e todos os controladores que estendem o MY_Controller e executam o método firewall terão acesso a ele. Além disso, você definiu um controlador Firewall com um método panel, que é o ponto de entrada para o painel de controle do Firewall Shieldon.

Login

Por fim, independentemente do método de implementação escolhido, acessar https://yoursite.com/firewall/panel/ deve exibir a página de login.

O nome de usuário e a senha padrão são shieldon_user e shieldon_pass, respectivamente. Por motivos de segurança, é altamente recomendável alterar as credenciais de login após o primeiro acesso.