Integrating a Web Application Firewall with PHP: A Guide Using Slim 3 Framework and Shieldon

In this article, we'll walk you through how to integrate a Web Application Firewall (WAF) with a PHP-based web application using the Slim 3 framework. By the end, you will understand how to set up a self-hosted WAF to improve your application's resilience to attacks and manage common security threats.

1. Introduction

A Web Application Firewall is a crucial line of defense for modern web applications. In this tutorial, we will build a secure PHP application from scratch using Slim 3 and integrate the Shieldon WAF to protect it.

What you will learn:

• Setting up a basic Slim 3 PHP application.
• Integrating and wiring the Shieldon WAF middleware.
• Accessing and configuring the Shieldon Control Panel.
• Configuring active protections (Daemon, CAPTCHA, Rate Limiting, XSS, and IP Management).
• Production hardening and handling false positives.

Prerequisites:

• PHP installed (refer to PHP's official guide).
• Composer installed (refer to Composer's official guide).
• A database server like MySQL.
• Basic understanding of PHP and terminal commands.

2. WAF Basics

Web Application Frewall(WAF) is a protocol that operates at the application layer level of the Open Sytsem Interconnection (OSI) model. It acts as a security block between Hyper-Text Transfer Protocol (HTTP) requests and the internet.It protects web applications from various internet attacks like SQL injection,cookie poisoning, Cross-Site scripting (XSS) and Cross-Site Forgery. WAF is a reverse proxy protocol, which means it acts as a shield for the server where it protects it from getting exposed not until the request passes through WAF before reaching the server.This is different from a proxy server which shields the client's identity through an intermediary.

WAF works through policies which aim to protect against vulnerabilities by monitoring the traffic and filtering malicious requests. This works based on two models:

1. Allow List - It allows or admits requests that have been approved by the set policies in WAF.For example, if a device with IP address 192.168.0.25 is whitelisted, all requests coming from this device will be accepted.
2. Block List - It denies server access to requests that do not meet the set policies in WAF.For example, if a device with IP address 192.168.0.30 is blacklisted, all requests coming from this device will be rejected.

Types of WAF

1. Host-based WAF - integrated into the software of an application.It is cheap and easy to customize. It however consumes alot of system's resources,complex to implement and high maintenance costs.
2. Network- based - Usually embedded on the system hardware.It is mainly installed to minimize latency.It however is very expensive to install, require physical space for storage and maintainence of the equipments.
3. Cloud based - the simplest to implement and maintain.They are also very easy to implement at no extra cost. They however rely on a third party provider hence some of the features may be black boxed by the provider.This calls for the need to ensure that the provider has sufficicient customization features that meet your needs.

3. Scaffolding the Slim Application

This section, we'll discuss the steps involved in installation of Shieldon, a PHP based web application firewall used to detect and block suspicious activity,often using Captcha for verification.

We will use Slim as our PHP library.

Requirements

1. PHP installed - Please refer here for installation guides.
2. Composer - refer here for installation guide.
3. A database application like MySQL.

Installation

Project set up

Install a slim application with the below commands on your terminal:

mkdir WAF-Project

This creates a folder for our project.

cd WAF-Project

The above command navigates to the project root folder.
WAF-Project in this case is our project name.

composer init

The command prompts you to choose your configuration for the project.Just press enter for default settings until all the prompts are done. It initializes composer on the root project and creates a composer.json file.

composer require slim/slim

The command installs slim on the project folder and lists it on composer.json.

Next,open the project on your editor.
Create a public folder at the root folder and inside it, create an index.php file.Paste the following code:

<?php
require __DIR__ . '/../vendor/autoload.php';

$app = new \Slim\App();

$app->get('/', function ($request, $response, $args) {
    return $response->write("Hello, Slim 3!");
});

$app->run();

Next, run the below command on your terminal:

php -S localhost:8080 -t public

Vist http://localhost:8080/. You should see Hello, Slim 3! which means our project set up is complete.

4. Installing and Wiring Middleware

Install Shieldon

On your terminal,run the below command:

composer require shieldon/shieldon "^2" 

This installs shieldon version 2.

composer install slim/csrf "^0.8"

Create a writeable folder inside the cache folder.

mkdir -p cache/shieldon_firewall
chmod 0777 cache/shieldon_firewall

This is where all sheildon files will be executed from.

On a new terminal tab,open MYSQL:

mysql -u root -p

Enter your password,then create an empty database:

create database shieldon_db;

This is the database that shieldon will use to store all configurations related to user behaviour,sessions and settings.We'll use it later in this tutorial.

Wiring Up Application Middleware

Create a new file middleware.php inside the src folder.Copy and paste the following code:

<?php

use Slim\App;
use Slim\Csrf\Guard;

return function (App $app) {
    // Shieldon Firewall middleware
    $app->add(new \Shieldon\Firewall\Integration\Slim3());

    // CSRF middleware
    $container = $app->getContainer();

    $guard = new Guard();
     // Makes tokens persistent across requests
    $guard->setPersistentTokenMode(true);

    // Configure failure handler
    $guard->setFailureCallable(function ($request, $response, $next) {
        $request = $request->withAttribute("csrf_status", false);
        return $next($request, $response);
    });

    $app->add($guard);

    // Add CSRF to container
    $container['csrf'] = function () use ($guard) {
        return $guard;
    };
};

Explanation

use Slim\App; - brings the Slim application class into scope for type hinting.

use Slim\Csrf\Guard; - brings Slim-Csrf class in to scope. It prevents the application's forms and routes from Cross Site Request Forgery (CSRF) attacks.

$app->add(new \Shieldon\Firewall\Integration\Slim3()); - it sits at the top most level,before the application logic. Any request to any routes passes through this to inspect them against attacks like XSS SQLi and bots.

$container - stores Slim’s dependency container, which can hold services like csrf, db and logger.

     // Configure failure handler
    $guard->setFailureCallable(function ($request, $response, $next) {
        $request = $request->withAttribute("csrf_status", false);
        return $next($request, $response);
    });

This defines what would happen if the token validation fails.
$request->withAttribute("csrf_status", false) - adds a rquest attribute csrf_status set to false.

return $next($request, $response);- continues the middleware chain rather than terminating it entirely.

$app->add($guard); - it registers Csrf Guard as a middleware for all requests.

Note:

The order of the middleware is important in that:

1. Shieldon conducts a security filtering first.
2. Csrf Guard runs second to protect against Csrf attacks.

Updating public/index.php

public/index.php

In the public/index.php,copy and paste the below code:

<?php
// Error reporting configuration
error_reporting(E_ALL & ~E_DEPRECATED);
ini_set('display_errors', 1);

// Start the session
session_start();

// Ensure clean output buffer
if (ob_get_level()) ob_end_clean();

require __DIR__ . '/../vendor/autoload.php';

use Psr\Http\Message\ServerRequestInterface as Request;
use Psr\Http\Message\ResponseInterface as Response;

// Create container
$container = new \Slim\Container([
    'settings' => [
        'displayErrorDetails' => true,
        'outputBuffering' => false
    ]
]);

$app = new \Slim\App($container);

// Load middleware (Shieldon + CSRF)
(require __DIR__ . '/../src/middleware.php')($app);


// Home route

$app->get('/', function (Request $request, Response $response, $args) {
    return $response->getBody()->write("Hello, Slim 3!");
});


//Shieldon Firewall Control Panel

$app->map(['GET', 'POST'], '/firewall/panel[/{params:.*}]', function (Request $request, Response $response, array $args) use ($app) {

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

    $firewall->configure(__DIR__ . '/../cache/shieldon_firewall');
    $firewall->controlPanel('/firewall/panel/');

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

    // CSRF from middleware
    $csrf = $app->getContainer()->get('csrf');
    $nameKey = $csrf->getTokenNameKey();
    $valueKey = $csrf->getTokenValueKey();

    $csrfName  = $request->getAttribute($nameKey);
    $csrfValue = $request->getAttribute($valueKey);

    $panel->csrf(
        [$nameKey => $csrfName],
        [$valueKey => $csrfValue]
    );

    $panel->entry();

    return $response;
});
$app->run();

Explanation

error_reporting(E_ALL & ~E_DEPRECATED); - tells the application to show all warnings related to deprecation.

ini_set('display_errors', 1); - this shows errors related to php directly on the browser.

session_start(); - this initializes PHP sessions.They are very essential to Shiledon Firewall and Csrf Guard for login persistence,CAPTCHA and storing session data.

ob_end_clean(); - clears output buffering if there was any running process that was using it.

require __DIR__ . '/../vendor/autoload.php'; - loads all classes from Slim and Shieldon automatically for my custom middleware.

use Psr\Http\Message\ServerRequestInterface as Request;
use Psr\Http\Message\ResponseInterface as Response;

The above defines shorter aliases for PSR's message interfaces for ServerRequestInterface and ResponseInterface. Slim passes the objects that implement these interfaces to every route callback.

$container = new \Slim\Container([
    'settings' => [
        'displayErrorDetails' => true,
        'outputBuffering' => false
    ]
]);

This sets up the Slim container.'displayErrorDetails' => true tells slim to show all error traces,which is very useful especially during development.

'outputBuffering' => falsesets the content buffering to false so it does not capture echoed content automatically.

$app = new \Slim\App($container); - instantiates Slim application created with the custom configurations above.

(require __DIR__ . '/../src/middleware.php')($app); - calls the middleware in the src directory and executes it immediately by passing $app as an arguement.Calling this line activates firewall and CSRF protection globally.Remember Slim 3 had been set on the middleware which inspects all requests and filtering out malicious ones before they reach the routes. CSRF Guard was also configured in the middleware to add anti-CSRF protection tokens to all POST requests.

$app->get('/', function (Request $request, Response $response, $args) {
    return $response->getBody()->write("Hello, Slim 3!");
});

This defines a simple home route that writes Hello, Slim 3! on the browser.

$app->map(['GET', 'POST'], '/firewall/panel[/{params:.*}]', function (Request $request, Response $response, array $args) use ($app) {})

Defines /firewall/panel.which allows GET and POST methods. It uses Slim's parameter pattern [/params:.*] to handle extra other path segments.This is mostly useful because Shieldon uses routes like /firewall/panel/security/authentication and /firewall/panel/settings/basic/.

$firewall = new \Shieldon\Firewall\Firewall($request); - creates a firewall instance bound to the current PSR-7 request.The firewall intercepts requests applying routes like IP restrictions,rate limiting and CAPTCHA challenges.

$firewall->configure(__DIR__ . '/../cache/shieldon_firewall'); - sets the storage location for Shieldon's data.The directory must be writeable by PHP.

$firewall->controlPanel('/firewall/panel/'); - tells where the admin panel is accessible from on the application.

$panel = new \Shieldon\Firewall\Panel(); -initializes the UI component that renders the control panel interface(HTML templates and CAPTCHA widgets).

$csrf = $app->getContainer()->get('csrf');
$nameKey = $csrf->getTokenNameKey();
$valueKey = $csrf->getTokenValueKey();

$csrfName  = $request->getAttribute($nameKey);
$csrfValue = $request->getAttribute($valueKey);

$panel->csrf(
    [$nameKey => $csrfName],
    [$valueKey => $csrfValue]
);

On the middleware,CSRF generated session keys and values and stored them for persistence in the session. Now,they are extracted and passed into Shieldon panel using $panel -> csrf() so Shieldon will include valid Slim generated CSRF tokens on HTML forms.

$panel->entry(); renders shieldon's control panel.It is what handles internally-based routing like /overview and /login.

$app -> run()- Slim takes over the entire HTTP lifecycle.It accepts the incoming request,passes it through all registered middleware,match it to the correct route, execute the callback and send back the final response to the client.

5. Accessing te Shieldon Control Panel

Run php -S localhost:8080 -t public. Open a new browser tab and access http://localhost:8080/firewall/panel . On the login page,use shieldon_user as username and shieldon_pass as the default password.

Click login.

You should be able to access shieldon dashboard as illustrated in the snapshot below:

6. Configuring Protections

Starting daemon

Daemon is a background process that runs in shieldon to monitor application activity.It is the core process that monitors user behaviour on the web application and when to trigger such events such as IP restrictions and CAPTCHA challenges.

To start daemon:

1. On Shieldon dashboard, click firewall on the side bar.

2. Click settings and select daemon on the right tab.
   

3. On the power switch,toggle on.

4. On the data driver section,select MYSQL.

5. Fill in the required details: host: 127.0.0.1,database:shieldon_db,user:root and password: {yourdbpassword}.
   

6. Scroll down and click save.

7. Reload your application.

8. Login in again.

Setting up CAPTCHA

To set up CAPTCHA, make sure that you have php-gd installed on your system.
You can check by running the below command:

php -i | grep gd

You should see gd as the return. If nothing is returned,run the below command:

#Debian distros
sudo apt-get install php-gd

#Arch distros
sudo pacman -S php-gd

1. For other Unix distros,please refer here
2. Mac: Please refer here and choose a method that suits you best.
3. Windows guide

Steps

1. On shieldon dashboard, click firewall and navigate to settings, then CAPTCHA tab on the right tabs.
2. Select the type of CAPTCHA,whether reCaptcha or Image.In this case,select Image.
3. Toggle the enable switch on the right of the Image type.
4. Select the type of character combination to use for the Image.
5. Enter the number of characters for every CAPTCHA image.

Upon the next login,a Login page that includes a CAPTCHA challenge is rendered as shown in the snapshot below:

Rate limiting

Rate limiting is a security mechanism that puts cap on a user action on a web application within a given period of time.These actions may be trying to login to the application or refreshing. It is a control measure that can be put on web applications to limit how many requests a single user can make in a single endpoint within a given timeframe.This can be used to protect the application against Denial-of-Service attacks which are often used to overwhelm a server with a lot of requests, rendering it unavailable to other users.

Attacks that can be stopped by rate limiting.

1. Brute Force attacks These are attacks that mainly use trial and error actions to decode user credentials.They are often carried out by bots that target login pages.
2. Denial of service - It is a cyber attack where an attacker renders a service unavailable to normal user by interupting the normal device's functionality. For example, an attacker may overwhelm a server with requests unti normal traffic in unable to be processed.
3. Data scraping - this is a technique where a computer program extracts data from output data generated by another program.

Why rate limiting is important

1. It is essential to implement rate limiting mechanism to ensure that applications are protected against attacks such as brute forcing and denial of services.
2. Rate limiting manages resource utilization by ensuring that a server is not overloaded by many requests which poses a huge limitation in terms of performance and availability.
3. Rate limiting reduces delays and improves the responsiveness of a server, which is very important for real-time applications.This improves user experience.
4. Rate limiting reduces abusive use of a server.Users are restricted from making excessive and unnecessary requests which can greatly impact server resources and its performance.

To implement rate limiting on shieldon, create a new file called /src/rateLimitingMiddleware.php and paste the below code:

<?php
class RateLimitMiddleware
{
    private int $maxAttempts;
    private int $timeDecay;


    public function __construct(int $maxAttempts = 3, int $timeDecay = 60)
    {
        $this->maxAttempts = $maxAttempts;
        $this->timeDecay = $timeDecay;
    }


    public function __invoke($request, $response, $next)
    {
        $ip = $_SERVER['REMOTE_ADDR'] ?? 'unknown';
        $key = 'rate_limit_' . $ip;
        $now = time();

        if (!isset($_SESSION[$key])) {
            $_SESSION[$key] = [
                'count' => 0,
                'reset' => $now + $this->timeDecay,
            ];
        }
        $record = &$_SESSION[$key];

        if ($now > $record['reset']) {
            $record['count'] = 0;
            $record['reset'] = $now + $this->timeDecay;
        }
        $record['count']++;
        if ($record['count'] > $this->maxAttempts) {
            $retryAfter = $record['reset'] - $now;

            $body = sprintf('Too many requests.Please try again after %d seconds.', $retryAfter);

            return $response
                ->withStatus(429)
                ->withHeader('Retry-After', $retryAfter)
                ->write($body);
        }
        return $next($request, $response);
    }
}

Then in /src/middleware.php, add this line below the shieldon middleware:

    $app->add(new RateLimitMiddleware(5, 60));

On the dashboard,log out and try refreshing the page continuously six times.You will reach limit and the page will return status 429 with the message Too many requests.Try again after x seconds.

Explanation

class RateLimitMiddleware
{....}

This initializes a reusable middleware class for Slim.It will intercept and modify any request and request before they reach the route controllers.

private int $maxAttempts;
private int $timeDecay;

maxAttempt defines the maximum number of requests a user can make within a window.

timeDecay defines the wait time in the window.

public function __construct(int $maxAttempts = 3, int $timeDecay = 60)
{
    $this->maxAttempts = $maxAttempts;
    $this->timeDecay = $timeDecay;
}

This is a constructor definition that tells what will be passed as arguements in the middleware.The arguements defined are maxAttempts and timeDecay.

public function __invoke($request, $response, $next)

Slim middlewares must implement __invoke() so that they can behave as callable functions.

When a request comes,Slim will execute:

$response = $middleware($request,$response,$next)

$request - PSR-7 request object.

$response - PSR-7 response object.

$next - the next callable middleware if allowed.

$ip = $_SERVER['REMOTE_ADDR'] ?? 'unknown';
$key = 'rate_limit_' . $ip;
$now = time();

This gets the user's IP address,then creates a unique session key for their session.It also captures the current Unix timestamp.

if (!isset($_SESSION[$key])) {
    $_SESSION[$key] = [
        'count' => 0,
        'reset' => $now + $this->timeDecay,
    ];
}
$record = &$_SESSION[$key];

If this is a new user,a new session entry is created.
$count stores the number of requests made so far.$reset stores the timestamp when the rate limit resets.$record is a reference (&) so the session array can be manipulated directly.

if ($now > $record['reset']) {
    $record['count'] = 0;
    $record['reset'] = $now + $this->timeDecay;
}

If the current time exceeds the set reset time,rate limit is set to expired. A new reset counter and a new window are created.

$record['count']++;

This increments the user's request count within the current time window.

if ($record['count'] > $this->maxAttempts) {
    $retryAfter = $record['reset'] - $now;

    $body = sprintf('Too many requests. Please try again after %d seconds.', $retryAfter);

    return $response
        ->withStatus(429)
        ->withHeader('Retry-After', $retryAfter)
        ->write($body);
}

If the count exceeds the limit,the time how long until the window resets is calculated,then create a message to show to the user that they have exceeded the set request limit,then return status code 429.

Cross Site Scripting Protection (XSS)

This is a security measure that aims at protecting attackers from injecting malicious script on application urls.Attacker inject these scripts by storing them as variables which when on the webpage are executed.To counter that, it is necessary to escape and sanitize variable,a technique called perfect injection resistance.Shieldon provides developers with XSS protection which when enabled,restricts such scripts from being executed as the webpage is rendered.

To enable XSS protection:

1. Open shieldon control panel.
2. Click firewall on the sidebar.
3. Select XSS Protection.
4. Toggle the switch for every method you wish to enable XSS protection for on the left.
5. Restart your application.

What happens?

When you enable XSS protection, all method variables (GET,POST) and cookie variables are scanned.Common patterns used in XSS attacks are detected.These patterns may include <script>,<iframe>, event handlers like onload= and onclick=.If such patterns are detected,the request is blocked immediately and a status 403 for unauthorized is returned.In shieldon,you will be required to solve a Capture and be redirected to /.

Below is a sample snapshot of what is returned if we try to embed a script on the url.
In this tutorial,http://localhost:8000/?test=<script>alert('xss')</script> was used to test.

IP management

This is a security practice that aims to either allow or deny access to the website by their IP address.Shieldon allows application admins to block,allow or temporarily limit requests from specific IP addresses from the control panel.

Components of IP Manager

1. Whitelist (Allow)

Allows certain IP addresses to access the page regardless of the firewall rules.This avoids the scenarios of trusted users being blocked by automated rules like rate limiting and XSS detection,one way of handling false positives which do come with firewall rules.

2. Blacklist(Deny access)

It prevents malicious IP addresses from accessing the application.It aims to block known attackers ,suspicious bots or abusive users from making requests to the server. Blacklisting focuses resources on known threats which improves security management.

Implementation on Shieldon Control Panel

To enable IP management on shieldon;

1. Open the dashboard.
2. Click Firewall on the left menu bar and select IP management.
3. Enter hte path you wish to enable IP manager for on the right.
4. Enter the IP address to take action on.
5. On the dropdown,select the action to take,either blacklist,whitelist or remove IP.
6. Click submit.

7. Handling False Positives on Shieldon

Even though a very efficient Web Application Firewall,Shieldon misinterprets legitimate users for illegitimate users.It's built in filtering engines are designed to be strict but sometimes,real world traffic triggers them unintentionally.Shieldon allows the administrator to fine tune its features to minimize these problems.

Causes of false positives

1. When a legitimate request includes patterns that resemble those flagged as illegitimate payloads like SQL keywords in a form field.
2. A super user refreshes the page or posts data more frequently,triggering rate limits.
3. Automated scripts send frequent requests that resemble bots.

Below are the ways that can be implemented to handle Shieldon's False positives:

1. Whitelisting

If certain users or servers are trusted,their IP addresses can be added on the whitelist so they are never blocked.This ensures they bypass most restrictions.

2. CAPTCHA Verification

Instead of blocking suspicious user requests immediately,CAPTCHA challenges can be enabled and if solved correctly,Shieldon recognizes them as human and temporarily whitelists their session.

3. Using logs to investigate

Shieldon logs can be examined to identify whether a block was a real attack or a false alarm and take action.

8. Production Hardening and Best Practices

Before deploying your application to a live server, follow these best practices:

1. Update Credentials: Immediately change the default shieldon_user and shieldon_pass in the control panel.

2. Directory Permissions: Restrict cache/shieldon_firewall permissions in production (e.g., chmod 0755) to prevent unauthorized modifications.

3. Disable Error Details: Change 'displayErrorDetails' => true to false in your Slim application container to prevent stack trace leaks.

4. Enforce HTTPS: Secure your application with an SSL certificate to protect CSRF tokens and active session variables.

Conclusion

Web Application Firewall protects the application at the application layer level and is designed to analyze every HTTP/S request before they reach the server.It acts as an intermediary between the user and the application,managing all communication before the server is reached.Shieldon ensures that only allowed actions ,based on security policy can be performed.It is therefore crucial to have a WAF like Shieldon set up to ensure that applications have automated security procedures that monitor and protect the server from malicious activity.They also ensure that application owners have complete oversight and control over their application's security environment.