Güvenli Tarama Güncelleme API'si (v4)

Genel bakış

Update API, istemci uygulamalarınızın Güvenli Tarama listelerinin karma sürümlerini yerel bir veritabanında depolamak amacıyla indirmesine olanak tanır. Daha sonra URL'ler yerel olarak kontrol edilebilir. Yalnızca yerel veritabanında bir eşleşme bulunursa istemcinin, URL'nin Güvenli Tarama listelerine eklenip eklenmediğini doğrulamak için Güvenli Tarama sunucularına istek göndermesi gerekir.

Update API'yi kullanmadan önce yerel bir veritabanı ayarlamanız gerekir. Güvenli Tarama, başlamak için kullanabileceğiniz bir Go paketi sağlar. Daha fazla bilgi için Yerel Veritabanları altındaki Veritabanı Kurulumu bölümüne bakın.

Yerel veritabanını güncelleme

Müşterilerin güncel kalmak için yerel veritabanlarındaki Güvenli Tarama listelerini düzenli olarak güncellemeleri gerekir. Bant genişliğinden tasarruf etmek için istemciler, ham URL'ler yerine URL'lerin karma ön eklerini indirir. Örneğin, "www.badurl.com/" bir Güvenli Tarama listesindeyse istemciler, URL'nin kendisi yerine bu URL'nin SHA256 karma ön ekini indirir. Çoğu durumda karma ön eklerin uzunluğu 4 bayttır. Diğer bir deyişle, tek bir liste girişini indirmenin ortalama bant genişliği maliyeti, sıkıştırmadan önce 4 bayttır.

Yerel veritabanındaki Güvenli Tarama listelerini güncellemek için threatListUpdates.fetch yöntemine HTTP POST isteği gönderin:

  • HTTP POST isteği, güncellenecek listelerin adlarını ve bellek ve bant genişliği sınırlamalarını hesaba katan çeşitli istemci kısıtlamalarını içerir.
  • HTTP POST yanıtı, tam güncelleme veya kısmi güncelleme döndürür. Yanıt minimum bekleme süresi de döndürebilir.

Örnek: ThreatListUpdates.fetch

HTTP POST isteği

Aşağıdaki örnekte, tek bir Güvenli Tarama listesi için güncellemeler istenmektedir.

İstek başlığı

İstek başlığı, istek URL'sini ve içerik türünü içerir. URL'deki API_KEY API anahtarınızı değiştirmeyi unutmayın.

POST https://safebrowsing.googleapis.com/v4/threatListUpdates:fetch?key=API_KEY HTTP/1.1
Content-Type: application/json

İstek içeriği

İstek gövdesi, istemci bilgilerini (kimlik ve sürüm) ve güncelleme bilgilerini (liste adı, liste durumu ve istemci kısıtlamaları) içerir. Daha fazla ayrıntı için threatListUpdates.fetch istek gövdesine ve kod örneğinden sonraki açıklamalara bakın.

{
  "client": {
    "clientId":       "yourcompanyname",
    "clientVersion":  "1.5.2"
  },
  "listUpdateRequests": [{
    "threatType":      "MALWARE",
    "platformType":    "WINDOWS",
    "threatEntryType": "URL",
    "state":           "Gg4IBBADIgYQgBAiAQEoAQ==",
    "constraints": {
      "maxUpdateEntries":      2048,
      "maxDatabaseEntries":    4096,
      "region":                "US",
      "supportedCompressions": ["RAW"]
    }
  }]
}
Müşteri bilgileri

clientID ve clientVersion alanları, tekil bir kullanıcıyı değil, bir istemci uygulamasını benzersiz şekilde tanımlamalıdır. (İstemci bilgileri, sunucu tarafı günlük kaydında kullanılır. İstemci kimliği için herhangi bir adı seçebilirsiniz ancak müşterinin gerçek kimliğini temsil eden, örneğin tek kelimeden oluşan ve tamamı küçük harfle gösterilen bir ad seçmenizi öneririz.

Güvenli Tarama listeleri

threatType, platformType ve threatEntryType alanları, Güvenli Tarama listelerini tanımlamak (adlandırmak) için birleştirilir. Bu örnekte bir liste tanımlanmıştır: MALWARE/WINDOWS/URL. İstek göndermeden önce, belirttiğiniz tür kombinasyonlarının geçerli olduğundan emin olun (Güvenli Tarama Listeleri'ne bakın).

İstemci durumu

state alanı, Güvenli Tarama listesinin geçerli istemci durumunu içerir. (İstemci durumları, threatListUpdates.fetch yanıtının newClientState alanında döndürülür.) İlk güncellemeler için state alanını boş bırakın.

Boyut kısıtlamaları

maxUpdateEntries alanı, istemcinin yönetebileceği toplam güncelleme sayısını belirtir (örnekte 2048). maxDatabaseEntries alanı, yerel veritabanının yönetebileceği toplam giriş sayısını belirtir (örnekte 4096). İstemciler, bellek ve bant genişliği sınırlamalarını korumak ve liste büyümesine karşı koruma sağlamak için boyut kısıtlamaları belirlemelidir. Daha fazla bilgi için Güncelleme Kısıtlamaları bölümünü inceleyin.

Desteklenen sıkıştırma

supportedCompressions alanında, istemcinin desteklediği sıkıştırma türleri listelenir. Bu örnekte, istemci yalnızca ham, sıkıştırılmamış verileri destekler. Ancak Güvenli Tarama ek sıkıştırma türlerini destekler (Sıkıştırma bölümüne bakın).

HTTP POST yanıtı

Bu örnekte verilen yanıt, istenen sıkıştırma türünü kullanarak Güvenli Tarama listesi için kısmi bir güncelleme döndürür.

Yanıt başlığı

Yanıt başlığı, HTTP durum kodunu ve içerik türünü içerir. HTTP/200 dışında bir durum kodu alan istemciler, geri çekilme moduna girmelidir (bkz. İstek Sıklığı).

HTTP/1.1 200 OK
Content-Type: application/json

Yanıt gövdesi

Yanıt gövdesi, güncelleme bilgilerini (liste adı, yanıt türü, yerel veritabanına uygulanacak ekleme ve kaldırma işlemleri, yeni istemci durumu ve sağlama toplamı) içerir. Örnekteki yanıtta minimum bekleme süresi de yer alıyor. Daha fazla bilgi için threatListUpdates.fetch yanıt gövdesine ve kod örneğindeki açıklamalara bakın.

{
  "listUpdateResponses": [{
    "threatType":      "MALWARE",
    "threatEntryType": "URL",
    "platformType":    "WINDOWS",
    "responseType" :   "PARTIAL_UPDATE",
    "additions": [{
      "compressionType": "RAW",
      "rawHashes": {
        "prefixSize": 4,
        "rawHashes":  "rnGLoQ=="
      }
    }],
    "removals": [{
      "compressionType": "RAW",
      "rawIndices": {
        "indices": [0, 2, 4]
      }
    }],
    "newClientState": "ChAIBRADGAEiAzAwMSiAEDABEAFGpqhd",
    "checksum": {
      "sha256": "YSgoRtsRlgHDqDA3LAhM1gegEpEzs1TjzU33vqsR8iM="
    }
  }],
  "minimumWaitDuration": "593.440s"
}
Veritabanı güncellemeleri

responseType alanı, kısmi veya tam güncellemeyi belirtir. Örnekte, kısmi bir güncelleme döndürüldüğünden, yanıt hem ekleme hem de kaldırma işlemlerini içerir. Birden fazla ekleme grubu ancak tek bir kaldırma grubu olabilir (bkz. Veritabanı Güncellemeleri).

Yeni müşteri durumu

newClientState alanı, yeni güncellenen Güvenli Tarama listesinin yeni istemci durumunu tutar. İstemciler, sonraki güncelleme istekleri için yeni istemci durumunu kaydetmelidir (threatListUpdates.fetch isteğindeki state alanı veya fullHashes.find isteğindeki clientStates alanı).

Sağlamalar

Sağlama, istemcilerin yerel veritabanında herhangi bir bozulma olmadığını doğrulamasını sağlar. Sağlama toplamı eşleşmezse istemcinin veritabanını temizlemesi ve boş bir state alanı ile yeniden güncelleme yayınlaması gerekir. Ancak bu durumdaki istemcilerin, güncellemeler için zaman aralıklarını takip etmesi gerekir (bkz. İstek Sıklığı).

Minimum bekleme süreleri

minimumWaitDuration alanı, istemcinin başka bir güncelleme isteği göndermeden önce 593,44 saniye (9,89 dakika) beklemesi gerektiğini belirtir. Yanıta bekleme süresinin dahil edilip edilmeyeceğini unutmayın (İstek Sıklığı bölümüne bakın).

URL'ler kontrol ediliyor

Bir URL'nin Güvenli Tarama listesinde olup olmadığını kontrol etmek için istemcinin öncelikle URL'nin karma ve karma ön ekini hesaplaması gerekir (bkz. URL'ler ve Karma Oluşturma). Ardından istemci, eşleşme olup olmadığını belirlemek için yerel veritabanını sorgular. Karma ön eki yerel veritabanında yoksa URL, güvenli kabul edilir (Güvenli Tarama listelerinde yer almaz).

Yerel veritabanında karma ön eki varsa (karma ön eki çakışması) istemcinin, karma ön ekini doğrulama için Güvenli Tarama sunucularına göndermesi gerekir. Sunucular, belirtilen karma önekini içeren tüm tam uzunluktaki SHA 256 karmalarını döndürür. Bu tam uzunluktaki karmalardan biri, söz konusu URL'nin tam uzunluktaki karmasıyla eşleşirse URL'nin güvenli olmadığı kabul edilir. Tam uzunluktaki karmaların hiçbiri söz konusu URL'nin tam uzunluktaki karmasıyla eşleşmiyorsa bu URL güvenli kabul edilir.

Google, incelediğiniz URL'ler hakkında hiçbir zaman bilgi edinmez. Google, URL'lerin karma ön eklerini öğrenir, ancak karma ön ekler gerçek URL'ler hakkında çok fazla bilgi vermez.

Bir URL'nin Güvenli Tarama listesinde olup olmadığını kontrol etmek için fullHashes.find yöntemine HTTP POST isteği gönderin:

  • HTTP POST isteği en fazla 500 tehdit girişi içerebilir.
  • HTTP POST isteği, kontrol edilecek URL'lerin karma öneklerini içerir. Bant genişliği kullanımını azaltmak için istemcilerin, birden fazla tehdit girişini tek bir istekte gruplandırması önerilir.
  • HTTP POST yanıtı, pozitif ve negatif önbellek süreleriyle birlikte eşleşen tam uzunlukta karmaları döndürür. Yanıt için minimum bekleme süresi de dönebilir.

Örnek: fullHashes.find

HTTP POST isteği

Aşağıdaki örnekte, iki Güvenli Tarama listesinin ve üç karma ön ekin adı karşılaştırma ve doğrulama için gönderilmiştir.

İstek başlığı

İstek başlığı, istek URL'sini ve içerik türünü içerir. URL'deki API_KEY API anahtarınızı değiştirmeyi unutmayın.

POST https://safebrowsing.googleapis.com/v4/fullHashes:find?key=API_KEY HTTP/1.1
Content-Type: application/json

İstek içeriği

İstek gövdesinde istemci bilgileri (kimlik ve sürüm), istemci durumları ve tehdit bilgileri (liste adları ve karma önekler) yer alır. JSON istekleri için karma öneklerin base64 olarak kodlanmış biçimde gönderilmesi gerekir. Daha fazla bilgi için fullHashes.find istek gövdesi ve kod örneğinden sonraki açıklamalara bakın.

{
  "client": {
    "clientId":      "yourcompanyname",
    "clientVersion": "1.5.2"
  },
  "clientStates": [
    "ChAIARABGAEiAzAwMSiAEDABEAE=",
    "ChAIAhABGAEiAzAwMSiAEDABEOgH"
  ],
  "threatInfo": {
    "threatTypes":      ["MALWARE", "SOCIAL_ENGINEERING"],
    "platformTypes":    ["WINDOWS"],
    "threatEntryTypes": ["URL"],
    "threatEntries": [
      {"hash": "WwuJdQ=="},
      {"hash": "771MOg=="},
      {"hash": "5eOrwQ=="}
    ]
  }
}
Müşteri bilgileri

clientID ve clientVersion alanları, tekil bir kullanıcıyı değil, bir istemci uygulamasını benzersiz şekilde tanımlamalıdır. (İstemci bilgileri, sunucu tarafı günlük kaydında kullanılır. İstemci kimliği için herhangi bir ad seçebilirsiniz ancak müşterinin gerçek kimliğini temsil eden bir ad (ör. şirket adınız) tek kelimelik bir şekilde ve tamamı küçük harfle gösterilen bir ad seçmenizi öneririz.

Tüm istemci durumları

clientStates alanı, istemcinin yerel veritabanındaki tüm Güvenli Tarama listeleri için istemci durumlarını tutar. (İstemci durumları, threatListUpdates.fetch yanıtının newClientState alanında döndürülür.)

Güvenli Tarama listeleri

threatTypes, platformTypes ve threatEntryTypes alanları, Güvenli Tarama listelerini tanımlamak (adlandırmak) için birleştirilir. Bu örnekte iki liste tanımlanmıştır: MALWARE/WINDOWS/URL ve SOCIAL_ENGINEERING/WINDOWS/URL. İstek göndermeden önce, belirttiğiniz tür kombinasyonlarının geçerli olduğundan emin olun (Güvenli Tarama Listeleri'ne bakın).

Tehdit karması ön ekleri

ThreatEntries dizisi, kontrol etmek istediğiniz URL'lerin karma ön eklerini içerir. hash alanı, yerel veritabanında bulunan tam karma önekini içermelidir. Örneğin, yerel karma ön eki 4 bayt uzunluğundaysa tehdit girişi 4 bayt uzunluğunda olmalıdır. Yerel karma ön eki 7 bayta uzatılmışsa tehdit girişi 7 bayt uzunluğunda olmalıdır.

Örnekteki istek üç karma ön ek içeriyor. Üç ön ekin tümü, tam uzunlukta eşleşen karma olup olmadığını belirlemek için Güvenli Tarama listelerinin her biriyle karşılaştırılır.

Not: Update API ve fullHashes.find yöntemi, hiçbir zaman URL alanını değil, her zaman hash alanını kullanmalıdır (ThreatEntry bölümüne bakın).

HTTP POST yanıtı

Aşağıdaki örnekte yanıt, Güvenli Tarama listesine göre düzenlenen eşleşen verileri, önbellek ve bekleme süreleriyle birlikte döndürür.

Yanıt başlığı

Yanıt başlığı, HTTP durum kodunu ve içerik türünü içerir. HTTP/200 dışında bir durum kodu alan istemcilerin geri çekilmesi gerekir (bkz. İstek Sıklığı).

HTTP/1.1 200 OK
Content-Type: application/json

Yanıt gövdesi

Yanıt gövdesi, eşleşme bilgilerini (liste adları ve tam uzunlukta karmalar, varsa meta veriler ve önbellek süreleri) içerir. Örnekteki yanıt gövdesi de minimum bekleme süresi içerir. Daha fazla bilgi için fullHashes.find yanıt gövdesi ve kod örneğinden sonraki açıklamalara bakın.

{
  "matches": [{
    "threatType":      "MALWARE",
    "platformType":    "WINDOWS",
    "threatEntryType": "URL",
    "threat": {
      "hash": "WwuJdQx48jP-4lxr4y2Sj82AWoxUVcIRDSk1PC9Rf-4="
    },
    "threatEntryMetadata": {
      "entries": [{
        "key": "bWFsd2FyZV90aHJlYXRfdHlwZQ==",  // base64-encoded "malware_threat_type"
        "value": "TEFORElORw=="  // base64-encoded "LANDING"
       }]
    },
    "cacheDuration": "300.000s"
  }, {
    "threatType":      "SOCIAL_ENGINEERING",
    "platformType":    "WINDOWS",
    "threatEntryType": "URL",
    "threat": {
      "hash": "771MOrRPMn6xPKlCrXx_CrR-wmCk0LgFFoSgGy7zUiA="
    },
    "threatEntryMetadata": {
      "entries": []
    },
    "cacheDuration": "300.000s"
  }],
  "minimumWaitDuration": "300.000s",
  "negativeCacheDuration": "300.000s"
}
Şununla eşleşiyor:

"Eşleşmeler" nesnesi, karma ön eklerinden ikisi için eşleşen tam uzunlukta bir karma döndürür. Bu karmalara karşılık gelen URL'ler güvenli olarak kabul edilir. Üçüncü karma ön eki için eşleşme bulunamadığından hiçbir şey döndürülmez. Bu karma ön ekine karşılık gelen URL güvenli kabul edilir.

Bu örneğin, bir tam uzunluktaki karmayı bir karma ön ekiyle eşleştirdiğini unutmayın. Bununla birlikte, aynı karma ön eki ile eşlenen birden çok tam karma olabilir.

Meta veri

threatEntryMetadata alanı isteğe bağlıdır ve tehdit eşleştirme hakkında ek bilgi sağlar. Şu anda meta veri, KÖTÜ AMAÇLI YAZILIM/WINDOWS/URL Güvenli Tarama listesi için kullanılabilir (bkz. Meta Veriler).

Önbellek süreleri

cacheDuration ve negativeCacheDuration alanları, karmaların güvenli veya güvenli olarak değerlendirilmesi gereken süreyi gösterir (Önbelleğe alma bölümüne bakın).

Minimum bekleme süreleri

minimumWaitDuration alanı, istemcinin başka bir fullHashes isteği göndermeden önce 300 saniye (5 dakika) beklemesi gerektiğini belirtir. Yanıta bekleme süresinin dahil edilip edilmeyeceğini unutmayın (İstek Sıklığı bölümüne bakın).