Arsitektur

Ganadev Shield memisahkan dua hal: logika keamanan (core) dan cara terhubung ke framework (adapter).

• ganadev/shield-core — semua logika keamanan, nol dependensi Laravel.
• ganadev/laravel-shield — “kulit” Laravel: membaca request, memanggil core, menerjemahkan keputusan.

Pipeline request

Setiap request melewati ShieldEngine::inspect():

Request
  → kumpulkan RequestContext (uri, method, host, ip, subset header, body opsional)
  → normalisasi (decode terbatas, lowercase, backslash→slash, gabungkan slash)
  → cek allowlist (tidak pernah melewati rule critical)
  → cocokkan aturan statis (signature)
  → cek sinyal perilaku (counter)
  → cek reputasi / ban aktif (via cache)
  → hitung skor risiko + eskalasi
  → putuskan: ALLOW | OBSERVE | CHALLENGE | BLOCK_REQUEST | TEMP_BAN
  → simpan event / perbarui reputasi
  → respons framework (atau lanjutkan request)

Aturan critical (/.env, /.git/config, AWS credentials, /proc/self/environ, php://input) selalu diblok, bahkan saat cookie trusted valid.

Komponen core (ringkas)

• Context\RequestContext — data request immutable.
• Normalization\Normalizer — murni, deterministik, decode terbatas (decode_depth, maks 3).
• Rules\* — aturan berbasis data + matcher registry.
• Detection\ThreatSignatureEngine + Detection\BehaviorDetector — signature & perilaku.
• Scoring\RiskScorer — akumulasi skor + eskalasi offense.
• Decision\DecisionEngine — deterministik: input sama → output sama.
• Reputation\* — BanPolicy, RiskDecay, BanRecord.
• Persistence\*Interface — kontrak penyimpanan & cache.
• Engine\ShieldEngine — orkestrator pipeline.

Pemisahan lewat kontrak

Core mendefinisikan interface; adapter yang mengimplementasikan:

• BanRepositoryInterface / EventRepositoryInterface — penyimpanan (Eloquent di Laravel).
• CacheAdapterInterface — penghitung & cache.
• ChallengeDriverInterface — verifikasi challenge.
• TrustedCookieInterface — cookie trusted.
• CrawlerVerifierInterface — verifikasi IP crawler.

Cache

• Database = sumber utama untuk ban & event.
• Cache = jalur cepat: ban aktif (TTL pendek), counter, status trusted cookie.
• LaravelCacheAdapter menambah prefix shield:{app_id}: agar cache bersama tidak bentrok.

Mode & fail-safe

• mode: observe | challenge | enforce — observe mencatat tanpa memblokir; challenge menurunkan ban menjadi challenge; enforce penuh.
• fail_mode: open | closed — saat store ban mati: open membiarkan request normal lewat (signature critical stateless tetap diblok), closed memblokir (deny-by-default).