Masalah umum

Halaman ini diurutkan dari yang paling sering:ditemukan.

Kenapa tidak bisa pasang 1.2.1

Rilis 1.2.1 sempat diberi tag Git, lalu tag-nya dipindahkan. Packagist menolak tag yang dipindahkan, jadi 1.2.1 tidak pernah muncul di metadata Composer:

composer require ganadev/laravel-shield:^1.2.1
# could not be 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:

composer require ganadev/laravel-shield:^1.2.2

Kalau Composer masih gagal, bersihkan cache-nya:

composer clear-cache

Middleware tidak muncul di php artisan about

Gejalanya: Shield terpasang, tidak ada error, tapi middleware tidak terlihat.

Periksalah tiga hal:

1. Package auto-discovery menyala. Di composer.json aplikasi Anda, jangan ada "extra": {"laravel": {"dont-discover": [...]}} yang menyebut Ganadev\Shield\Laravel\ShieldServiceProvider. Kalau iya, jalankan composer dump-autoload.

2. Middleware benar-benar didaftarkan di bootstrap/app.php:

   $middleware->append([
       \Ganadev\Shield\Laravel\Middleware\SecurityFirewallMiddleware::class,
   ]);

3. Cached. Jalankan php artisan optimize:clear.

Semua orang suddenly kena challenge

Hampir selalu satu dari dua hal.

Trusted proxy belum diatur

Kalau aplikasi Anda di belakang Cloudflare, load balancer, atau reverse proxy, Laravel melihat IP proxy — bukan IP pengunjung. Semua orang jadi terlihat berasal dari satu alamat, dan rate limit perilaku langsung menyala untuk seluruh pengguna.

Perbaikannya ada di Instalasi. Yang penting: tuliskan CIDR proxy yang Anda percaya, jangan at: '*'.

Rate limit terlalu ketat untuk traffic Anda

Kalau jumlah request Anda memang besar, naikkan batasnya:

SHIELD_BEHAVIOR_UNIQUE_URI_LIMIT=60
SHIELD_BEHAVIOR_WINDOW_SECONDS=120
SHIELD_BEHAVIOR_PATH_RATE_LIMIT=90

Naikkan satu per satu, lalu php artisan config:clear dan amati.

Pengunjung asli masih kena challenge berulang

Gejalanya: orang menyelesaikan challenge, lalu langsung diminta lagi di halaman berikutnya.

Penyebabnya hampir selalu trusted cookie tidak tersimpan. Periksa:

1. HTTPS aktif. Tanpa itu, browser menerima cookie Secure tapi tidak pernah mengirimkannya. Di development, http://localhost diperlakukan browser modern sebagai konteks aman.

2. Middleware Shield tidak masuk group web. Kalau iya, EncryptCookies mendekripsi cookie lebih dulu, sementara Shield membaca cookie terenkripsi. Cari pesan ini di log:

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

   Kalau muncul, kembalikan middleware ke posisi global.

3. IP atau User-Agent berubah di tengah sesi. Trusted cookie terikat pada keduanya, jadi perpindahan jaringan membuat cookie tidak berlaku.

Blokir mengembalikan HTML, padahal kliennya API

Gejalanya: klien API Anda gagal dengan Unexpected token < atau gagal parse JSON.

Shield membalas JSON kalau request-nya jelas meminta JSON. Kalau tidak, masukkan path-nya ke api.paths:

SHIELD_API_DETECT_ACCEPT=true

'api' => [
    'paths' => ['/api', '/oauth/token'],
],

Kalau framework Anda mengirim Accept: application/json untuk form biasa, matikan detect_accept supaya tidak salah tebak.

InvalidConfigException saat boot

Aplikasi gagal start begitu saja, dengan pesan exception. Ini memang perilaku yang disengaja — lebih baik gagal dini daripada berjalan dengan konfigurasi keliru.

allowlist.paths tidak valid

Pesan	Perbaikan
Kosong atau '/' ditolak	Hapus entrinya. Kalau memang mau semua, pakai hosts.
Tidak diawali /	Tulis '/admin', bukan 'admin'.
Mengandung query string	Hapus ? beserta isinya.

Regex rule may be ReDoS-prone

Regex yang Anda tulis terlalu lambat. Shield mengujinya dengan payload 64 karakter berulang dan menolak apa pun yang melebihi 50 milidetik. Persempit polanya.

thresholds tidak naik berurutan

challenge, ban, dan strong_ban harus naik berurutan. Nilai yang sama atau turun ditolak saat boot.

Tabel security_events tumbuh sangat besar

Tiga penyebab yang paling mungkin:

1. SHIELD_LOG_LEVEL=all. Pakai suspicious di produksi.

2. Scheduler tidak jalan. shield:prune sudah dijadwalkan Shield sendiri, tapi jadwal itu hanya dieksekusi kalau cron berikut aktif:

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

3. Umur retensi terlalu lama. Turunkan SHIELD_LOG_RETENTION_DAYS.

Untuk membersihkannya sekarang:

php artisan shield:prune --days=7

Ban tidak hilang setelah shield:release

Ban disimpan di cache 30 detik. Ban bisa masih aktif sebentar setelah dilepas:

php artisan cache:clear

Kalau ban itu benar-benar hilang tapi IP tetap diblokir, cek dua hal:

• masih ada baris lain di security_ip_bans dengan IP yang sama,
• offense count sudah naik sehingga durasi ban yang berikutnya jauh lebih panjang. Melepas ban tidak mereset penghitung.

InvalidConfigException: regex rule gagal compile

Regex-nya tidak valid secara sintaks. Test dulu dengan PHP langsung:

php -r 'var_dump(preg_match("~polaanda~i", "contoh"));'

Kalau hasilnya false, pola salahnya ada di sana.

Googlebot tidak bisa mengindeks situs

Periksa satu per satu:

1. DNS server bisa reverse lookup? Verifikasi crawler bergantung pada itu. Isi bots.verification.ip_ranges sebagai cadangan.
2. bots.mode masih observe? Kalau sudah challenge, satu gangguan DNS akan membuat crawler sah kena challenge.
3. Log menunjukkan apa? php artisan shield:report, cari unverified_crawler_claim.

Detailnya ada di Bot dan crawler.

Perintah Artisan tidak ditemukan

php artisan list | grep shield

Kalau kosong, periksa apakah package benar-benar terpasang:

composer show ganadev/laravel-shield

Kalau terpasang tapi perintahnya tidak muncul, php artisan optimize:clear biasanya menyelesaikannya.

Apa selanjutnya kalau tidak ada yang cocok di sini

1. php artisan shield:health — cek komponennya.
2. php artisan shield:report — lihat apa yang sebenarnya terjadi.
3. php artisan shield:rules:list — pastikan rule yang Anda harapkan aktif.

Kalau masih buntu, buka issue di repository GitHub dengan keluaran ketiga perintah di atas. Sertakan php artisan about dan versi Laravel Anda — jangan sertakan APP_KEY atau kredensial apa pun.