JSON gövdeli API isteklerinde şema benzeri kontrol (anahtar listesi, derinlik, uzunluk) yapabilir miyim?

Kısa cevap

Evet; tam bir JSON Schema doğrulaması olarak değil, yapısal sınırlar olarak (JSON). Bir sayfa tipinin JSON sekmesindeki ortak kuralda izin verilen anahtar yolları (Allowed JSON Keys, user.email gibi noktalı tam yol; kapsayıcı yollar da listede olmalı), iç içe derinlik (JSON Depth), değer sayısı (JSON Key Count), anahtar adı uzunluğu (JSON Key Length), metin değer uzunluğu (JSON Value Length) ve deseni (JSON Value Pattern) tanımlanır. Çözümlenemeyen JSON Block Invalid JSON Contents ile, JSON kabul etmemesi gereken bir endpoint'e gelen her JSON gövdesi Block All JSON Contents ile engellenir. Tek bir alana özel uzunluk ve desen, Add Argument Rule for JSON ile açılan değişken kuralında verilir. Tip denetimi (sayı, boolean, dizi), zorunlu anahtar, dizi eleman sayısı, tekrar sınırı ve sayısal aralık denetimi yoktur; değer denetimleri yalnızca metin değerlere uygulanır. Gövde, Content-Type …/json ya da …+json türündeyse JSON olarak denetlenir. Her ihlal 24 puanlık yapısal ihlaldir ve yalnızca Monitor ile Blocking modlarında uygulanır. Any Paths kuralında Block Invalid JSON Contents varsayılan olarak kapalıdır.

Sorun: API Gövdesi Beklenmeyen Alanlar ve Biçimler Taşıyor

Bir API endpoint'i belirli bir JSON şekli bekler; ancak istemci beklenmeyen alanlar (ör. isAdmin), aşırı derin iç içe nesneler, çok sayıda değer ya da çok uzun metinler gönderebilir. Bu sapmalar imza taramasına takılmayabilir: mass assignment girişimleri, kaynak tüketen gövdeler ya da ayrıştırıcıyı zorlayan yapılar imza taşımaz. Sayfa tipinin JSON sekmesi bu sapmaların her birini 24 puanlık yapısal ihlal olarak işaretler; puan her koruma düzeyinin engelleme eşiğini tek başına aşar (engelleme eşiği).

Neler denetlenir, neler denetlenmez:

Denetim	Ne ölçer	Any Paths varsayılanı
Allowed JSON Keys	Listede olmayan her farklı yol (kapsayıcılar dahil) ihlaldir; büyük/küçük harfe duyarlı	Liste yok (kısıtsız)
JSON Depth	Her nesne ve dizi bir seviye: {"a":{"b":1}} = 2, {"a":[{"b":1}]} = 3	En fazla 64
JSON Key Count	Ağacın ucundaki değer sayısı; her dizi elemanı ayrı sayılır	En fazla 65536
JSON Key Length	Her anahtar adının (yolun son parçası) UTF-8 bayt uzunluğu	0–1024
JSON Value Length	Her metin değerin UTF-8 bayt uzunluğu	0–1048576
JSON Value Pattern	Metin değerin uyması gereken regex (pozitif desen)	Desen yok
Block Invalid JSON Contents	Çözümlenemeyen gövde	Kapalı (çözümlenemeyen gövde ham içerik olarak imza taramasından geçer)
Block All JSON Contents	Bu endpoint'e gelen her JSON gövdesi	Kapalı
Tip, zorunlu anahtar, dizi eleman sayısı, sayısal aralık, tekrar sınırı	-	Denetim yoktur

Çözüm: 3 Yöntem

Üç yöntem aynı JSON denetimlerini yazar. Ön koşul: vService'te WAF açıktır (Bir vService'te WAF korumasını nasıl etkinleştiririm?) ve endpoint için bir sayfa tipi vardır ya da eklenir (Yeni bir page type'ı elle nasıl eklerim?).

Durumunuz	Uygun yöntem
Arayüzden tanımlamak istiyorum	Yöntem 1: JSON sekmesi
Komut satırından tanımlamak istiyorum	Yöntem 2: WEB-CLI
API'nin OpenAPI tanımı var; üst düzey alan listesini oradan almak istiyorum	Yöntem 3: Import (OpenAPI)

Yöntem 1: JSON Sekmesi Önerilen

• Nasıl çalışır Ortak kural endpoint'e gelen bütün JSON gövdesine, değişken kuralı tek bir anahtar yoluna uygulanır. Bir yolun değişken kuralı varsa o yolun değer denetimleri yalnızca bu kuraldan alınır.
• Nerede açılır Left Monitor Panel → WAF-Protected vServices → vService → WAF Management → host grubunun mod kartındaki N page types → kural → detay panelinde JSON sekmesi
• Gereksinim Checks'te Structure Checks ve Argument Checks açık; 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. Allowed JSON Keys için Argument Checks, diğer sınırlar ve Block Invalid JSON Contents için Structure Checks işaretli olmalıdır; Block All JSON Contents bu anahtarlardan bağımsızdır. Listede Max. Allowed Arguments değerinden (varsayılan 25) fazla yol olacaksa değer artırılır ve Edit tıklanır.

2

Adım 2 Kuralın JSON sekmesini aç

WAF Management sekmesinde host grubunun mod kartı altındaki N page types satırına tıklanır; listede endpoint'in kuralına tıklanır ve sağdaki detay panelinde JSON sekmesi seçilir (ekrana erişim). Tablonun sonunda Rule Source satırı varsa değerler Any Paths ya da bir glob kuraldan devralınıyordur.

3

Adım 3 Ortak kural formunu aç

Add Common Rule for JSON tıklanır; kuralın kendi JSON denetimi zaten varsa aynı yerde Edit Common Rule for JSON görünür. Form Any Paths kuralının değerleriyle dolu açılır (Add Common Rule for JSON ekranı).

4

Adım 4 Sınırları gir

Örnek gövde {"order":{"id":"A1","items":[{"sku":"X","qty":2}]}} için:

• Allowed JSON Keys kısıtı açılıp order, order.id, order.items, order.items.sku, order.items.qty yolları 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?).
• JSON Depth = Less Than or Equal To 4 (örnekte en dıştaki nesne, order nesnesi, items dizisi ve dizideki nesne dört seviyedir) (JSON / XML iç içe derinliğini sınırlayabilir miyim?).
• JSON Key Count, JSON Key Length ve JSON Value Length endpoint'in beklediği en büyük değerlere göre daraltılır.
• Block Invalid JSON Contents işaretlenir (Bozuk (parse edilemeyen) JSON / XML / form gövdelerini engelleyebilir miyim?).

5

Adım 5 Ortak kuralı kaydet

Formdaki Add (düzenlemede Edit) tıklanır; ayrı bir dağıtım adımı yoktur ve kayıtla birlikte bu kural için devralma sona erer.

6

Adım 6 Değişken kuralı formunu aç

Tek bir alana özel sınır gerekiyorsa aynı sekmedeki Add Argument Rule for JSON tıklanır.

7

Adım 7 Alanı ve sınırını gir

Argument Name alanına tam yol yazılır (ör. order.id); yalnızca son parça (id) iç içe anahtarı yakalamaz. JSON Value Length ve JSON Value Pattern girilir; desen değerin her yerinde aranır, tam eşleşme için ^[A-Z][0-9]{1,8}$ gibi ^ ve $ ile sınırlanır (Bir parametrenin değerini uzunluk veya regex desenle kısıtlayabilir miyim (Value length / Value pattern)?). Form ön-dolu gelir; kayıttan sonra boş bırakılan alan ortak kuraldan devralınmaz, kısıt yok demektir.

8

Adım 8 Değişken kuralını kaydet

Formdaki Add tıklanır. Değişken kuralı yolu Allowed JSON Keys listesine eklemez; yol listede ayrıca bulunmalıdı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

1Fazladan anahtarMonitor modu · Event Logs

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

Komut: curl -s -o /dev/null -w "%{http_code}\n" -H "Content-Type: application/json" -d '{"order":{"id":"A1","isAdmin":"true"}}' https://api.example.com/api/v1/orders

BeklenenAllowed JSON keys · order.isAdmin (24)

Monitor modunda istek geçirilir; Blocking modunda engellenir. Learning modunda bu denetimler çalışmaz.

2Detay paneliPage Types

Kuralın JSON sekmesinde ortak kural ve değişken tablosu okunur.

BeklenenGirilen sınırlar; Rule Source satırı yok

Yöntem 2: WEB-CLI

• Nasıl çalışır JSON ortak kuralı ve değişken kuralı waf rule-parts add … loc json ile yazılır; --arg verilmezse parça bütün gövdeye, verilirse o yola uygulanır.
• Nerede açılır WEB-CLI → waf rule-parts
• Gereksinim WEB-CLI erişimi ve WAF alanında değiştirme yetkisi; vService, host grubu ve kural kimlikleri; 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 Kimlikleri al

Host grubunun kimliği waf host-groups list poolId <vService>, kuralın kimliği şu komutun çıktısından okunur:

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

2

Adım 2 Ortak kuralı ekle

WEB-CLI'da JSON parçasının varsayılanları arayüzdeki formdan farklıdır: Block All JSON Contents (--jsonBlockAll) ve Block Invalid JSON Contents true, anahtar uzunluğu 1–32, derinlik en fazla 8, değer sayısı en fazla 1024, her metin değerin uzunluğu 0–1024 gelir; daha uzun metin değer taşıyan endpoint'te --valueLength.val2 ile artırılır. JSON kabul eden bir endpoint için --jsonBlockAll false yazılır:

waf rule-parts add poolId <vService> hostGroupId <grup> ruleId <kural> loc json --jsonBlockAll false --jsonAllowedArgs.0 order --jsonAllowedArgs.1 order.id --jsonAllowedArgs.2 order.items --jsonAllowedArgs.3 order.items.sku --jsonAllowedArgs.4 order.items.qty --jsonDepth.op "<=" --jsonDepth.val 4

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

3

Adım 3 Değişken kuralını ekle

$ içeren desen tırnak içinde yazılır:

waf rule-parts add poolId <vService> hostGroupId <grup> ruleId <kural> loc json --arg order.id --valueLength.op - --valueLength.val 1 --valueLength.val2 9 --argRegex.input '^[A-Z][0-9]{1,8}$'

Doğrulama

1ParçalarTR7 tarafı

Kuralın parçaları listelenir.

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

Beklenenloc json parçaları: bütün gövde ve order.id

Yöntem 3: Import (OpenAPI)

• Nasıl çalışır Gövde şemasının en üst düzey alan adları Allowed JSON Keys listesine, alanların maxLength, pattern ve enum kısıtları değişken kurallarına yazılır. İç içe yollar üretilmez.
• Nerede açılır Left Monitor Panel → WAF-Protected vServices → vService → WAF Management → N page types → 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 Page Types ekranını aç ve yedek al

WAF Management sekmesinde N page types satırına tıklanır ve araç çubuğundaki Export ile kural setinin yedeği alınır.

2

Adım 2 Tanımı içe aktar

Araç çubuğundaki Import (OpenAPI) tıklanır, dosya seçilir ve Are you sure? sorusu Yes ile onaylanır.

3

Adım 3 İç içe yolları tamamla

Üretilen kuralda Yöntem 1'in 2–5. adımlarıyla Allowed JSON Keys listesine iç yollar eklenir ve derinlik, değer sayısı gibi sınırlar daraltılır. Ayrıntılar: OpenAPI tanımımdan API koruma kurallarını otomatik oluşturabilir miyim?

Doğrulama

1Alan listesiPage Types

Kuralın JSON sekmesinde Allowed JSON Keys listesi okunur.

BeklenenÜst düzey alanlar ve elle eklenen iç yollar

Sık Yapılan Hatalar

• Kapsayıcı yolu listeye eklememek. order.items.sku için order ve order.items da listede olmalıdır; listede olmayan her kapsayıcı ayrı bir ihlal üretir.
• Yalnızca son parçayı yazmak. Değişken kuralında sku yazılırsa order.items.sku yakalanmaz; tam yol yazılır.
• Sayı alanına uzunluk ya da desen koymak. JSON değer denetimleri yalnızca metin değerlere uygulanır; "qty": 2 gibi sayı ve true gibi boolean değerler denetlenmez.
• Content-Type'ı denetlememek. Gövde …/json ya da …+json türünde bir Content-Type ile gelmiyorsa JSON denetimleri çalışmaz; gövde ham içerik olarak taranır (API'mden gelen JSON istekleri "Block Invalid JSON Contents" kuralıyla engelleniyor; neden?).
• WEB-CLI'da --jsonBlockAll false yazmamak. Varsayılan true olduğu için endpoint'e gelen bütün JSON gövdeleri ihlal olur.
• Listenin Max. Allowed Arguments değerini aşması. Liste o kural için uyarı vermeden devre dışı kalır.
• Learning modunda denetimlerin çalışmasını beklemek. JSON sınırları yalnızca Monitor ve Blocking modlarında uygulanır.

Dokümantasyonda nasıl yapılır

• JSON · JSON nedir?
• JSON · Allowed JSON Keys
• JSON · JSON Depth
• Path Check Fields · İki katman
• WEB-CLI · waf rule-parts (JSON gövde)

İlgili sorular

• JSON / XML iç içe derinliğini sınırlayabilir miyim?
• JSON'da yalnızca belirli anahtarların gelmesine izin verebilir miyim; iç içe anahtar yolları nasıl yazılır?
• Bozuk (parse edilemeyen) JSON / XML / form gövdelerini engelleyebilir miyim?
• Bir sayfada JSON veya XML gövdesini tamamen yasaklayabilir miyim (Block All JSON Contents / Block All XML Contents)?