Instalasi

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

1. Pasang package

composer require ganadev/laravel-shield:^1.2.2 ganadev/shield-core:^1.2.2

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

Jangan pakai ^1.2.1

Rilis 1.2.1 ditarik dari metadata Packagist dan tidak bisa diinstal. Rilis yang bisa diinstal adalah 1.2.2.

Catatan: sudah punya versi 1.0.x? Baca Upgrade ke v1.2.2 lebih dulu — ada dua perubahan default dan satu validasi baru yang bisa membuat aplikasi gagal boot.

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

Catatan: config/shield.php hasil publish mengunci seluruh default di dalamnya. mergeConfigFrom hanya mengisi kunci yang belum ada, jadi default baru di rilis berikutnya tidak masuk ke file ini. Saat upgrade, bandingkan file Anda dengan vendor/ganadev/laravel-shield/config/shield.php dan terapkan perubahannya manual.

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,
    ]);
})

Jangan pindahkan ke dalam group web

Posisi global itu wajib, bukan sekadar preferensi. Konsekuensinya:

• Request ke path tanpa route (mis. /.env) harus tetap diperiksa. Group web hanya berjalan setelah routing, sehingga firewall di dalam group tidak pernah melihat request tersebut.
• Group web menempatkan EncryptCookies di dalamnya. Bila Shield ikut masuk ke group itu, Laravel sudah men-decrypt cookie lebih dulu, sementara Shield membaca cookie terenkripsi itu sendiri untuk trusted-cookie flow. Akibatnya setiap pengguna yang sudah lolos challenge akan ditanya ulang terus-menerus.

Sejak 1.2.1 kondisi kedua tidak lagi gagal diam-diam: LaravelTrustedCookie mendeteksi nilai yang sudah ter-decrypt dan menulis satu peringatan ke log application:

Ganadev Shield: cookie trusted diterima dalam bentuk yang sudah ter-decrypt.

Kalau Anda melihat peringatan itu, kembalikan middleware ke posisi global.

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,
    );
})

Sejak 1.2.0, kondisi ini juga memberi warning otomatis saat boot lewat logger()->warning() tanpa perlu menjalankan perintah apa pun. Pesannya muncul kalau header forwarded terdeteksi tanpa trusted proxies, atau app.url menunjuk host publik sementara mode adalah challenge/enforce. Kalau alert monitoring Anda menangkap semua level log, tambahkan filter agar warning ini tidak berubah jadi noise.

php artisan shield:health tetap menyediakan pemeriksaan yang sama plus ringkasan komponen lain.

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.