API için pozitif güvenlik modelini (izin verilen endpoint, metot, parametre) nasıl kurarım?

Kısa cevap

Pozitif model sayfa tipleriyle kurulur: her endpoint bir sayfa tipidir (tam path ya da /api/v1/users/* gibi glob), izin verilen metotlar Allowed Methods alanında, izin verilen ve zorunlu query parametreleri, header'lar ve JSON anahtarları o sayfa tipinin Query, Header ve JSON sekmelerinde tanımlanır. Tanımda olmayan endpoint'leri reddetmek için Any Paths kuralının Allowed methods değeri None yapılır; hiçbir sayfa tipine uymayan her istek 24 puanlık Allowed methods ihlali olur ve her koruma düzeyinde tek başına engelleme eşiğini aşar. Kural seti dört yoldan kurulur: OpenAPI tanımından Import (OpenAPI), trafiği öğrenip Analysis & Learning (API için Comprehensive modu, Only Browsers işareti kaldırılmış; sonuçtaki bilinmeyen ya da şüpheli path'ler uygulamadan önce analizden çıkarılır), Page Types ekranında elle Add ya da WEB-CLI'da waf fw-rules ve waf rule-parts komutları. İzin ve zorunluluk listeleri Checks'teki Argument Checks, uzunluk ve derinlik sınırları Structure Checks açıkken ve host grubu Monitor ya da Blocking modundayken uygulanır; Learning modunda uygulanmaz. Kural path başınadır: aynı path'e gelen POST ve PUT istekleri aynı sayfa tipinin denetimlerini paylaşır.

Sorun: API'ye Yalnızca Tanımlı İstekler Ulaşmalı

İmza taraması bilinen saldırı desenlerini yakalar; ancak bir API'nin hangi endpoint'leri, hangi metotları ve hangi parametreleri kabul ettiğini bilmez. Tanımsız bir endpoint'e yapılan istek, beklenmeyen bir parametre ya da izin verilmeyen bir metot (ör. DELETE) imzası olmadığı için geçer. Pozitif modelde ise API'nin beklenen şekli tanımlanır ve bu şeklin dışındaki her istek 24 puanlık yapısal ihlal olur (Negatif güvenlik modeli (imza tarama) ile pozitif güvenlik modeli arasındaki fark nedir?). İki model aynı puanda birleşir; imza taraması pozitif modelle birlikte çalışmaya devam eder (hibrit güvenlik modeli).

Çözüm: 4 Yöntem

Yöntemler kural setini farklı kaynaklardan kurar; birlikte de kullanılabilir (ör. OpenAPI'den içe aktarıp eksikleri elle tamamlamak). Hepsinde ön koşullar aynıdır: vService'te WAF açıktır (Bir vService'te WAF korumasını nasıl etkinleştiririm?) ve API ayrı bir alan adındaysa kendi host grubu vardır (Host Group nasıl eklenir; Virtual Host Patterns alanına ne yazılır?). Kurulumdan sonra Monitor modunda gelen false positive'ler Event Logs'tan öğretilerek kural setine işlenir (Yanlışlıkla engellenen bir isteğe nasıl izin veririm?).

Durumunuz	Uygun yöntem
API'nin OpenAPI ya da Swagger tanımı var	Yöntem 1: Import (OpenAPI)
Tanım yok; API trafiği var ya da test trafiği üretilebilir	Yöntem 2: Öğrenme ve Analysis & Learning
Az sayıda endpoint; listeleri elle yazmak istiyorum	Yöntem 3: Page Types ekranında elle
Betik ya da otomasyonla kurmak istiyorum	Yöntem 4: WEB-CLI

Yöntem 1: Import (OpenAPI) Önerilen

• Nasıl çalışır Tanımdaki her path bir sayfa tipine dönüşür: {id} şablonları glob'a, operasyonlar Allowed Methods listesine, query ve header parametreleri izin ve zorunluluk listelerine, gövde şemasının alan adları JSON, XML ya da form izin listesine yazılır. İçe aktarma mevcut kurallarla birleştirilir.
• Nerede açılır Left Monitor Panel → WAF-Protected vServices → vService → WAF Management → host grubunun mod kartındaki N page types satırı → Import (OpenAPI)
• Gereksinim OpenAPI 3.0 ya da Swagger 2.0 dosyası (.json, .yaml, .yml); WAF alanında değiştirme yetkisi
• vService tipi HTTP

Adım adım yapılandırma

1

Adım 1 Checks ayarlarını kontrol et

Left Monitor Panel → WAF-Protected vServices → vService → WAF Management sekmesinde, Inspection & Blocking bölümündeki Checks kartının sağ üstündeki kalem ikonu tıklanır (Checks Edit ekranı). Structure Checks ve Argument Checks işaretli olmalıdır (ikisi de varsayılan olarak işaretlidir). Max. Allowed Arguments (varsayılan 25) en uzun izin listesinden küçükse artırılır; aşan liste o kural için sessizce devre dışı kalır.

2

Adım 2 Checks'i kaydet

Değişiklik yapıldıysa Edit tıklanır; değişiklik yoksa pencere kapatılır.

3

Adım 3 Page Types ekranını aç

WAF Management sekmesinde API'nin host grubuna ait mod kartının altındaki N page types satırına tıklanır; Page Types sekmesi host grubunun adıyla açılır (ekrana erişim).

4

Adım 4 Mevcut kuralların yedeğini al

Araç çubuğundaki Export tıklanır; kural seti JSON dosyası olarak iner. İçe aktarma aynı path'li mevcut kuralların yerine geçtiği için tek geri dönüş yolu bu yedektir.

5

Adım 5 Tanım dosyasını seç

Araç çubuğundaki Import (OpenAPI) tıklanır ve açılan dosya seçiciden tanım dosyası seçilir (içe aktarma adımları).

6

Adım 6 İçe aktarmayı onayla

Are you sure? sorusu Yes ile onaylanır. İşlem bitince "OpenAPI import: N path applied" bildirimi görünür; uyarı varsa (ör. düşürülen regex desenleri) bildirimde listelenir. Ayrı bir dağıtım adımı yoktur. Dönüşümün sınırları (iç içe JSON alanları, zorunlu alanlar): OpenAPI tanımımdan API koruma kurallarını otomatik oluşturabilir miyim?

7

Adım 7 Any Paths kuralını düzenlemeye aç

Page Types listesinde italik Any Paths satırı seçilip araç çubuğundaki Edit tıklanır (Any Paths kuralını düzenleme).

8

Adım 8 Tanımsız endpoint'leri kapat

Allowed Methods = None seçilir. Bu ayardan sonra hiçbir sayfa tipine uymayan her istek (dış izleme sistemlerinin yokladığı path'ler, statik dosyalar, dokümantasyon sayfaları dahil) ihlal olur; bu path'ler önce kendi sayfa tipleriyle eklenir (Yöntem 3).

9

Adım 9 Any Paths'i kaydet

Formdaki Edit tıklanır; WAF yapılandırması yeniden üretilip uygulanır. Cluster'da değişiklik varsayılan auto-sync ile eş cihaza gönderilir; Manual Sync Mode açıksa Synchronize ile gönderilir.

Doğrulama

1Üretilen kurallarPage Types

Listede tanımdaki path'ler (şablonlu olanlar glob olarak) görünür; bir kurala tıklandığında açılan detay panelinin Path sekmesinde Allowed methods, Query ve JSON sekmelerinde izin listeleri okunur.

BeklenenPath başına bir kural; N page types sayısı arttı

2Tanımsız endpointMonitor modu · Event Logs

Host grubu Monitor modundayken tanımda olmayan bir path'e istek gönderilir; WAF Event Logs kaydının Attacks sekmesine bakılır.

Komut: curl -s -o /dev/null -w "%{http_code}\n" https://api.example.com/api/v1/undefined

BeklenenAllowed methods (24)

Monitor modunda istek geçirilir; aynı istek Blocking modunda engellenir.

Yöntem 2: Öğrenme ve Analysis & Learning

• Nasıl çalışır Host grubu Learning modunda API trafiğini öğrenme günlüğüne yazar; analiz bu günlükten her endpoint için sayfa tipi, metot listesi ve parametre listeleri üretir.
• Nerede açılır Left Monitor Panel → WAF-Protected vServices → vService → WAF Management → host grubunun mod kartındaki Analysis & Learning yazısı
• Gereksinim WAF alanında değiştirme yetkisi; öğrenme günlüğünde API trafiği (Learning modu ya da Blocking/Monitor modunda Conditional Learning ile seçilen kaynakların trafiği)
• vService tipi HTTP

Adım adım yapılandırma

1

Adım 1 Checks ayarlarını kontrol et

Yöntem 1'in 1–2. adımlarındaki gibi Structure Checks, Argument Checks ve Max. Allowed Arguments kontrol edilir. Argument Checks kapalıysa analiz izin ve zorunluluk listesi önermez.

2

Adım 2 API trafiğini biriktir

Host grubu Learning modunda bırakılır ve API'nin gerçek ya da test istemcilerinden trafik gelmesi beklenir (WAF Mode). Host grubu Blocking ya da Monitor modundaysa yalnızca güvenilen test kaynaklarının trafiği Conditional Learning ile kaydedilir (Conditional Learning ile Teacher arasındaki fark nedir; hangisini ne zaman kullanmalıyım?).

3

Adım 3 Analiz penceresini aç

WAF Management sekmesinde host grubunun mod kartı altındaki Analysis & Learning yazısına tıklanır; New Analyze for başlıklı pencere açılır (yeni analiz oluşturma).

4

Adım 4 API'ye uygun seçenekleri seç

Alan	API için değer	Neden
Ignore Old Rules	Create New Rules (varsayılan)	Kural seti sıfırdan kurulur
Rule Creating Mode	Comprehensive (Each page is learned) (varsayılan Data based)	Her endpoint kendi sayfa tipini alır; Create New Rules ile birlikte Any Paths kuralının Allowed methods değeri None yapılır ve öğrenilmemiş her erişim ihlal olur (Rule Creating Mode seçenekleri (Comprehensive, Data Based, Page Independent) arasındaki fark nedir; hangisini seçmeliyim?)
Only Browsers	İşaret kaldırılır (varsayılan işaretli)	Tarayıcı olarak tanınmayan API ve mobil istemcilerin trafiği aksi hâlde analize hiç girmez ("Only Domains" ve "Only Browsers" filtreleri ne işe yarar?)
Country Filter	API istemcilerinin ülkeleri eklenir ya da No filter seçilir	Varsayılan Use Selected ile yalnızca Local Networks ve Turkey'dir; diğer ülkelerden gelen istekler analize girmez

Analyze Date varsayılan olarak son 3 aydır. Pencere, kullanıcının bu vService için daha önce başlattığı analizdeki seçimlerle (tarih aralığı, Rule Creating Mode, filtreler, Only Browsers) açılır; tablodaki varsayılanlar ilk analizde geçerlidir.

5

Adım 5 Analizi başlat

Start Analyzing tıklanır; pencere kapanır ve ilerleme mod kartındaki çubuktan izlenir.

6

Adım 6 Sonucu incele

Analiz bittiğinde mod kartındaki ev ikonuyla geçmiş analizler listesi açılır, analiz seçilip Edit ile Analyze Page Types sekmesi açılır ve üretilen endpoint'ler incelenir (Analiz sonucunu uygulamadan önce inceleyip düzenleyebilir miyim (Analyze Page Types ekranı)?).

7

Adım 7 Şüpheli path'leri analizden çıkar

Analiz sonucunda çıkan path'ler kontrol edilir; listede yalnız WAF kuralı oluşturulacak endpoint'ler kalmalıdır. Bilinmeyen ya da şüpheli path'lerin (ör. tarama araçlarının denediği adresler) analizden elle çıkarılması önerilir: bu path'ler Analyze Page Types ekranının sağ bölmesinde seçilip Exclude from Analysis tıklanır; çıkarılan path'ler kural üretmez.

8

Adım 8 Sonucu uygula

Analyze Page Types ekranındaki Apply tıklanır ve Are you sure? onaylanır; kurallar host grubuna yazılır. Uygulama, vService'in kalıcı Rule Creation Policy ayarını da seçilen moda eşitler.

Doğrulama

1Kural setiPage Types

Page Types listesinde endpoint başına kural, Any Paths satırının detay panelinin Path sekmesinde Allowed methods değeri okunur.

BeklenenEndpoint'ler listede · Any Paths: Allowed methods None

Yöntem 3: Page Types Ekranında Elle

• Nasıl çalışır Her endpoint için sayfa tipi eklenir, metotlar seçilir ve izin listeleri sekme sekme yazılır; Any Paths kuralı kapatılır.
• Nerede açılır Left Monitor Panel → WAF-Protected vServices → vService → WAF Management → N page types → Add · kurala tıklayınca açılan detay paneli
• Gereksinim Endpoint, metot ve parametre listesi; WAF alanında değiştirme yetkisi
• vService tipi HTTP

Adım adım yapılandırma

1

Adım 1 Checks ayarlarını kontrol et

Yöntem 1'in 1–2. adımlarındaki gibi Structure Checks, Argument Checks ve Max. Allowed Arguments kontrol edilir.

2

Adım 2 Page Types ekranını aç

WAF Management sekmesinde host grubunun mod kartı altındaki N page types satırına tıklanır.

3

Adım 3 Sayfa tipi formunu aç

Araç çubuğundaki Add tıklanır (Add).

4

Adım 4 Endpoint'i ve metotları gir

Path alanına endpoint yazılır: tek bir path için /api/v1/users, path parametresi taşıyan endpoint için /api/v1/users/* (glob'da * bir path segmentiyle eşleşir; sondaki / yazılmaz). Allowed Methods = Multiple Methods seçilip endpoint'in metotları (ör. GET, POST) işaretlenir; varsayılan Any Methods her metoda izin verir. OWASP kutusu varsayılan olarak işaretsizdir; path'in de imza taramasından geçmesi için işaretlenir (query, header ve gövde taraması bu kutudan bağımsızdır). Glob path'te formdaki test tablosuyla desen denenir (Yeni bir page type'ı elle nasıl eklerim?).

5

Adım 5 Sayfa tipini kaydet

Add tıklanır. Her endpoint için 3–5. adımlar tekrarlanır; dış izleme sistemlerinin yokladığı path'ler ve statik dosya path'leri de bu adımlarla eklenir.

6

Adım 6 Query ortak kuralını aç

Listede kurala tıklanır; sağda açılan detay panelinde Query sekmesi seçilip Add Common Rule for Query tıklanır (Add Common Rule for Query ekranı). Form Any Paths kuralının değerleriyle dolu açılır.

7

Adım 7 Query listelerini gir

Allowed Query Parameters kısıtı açılıp izin verilen parametre adları (ör. page, size) eklenir; zorunlu olanlar Required Query Parameters listesine yazılır. Ad eşleşmesi büyük/küçük harfe duyarlıdır (Bir sayfada yalnızca izin verdiğim query parametrelerinin gelmesini nasıl sağlarım (Allowed Query Parameters)?).

8

Adım 8 Query ortak kuralını kaydet

Formdaki Add tıklanır.

9

Adım 9 Header ortak kuralını ekle

Aynı panelde Header sekmesi seçilip Add Common Rule for Header tıklanır; API'nin her istekte beklediği header'lar (ör. authorization, x-api-key) Required Headers listesine yazılır ve Add tıklanır (Zorunlu parametre tanımlayabilir miyim (Required Query Parameters / Required Headers / Required Form Fields)?). Bu denetim header'ın varlığına bakar; değerini doğrulamaz.

10

Adım 10 JSON ortak kuralını ekle

JSON sekmesi seçilip Add Common Rule for JSON tıklanır; Allowed JSON Keys kısıtı açılıp gövdedeki anahtar yolları noktayla yazılır. İç içe yollarda kapsayıcı da listeye girer: {"user":{"email":"…"}} için user ve user.email. JSON Depth gibi sınırlar da burada daraltılır; Add tıklanır (JSON'da yalnızca belirli anahtarların gelmesine izin verebilir miyim; iç içe anahtar yolları nasıl yazılır?).

11

Adım 11 Any Paths kuralını düzenlemeye aç

Listede italik Any Paths satırı seçilip araç çubuğundaki Edit tıklanır.

12

Adım 12 Tanımsız endpoint'leri kapat

Allowed Methods = None seçilir.

13

Adım 13 Kaydet

Formdaki Edit tıklanır; ayrı bir dağıtım adımı yoktur. Cluster'da değişiklik varsayılan auto-sync ile eş cihaza gönderilir; Manual Sync Mode açıksa Synchronize ile gönderilir.

Doğrulama

1Beklenmeyen parametreMonitor modu · Event Logs

Listede olmayan bir query parametresiyle istek gönderilir ve Event Logs kaydının Attacks sekmesine bakılır.

Komut: curl -s -o /dev/null -w "%{http_code}\n" "https://api.example.com/api/v1/users/42?debug=1"

BeklenenAllowed query parameters (24)

2İzinsiz metotMonitor modu · Event Logs

Endpoint'e listede olmayan bir metotla istek gönderilir.

Komut: curl -s -o /dev/null -w "%{http_code}\n" -X DELETE https://api.example.com/api/v1/users/42

BeklenenAllowed methods (24)

Yöntem 4: WEB-CLI

• Nasıl çalışır Sayfa tipi waf fw-rules add ile, alan denetimleri waf rule-parts add ile yazılır. Komutlar vService, host grubu ve kural kimliklerini ister.
• Nerede açılır WEB-CLI → waf fw-rules · waf rule-parts
• Gereksinim WEB-CLI erişimi ve WAF alanında değiştirme yetkisi; Checks'te Structure Checks ve Argument Checks açık (Yöntem 1, 1. adım)
• vService tipi HTTP

Adım adım yapılandırma

1

Adım 1 Host grubunun kimliğini al

<vService> yerine vService'in kimliği yazılır; host grubunun kimliği çıktıdan okunur:

waf host-groups list poolId <vService>

2

Adım 2 Sayfa tipini ekle

Path zorunlu alandır; satıra başka -- alanları da yazıldığı için --path.input biçiminde yazılır ve * içeren değer tek tırnakla verilir. CLI'da seçilebilen metotlar GET, HEAD, OPTIONS, POST, PUT, PATCH, DELETE, TRACE ve CONNECT'tir. Path'in imza taraması --argOwasp ile açılır (varsayılan false):

waf fw-rules add poolId <vService> hostGroupId <grup> --path.input '/api/v1/users/*' --allowedMethods.type multiple --allowedMethods.input.0 GET --allowedMethods.input.1 POST --argOwasp true

Komut başarılı olduğunda çıktı vermez.

3

Adım 3 Kuralın kimliğini al

waf fw-rules list poolId <vService> hostGroupId <grup>

4

Adım 4 Query izin listesini ekle

<kural> yerine 3. adımdaki kimlik yazılır. --arg verilmediği için parça bölümdeki bütün parametrelere uygulanır:

waf rule-parts add poolId <vService> hostGroupId <grup> ruleId <kural> loc query --queryAllowedArgs.0 page --queryAllowedArgs.1 size

WEB-CLI'da yazılmayan alanlar şema varsayılanlarıyla kaydedilir ve bu sınırlar arayüzdeki formdan farklıdır: Query'de anahtar sayısı en fazla 16, anahtar uzunluğu 1–128, toplam boyut en fazla 8192, her değerin uzunluğu 0–1024'tür; daha uzun değer taşıyan endpoint'te --valueLength.val2 ile artırılır (loc query).

5

Adım 5 JSON izin listesini ekle

JSON parçasında Block All JSON Contents (--jsonBlockAll) WEB-CLI'da varsayılan olarak true gelir; JSON kabul eden bir endpoint için false yazılmazsa bu endpoint'e gelen bütün JSON istekleri ihlal olur. Diğer varsayılanlar: anahtar uzunluğu 1–32, değer sayısı (JSON Key Count) en fazla 1024, derinlik en fazla 8, her metin değerin uzunluğu 0–1024, Block Invalid JSON Contents açık:

waf rule-parts add poolId <vService> hostGroupId <grup> ruleId <kural> loc json --jsonBlockAll false --jsonAllowedArgs.0 user --jsonAllowedArgs.1 user.email

6

Adım 6 Any Paths kuralının kimliğini al ve kapat

3. adımdaki listede Any Paths kuralı default rule olarak görünür; kimliği okunur ve Allowed methods değeri none yapılır (update yalnızca yazılan alanı değiştirir):

waf fw-rules update poolId <vService> hostGroupId <grup> id <any-paths-kimliği> --allowedMethods.type none

Doğrulama

1ParçalarTR7 tarafı

Kuralın parçaları listelenir.

Komut: waf rule-parts list poolId <vService> hostGroupId <grup> ruleId <kural>

Beklenenquery ve json parçaları

Kurallar arayüzde Page Types listesinde de görünür.

Sık Yapılan Hatalar

Any Paths'i None yapıp yardımcı path'leri tanımlamamak

Allowed methods = None olan Any Paths kuralı, sayfa tipi olmayan her isteği ihlal sayar; Blocking modunda dış izleme sistemlerinin yokladığı path'ler, statik dosyalar ve dokümantasyon sayfaları da engellenir. Bu path'ler Any Paths kapatılmadan önce sayfa tipi olarak eklenir ve değişiklik önce Monitor modunda denenir (Monitor modunu false positive ayıklamak için nasıl kullanırım?).

• JSON listesinde kapsayıcı yolu unutmak. user.email için user da listede olmalıdır; listede olmayan her yol ayrı bir ihlal olur.
• Listenin Max. Allowed Arguments değerini aşması. Liste o kural için sessizce devre dışı kalır; Checks'teki değer en uzun listeden büyük tutulur.
• Learning modunda denetimlerin çalışmasını beklemek. İzin listeleri ve yapısal sınırlar yalnızca Monitor ve Blocking modlarında uygulanır.
• Analizde Only Browsers işaretini bırakmak. API ve mobil istemcilerin trafiği analize girmez; analiz yalnızca tarayıcı trafiğinden kural üretir.
• WEB-CLI'da --jsonBlockAll değerini yazmamak. Varsayılan true olduğu için endpoint'e gelen bütün JSON gövdeleri ihlal olur.
• Metot başına farklı gövde kuralı beklemek. Kural path başınadır; metot yalnızca Allowed methods ile kısıtlanır, aynı path'in POST ve PUT gövdeleri aynı listeyle denetlenir.
• Doğrudan Blocking moduna geçmek. Yeni kural seti önce Monitor modunda gerçek trafikle denenir (Learning modundan Monitor'a, Monitor'dan Blocking'e ne zaman geçmeliyim?).

Dokümantasyonda nasıl yapılır

• Add · Allowed Methods
• Import (OpenAPI) · İçe aktarma adımları
• Analysis & Learning · Rule Creating Mode
• JSON · Allowed JSON Keys
• WEB-CLI · waf rule-parts (JSON gövde)

İlgili sorular

• Negatif güvenlik modeli (imza tarama) ile pozitif güvenlik modeli arasındaki fark nedir?
• Rule Creating Mode seçenekleri (Comprehensive, Data Based, Page Independent) arasındaki fark nedir; hangisini seçmeliyim?
• JSON'da yalnızca belirli anahtarların gelmesine izin verebilir miyim; iç içe anahtar yolları nasıl yazılır?
• OpenAPI tanımımdan API koruma kurallarını otomatik oluşturabilir miyim?