API istemcileri için HTML yerine JSON engelleme yanıtı dönebilir miyim?

Kısa cevap

Evet. Yalnızca API istekleri JSON alsın isteniyorsa API isteklerini ayıran bir koşul (ör. path /api/ ile başlar) ile Blocking Page penceresindeki Conditional Blocking Pages listesine application/json türünde bir Content Pages profili ve isteğe göre ayrı bir durum kodu (ör. 403) eklenir; diğer istekler HTML sayfayı almaya devam eder. Bütün engelleme yanıtlarının JSON olması yeterliyse Ready-made Templates altındaki JSON default blocking page şablonu kaynağı Manual content, türü application/json yapar, gövdeye {"attackInfo": %WAF_INFO} koyar ve mevcut koşullu sayfaları kaldırır. %WAF_INFO saldırı ayrıntısını (varsayılan olarak imza kimliği, saldırı alanı, puan ve izleme durumu) yanıta yazar; ayrıntının istemciye gösterilmesi istenmiyorsa gövdede yalnızca %UID gibi bir istek kimliği bırakılır. Ayar Edit ile kaydedilir.

Sorun: API İstemcileri Engellemede HTML Gövde Alıyor

API istemcileri ve mobil uygulamalar HTML engelleme sayfasını ayrıştıramaz; hata işleyicileri için yapısal (JSON) bir gövde ve beklenen bir durum kodu gerekir.

Çözüm: Üç Yöntem

Durumunuz	Uygun yöntem
Yalnızca API istekleri JSON alsın, diğerleri HTML	Yöntem 1: Koşullu JSON sayfası
Bütün engelleme yanıtları JSON olsun	Yöntem 2: JSON şablonu
Varsayılan engelleme yanıtını betik ya da komut satırıyla JSON yapacağım (koşullu sayfalar kalır)	Yöntem 3: WEB-CLI

Yöntem 1: Koşullu JSON Sayfası Önerilen

• Nasıl çalışır API isteklerini ayıran koşula JSON sayfa profili ve durum kodu bağlanır; koşula uymayan istekler varsayılan sayfayı alır.
• Nerede açılır Content Pages · Conditions · Blocking Page kartı → kalem ikonu → Conditional Blocking Pages
• Gereksinimapplication/json türünde bir Content Pages profili ve API isteklerini ayıran bir istek koşulu (Content Pages ve Conditions ekranlarında ekleme Load Balancer alanında değiştirme yetkisi ister)
• Sınır En fazla beş koşullu sayfa

Adım adım yapılandırma

1

Adım 1 Sayfa formunu aç

Load Balancer → Profiles → Content Pages ekranında Add tıklanır (nasıl eklenir).

2

Adım 2 JSON sayfasını tanımla

Content Page Name verilir, Content Type alanına application/json yazılır ve Content alanına gövde girilir:

{"error":"blocked","requestId":"%UID"}

3

Adım 3 Sayfayı kaydet

Add tıklanır; sayfa profil listesine eklenir.

4

Adım 4 Koşul formunu aç

Load Balancer → Conditions ekranında Add tıklanır (nasıl eklenir).

5

Adım 5 API koşulunu tanımla

Criteria = Path seçilir; etiketsiz eşleştirme yöntemi listesinde Start seçilir ve Query alanına /api/ yazılır. API'ler path ile ayrılmıyorsa HTTP Header koşulu (ör. Accept başlığı Includes application/json) kullanılır.

6

Adım 6 Koşulu kaydet

Add tıklanır; koşul listeye eklenir.

7

Adım 7 Blocking page penceresini aç

Left Monitor Panel → WAF-Protected vServices → vService → WAF Management sekmesinde Inspection & Blocking bölümündeki Blocking page kartının sağ üstündeki kalem ikonuna tıklanır.

8

Adım 8 Koşullu sayfa ekle

Conditional Blocking Pages altında Add Conditional Page tıklanır; CONDITIONAL PAGE #n başlıklı yeni girdi açılır.

9

Adım 9 Koşulu seç

Girdideki Condition alanında (boşken Select conditions yazar) 6. adımdaki koşul seçilir.

10

Adım 10 Sayfayı seç

Page Profile alanında 3. adımdaki JSON sayfası seçilir.

11

Adım 11 Durum kodunu seç

Status Code alanında 403 seçilir; Use Default Status Code bırakılırsa girdi Blocking Status Code değerini kullanır.

12

Adım 12 Kaydet

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

Doğrulama

1Blocking page kartıTR7 tarafı

WAF Management sekmesindeki Blocking page kartında koşullu sayfa satırına bakılır.

Beklenen<koşul> → the <JSON sayfası> page is shown (403)

2API isteğiİstemci tarafı

Blocking modundaki host grubuna API path'inde imza tetikleyen istek gönderilir.

Komut: curl -i "https://www.example.com/api/items?q=%3Cscript%3Ealert(1)%3C/script%3E"

BeklenenHTTP 403 · content-type: application/json; charset=utf-8 · {"error":"blocked","requestId":"…"}

Aynı istek /api/ dışındaki bir path'e gönderildiğinde varsayılan HTML sayfa döner.

Yöntem 2: JSON Şablonu

• Nasıl çalışır Varsayılan engelleme yanıtı JSON olur; şablon mevcut koşullu sayfaları kaldırdığı için bütün engellemeler bu gövdeyi alır.
• Nerede açılırBlocking Page kartı → kalem ikonu → Ready-made Templates → JSON Default Blocking Page
• Gereksinim WAF açık HTTP vService
• Kapsam Mevcut koşullu sayfalar kaldırılır

Adım adım yapılandırma

1

Adım 1 Blocking page penceresini aç

Left Monitor Panel → WAF-Protected vServices → vService → WAF Management → Blocking Page kartının sağ üstündeki kalem ikonuna tıklanır.

2

Adım 2 Şablonu seç

Ready-made Templates altındaki JSON Default Blocking Page şablonuna tıklanır.

3

Adım 3 Onayla

Apply "JSON default blocking page"? onayı kabul edilir. Formda koşullu sayfa varsa onayın altında This replaces the current blocking page settings, including the N conditional page(s) below. yazar; onayla bu girdiler listeden kalkar. Blocking Page Source Manual Content, Blocking Page Content Type application/json olur ve Blocking Page alanına {"attackInfo": %WAF_INFO} gelir.

4

Adım 4 Gövdeyi düzenle (gerekiyorsa)

Saldırı ayrıntısının istemciye gösterilmesi istenmiyorsa Blocking Page alanındaki gövde {"error":"blocked","requestId":"%UID"} olarak değiştirilir (Engelleme sayfasında hangi Smart Variable'ları kullanabilirim (%UID, %SRCIP, %WAFSCORE, %WAFINFO …); saldırı detayını göstermek güvenli mi?).

5

Adım 5 Durum kodunu seç (gerekiyorsa)

Blocking Status Code listesinden 403 seçilir; şablon kodu değiştirmez.

6

Adım 6 Kaydet

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

Doğrulama

1Blocking page kartıTR7 tarafı

WAF Management sekmesindeki Blocking page kartının cümlesine bakılır.

BeklenenA blocked client gets the inline content (application/json) with status 403

Yöntem 3: WEB-CLI

• Nasıl çalışır Kaynak, içerik türü, gövde ve kod WEB-CLI ile yazılır; varsayılan yanıt Yöntem 2'deki gibi JSON olur, ancak komut yalnızca yazılan alanları değiştirdiği için mevcut koşullu sayfalar kalır.
• Nerede açılır WEB-CLI → waf options update
• Gereksinim WEB-CLI erişimi
• Kapsam Varsayılan engelleme yanıtı; koşullu JSON sayfası komutla eklenirken Ziyaretçinin diline göre engelleme sayfası gösterebilir miyim? sayfasındaki WEB-CLI adımları izlenir

Adım adım yapılandırma

1

Adım 1 JSON yanıtı yaz

--blockingContentSource null kaynağı Manual Content yapar; kaynak Content Profile kalırsa yazılan gövde kullanılmaz. Komut çıktı vermez:

waf options update poolId <vService> --syncWithDefaultFwRules false --blockingContentSource null --blockingContentType application/json --blockingContent '{"error":"blocked","requestId":"%UID"}' --blockingStatusCode 403

Doğrulama

1Ayar kaydıTR7 tarafı

vService'in WAF ayarları görüntülenir.

Komut: waf options show poolId <vService>

BeklenenblockingContentType application/json · blockingStatusCode 403

Kartta Yöntem 2'deki cümle görünür.

Sık Yapılan Hatalar

• Dış API'de %WAF_INFO döndürmek. Yanıt, isteği yakalayan imzanın kimliğini, saldırı alanını, puanı ve ayara göre saldırı desenini istemciye gösterir; dış istemciler için istek kimliği (%UID) yeterlidir (Engelleme sayfasında hangi Smart Variable'ları kullanabilirim (%UID, %SRCIP, %WAFSCORE, %WAFINFO …); saldırı detayını göstermek güvenli mi?).
• JSON gövdeyle 418 bırakmak. 418 standart bir hata kodu değildir; API istemcilerinin hata işleyicileri çoğunlukla 403 ya da 400 bekler.
• Koşul olarak yalnızca Accept başlığına güvenmek. Accept başlığı göndermeyen istemciler koşula uymaz ve HTML sayfa alır; API'ler path ile ayrılabiliyorsa Path koşulu tercih edilir.
• Koşullu sayfalar varken JSON şablonunu uygulamak. Şablon mevcut koşullu sayfaların hepsini kaldırır; Yöntem 1 ile kurulmuş girdiler korunacaksa şablon kullanılmaz, Blocking Page Source ve sayfa alanları elle değiştirilir (Hazır engelleme sayfası şablonları nelerdir (Türkçe, İngilizce, JSON)?).
• Komutla gövde yazıp kaynağı değiştirmemek. Kaynak Content Profile iken yazılan gövde kullanılmaz; kart A blocked client gets the … page demeye devam eder.

Dokümantasyonda nasıl yapılır

• Blocking Page · Conditional Blocking Pages
• Blocking Page · Ready-made Templates
• Content Pages · Content Type
• WEB-CLI waf options · Engelleme sayfası

İlgili sorular

• Engellemede neden varsayılan olarak 418 durum kodu dönüyor; bunu değiştirebilir miyim?
• Koşula bağlı farklı engelleme sayfaları tanımlayabilir miyim (Conditional Blocking Pages)?
• REST API'lerimi TR7 WAF ile koruyabilir miyim?