Skor & Keputusan

Shield tidak menebak. Ia menjumlahkan angka, lalu membandingkan dengan ambang. Halaman ini menjelaskan kedua langkah itu.

Langkah 1: menghitung skor

$total = $signatureScore
       + $behavior->totalDelta
       + $escalationScore
       + $challengePenalty;

Bagian	Asalnya
signatureScore	Penjumlahan skor semua rule yang cocok.
behaviorScore	Penjumlahan delta dari sinyal perilaku.
escalationScore	Bonus dari riwayat offense sebelumnya.
challengePenalty	Cadangan untuk kegagalan challenge.

challengePenalty selalu 0 saat ini. Nilainya sudah disiapkan supaya mekanisme penalti challenge bisa ditambahkan tanpa mengubah signature method.

Tidak ada plafon. Satu request yang cocok tiga rule berat bisa langsung melewati strong_ban, dan itu memang disengaja.

Kenapa behavior tidak langsung memengaruhi eskalasi

Kalau riwayat offense langsung menambah skor, lalu satu request biasa pun bisa memicu ban berat pada IP yang punya riwayat. RiskScorer deshalb memakai syarat tambahan:

public const MIN_ESCALATION_BEHAVIOR_SCORE = 10;

$hasViolation = $signatureScore > 0
    || $behavior->totalDelta >= self::MIN_ESCALATION_BEHAVIOR_SCORE;

Artinya bonus offense hanya berlaku kalau request itu benar-benar bermasalah: ada rule yang cocok, atau sinyal perilaku dessen minimal 10 poin. Sinyal lemah seperti referrer yang hilang atau User-Agent ganjil tidak cukup untuk menaikkan skor lewat riwayat.

Eskalasi dibatasi lima langkah

$escalationScore = min($offenseCount, 5) * $config->escalationStep;

Dengan escalation.step bawaan 5:

Offense ke-	Bonus
1	5
2	10
3	15
4	20
5 dan seterusnya	25

Plafon 25 itu disengaja. Kalau tidak, offense ke-30 akan menambah 150 poin dan ban berikutnya jadi tidak masuk akal.

Langkah 2: ambang menjadi keputusan

DecisionEngine sepenuhnya deterministik. Input sama, hasil selalu sama.

if ($score->hasCritical)          return BLOCK_REQUEST;
if ($score->total >= $strongBan)  return TEMP_BAN;
if ($score->total >= $ban)        return TEMP_BAN;
if ($score->total >= $challenge)  return CHALLENGE;
if ($score->total >= 5)           return OBSERVE;
                                return ALLOWED;

Dengan ambang bawaan 10 / 20 / 30:

Total skor	Keputusan
0 – 4	ALLOWED
5 – 9	OBSERVE
10 – 19	CHALLENGE
20 – 29	TEMP_BAN
30 ke atas	TEMP_BAN
Rule critical cocok	BLOCK_REQUEST, apa pun skornya

Lantai OBSERVE bernilai 5 dan tidak bisa dikonfigurasi. Nilai di bawah itu tidak menarik informasi apa pun.

strong_ban dan ban menghasilkan keputusan yang sama

Keduanya mengembalikan TEMP_BAN. Yang membedakan adalah urutan dan validasi: thresholds wajib naik ketat (challenge < ban < strong_ban), dan boot gagal kalau tidak. Pada praktiknya, perbedaan durasi ban datang dari offense_count, bukan dari ambangnya. Kalau Anda menaikkan strong_ban dengan harapan melihat efek yang jelas, periksa dulu hasilnya di php artisan shield:report.

Tiga koreksi setelah ambang

Setelah intendedDecision dihitung, tiga koreksi diterapkan berurutan. Urutan ini penting dan tidak boleh dibalik.

1. Ban aktif

Kalau ada ban yang sedang berlaku:

Kondisi	Hasil
Sudah ada rule critical	Tidak diubah.
Keputusan ALLOWED atau OBSERVE, cookie tepercaya valid	ALLOWED
Keputusan ALLOWED atau OBSERVE, tanpa cookie	CHALLENGE
Keputusan lain	Tidak diubah.

Jadi ban aktif tidak langsung menolak request biasa — ia menaikkan menjadi challenge lebih dulu. Ini yang memberi kesempatan pengguna sah lolos captcha.

2. Cookie tepercaya

if ($trusted && $intended === CHALLENGE && $score->total < $thresholdBan) {
    return ALLOWED;
}

Dua syarat harus terpenuhi: keputusannya CHALLENGE, dan skornya di bawah ambang ban. Kalau skornya sudah melewati ambang ban, cookie tepercaya tidak membantu. Mengizinkan orang yang berperilaku seperti penyerang bukan tindakan yang dilakukan.

3. Mode

Mode	Yang terjadi
observe	Selalu OBSERVE, apa pun skor dan keputusannya.
challenge	critical tetap BLOCK_REQUEST. TEMP_BAN diturunkan jadi CHALLENGE. Selain itu tidak diubah.
enforce	Tidak ada perubahan sama sekali.

Inilah alasan shouldBlock() harus dipakai, bukan verdict->decision. Di mode observe, intended bisa TEMP_BAN sementara decision adalah OBSERVE.

Alasan yang tersimpan

Setiap keputusan membawa kode alasan yang bisa disimpan dan dicari:

Alasan	Kapan
observe_mode: would_have_been_TEMP_BAN	Mode observe menahan sebuah keputusan terminal.
critical_signature_sensitive.env	Rule critical cocok.
active_ban_challenge	Ban aktif dinaikkan menjadi challenge.
score_challenge	Skor melewati ambang challenge.
score_ban	Skor melewati ambang ban.
trusted_cookie	Cookie tetrusted yang membuat request diizinkan.
block_request	Diblokir tanpa skor, misalnya fail_closed.
allowed	Tidak ada yang salah.

Alasan observe_mode: would_have_been_... yang paling berguna. Dia memberi tau apa yang akan terjadi kalau Anda menaikkan mode — tanpa harus menakannya dulu.

Dua lapis yang perlu Anda ingat

$result->verdict->intended;   // apa yang seharusnya terjadi
$result->verdict->decision;   // apa yang benar-benar terjadi
$result->verdict->downgraded(); // apakah observe menahan sesuatu

Simpan intended di log. Kalau suatu saat Anda ingin menaikkan mode ke enforce, data itu sudah memberi tahu apa yang akan berubah — termasuk berapa banyak pengguna yang akan kena.

Cara menaikkan mode dengan aman

1. Jalankan dengan observe selama beberapa hari.
2. Baca php artisan shield:report, cari observe_mode:.
3. Periksa intended yang muncul. Kalau semuanya TEMP_BAN dari sensitive.env saja, Anda siap.
4. Naikkan ke challenge.
5. Kalau CHALLENGE muncul dari score_challenge pada user-Agent normal, turunkan ambang atau perbaiki rules sebelum ke enforce.

Berikutnya

• Deteksi Perilaku — dari mana angka perilaku itu datang.
• Ban & Risk Decay — apa yang terjadi setelah keputusan TEMP_BAN.