OpenAPI tanımımdan API koruma kurallarını otomatik oluşturabilir miyim?

Kısa cevap

Evet. Page Types ekranındaki Import (OpenAPI), OpenAPI 3.0 ya da Swagger 2.0 tanımını (.json, .yaml, .yml) okuyup her path için bir sayfa tipi üretir (belgenin kurallara dönüştürülmesi): {id} gibi şablonlar glob'a (/users/*), operasyonlar Allowed Methods listesine, query ve header parametreleri izin listelerine, bütün operasyonlarda zorunlu olan parametreler zorunluluk listelerine, uzunluk, desen ve sabit değer listesi kısıtları değer denetimlerine, gövde şemasının alan adları JSON, XML ya da form izin listesine dönüşür. İçe aktarma mevcut kurallarla birleştirilir; aynı path'li kural belgedekiyle değiştirilir, diğer kurallar korunur; üçüncü taraf bir belgede Any Paths kuralı da korunur (TR7'nin Export (OpenAPI) ile ürettiği belge Any Paths kuralını da değiştirir). API koruması açısından üç sınır vardır: JSON ve XML gövdede yalnızca en üst düzey alan adları listeye yazılır, iç içe yollar listede olmadığı için ihlal sayılır ve elle eklenir; JSON ve XML için zorunlu alan üretilmez; tanımsız endpoint'ler Any Paths ile denetlenmeye devam eder, reddedilmeleri için Any Paths kuralının Allowed methods değeri ayrıca None yapılır. Bu yüzden içe aktarmadan önce Export ile yedek alınır, sonra kurallar Monitor modunda gerçek trafikle denenir. WEB-CLI'da OpenAPI içe aktarma komutu yoktur.

Sorun: API Tanımı Hazır, Kural Seti Elle Yazılmak İstenmiyor

API'nin endpoint, metot ve parametre listesi OpenAPI tanımında zaten yazılıdır. Bu listeyi trafikten öğrenmek zaman alır ve az kullanılan endpoint'leri kaçırabilir; elle yazmak ise hata riski taşır. Import (OpenAPI), pozitif güvenlik modelini trafiğin öğrenilmesini beklemeden doğrudan belgeden kurar (kullanım senaryoları). Ekranın genel kullanımı ve dönüşüm ayrıntıları OpenAPI / Swagger dosyamdan otomatik kural üretebilir miyim? sayfasındadır; bu sayfa içe aktarılan kural setinin API'yi gerçekten koruyacak hâle getirilmesini anlatır.

Belgeden neyin üretildiği:

Belgedeki öğe	Üretilen kural	Not
Path (/pet/{petId})	Sayfa tipi (/pet/*, glob)	servers ön eki path'e eklenmez
Operasyonlar (get, post…)	Allowed Methods = Multiple Methods	Belgede olmayan metotlar ihlal olur
Query ve header parametreleri	Allowed Query Parameters, Allowed Headers	Path ve cookie parametreleri yok sayılır
required: true parametre	Required Query Parameters, Required Headers	Yalnızca path'in bütün operasyonlarında zorunluysa
minLength, maxLength, pattern, enum, sayı tipleri	Değişken kuralında değer uzunluğu ve değer deseni	Desteklenmeyen regex özellikleri düşürülür ve uyarı verilir
JSON, XML ya da form gövde şeması	Allowed JSON Keys, Allowed XML Keys, Allowed Form Fields	Yalnızca şemanın en üst düzey alan adları; zorunluluk yalnızca form için
Yeni her kural	Path length 1–8192, Path depth ≤ 256, OWASP açık	Varsayılan path kısıtları

Çözüm

İçe aktarma tek adımdır; ardından üç tamamlama yapılır: iç içe JSON yolları eklenir, tanımsız endpoint'ler kapatılır ve kural seti Monitor modunda denenir. İşlemin ön koşulu vService'te WAF'ın açık olması (Bir vService'te WAF korumasını nasıl etkinleştiririm?) ve API ayrı bir alan adındaysa kendi host grubunun bulunmasıdır (Host Group nasıl eklenir; Virtual Host Patterns alanına ne yazılır?).

Import (OpenAPI) ve Tamamlama

• Nasıl çalışır Belge sayfa tiplerine dönüştürülür ve mevcut kurallarla birleştirilir; ardından belgeden üretilemeyen denetimler elle tamamlanır.
• 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ı; 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 Checks kartının kalem ikonu tıklanır. Structure Checks ve Argument Checks işaretli olmalıdır. Belgedeki en uzun parametre ya da alan listesi Max. Allowed Arguments değerini (varsayılan 25) aşıyorsa değer artırılır; aşan liste o kural için sessizce devre dışı kalır. Değişiklik yapıldıysa Edit tıklanır.

2

Adım 2 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 (ekrana erişim).

3

Adım 3 Yedek al

Araç çubuğundaki Export tıklanır; kural seti JSON dosyası olarak iner. Belgedeki path'lerle aynı path'li kurallar değiştirileceği için tek geri dönüş yolu bu yedektir (operasyonel en iyi uygulamalar).

4

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

Araç çubuğundaki Import (OpenAPI) tıklanır ve dosya seçiciden tanım dosyası seçilir.

5

Adım 5 İçe aktarmayı onayla

Are you sure? sorusu Yes ile onaylanır (içe aktarma adımları). Sonuçta "OpenAPI import: N path applied" bildirimi görünür; uyarı varsa (düşürülen regex desenleri, operasyonu olmayan path'ler) bildirimde listelenir ve okunur. Dosya çözümlenemezse ya da bir desen desteklenmiyorsa içe aktarmanın tamamı reddedilir ve mevcut kurallar değişmez (doğrulama ve hatalar).

6

Adım 6 İç içe gövde taşıyan kuralı aç

Gövdesinde iç içe nesne bulunan endpoint'in kuralına tıklanır; sağdaki detay panelinde JSON sekmesi seçilip Edit Common Rule for JSON tıklanır (JSON ortak kuralı).

7

Adım 7 İç yolları listeye ekle

Allowed JSON Keys listesine iç yollar noktayla eklenir. Örneğin {"user":{"name":"…","email":"…"}} gövdesi için içe aktarma yalnızca user yazar; user.name ve user.email eklenir. Dizi indisi yolu uzatmaz (JSON'da yalnızca belirli anahtarların gelmesine izin verebilir miyim; iç içe anahtar yolları nasıl yazılır?). XML gövdelerde aynı tamamlama XML sekmesinde yapılır.

8

Adım 8 JSON kuralını kaydet

Formdaki Edit tıklanır. İç içe gövde taşıyan her endpoint için 6–8. adımlar tekrarlanır.

9

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

Listede italik Any Paths satırı seçilip araç çubuğundaki Edit tıklanır. Üçüncü taraf bir belge Any Paths kuralını değiştirmez.

10

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

Allowed Methods = None seçilir. Belgede olmayan ama erişilmesi gereken path'ler (dokümantasyon, dış izleme sistemlerinin yokladığı path'ler) önce kendi sayfa tipleriyle eklenir (API için pozitif güvenlik modelini (izin verilen endpoint, metot, parametre) nasıl kurarım?).

11

Adım 11 Any Paths'i kaydet

Formdaki Edit tıklanır; WAF yapılandırması yeniden üretilip uygulanır.

12

Adım 12 Host grubunu Monitor moduna al

WAF Management sekmesinde host grubunun mod kartında, başlık şeridinin sağ alt köşesindeki Edit yazısı tıklanır, WAF Mode = Monitor Mode seçilir ve Edit ile kaydedilir. Event Logs'ta meşru istekler için ihlal kalmadığında aynı yoldan Blocking Mode seçilir (Learning modundan Monitor'a, Monitor'dan Blocking'e ne zaman geçmeliyim?). Cluster'da değişiklikler 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 belgedeki path'ler görünür; şablonlu path'ler glob olarak vurgulanır. Kuralın detay panelindeki Path, Query, Header ve JSON sekmelerinde metot ve izin listeleri okunur.

BeklenenPath başına bir kural; mod kartında N page types arttı

2Meşru trafikMonitor modu · Event Logs

Monitor süresince API'nin gerçek istekleri için Event Logs kayıtlarının Attacks sekmesine bakılır.

BeklenenAllowed JSON keys, Allowed query parameters ve Allowed methods kaydı yok

Kayıt varsa ihlal satırı listede eksik kalan yolu ya da parametreyi gösterir; ilgili liste tamamlanır ya da kayıt Allow / Teach ile öğretilir.

Sık Yapılan Hatalar

İçe aktarmadan sonra doğrudan Blocking moduna geçmek

İç içe JSON ve XML yolları listede olmadığı için iç içe gövde gönderen meşru istekler 24 puanlık Allowed JSON Keys ihlali üretir ve Blocking modunda engellenir. Kural seti önce Monitor modunda denenir.

• Any Paths'in de daraldığını sanmak. Üçüncü taraf bir belge Any Paths kuralına dokunmaz; belgede olmayan endpoint'ler Any Paths ile denetlenmeye devam eder.
• JSON gövdede zorunlu alan beklemek. Zorunluluk yalnızca query, header ve form için üretilir; JSON ve XML için zorunlu anahtar denetimi yoktur.
• Sayı tipindeki alanlara desen denetimi beklemek. Sayı ve boolean tipleri için üretilen değer deseni JSON'daki sayı ve boolean değerlere uygulanmaz; JSON değer denetimleri yalnızca metin değerlere uygulanır.
• Geniş şemalarda Max. Allowed Arguments'ı artırmamak. Listesi bu sınırı aşan kuralın izin listesi uyarı vermeden devre dışı kalır.
• Export yedeği almamak. Aynı path'li kurallardaki elle yapılmış özelleştirmeler içe aktarmayla kaybolur; geri alma adımı yoktur.
• Eski bir tanım kullanmak. Kaldırılmış endpoint'ler için kural üretilir, yeni endpoint'ler kapsanmaz; belge her API sürümünde yeniden içe aktarılır. Aynı belgenin tekrar içe aktarılması kopya kural üretmez.

Dokümantasyonda nasıl yapılır

• Import (OpenAPI) · Belgenin kurallara dönüştürülmesi
• Import (OpenAPI) · İçe aktarma adımları
• Import (OpenAPI) · Operasyonel en iyi uygulamalar
• JSON · Allowed JSON Keys

İlgili sorular

• OpenAPI / Swagger dosyamdan otomatik kural üretebilir miyim?
• Import yaptığımda mevcut kurallar ne olur (tam değiştirme)?
• JSON'da yalnızca belirli anahtarların gelmesine izin verebilir miyim; iç içe anahtar yolları nasıl yazılır?
• API için pozitif güvenlik modelini (izin verilen endpoint, metot, parametre) nasıl kurarım?