Konfigurasi

Shield Core menerima satu array konfigurasi. Bentuknya sudah ditentukan oleh ShieldConfig, dan konfigurasi yang tidak lengkap akan diisi default.

use Ganadev\Shield\Core\Config\ShieldConfig;

$config = ShieldConfig::fromArray(require 'shield.php');

Kalau Anda hanya ingin mencoba, ShieldConfig::defaults() mengembalikan array default tanpa perlu file sama sekali.

Yang paling sering diubah

Delapan kunci ini yang benar-benar dipakai setiap hari. Sisanya biarkan default sampai Anda punya alasan.

return [
    'enabled' => true,

    // observe → challenge → enforce. Mulai dari observe.
    'mode' => 'observe',

    'thresholds' => [
        'challenge' => 10,
        'ban' => 20,
        'strong_ban' => 30,
    ],

    'ban' => [
        'durations' => [15, 60, 360, 1440],
    ],

    'behavior' => [
        'unique_uri_limit' => 25,
        'window_seconds' => 60,
        'not_found_limit' => 20,
    ],

    'logging' => [
        'level' => 'suspicious',
    ],

    'bots' => [
        'mode' => 'observe',
    ],

    'rules' => [
        'packs' => [
            'wordpress' => false,
            'injection' => true,
        ],
    ],
];

Tabel lengkap

Dasar

Kunci	Default	Arti
enabled	true	Matikan seluruh Shield tanpa menghapus konfigurasi.
mode	observe	observe, challenge, atau enforce.
app_id	'default'	Label aplikasi di log kejadian.
response_code	404	Status HTTP untuk request yang diblokir.
fail_mode	open	open atau closed. Lihat catatan di bawah.
rule_version	'1.0.0'	Versi rule yang dipakai saat event dicatat.

Ambang

Kunci	Default
thresholds.challenge	10
thresholds.ban	20
thresholds.strong_ban	30
escalation.step	5

Ketiganya harus naik berurutan. Nilai yang sama atau menurun akan ditolak saat boot, karena urutan keputusan jadi tidak punya arti.

Ban

Kunci	Default	Arti
ban.durations	[15, 60, 360, 1440]	Menit, dibaca berurutan sesuai offense ke berapa.

Empat entri berarti ban pertama 15 menit, kedua 1 jam, ketiga 6 jam, keempat 24 jam. Setelah entri terakhir, durasi terakhir dipakai terus.

Normalisasi dan performa

Kunci	Default	Arti
decode_depth	2	Berapa kali URI di-decode ulang.
performance.max_uri_length	2048	Panjang URI yang diproses.
performance.ban_cache_ttl_seconds	30	Masa cache ban aktif.

decode_depth adalah pertahanan terhadap encoding berlapis. Naikkan kalau Anda melihat payload yang lolos dengan satu kali decode, tapi jangan berlebihan — setiap tingkat menambah pekerjaan CPU.

Perilaku

Kunci	Default	Arti
behavior.unique_uri_limit	25	Berapa URI berbeda sebelum dicatat sebagai sinyal.
behavior.window_seconds	60	Panjang jendela counter.
behavior.not_found_limit	20	Berapa 404 sebelum dicatat.
behavior.path_rate_limit	30	Batas request per path.
behavior.sensitive_path_rate_limit	8	Batas request untuk path sensitif.
behavior.sensitive_paths	7 path	Path yang dianggap sensitif.
behavior.missing_referer_signal	true	Hitung referrer yang hilang sebagai sinyal.
behavior.suspicious_user_agents	[]	Tambahan User-Agent mencurigakan.
behavior.scanner_user_agents	13 entri	User-Agent scanner yang dikenali.
behavior.scanner_ua_signal	4	Skor untuk User-Agent scanner.

Default sensitive_paths mencakup /login, /wp-login.php, /admin/login, /administrator/, /api/login, /api/auth, dan /user/login.

Bot

Kunci	Default	Arti
bots.mode	observe	off, observe, atau challenge.
bots.known_agents	17 entri	User-Agent yang dikenali sebagai bot.
bots.unverified_claim_signal	4	Skor untuk klaim bot yang gagal diverifikasi.
bots.verification.enabled	true	Verifikasi lewat reverse DNS.
bots.verification.ttl_hours	24	Masa cache hasil verifikasi.
bots.verification.hostnames	9 bot	Hostname yang diizinkan per bot.
bots.verification.ip_ranges	[]	CIDR cadangan untuk bot tertentu.

Detail lengkapnya ada di Verifikasi Crawler.

Rule

Kunci	Default	Arti
rules.packs.injection	true	Paket aturan injeksi aktif.
rules.packs.wordpress	false	Paket aturan WordPress nonaktif.
rules.skip_paths	[]	Path yang dilewati seluruh rule.

Daftar rule dan cara menambahnya ada di Aturan.

Log

Kunci	Default	Arti
logging.level	suspicious	all, suspicious, atau blocked.
logging.bypass_events	true	Catat request yang melewati allowlist.

Tiga level itu:

Level	Yang dicatat
all	Setiap request.
suspicious	Semua keputusan kecuali ALLOW biasa.
blocked	Hanya keputusan terminal: BLOCK_REQUEST dan TEMP_BAN.

Challenge dan tepercaya

Kunci	Default	Arti
challenge.driver	turnstile	Driver challenge yang dipakai.
trusted.enabled	true	Pakai cookie tepercaya setelah challenge lolos.
trusted.ttl_minutes	60	Masa berlaku cookie.

Allowlist

Kunci	Default	Arti
allowlist.hosts	[]	Host yang bebas.
allowlist.paths	[]	Path yang bebas.
allowlist.ips	[]	IP yang bebas.

Aturan allowlist ada di Arsitektur.

Inspeksi body dan API

Kunci	Default	Arti
inspection.body.enabled	true	Periksa isi body pada rule tertentu.
inspection.body.max_bytes	65536	Batas byte yang dibaca.
api.paths	[]	Prefix path yang diperlakukan sebagai API.
api.detect_accept	true	Deteksi API dari header Accept.

Privasi

Kunci	Default
privacy.sensitive_query_parameters	token, password, passwd, key, secret, code, auth

Parameter ini disamarkan jadi *** sebelum disimpan ke log.

Tampilan

Kunci	Default
views.blocked	shield::blocked
views.challenge	shield::challenge
branding.title	Ganadev Laravel Shield
branding.accent_color	#22d3ee
branding.background_color	#0b1220
branding.show_rule_id	false

show_rule_id sebaiknya tetap false di produksi. Menampilkan ID rule membantu penyerang menyetel tools-nya.

Catatan penting

fail_mode

Default open: kalau BanRepository melempar exception, request tetap diteruskan dan infrastructureDegraded diisi true.

closed memblokir semua request dengan skor 99 dan alasan fail_closed. Pilih ini hanya kalau Anda benar-benar lebih memilih request ditolak daripada melewatkan request tanpa pemeriksaan — dan sudah punya cara cepat menemukan masalahnya.

response_code

Default 404 disengaja. Dengan begitu penyerang tidak bisa memastikan ada atau tidaknya proteksi di depan situs Anda.

403 dan 429 juga sah. 429 berguna kalau Anda memang ingin memberi tahu bahwa ada pembatas.

max_uri_length

URI dipotong pada batas ini sebelum rule dicocokkan. Kalau aplikasi Anda punya URL yang sangat panjang dan sah, naikkan nilai ini — tapi ingat bahwa memproses URI panjang tetap mahal.

Yang tidak ada di Core

Kunci berikut ada di adapter Laravel, bukan di Core, karena butuh infrastruktur yang tidak dimiliki Core:

Kunci adapter	Keterangan
middleware	Middleware yang mendaftarkan Shield.
views.paths	Lokasi file Blade.
database.connection	Koneksi untuk migration.
logging.retention_days	Umur simpan event.
admin.prefix, admin.middleware	Routing panel admin.
challenge.*	Kredensial dan URL API driver.
bots.verify_timeout	Timeout saat resolve DNS.

Kalau Anda menulis adapter sendiri, kunci-kunci itu tetap perlu Anda definisikan — hanya tempatnya berbeda.

Kesalahan konfigurasi yang paling sering muncul

Gejala	Penyebab
Boot gagal, pesan soal regex	Pola terlalu lambat atau tidak valid.
Boot gagal, threshold	Nilai thresholds tidak naik berurutan.
Semua orang dari satu IP kena ban	Trusted proxy belum diatur di adapter.
Ban tidak hilang setelah dilepas	Cache 30 detik masih menyimpan.
Tabel event membengkak	logging.level masih all.
Bot sah tersingkir	bots.mode challenge tanpa fallback ip_ranges.

Daftar lengkap gejalanya ada di Masalah Umum.