Web Application Firewall (WAF) üzerinde koruma altına alınmış bir nesne veya nesne grubu için Agentic API Security özelliğini etkinleştirdiğinizde sistem API varlıklarınızı otomatik olarak keşfeder. API varlıklarını manuel olarak da içe aktarabilirsiniz. Bu konuda varlık yönetimi sayfasında API varlıklarınızı nasıl yöneteceğinizi açıklıyoruz.
Kullanım notları
Bu özellik yalnızca Agentic API Security özelliği etkinleştirilmiş koruma nesneleri veya grupları için geçerlidir. Özelliği etkinleştirmek üzere API Security > Policy Configurations > Applicable Object Configurations sayfasına gidin ve hedef koruma nesnesi için Basic Detection anahtarını açın.
Eski API Security özelliği Import API Assets from Swagger veya Schema Configuration işlevlerini desteklemez. Bu özellikleri kullanmak için Agentic API Security sürümüne yükseltme yapmanız gerekir. Daha fazla bilgi için bkz. [[Announcement] Notification of API Security Module Upgrade for Web Application Firewall](t3353926.xdita#).
Sayfaya genel bakış
Konsola erişim
Web Application Firewall 3.0 konsolunda oturum açın. Üst menü çubuğundan WAF örneği için kaynak grubunu ve bölgeyi (Chinese Mainland veya Outside Chinese Mainland) seçin.
Sol gezinme bölmesinde seçeneklerini belirleyin.
Assets sekmesine tıklayın.
Özellik alanları
Assets sekmesinde API varlığı istatistiklerini görüntüleyebilir ve filtreler kullanarak varlık arayabilirsiniz. Sayfa üç ana alandan oluşur:
API varlığına genel bakış: Sayfanın üst kısmında yer alır ve API varlıklarınız için genel istatistikleri gösterir.
Uygulama sitesi çubuğu: Sayfanın sol alt kısmında bulunur ve varlıkları site bazında filtrelemenize olanak tanır.
API varlığı listesi: Sayfanın sağ alt kısmında yer alır ve filtreleme kriterlerinizle eşleşen API varlıklarının ayrıntılarını listeler.
API Asset Overview
Bu alanda API varlıklarınız için Total API Assets, New Today, Active APIs, Deactivated APIs, Response-sensitive Sites, Response-sensitive APIs, Cross-border Data Transmission APIs ve Machine-requested APIs dahil olmak üzere çeşitli istatistikler sunulur.
New Events Today, Deactivated APIs, Response-sensitive Sites veya Response-sensitive APIs değerlerine tıklayarak aşağıdaki API varlığı listesinde ilgili varlıkları görüntüleyebilirsiniz.
İstatistiksel dönem 30 gündür. 30 günden uzun süredir erişim kaydı bulunmayan API'ler varlık listesinden kaldırılır. Swagger dosyasından içe aktarılan API varlıkları bu kuraldan etkilenmez ve trafik oluşturana kadar pasif olarak işaretlenmez veya kaldırılmaz.
Uygulama sitesi çubuğu
Sayfanın sol alt kısmındaki site çubuğunda site adları (etki alanları) ve bunlarla ilişkili API sayıları gösterilir. Varsayılan olarak API Asset List tüm uygulama sitelerine ait verileri görüntüler. Bir siteye tıkladığınızda API Asset List içinde o sitenin ayrıntılı verilerini görebilirsiniz.
API Assets
Arama ve filtreleme
Varlık listesinin üzerindeki arama çubuğu sayesinde API varlıklarını API adı, açıklamalar, zaman aralığı, hassas veri türü, hizmet nesnesi, iş amacı, istek yöntemi, aktif durum, izleme durumu, kimlik doğrulama durumu ve API hassasiyet düzeyi gibi kriterlere göre filtreleyebilirsiniz.
API varlıklarını Swagger'dan manuel olarak içe aktarma
Agentic API Security, trafiğe dayalı API varlıklarının otomatik keşfi ve yönetimini destekler; bu yaklaşım çevrimiçi çalışan API'lerin keşfi için uygundur. Ancak henüz yayına alınmamış, trafiği düşük, kademeli yayımda olan veya istek/yanıt sözleşme düzeyinde doğrulama gerektiren senaryolarda otomatik keşif gecikebilir veya parametre bilgileri eksik kalabilir. Böyle durumlarda Swagger (OpenAPI) teknik özellikleri dosyasını manuel olarak içe aktararak geliştirme ekibinizin tanımladığı API sözleşmelerini toplu şekilde API varlığı olarak sisteme yükleyebilirsiniz. Bu yöntem varlıkları önceden sisteme dahil etmenizi sağlar ve ileride şema doğrulaması ile hassas veri tespiti için kesin bir API yapısı sunar.
Yordam
API Assets bölümünde sağ taraftaki Import Swagger düğmesine tıklayın.
-
Import API Assets from Swagger iletişim kutusunda boyutu en fazla 5 MB olan bir JSON dosyası yükleyin. Aşağıda bir örnek verilmiştir.
{ "openapi": "3.0.3", "info": { "title": "User Information API", "version": "1.0.0" }, "servers": [ { "url": "https://user.example.com" } ], "paths": { "/users/{userId}": { "get": { "summary": "Query user information", "parameters": [ { "name": "userId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Query successful", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserResponse" } } } } } } } }, "components": { "schemas": { "UserResponse": { "type": "object", "properties": { "userId": { "type": "string" }, "userName": { "type": "string" }, "phone": { "type": "string" }, "idCard": { "type": "string" } } } } } } -
Dosya yüklendikten sonra sistem API'leri otomatik olarak ayrıştırır. Aşağıdaki ayarları tamamlayın:
Associated Protected Object: API'lerle ilişkilendirilecek koruma nesnesini seçin.
-
Handling for existing APIs: Sistem aynı API varlığını trafiktan otomatik olarak keşfetmişse yinelenen öğeyi nasıl ele alacağınızı seçin:
Skip: Sistemin keşfettiği mevcut varlığı korur ve bu yüklemedeki yinelenen öğeyi yok sayar.
Overwrite: Bu yüklemedeki API teknik özelliklerini kullanarak mevcut keşfedilen varlığın şemasını günceller. Mevcut varlığın çağrı hacmi, aktif durumu, risk kayıtları ve diğer bilgileri etkilenmez.
Yapılandırmayı tamamladıktan sonra API Assets bölümünün sağ tarafında bulunan Import Records seçeneğine tıklayarak içe aktarma durumunu ve sonuçlarını görüntüleyin.
API varlığı için şema yapılandırma
Agentic API Security, bir API varlığı için istek parametrelerinin ve yanıt yapısının teknik özelliklerini tanımlayan şema yapılandırmanıza olanak tanır. Bu şema resmi API sözleşmesi olarak görev yapar ve şema doğrulama ilkesi çalışma zamanındaki istekleri tanımlanan yapıyla karşılaştırmak için bu sözleşmeyi kullanır.
Yordam
API Assets listesinde hedef API varlığını bulun.
-
Actions sütununda Configure Schema seçeneğine tıklayın. Şemayı aşağıdaki iki moddan birini kullanarak yapılandırabilirsiniz.
Görsel mod
Görsel Modda şemayı Parameters, Request body ve Responses olmak üzere üç ayrı sekmede yapılandırabilirsiniz. Method, HostName ve Path gibi bilgiler değiştirilemez.
Parameters
Yol, sorgu, üstbilgi veya çerez konumlarında bulunan parametreler ekleyebilirsiniz. Her parametre için aşağıdaki ayarları yapılandırabilirsiniz:
Parametre
Açıklama
Alan adı
Parametrenin adıdır. Bu ayar zorunludur.
Tür
Parametrenin veri türüdür (örneğin string, integer veya boolean).
required
Parametrenin zorunlu olup olmadığını belirtir. Yol konumundaki parametreler her zaman zorunludur. Diğer konumlar için bu ayarı açıp kapatabilirsiniz.
format
Parametrenin biçimidir (örneğin email, date veya uuid). Kullanılabilir seçenekler seçilen türe bağlıdır.
pattern
Doğrulama için kullanılan normal ifadedir. Bu ayar yalnızca string türü için geçerlidir.
enum
Kabul edilebilir değerlerin listesidir. Birden çok değeri virgülle ayırın.Request body
İstek gövdesinin zorunlu olup olmadığını belirtebilir ve Content-Type değerine (örneğin application/json) göre istek gövdesinin alan yapısını tanımlayabilirsiniz. Alan ayarları Parameters bölümündekilerle aynıdır.
Responses
200 gibi bir durum kodu ekleyebilir ve her durum kodu için yanıt üstbilgileri ile yanıt gövdesini yapılandırabilirsiniz:
Yanıt üstbilgileri: Yanıt üstbilgi alanları için alan adı, tür ve required, format, pattern, enum özelliklerini tanımlayın.
Yanıt gövdesi: Content-Type değerine göre yanıt gövdesinin alan yapısını tanımlayın. Alan ayarları yukarıda açıklandığı gibidir. Ayrıca yanıt gövdesindeki alanlar için hassas veri türünü ayarlayabilirsiniz; bu ayar API yanıtlarının gerçek zamanlı veri maskelemesinde kullanılır. Hassas veri türleri yalnızca Responses bölümünde yapılandırılabilir.
JSON modu
JSON Modunda OpenAPI 3.0.x/3.1.x teknik özelliklerine uygun JSON içeriğini doğrudan düzenleyebilirsiniz. Aşağıdaki gereksinimler geçerlidir:
JSON içeriği yalnızca bir yol ve bir yöntem içerebilir; bunlar mevcut API varlığının yöntemi, etki alanı adı ve yoluyla eşleşmelidir.
serversdizisi mevcut varlıkla eşleşen bir etki alanı adı içermelidir.
JSON örneği
{ "openapi": "3.0.3", "info": { "title": "Create User API", "version": "1.0.0" }, "servers": [ { "url": "https://www.example.com" } ], "paths": { "/users": { "post": { "summary": "Create user", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "userName": { "type": "string" }, "email": { "type": "string", "format": "email" }, "status": { "type": "string", "enum": ["active", "inactive"] } }, "required": ["userName", "email"] } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "userId": { "type": "integer", "format": "int64" }, "userName": { "type": "string" }, "email": { "type": "string", "format": "email", "x-sensitive-data-types": ["Email"] } }, "required": ["userId"] } } } } } } } } } Gerçek istekleri ve yanıtları doğrulamak üzere bir Schema Validation şablonu yapılandırın. Daha fazla bilgi için bkz. IV. Response Policy Configuration.
API varlığı ayrıntılarını görüntüleme
API Asset List içinde bir API adına tıklayarak API Details sayfasına gidin. Bu sayfada Overview, Sample Request, Traffic Analytics, Risks and Events ve Protection Suggestions olmak üzere beş sekme bulunur.
Overview
Sayfanın üst kısmındaki genel bakış kartında ilişkili etki alanı, ilk keşfedilme zamanı, son aktif olma zamanı, iş amacı, hizmet nesnesi, kimlik doğrulama durumu, ilişkili koruma nesnesi ve açıklamalar gibi bilgiler görüntülenir.
Örnek istek
Sample Request sekmesine tıklayarak aşağıdaki bilgilere erişin:
Sensitive Data Type: İstek veya yanıt hassas veri içeriyorsa belirli türler burada gösterilir.
-
İstek Örneği Görüntüleme: Bu bölümde rastgele seçilen en fazla beş API istek örneği görüntülenir. Split Display ve Merge Display modları arasında geçiş yapabilirsiniz:
Split Display: Örneği Sensitive Data, Standard, Request Header, Response Header, Request Body ve Response Body bölümlerine ayırır; bu bölümleri tek tek görüntüleyip kopyalayabilirsiniz.
Merge Display: Örneği Sensitive Data, Sample Request ve Sample Response bölümlerinde birleştirir; trafik yeniden oynatma testlerini kolaylaştırmak için bu bölümleri tek tek görüntüleyip kopyalayabilirsiniz.
-
Doğrulama İşlemleri:
API erişimini hızlıca test etmek için Browser seçeneğine tıklayın.
Manuel erişim doğrulaması için cURL komutu almak üzere Command Line seçeneğine tıklayın.
Parametre Tanıma Sonuçları: Request Parameter Type ve Response Parameter Type alanlarında trafik temel alma işleminden elde edilen Parameter, Value Characteristics ve Parameter Position sonuçları görüntülenir.
Trafik analizi
Traffic Analytics sekmesine tıklayarak API'nin son 30 günlük erişim verilerini görüntüleyin:
Traffic Analytics: API çağrı eğilimini ve Total Calls, Bot Requests ile Cross-border Requests istatistiklerini gösterir.
Top 20 Access Sources: Bu bölümde son 30 günün en iyi 20 erişim kaynağı listelenir; Total Traffic, Bot Traffic ve Cross-border Traffic ölçütlerine göre sıralama yapabilirsiniz.
Client Source Statistics: Bu bölümde son 30 günlük erişim kaynağı dağılımı Referer, istemci türü, coğrafi konum ve hesap olmak üzere dört boyutta istatistiksel olarak sunulur.
Riskler ve olaylar
Risks and Events sekmesine tıklayarak API ile ilişkili Risks, IP Security Events ve Account Security Events bilgilerini görüntüleyin. Actions sütununda View Details seçeneğine tıklayarak daha fazla bilgi için ayrıntılar sayfasına gidin.
Koruma önerileri
Protection Suggestions sekmesine tıklayın. WAF, API çağrı temel çizgisini analiz ederek hedefe yönelik güvenlik önerileri sunar.
Rutin işlemler
API Asset List içinde listenin sağ üst köşesindeki
simgesine tıklayarak hangi sütunların görüntüleneceğini seçebilir ve aşağıdaki işlemleri uygulayabilirsiniz:
Varlık listesini dışa aktarmak için listenin sağ üst köşesindeki
simgesine tıklayın. Bu işlem bir dışa aktarma görevi oluşturur. Ardından sayfanın sağ üst köşesindeki Export Record seçeneğine tıklayın, dışa aktarma geçmişi listesinde hedef dosyayı bulun ve Download sütunundaki Actions seçeneğine tıklayarak dosyayı indirin.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|