Shield Kütüphanesi

Shield, KUT uygulamalarında istek hızı sınırlama, başarısız işlem takibi, geçici engelleme, doğrulama kararı, IP beyaz listesi ve kara liste yeteneklerini tek bir kütüphanede toplar. Veritabanına ihtiyaç duymaz; Config/Storage.php içinde uygulama için seçilmiş cache sürücüsünü kullanır.

Başlatma ve otomatik istek koruması

Shield::init();
Shield::guardRequest();

guardRequest(), Config/Security.php içindeki auto.policies listesini sırayla uygular. İstemci sınırı aşarsa controller ve model çalışmadan HTTP 429 yanıtı üretilir.

İşlem koruma

$decision = Shield::action('account.login')
    ->user(['username' => Post::username()])
    ->check();

if($decision->blocked())
{
    return Shield::respond($decision);
}

if($decision->challenged())
{
    // Uygulama reCAPTCHA, OTP veya kendi doğrulama akışını gösterebilir.
}

Başarısız işlem fail() ile sayılır; başarılı işlem ilgili sayaçları temizler:

if(! $credentialsAreValid)
{
    $decision = Shield::fail();
}
else
{
    Shield::clear('account.login');
}

Decision; allowed(), denied(), challenged(), blocked(), limit(), remaining(), resetAt(), retryAfter() ve reason() yöntemlerini sağlar. Shield doğrulama arayüzü üretmez; geliştirici kararın uygulamadaki karşılığını belirler.

Security.php yapılandırması

'shield' =>
[
    'enabled' => true,
    'headers' => true,
    'trustedProxies' => [],

    'features' =>
    [
        'rateLimit' => true,
        'challenge' => true,
        'whitelist' => true,
        'blacklist' => true
    ],

    'lists' =>
    [
        'whitelist' => ['enabled' => true, 'ips' => ['127.0.0.1', '::1']],
        'blacklist' => ['enabled' => true, 'ips' => []]
    ],

    'auto' =>
    [
        'enabled' => true,
        'policies' => ['request.burst', 'request.sustained']
    ],

    'policies' =>
    [
        'request.burst' =>
        [
            'limit' => 120,
            'window' => '10 seconds',
            'blockFor' => '30 seconds'
        ],
        'account.login' =>
        [
            'limit' => 8,
            'window' => '5 minutes',
            'challengeAfter' => 4,
            'blockFor' => '15 minutes'
        ]
    ]
]

Özellikler features altında ayrı ayrı etkinleştirilebilir. Politika adları noktalı yol biçimindedir. account.* gibi joker politika tanımları aynı gruptaki işlemlere ortak kural uygulayabilir.

Rate limit davranışı

• limit: pencere içinde izin verilen istek veya başarısız işlem sayısıdır.
• window: sayacın yenileneceği süredir.
• challengeAfter: engelden önce ek doğrulama önerilecek eşiktir; sıfırsa challenge kullanılmaz.
• blockFor: sınır aşıldıktan sonraki geçici engel süresidir.

Shield::protect('api.token', ['account' => $accountId]) tek çağrıda politika seçip sayacı artırır. Kimlik değerleri dosyalara açık biçimde yazılmaz; proje anahtarıyla HMAC üretilir.

HTTP yanıtları

respond() veya abort() kullanıldığında Shield uygun HTTP durumunu ve RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset, Retry-After başlıklarını üretir. Hız sınırı için 429, kara liste için 403 kullanılır.

Whitelist ve blacklist

Listeler tek IP adresi veya IPv4/IPv6 CIDR aralığı kabul eder. Whitelist eşleşmesi bütün sayaçları atlar. Blacklist eşleşmesi isteği sayaçtan bağımsız olarak reddeder. Proxy başlıkları yalnız trustedProxies içinde tanımlı doğrudan vekillerden geldiğinde kabul edilir.

Depolama

Shield ayrı bir sürücü seçmez. Config/Storage.php dosyasındaki cache.driver değeri file, redis, apc veya memcache olduğunda Shield aynı sürücüyü ve bağlantı ayarlarını kullanır. Anahtarlar proje/container ve Shield kapsamıyla ayrılır.

File sürücüsü kayıtları container projesinin Storage/Shield dizininde atomik kilitlemeyle saklar. Paylaşımlı sürücüler kendi TTL mekanizmasıyla süresi dolan kayıtları kaldırır. Shield kayıtları genel Cache verilerinden mantıksal olarak ayrıdır; uygulama önbelleğini temizlemek güvenlik sayaçlarını silmez.

Süresi dolmuş kayıtları temizleme

Temizlik HTTP istekleri sırasında otomatik çalıştırılmaz. File sürücüsünde süresi dolmuş kayıtlar zamanlanmış görevden veya bakım komutundan açıkça temizlenebilir. Redis, APCu ve Memcached kayıtları sürücünün TTL mekanizmasıyla silindiğinden yöntem sıfır döndürür.

Shield::init();
$removed = Shield::prune();

prune() yalnız süresi dolmuş kayıtları kaldırır ve silinen kayıt sayısını döndürür. OrunCP bu yöntemi Commands/Jobs.php içindeki zamanlanmış görev döngüsünde çağırır. Kendi uygulamanızda aynı yöntemi Buyruk komutundan, cron görevinden veya yönetim aracından çağırabilirsiniz.