Instalasi

Panduan ini mengantar Anda dari aplikasi Laravel yang masih polos sampai Laravel Shield aktif dan mencatat kejadian, dalam sekitar 10 menit.

Versi yang didokumentasikan

Halaman ini untuk v1.2.x. Ubah versinya lewat pemilih versi di pojok kanan atas kalau aplikasi Anda memakai rilis lain.

Yang Anda butuhkan

• PHP ^8.2 atau lebih baru
• Composer
• Laravel 11, 12, atau 13
• Database yang sudah terhubung ke aplikasi Anda

Langkah 1 — Pasang paketnya

composer require ganadev/laravel-shield:^1.2.2

laravel-shield menarik ganadev/shield-core secara otomatis, jadi Anda tidak perlu memasang core sendiri. Provider-nya juga terdeteksi otomatis oleh Laravel package auto-discovery — tidak perlu didaftarkan manual di config/app.php.

Jangan memasang 1.2.1

Rilis 1.2.1 sempat diberi tag Git, lalu tag-nya dipindahkan. Packagist menolak tag yang dipindahkan dan menarik 1.2.1 dari metadata, sehingga composer tidak akan pernah memuatnya:

composer require ganadev/laravel-shield:^1.2.1
# → found ... but it does not match the constraint

Halaman HTML di Packagist masih menampilkan 1.2.1, jadi mudah tertukar. Yang benar dan bisa dipasang adalah 1.2.2.

Langkah 2 — Publish konfigurasi dan tabel

# File konfigurasi
php artisan vendor:publish --provider="Ganadev\Shield\Laravel\ShieldServiceProvider" --tag=shield-config

# Migrasi database
php artisan vendor:publish --provider="Ganadev\Shield\Laravel\ShieldServiceProvider" --tag=shield-migrations

# Tampilan halaman blokir & challenge (opsional)
php artisan vendor:publish --provider="Ganadev\Shield\Laravel\ShieldServiceProvider" --tag=shield-views

# Jalankan migrasi
php artisan migrate

Hasilnya:

Tag	Menulis ke	Isi
shield-config	config/shield.php	Semua opsi konfigurasi.
shield-migrations	database/migrations/	Tabel security_ip_bans dan security_events.
shield-views	resources/views/vendor/shield/	Halaman blocked dan challenge.

Perhatikan config/shield.php

mergeConfigFrom di Laravel hanya mengisi kunci yang belum ada di file config Anda. Begitu Anda publish, config/shield.php Anda berisi seluruh kunci beserta nilainya — dan kunci baru di rilis berikutnya tidak akan mengisi otomatis.

Artinya setiap kali Shield naik versi, Anda perlu membandingkan file Anda dengan vendor/ganadev/laravel-shield/config/shield.php dan menyalin sendiri perubahannya. Halaman Masalah Umum membahas gejalanya.

Langkah 3 — Daftarkan middleware

Middleware wajib dipasang sebagai middleware global, bukan di dalam group web.

Buka bootstrap/app.php:

use Illuminate\Foundation\Configuration\Middleware;

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

Kenapa harus global?

Kalau Shield ditaruh di dalam group web, ia tidak akan bekerja untuk beberapa kasus penting:

1. Request ke URL yang tidak ada di router. seperti /.env. Group web baru berjalan setelah routing selesai, jadi firewall tidak pernah melihat request itu — padahal justru request itulah yang paling ingin kita tolak.
2. Trusted cookie tidak akan bekerja. Group web berisi EncryptCookies. Kalau Shield ikut masuk ke dalam group itu, Laravel lebih dulu mendekripsi cookie, sementara Shield sendiri membaca cookie terenkripsi untuk memeriksa trusted-cookie. Akibatnya setiap pengguna yang sudah lolos challenge akan ditanya ulang terus-menerus.

Sejak 1.2.1, kondisi nomor 2 tidak lagi gagal diam-diam. Shield menulis satu peringatan di log aplikasi:

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

Kalau Anda menemukan pesan itu, kembalikan middleware ke posisi global.

Langkah 4 — Isi environment

SHIELD_ENABLED=true
SHIELD_MODE=observe
SHIELD_APP_ID=my-app
SHIELD_CHALLENGE=turnstile

Variabel	Isi	Kapan perlu
SHIELD_MODE	observe, challenge, atau enforce	Selalu. Mulai dengan observe.
SHIELD_APP_ID	Nama unik untuk aplikasi Anda	Selalu, kalau butuh terutama agar dua aplikasi di server yang sama tidak saling berbagi ban di cache.
SHIELD_CHALLENGE	turnstile, recaptcha, atau null	Baru ketika Anda mau memakai challenge.

SHIELD_MODE=observe berarti Shield mencatat kejadian tetapi tidak memblokir siapa pun. Ini mode yang aman untuk pemasangan pertama.

Langkah 5 — Atur trusted proxy

Ini bagian yang paling sering terlewat, dan kalau sampai salah dampaknya besar.

Semua ban, challenge, dan penghitung perilaku di Shield berbasis IP klien. Kalau aplikasi Anda berada di belakang load balancer, reverse proxy, atau Cloudflare, maka Laravel secara default melihat IP proxy — bukan IP pengunjung.

Akibatnya semua orang terlihat datang dari satu IP, dan Shield bisa: memblokir semua pengguna sekaligus, memberi challenge massal, atau salah menghitung rate limit.

Kalau Anda memakai Cloudflare, allowlist ini yang perlu ditambahkan:

use Illuminate\Http\Request;

$middleware->trustProxies(
    at: '173.245.48.0/20,103.21.244.0/22,103.22.200.0/22,103.31.4.0/22,141.101.64.0/18,108.162.192.0/18,190.93.240.0/20,188.114.96.0/20,197.234.240.0/22,198.41.128.0/17,162.158.0.0/15,104.16.0.0/13,104.24.0.0/14,172.64.0.0/13,131.0.72.0/22',
    headers: Request::HEADER_X_FORWARDED_FOR,
);

Jangan pernah pakai at: '*'

trustProxies(at: '*') berarti “percaya header forwarded dari siapa saja”. Kalau aplikasi Anda bisa dijangkau langsung tanpa lewat proxy, penyerang cukup mengganti header X-Forwarded-For untuk menyembunyikan IP aslinya — dan seluruh proteksi berbasis IP Shield jadi tidak berguna.

Selalu tuliskan rentang CIDR proxy yang Anda percaya, bukan *.

Mulai 1.2.0, Shield otomatis menulis peringatan di log kalau header forwarded terdeteksi tanpa trusted proxy yang dikonfigurasi, atau kalau APP_URL menunjuk ke host publik sementara mode-nya challenge/enforce. Tidak perlu menjalankan perintah apa pun untuk melihatnya.

Langkah 6 — Jalankan

php artisan serve

Lalu periksa apakah semua komponen sehat:

php artisan shield:health

Perintah ini memeriksa koneksi database, cache, mesin Shield, konfigurasi trusted proxy, dan resolusi DNS untuk verifikasi crawler.

Langkah 7 — Aktifkan scheduler

Shield sudah menjadwalkan shield:prune sendiri setiap hari, jadi Anda tidak perlu mendaftarkan perintahnya. Tapi Laravel hanya menjalankan jadwal itu kalau schedule:run benar-benar dieksekusi. Tambahkan cron berikut:

* * * * * cd /path/ke/aplikasi && php artisan schedule:run >> /dev/null 2>&1

Tanpa cron itu, tabel security_events akan tumbuh tanpa batas.

Aktivasi bertahap (disarankan)

Jangan langsung masuk ke mode enforce. Urutan yang aman:

1. Mode observe selama 1–3 hari. Shield mencatat, tidak memblokir.
2. Baca shield:report. Cari rule yang aktif tanpa alasan, atau IP asli yang ikut kena.
3. Naikkan mode ke challenge. Pengunjung asli mungkin terdampak sedikit, sementara penyerang belum. Amati beberapa hari lagi.
4. Naikkan ke enforce. Perlahan.
5. Aktifkan eskalasi ban. Biarkan durasi ban naik otomatis untuk yang mengulangi.

Setiap tahap, periksa manual release dan challenge pass rate sebagai penanda ada false positive.

Langkah berikutnya

• Konfigurasi — semua opsi yang bisa Anda ubah.
• Masalah Umum — kalau ada yang tidak beres.
• Perintah Artisan — cara melihat apa yang terjadi.