Import (OpenAPI)

Import (OpenAPI) Nedir?

Import (OpenAPI), bir OpenAPI veya Swagger tanım dosyasından sayfa tipleri (WAF kuralları) üretir. İki tipik kullanım vardır:

• Uygulamanın kendi API tanımından koruma kurmak: Uygulama ekibinin sağladığı OpenAPI belgesi içe aktarılır; belgedeki her path, metot listesi ve parametre şemalarıyla birlikte bir sayfa tipine dönüştürülür. Böylece pozitif güvenlik modeli, trafiğin öğrenilmesini beklemeden doğrudan API dokümanından kurulur.
• TR7 çıktısını geri yüklemek: Export (OpenAPI) ile alınmış bir belge içe aktarıldığında kurallar, belgenin TR7'ye özel bölümünden kayıpsız olarak geri yüklenir (Any Paths dahil).

İçe aktarma birleştirmedir, aynı path'li kural değiştirilir

Import mevcut kural setini tümüyle değiştirirken, Import (OpenAPI) birleştirme yapar: belgede yer almayan mevcut kurallara dokunulmaz. Belgedeki her path için ise aynı path'li bir kural varsa bu kural, belgeden türetilen kuralla tümüyle değiştirilir (üzerindeki elle yapılmış özelleştirmeler kaybolur); yoksa yeni kural olarak eklenir.

İçe Aktarma Adımları

1. Araç çubuğundaki Import (OpenAPI) butonuna tıklanır ve açılan dosya seçiciden tanım dosyası seçilir; .json, .yaml ve .yml dosyaları kabul edilir.
2. "Are you sure?" onay sorusu Yes butonuyla onaylanır; No seçilirse hiçbir değişiklik yapılmaz.
3. Dosya yüklenir ve dönüştürülür. İşlem sürerken buton simgesi dönen bir simgeye dönüşür ve araç çubuğundaki diğer işlemler geçici olarak pasifleşir.

İşlem sonunda kaç path'in uygulandığını ve varsa dönüştürme uyarılarını özetleyen bir bildirim gösterilir: "OpenAPI import: N path applied" (uyarı varsa "— k warning(s): ..." ekiyle ve turuncu renkte; bildirimde en fazla ilk sekiz uyarı listelenir). Ek bir dağıtım (deploy) adımı yoktur; WAF yapılandırması otomatik olarak yeniden üretilip uygulanır ve mod kartındaki N Page Types sayısı yeni path'lerle birlikte artar.

Belgenin Kurallara Dönüştürülmesi

• Kabul edilen biçimler: OpenAPI 3.0 (JSON veya YAML) ve Swagger 2.0 (içe aktarımda otomatik olarak 3.0'a yükseltilir).
• Path şablonları: {petId} gibi şablon parametreleri, tek path segmentiyle eşleşen * glob karakterine çevrilir; kural listede glob kuralı olarak yer alır. Örneğin /pet/{petId} belgesi /pet/* kuralına dönüşür.
• Sunucu adresleri: Belgedeki servers adresleri path'lere ön ek olarak uygulanmaz; path'ler belgede yazıldığı gibi alınır.
• Metotlar: Path'in operasyonları, kuralın Allowed Methods listesine dönüşür.
• Parametreler ve gövde: Sorgu ve başlık parametreleri Check Fields izin listelerine yazılır; tüm operasyonlarda required olan parametreler zorunlu alan olur. Şema kısıtları (uzunluk, desen, sabit değer listesi, sayı tipleri) alan denetimlerine çevrilir. Gövde şemalarından form, JSON ve XML içerik türleri işlenir; diğer içerik türleri ve cookie parametreleri yok sayılır.
• Varsayılan kısıtlar: Belgeden üretilen her yeni kural, varsayılan path kısıtlarıyla oluşturulur: Path Length 1–8192, Path Depth ≤ 256, OWASP taraması açık.
• Any Paths: Üçüncü parti bir belge Any Paths (catch-all) kuralına dokunmaz. Belge bir TR7 çıktısıysa, belgede taşınan Any Paths yapılandırması hedef grubunkinin yerine geçer.

Yeniden içe aktarma güvenlidir

Aynı belgenin tekrar içe aktarılması kopya kural üretmez; path'ler mevcut karşılıklarının yerine geçer ve sonuç aynı kalır.

Doğrulama ve Hatalar

• Dosya OpenAPI/YAML olarak çözümlenemiyorsa içe aktarma, ayrıştırıcının döndürdüğü hata metniyle reddedilir ve mevcut kural seti değişmez.
• Belgedeki bir alan deseni WAF motoru tarafından desteklenmiyorsa içe aktarmanın tamamı "Invalid WAF pattern (...)" hatasıyla reddedilir; mevcut kural seti değişmez.
• Desteklenmeyen regex özellikleri (geriye başvuru, ileri/geri bakış) içeren şema desenleri kural üretiminde düşürülür ve sonuç bildiriminde uyarı olarak listelenir; ilgili alan, izin listesinde desensiz olarak yine yer alır.
• Operasyonu olmayan path'ler atlanır ve uyarı olarak bildirilir.

Operasyonel En İyi Uygulamalar

• İçe aktarmadan önce yedek alınmalı. Belgedeki path'lerle aynı path'li mevcut kurallar değiştirileceğinden, öncesinde Export ile alınan yedek tek geri dönüş yoludur.
• Uygulamanın güncel API tanımı kullanılmalı. Eski bir tanım, kaldırılmış uç noktalar için kural üretir ve yeni uç noktaları kapsamaz; tanımda yer almayan path'lere gelen istekler Any Paths kuralıyla denetlenmeye devam eder.
• Sonuç bildirimi ve üretilen kurallar gözden geçirilmeli. İçe aktarma sonrasında uyarılar (özellikle düşürülen desenler) okunmalı ve üretilen kurallar listede kontrol edilmelidir; gerekli ince ayarlar Edit ile yapılır.