README

Wafy is a robust Laravel package developed by Bdsa designed to automatically ban IP addresses and detect malicious requests, including SQL Injection, XSS, and more.

Features

• 🛡️ IP Banning: Automatically block IPs engaging in suspicious activity.
• 🕵️ Malicious Request Detection: Detects SQLi, XSS, LFI, and RCE attempts.
• ⏱️ Temporary & Permanent Bans: Configurable ban durations.
• ⚙️ Customizable Patterns: Define your own regex patterns for detection.
• 🖥️ Artisan Commands: Easily manage banned IPs via CLI.

Installation

1. Require with Composer

Add the package to your project:

composer require bdsa/wafy

2. Publish Configuration

Publish the configuration file and migrations:

php artisan vendor:publish --provider="Bdsa\Wafy\WafyServiceProvider"

3. Run Migrations

Create the banned_ips table:

php artisan migrate

Usage

Middleware

Wafy provides two key middlewares : BlockBannedIp & DetectMaliciousRequests.

Protecting Routes

Apply the middleware to your routes or groups:

use Bdsa\Wafy\Middleware\BlockBannedIp;
use Bdsa\Wafy\Middleware\DetectMaliciousRequests;

Route::group(['middleware' => ['block.banned.ip', 'detect.malicious.requests']], function () {
    Route::get('/', function () {
        return view('welcome');
    });
    
    // Your protected routes
});

Artisan Commands

Manage banned IPs directly from the terminal:

• Ban an IP manually:

  php artisan wafy:ban {ip_address} [--reason="Your reason"]

• Unban an IP:

  php artisan wafy:unban {ip_address}

• List all banned IPs:

  php artisan wafy:list

• Enable/Disable WAF:

  php artisan wafy:mode {enable|disable}

• Set Action Mode (Block or Log-Only):

  php artisan wafy:action {block|log}

ℹ️ Note — wafy:mode and wafy:action are temporary runtime overrides. These two commands store their state in the cache, so they are meant for momentary situations (testing, incident response). Any cache flush (php artisan cache:clear, config:cache, a deploy, a Redis restart…) resets them, and Wafy falls back to the values in config/wafy.php. To change the behaviour permanently, edit config/wafy.php (or the matching WAFY_* environment variables) — that is the source of truth.

⚠️ Running behind a reverse proxy / CDN (read this first)

Wafy identifies clients by IP ($request->ip()) and can ban them. If your application runs behind a reverse proxy, load balancer or CDN (Nginx, Traefik, Cloudflare, AWS ALB…), you must configure Laravel's TrustProxies middleware so that $request->ip() returns the real client IP.

• If you don't configure trusted proxies, every request appears to come from the proxy. The first malicious request then bans your own proxy, cutting off all traffic.
• If you trust proxies with a blanket *, the X-Forwarded-For header becomes attacker-controlled: an attacker can spoof a clean IP to bypass bans, or forge a victim's IP to get it banned. Only trust the specific proxy ranges you use.

Also add your proxy / CDN ranges and any critical infrastructure to wafy.allowed_ips (CIDR ranges are supported) so they can never be banned.

Configuration

The configuration file is located at config/wafy.php. Besides the detection patterns, the following options control how bans are applied:

Default protection covers:

• SQL Injection (SQLi): UNION SELECT, common SQL verbs, hex encoding.
• Local File Inclusion (LFI): Directory traversal (../), system files (/etc/passwd).
• Cross-Site Scripting (XSS): Script tags, event handlers (onload, onerror).
• Remote Code Execution (RCE): Shell commands (cat, wget), PHP execution functions.

Example config/wafy.php:

return [
    'enabled' => env('WAFY_ENABLED', true),
    'patterns' => [
        '/(union(\s+all)?\s+select)/i',
        '/(select\s+.*\s+from|delete\s+from|update\s+.*\s+set)/i',
        '/(<script.*?>.*?<\/script>)/is',
        // Add your custom patterns here
    ],
    'allowed_ips' => [
        '127.0.0.1', // Localhost
        '192.168.1.1', // Office IP
    ],
    'notifications' => [
        'enabled' => env('WAFY_NOTIFICATIONS_ENABLED', false),
        'channels' => ['mail'], // Choose 'mail', 'slack' or both
        'email' => env('WAFY_NOTIFICATION_EMAIL', 'admin@example.com'),
        'slack_webhook' => env('WAFY_SLACK_WEBHOOK', ''),
    ],
];

Testing

To run the package tests:

vendor/bin/phpunit

License

This project is licensed under the MIT License.