Instalasi

Persyaratan: PHP ^8.2, Composer, Laravel 11/12/13 (diuji pada Laravel 12 & 13).

1. Pasang package

composer require ganadev/laravel-shield ganadev/shield-core

laravel-shield otomatis menarik ganadev/shield-core. Provider terdaftar otomatis (auto-discovery).

2. Publish aset

php artisan vendor:publish --provider="Ganadev\Shield\Laravel\ShieldServiceProvider" --tag=shield-config
php artisan vendor:publish --provider="Ganadev\Shield\Laravel\ShieldServiceProvider" --tag=shield-migrations
php artisan vendor:publish --provider="Ganadev\Shield\Laravel\ShieldServiceProvider" --tag=shield-views   # opsional
php artisan migrate

• shield-config → config/shield.php
• shield-migrations → tabel security_ip_bans & security_events
• shield-views → halaman branded resources/views/vendor/shield/{blocked,challenge}.blade.php

3. Daftarkan middleware

Pasang sebagai middleware global (bukan group web) supaya request ke path tanpa route (mis. /.env) ikut diperiksa. Letakkan setelah resolusi trusted proxy:

bootstrap/app.php

->withMiddleware(function (Middleware $middleware): void {
    $middleware->append([
        \Ganadev\Shield\Laravel\Middleware\SecurityFirewallMiddleware::class,
    ]);
})

4. Atur environment

SHIELD_MODE=observe        # mulai aman: catat dulu tanpa memblokir
SHIELD_APP_ID=my-app
SHIELD_CHALLENGE=turnstile # turnstile | recaptcha | null

5. Trusted proxy & IP (penting di produksi)

Semua ban, challenge, dan penghitung berbasis IP klien. Jika di belakang load balancer / reverse proxy, atur trusted proxies agar $request->ip() mengembalikan IP asli. Tanpa itu, semua pengguna terlihat satu IP → ban/challenge massal.

->withMiddleware(function (Middleware $middleware) {
    $middleware->trustProxies(
        at: '192.168.0.1,192.168.0.2',
        headers: Request::HEADER_X_FORWARDED_FOR,
    );
})

php artisan shield:health memberi peringatan jika header forwarded terdeteksi tanpa trusted proxies.

6. Jalankan

php artisan serve

Gunakan php artisan shield:report untuk ringkasan event dan shield:health untuk cek komponen.

Rollout bertahap (disarankan)

1. Mode observe 24–72 jam → pantau shield:report.
2. Aktifkan enforce untuk aturan critical dulu.
3. Aktifkan behavior challenge dengan threshold hati-hati.
4. Aktifkan eskalasi ban setelah observasi.
5. Pantau manual release & challenge pass rate sebagai tanda false-positive.