HoneypotPlus: a Laravel csomagom a kártékony IP-k észlelésére és tiltására

Bevezetés és kontextus

Ha internetre exposed Laravel alkalmazásokat hostolsz, már tudod: a botok sosem állnak le. Amint egy oldal élőbe kerül, azonnal pásztázni kezdik érzékeny fájlok után: .env, wp-admin, .git, phpinfo.php. Még akkor is, ha az alkalmazásodnak semmi köze a WordPress-hez!

Egy tiszta módot kerestem ezeknek a felderítési kísérleteknek az észlelésére, a naplózására és az automatikus reagálásra: IP tiltása a Cloudflare-en, jelentése az AbuseIPDB-nek. A Laravel ökoszisztémában nem volt olyan, ami pontosan ezt csinálta volna. Így létrehoztam a HoneypotPlus-t.

Figyelem: A HoneypotPlus nem űrlap honeypot. Ha az űrlapjaidat akarod védeni a spam ellen, nézd meg a spatie/laravel-honeypot csomagot. A HoneypotPlus a hálózati felderítés észleléséről szól az érzékeny útvonalakon.

Mit csinál a csomag?

Az elv egyszerű: megadsz egy listát "csapda" útvonalakból. Bármely IP, amely megpróbál hozzáférni ezekhez, azonnal kártékonynak minősül.

Konkrétan a HoneypotPlus:

• Érzékeli az érzékeny útvonalakhoz (.env, wp-admin, .git stb.) való hozzáférést egy middleware-en keresztül
• Adatbázisba rögzíti a támadást (IP, útvonal, user-agent, HTTP metódus, időbélyeg)
• Automatikusan kitiltja az IP-t a Cloudflare Firewall API-n keresztül (ha a hitelesítő adatok jelen vannak)
• Jelenti az IP-t az AbuseIPDB-nek (ha az API kulcs jelen van)
• Automatikusan megtisztítja a lejárt tiltásokat a Laravel scheduler segítségével
• Interaktív CLI felületet biztosít a blokkolt IP-k kezeléséhez

A Cloudflare és AbuseIPDB integrációk opcionálisak és automatikusan aktiválódnak, amint a megfelelő környezeti változók jelen vannak. Nulla extra konfiguráció.

Telepítés

Telepítés Composerrel:

composer require ilogus/laravel-honeypotplus

Ezután futtasd a telepítő parancsot, amely publikálja a konfigot és a migrációt:

php artisan honeypot-plus:install

Add hozzá a middleware-t a bootstrap/app.php fájlban:

use HoneypotPlus\Middleware\HoneypotPlusMiddleware;

return Application::configure(basePath: dirname(__DIR__))
    ->withMiddleware(function (Middleware $middleware) {
        $middleware->append(HoneypotPlusMiddleware::class);
    })
    ->create();

Használd az append() metódust, ne a prepend()-et. A middleware-nek a Laravel routing előtt kell futnia, különben a Laravel egy szabványos 404-et ad vissza, és a kártékony IP sosem lesz észlelve.

Ezután állítsd be a környezeti változókat a .env fájlban:

HONEYPOT_PLUS_ENABLE=true
HONEYPOT_PLUS_LOGGING=true
HONEYPOT_PLUS_BAN_DURATION_HOURS=24

# Cloudflare (opcionális)
HONEYPOT_PLUS_CLOUDFLARE_API_TOKEN=your_token
HONEYPOT_PLUS_CLOUDFLARE_ZONE_ID=your_zone_id

# AbuseIPDB (opcionális)
HONEYPOT_PLUS_ABUSEIPDB_KEY=your_key

Honeypot szabályok testreszabása

A config/honeypot-plus.php fájlban megadhatod saját csapda útvonalaidat. A csomag támogatja mind a statikus útvonalakat, mind a regex mintákat:

'honeypots' => [
    '/.env',
    '/wp-admin',
    '/.git',
    // Regex minták (regex: előtaggal)
    'regex:/^\.env\./i',
    'regex:/wp-config\.php$/i',
],

Eseményvezérelt architektúra

Ez az a rész, ami a legjobban érdekel ebben a csomagban: az architektúra teljes egészében a Laravel eseményrendszerén alapul.

Amikor egy IP aktivál egy csapdát, a middleware egy HoneypotAttackDetected eseményt küld:

final class HoneypotAttackDetected
{
    use Dispatchable, SerializesModels;

    public function __construct(
        public string $ip,
        public string $honeypotRule,
        public ?string $userAgent,
        public string $httpMethod,
        public string $pathRequested,
    ) {}
}

A belső HandleHoneypotAttack listener kezeli: rögzíti a támadást, meghívja a Cloudflare-t, és jelenti az AbuseIPDB-nek.

De az igazi előny az, hogy írhattok saját listenereket. Ha továbbítani akarjátok ezeket az eseményeket az Elasticsearch, Kibana, Slack csatorna, webhook vagy bármilyen más eszköz felé, csak fel kell iratkozni a HoneypotAttackDetected eseményre az EventServiceProvider-ben:

use HoneypotPlus\Events\HoneypotAttackDetected;
use App\Listeners\ForwardAttackToElasticsearch;

protected $listen = [
    HoneypotAttackDetected::class => [
        ForwardAttackToElasticsearch::class,
    ],
];

A listenered megkapja az összes szükséges információt: az IP-t, a kiváltott szabályt, a user-agent-et, a HTTP metódust és a kért útvonalat. Ezután azt csinálsz vele, amit akarsz.

class ForwardAttackToElasticsearch implements ShouldQueue
{
    public function handle(HoneypotAttackDetected $event): void
    {
        // Küldés az Elasticsearch, Kibana, Slack stb. felé
        ElasticsearchClient::index([
            'index' => 'honeypot-attacks',
            'body'  => [
                'ip'           => $event->ip,
                'rule'         => $event->honeypotRule,
                'path'         => $event->pathRequested,
                'user_agent'   => $event->userAgent,
                'method'       => $event->httpMethod,
                'detected_at'  => now()->toIso8601String(),
            ],
        ]);
    }
}

A ShouldQueue implementálásával a feldolgozás aszinkron módon történik. A HTTP válaszod nem blokkolódik.

Kezelés CLI-n

A csomag egy interaktív Artisan parancsot biztosít a blokkolt IP-k kezeléséhez:

php artisan honeypot-plus:manage

Elérhető műveletek:

• Blokkolt IP-k listázása
• IP manuális tiltása
• IP feloldása
• Statisztikák megtekintése

Használhatod a facade-et közvetlenül a kódban is:

use HoneypotPlus\Facades\HoneypotPlus;

HoneypotPlus::ban('192.168.1.1', 24);      // Tiltás 24 órára
HoneypotPlus::isBanned('192.168.1.1');     // Ellenőrzés, hogy tiltva van-e
HoneypotPlus::unban('192.168.1.1');        // Feloldás
$stats = HoneypotPlus::getStats();         // Statisztikák

Automatikus tisztítás

A Laravel scheduler automatikusan konfigurálva van. A lejárt tiltások rendszeresen megtisztításra kerülnek minden manuális beavatkozás nélkül. Ellenőrzéshez:

php artisan schedule:list

Konklúzió

Ez a csomag elsősorban egy gyakorlati eszköz, amelyet a saját projektjeimben használok. Az a döntés, hogy a Laravel eseményrendszerét választottam a monolitikus feldolgozás helyett, tudatos volt: ez teszi a csomagot bővíthetővé a forráskód megváltoztatása nélkül.

Ha exposed Laravel alkalmazásaid vannak, ez az a fajta dolog, amit egyszer telepítesz, és elfelejted, amíg egy nap meg nem nézed a statisztikákat, és rá nem jössz, mennyi bot fut folyamatosan.

A forráskód elérhető a GitHubon. A hozzájárulások és a visszajelzések üdvözöltek.