jlrodriguezdev / laravel-bot-protection

v1.1.1 2026-10-24 00:37 UTC

Requires

• php: ^8.1|^8.2|^8.3|^8.4|^8.5
• illuminate/cache: ^9.0|^10.0|^11.0|^12.0
• illuminate/http: ^9.0|^10.0|^11.0|^12.0
• illuminate/support: ^9.0|^10.0|^11.0|^12.0

MIT

• jlrodriguezdev

• security
• firewall
• laravel
• anti-bot
• crawlers
• waf
• bot-protection
• scrapers
• php2shell

Published on Packagist.org on 2026-10-24 00:37 UTC

README

High-Performance Web Application Firewall (WAF) & Anti-Bot Middleware for Laravel Applications
Battle-tested and running live in production at LATIRU.RU.

🌐 Choose Your Language / Выберите язык / Elige tu idioma

• 🇪🇸 Leer en Español (README.es.md) — Documentación completa en Español y caso de estudio real en producción.
• 🇬🇧 Read in English (README.md) — Full documentation in English, architecture, and production case study.
• 🇷🇺 Читать на русском (README.ru.md) — Полная документация на русском языке и разбор реальных логов атак.

🇬🇧 English - Laravel BotProtection

1. Overview & Real Production Case Study

BotProtection is a zero-dependency, battle-tested Laravel middleware designed to defend web platforms against hostile automated scrapers, exploit reconnaissance bots, and scanning toolkits.

🚀 Live Case Study from LATIRU.RU:
On October 22, 2026, our production platform LATIRU.RU came under heavy automated scanning and reconnaissance during the global wave of PHP2Shell (CVE-2026-109618 / CVE-2026-109619) attacks.
As audited in our Laravel Telescope and daily error traces, automated attacker bots bombarded the application with exploit probes:

• POST /php-cgi/php-cgi.exe... -> Blocked with 405 / 403
• POST /api/gql and POST /graphql/api -> Blocked with 405 / 403
• GET /.env, GET /.git/config, GET /.vscode/sftp.json -> Neutralized with 404

The Result: The strike system accumulated the violation counts and permanently blacklisted the offending IP addresses within 3 requests. Subsequent probes to public routes (/, /events, /calc) were instantly dropped with 403 Forbidden (errors.bot-detected), protecting our PHP workers and MySQL database from exhaustion.

2. Key Features

• Automated Scraper & Headless Tool Neutralization: Drops traffic from headless browsers, automation toolkits, and scripted probes (curl, wget, python-requests, scrapy, selenium, webdriver, phantomjs).
• Official Search Engine Whitelist: Zero false positives for legitimate search crawlers:
  • Google: googlebot, google-inspectiontool, google-extended.
  • Yandex: yandexbot, yandeximages, yandexvideo, yandexsitelinks, yandexmarket, yandexaccessibility.
  • Bing: bingbot, bingpreview, msnbot.
  • Social Previews: TelegramBot, WhatsApp, TwitterBot, Facebot.
• Strike-Based Permanent IP Blacklisting: Probes sending invalid HTTP methods (POST, PUT, DELETE) to sensitive root routes (/, /api, /admin) receive strikes in Cache. Upon reaching 3 violations, the IP is blacklisted automatically with an immediate 403 Forbidden.
• PHP2Shell Reconnaissance Shield: Before memory corruption or RCE chains can be staged against PHP runtimes, BotProtection drops the automated scanner at the application door.
• Contextual Rate Limiting: IP-based decay counter returning clean 429 Too Many Requests responses under aggressive bursts.

3. Installation

Require with Composer:

composer require jlrodriguezdev/laravel-bot-protection

Register in your application:

For Laravel 9 & 10 (app/Http/Kernel.php):

protected $middlewareGroups = [
    'web' => [
        // ...
        \Jlrodriguezdev\BotProtection\Middleware\BotProtection::class,
    ],
];

For Laravel 11 & 12 (bootstrap/app.php):

->withMiddleware(function (Middleware $middleware) {
    $middleware->web(append: [
        \Jlrodriguezdev\BotProtection\Middleware\BotProtection::class,
    ]);
})

Publish Configuration & Views:

php artisan vendor:publish --provider="Jlrodriguezdev\BotProtection\BotProtectionServiceProvider"

4. Configuration (config/bot-protection.php)

return [
    'enabled' => env('BOT_PROTECTION_ENABLED', true),
    'rate_limit' => env('BOT_PROTECTION_RATE_LIMIT', 60),
    'strike_threshold' => 3,
    'whitelist_ips' => [
        '127.0.0.1',
        '::1',
        // 'your.server.public.ip', // Whitelist server's own IP so internal CLI/cron calls are never blocked
    ],
    'blacklisted_ips' => [
        //
    ],
];

💡 Important Note on Whitelist Testing:
If you test the middleware by running curl directly from inside the server via SSH, the request originates from 127.0.0.1 or the server's public IP. Because those IPs are whitelisted to prevent local Cron jobs and artisan daemons from locking themselves out, the server will legitimately return 200 OK.
To test real bot blocking, run the curl probe from an external workstation or laptop:

# Run this from your laptop or external IP:
curl -s -i -A "curl/8.4.0" "https://yourdomain.com/"
# Response: HTTP 403 Forbidden ("errors.bot-detected")

Or test programmatically via Tinker:

php artisan tinker --execute="
\$req = \Illuminate\Http\Request::create('/', 'GET', [], [], [], ['HTTP_USER_AGENT' => 'curl/8.4.0', 'REMOTE_ADDR' => '1.2.3.4']);
\$res = app(\Jlrodriguezdev\BotProtection\Middleware\BotProtection::class)->handle(\$req, fn(\$r) => 'OK');
echo 'Status: ' . (is_string(\$res) ? \$res : \$res->getStatusCode()) . PHP_EOL;
"
# Output: Status: 403

5. Architecture & Decision Flow

flowchart TD
    A[Incoming Request] --> B{Bot Protection Active?}
    B -- No --> Z[Allow Request]
    B -- Yes --> C{SEO Whitelist: Google / Yandex / Social?}
    C -- Yes --> Z
    C -- No --> D{IP in Whitelist?}
    D -- Yes --> Z
    D -- No --> E{IP in Blacklist?}
    E -- Yes --> F[Abort 403: Bot Detected]
    E -- No --> G{Scanner Signature: Curl / Python / Headless?}
    G -- Yes --> F
    G -- No --> H{Invalid HTTP Method on Sensitive Route?}
    H -- Yes --> I[Increment Violation in Cache]
    I --> J{Violations >= 3?}
    J -- Yes --> K[Auto-Blacklist IP Permanently]
    K --> L[Abort 405 / 403]
    J -- No --> L
    H -- No --> M{Exceeds Rate Limit?}
    M -- Yes --> N[Abort 429: Too Many Requests]
    M -- No --> Z

Loading

📄 License

MIT License. Created by jlrodriguezdev.