Ban & Reputasi

Ban adalah keputusan terberat yang bisa diambil Shield. Ia memblokir satu alamat IP untuk sementara. Karena berat, Shield berhati-hati: ban baru muncul setelah skor mencapai thresholdBan (20 secara bawaan).

Kapan ban muncul

1. Ban dari skor

Pada mode challenge/enforce, request yang skornya mencapai thresholdBan menghasilkan TEMP_BAN. Durasi ditentukan oleh urutan offense, bukan oleh tingginya skor:

Offense ke-	Durasi
1	banDurations[0] (default 15 menit)
2	banDurations[1] (default 1 jam)
3	banDurations[2] (default 6 jam)
4 dan seterusnya	banDurations[3] (default 24 jam)

2. Ban yang berlaku lintas request

Penghitung perilaku (menyelusuri URL, banjir login) menaikkan skor request. Kalau skor gabungan mencapai ambang, IP diban — bukan karena satu request, tetapi karena polanya.

3. Cache ban

Ban dicatat di database dan disalin ke cache selama banCacheTtlSeconds (default 30 detik). Cache ini dibaca tiap request supaya pemeriksaan cepat. Perubahan langsung di database tidak terlihat sampai cache kedaluwarsa.

Panjang ban

public array $banDurations = [15, 60, 360, 1440];   // menit
public int $escalationStep = 5;                      // tambahan skor risiko

banDurations adalah durasi per offense seperti tabel di atas. escalationStep bukan pengali durasi: ia menambah skor risiko request sebesar min(offenseCount, 5) * escalationStep ketika ada signature match atau sinyal perilaku yang mencapai ambang challenge (total sinyal >= 10).

Eskalasi

Request biasa tidak dihitung sebagai offense. Offense baru bertambah saat engine membuat ban baru; challenge yang gagal tidak menambah offense. Riwayat offense tidak dihapus saat ban dirilis, jadi pelaku yang kembali bisa mendapat durasi berikutnya.

Riwayat offense tersimpan tidak meluruh. Pelusan offenseCount hanya dipakai untuk menghitung bonus skor selama ban masih aktif; nilai di database tidak ditulis ulang. Durasi ban berikutnya tetap memakai offenseCount tersimpan + 1, jadi tidak turun setelah masa tenang.

Pelaporan & penilaian reputasi

Shield menilai reputasi IP dari “ban yang sudah pernah diberikan”. Detail tercatat di tabel security_ip_bans: kapan ban dibuat, berapa lama, alasan, dan siapa yang melepas.

Baca ringkasannya lewat:

php spark shield:report

Melepas ban

Lewat perintah Spark

php spark shield:release 203.0.113.10

Tambahkan alasannya supaya tercatat:

php spark shield:release 203.0.113.10 --reason="pelanggan salah ketik"

Per-release tidak mereset offense

Jumlah pelanggaran tidak dihapus. Pelaku yang langsung kembali akan mendapat durasi ban yang lebih panjang.

Lewat Admin API

Jika panel admin diaktifkan, buka POST /{prefix}/bans/{id}/release (lihat Admin API).

Melepas ban lewat SQL

banCacheTtlSeconds menyimpan hasil pembacaan status ban di cache. UPDATE langsung ke database tidak menghapus cache tersebut, sehingga engine bisa saja masih menganggap ban aktif hingga 30 detik (default) setelah SQL release.

Perbaikan: gunakan php spark shield:release <ip> yang melewati CachedBanRepository dan menghapus cache, bersihkan cache aplikasi, atau tunggu TTL-nya habis.

Penanda manual review

Saat ban baru dibuat dengan offenseCount >= 5, metadata ban diberi manual_review: true. Ini penanda untuk ditinjau, bukan perubahan status ban. Riwayat release (release_reason, released_by) muncul di metadata ban, bukan sebagai kolom terpisah.

Reset offense

Tidak ada perintah resmi untuk mereset offenseCount. Jika benar-benar perlu memulai riwayat baru untuk satu IP, hapus baris riwayat IP tersebut dari security_ip_bans setelah memastikan tidak ada ban aktif, lalu bersihkan cache aplikasi karena cache ban dapat menyimpan status lama hingga banCacheTtlSeconds. Lakukan hanya dengan pemahaman bahwa audit trail ikut hilang.

Kalau terlalu banyak false positive

1. Turunkan unverifiedClaimSignal atau matikan missingRefererSignal kalau situs Anda banyak menerima traffic tanpa Referer (mis. aplikasi native).
2. Kenali dulu siapa yang kena: php spark shield:report.
3. Naikkan thresholdBan (30 misalnya) supaya ban hanya untuk yang benar-benar parah.
4. Pertimbangkan allowlist hanya untuk kasus yang benar-benar Anda percaya.

Kalau IP asli ikut kena ban

Ini hampir selalu bukan karena salah hitung Shield, melainkan karena semua pengguna terlihat satu IP — artinya proxyIPs belum diatur di app/Config/App.php. Perbaiki dulu, baru lepas ban dengan shield:release.