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

Genel Bakış

Update API, istemci uygulamalarınızın Güvenli Tarama listelerinin karma oluşturma işlemi uygulanmış sürümlerini indirmesine olanak tanır. yerel veritabanında saklamanızı sağlar. Böylece URL'ler yerel olarak kontrol edilebilir. Yalnızca istemcinin, alan adının doğrulanması için Güvenli Tarama sunucularına bir istek göndermesi URL'nin Güvenli Tarama listelerine eklenip eklenmediğini kontrol eder.

Update API'yi kullanmadan önce yerel bir veritabanı oluşturmanız gerekir. Güvenli Tarama, Başlamak için kullanabileceğiniz Go paketi. Daha fazla ayrıntı için Yerel Veritabanları.

Yerel veritabanını güncelleme

İstemcilerin güncel kalabilmek için yerel veritabanlarındaki Güvenli Tarama listelerini düzenli olarak güncellemesi gerekir. Müşteriler, bant genişliğinden tasarruf etmek için ham URL'ler yerine URL'lerin karma ön eklerini indirir. Örneğin, "www.badurl.com/" Güvenli Tarama listesindeyse müşteriler URL'nin kendisini değil, SHA256 karma ön ekini indirir. Çoğu durumda karma önekler 4 bayt uzunluğundadır, yani tek bir listeyi indirmenin ortalama bant genişliği maliyeti giriş, sıkıştırmadan 4 bayt öncedir.

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

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

Örnek: tehditListUpdates.fetch

HTTP POST isteği

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

İstek başlığı

İstek başlığı, istek URL'sini ve içerik türünü içerir. API'nizi değiştirmeyi unutmayın API_KEY tuşuna bası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ını, liste durumunu ve istemci kısıtlamalarını içerir). Daha fazla bilgi için threatListUpdates.fetch istek gövdesine ve kod örneğinin ardından gelen 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ı, bireysel bir kullanıcıyı değil, 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 istediğiniz adı seçebilirsiniz ancak istemcinin gerçek kimliğini temsil eden bir ad seçmenizi öneririz (ör. şirketinizin adı, tek bir kelime olarak ve tamamen küçük harflerle yazılmış şekilde).

Güvenli Tarama listeleri

threatType, platformType ve threatEntryType alanları Güvenli Tarama listelerini tanımlamak (adlandırmak) için birleştirilir. Ö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 bölümü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 ( (örneğin, 2048). maxDatabaseEntries alanı, yerel yönetebileceği bir kaynaktır (örnekte 4096). Müşteriler boyut kısıtlamaları ayarlamalıdır belleğe ve bant genişliği sınırlamalarını korumak ve bahsedeceğim. Daha fazla bilgi için Güncelleme Kısıtlamaları bölümüne bakın.

Desteklenen sıkıştırma işlemleri

supportedCompressions alanında, istemcinin desteklediği sıkıştırma türleri listelenir. Örneğin, istemci yalnızca ham ve 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, yanıtta istenen sıkıştırma türü kullanılarak Güvenli Tarama listesi için kısmi bir güncelleme döndürülür.

Yanıt başlığı

Yanıt üstbilgisi, HTTP durum kodunu içerir. ve içerik türü. HTTP/200 dışında bir durum kodu alan istemciler geri yükleme 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ü, eklemeleri ve kaldırmaları, yeni müşteri için bir denetim toplamı) içerir. Örnekteki yanıt, minimum bekleme süresi de içerir. Daha fazla daha fazla bilgi için threatListUpdates.fetch yanıt gövdesi ve kod örneğindeki açıklamaları izlemelisiniz.

{
  "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 gösterir. Bu örnekte, kısmi güncelleme hatası döndürülür, dolayısıyla yanıt hem ekleme hem de kaldırma işlemlerini içerir. Birden fazla ekleme grubu olabilir ancak yalnızca bir kaldırma grubu olabilir (Veritabanı Güncellemeleri bölümüne bakın).

Yeni istemci durumu

newClientState alanı, yeni güncellenen Güvenli Tarama listesi için yeni istemci durumunu barındırır. Müşteriler, sonraki güncelleme istekleri için yeni istemci durumunu (state threatListUpdates.fetch isteği veya clientStates fullHashes.find isteği).

Denetim Toplamları

Sağlama, istemcilerin yerel veritabanında herhangi bir bozulma olmadığını doğrulamasını sağlar. Öğe denetim toplamı eşleşmiyor, istemcinin veritabanını temizlemesi ve güncelleştirmeyi boş bir state alanı boş bırakılamaz. Ancak bu durumdaki müşteriler, güncellemeler için yine de zaman aralıklarını izlemelidir. (bkz. İstek Sıklığı).

Minimum bekleme süreleri

minimumWaitDuration alanı, istemcinin 593,44 saniye (9,89 dakika) beklemesi gerektiğini belirtir . Bekleme süresinin, yanıtı (İ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 müşterinin öncelikle karmayı ve karmayı hesaplaması gerekir. önekini kullanın (URL'ler ve Karma oluşturma bölümüne bakın). Ardından istemci, eşleşme olup olmadığını belirlemek için yerel veritabanı sorgular. Karma oluşturma ön eki yerel veritabanında bulunmuyorsa URL güvenli kabul edilir (Güvenli Tarama listelerinde yer almaz).

Yerel veritabanında karma ön eki varsa (karma öneki çakışması) istemci, karma önekini doğrulama için Güvenli Tarama sunucularına göndermelidir. Sunucular, belirtilen karma ön ekini 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 güvenli değil olarak kabul edilir. Tam uzunluktaki karma şifrelerden hiçbiri söz konusu URL'nin tam uzunluktaki karma şifresiyle eşleşmiyorsa bu URL güvenli kabul edilir.

Google, incelemekte olduğunuz URL'ler hakkında hiçbir noktada bilgi almaz. Google, karmayı ancak karma önekler gerçek URL'ler hakkında fazla bilgi vermez.

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

  • HTTP POST isteği en fazla 500 tehdit girişi içerebilir.
  • HTTP POST isteği, kontrol edilecek URL'lerin karma ön eklerinin içerir. Müşteriler Bu öneri, bant genişliği kullanımını azaltmak için birden fazla tehdit girişini tek bir istekte toplanmalıdır.
  • HTTP POST yanıtı, pozitif ve negatif önbellek süreleri. Yanıt da minimum bekleme süresi döndürebilir.

Örnek: fullHashes.find

HTTP POST isteği

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

İstek başlığı

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

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

İstek içeriği

İstek gövdesi; istemci bilgilerini (kimlik ve sürüm), istemci durumlarını ve tehdit bilgilerini (liste adları ve karma ön ekleri) içerir. JSON isteklerinde karma ön ekleri base64 kodlu biçimde gönderilmelidir. Daha fazla bilgi için fullHashes.find istek gövdesi ve kod örneğindeki açıklamaları izlemelisiniz.

{
  "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ı, bireysel kullanıcı. (İstemci bilgileri sunucu tarafında günlük kaydında kullanılır. Öğe kimliği için Ancak, müşterinin gerçek kimliğini temsil eden bir ad seçmenizi öneririz, örneğin: (hepsi küçük harflerle yazılmış, tümü tek bir kelime halinde sunulan şirket adınız).)

Tüm istemci durumları

clientStates alanı, tüm Güvenli Tarama listelerinin istemci durumlarını yerel veritabanını kullanır. (İstemci durumları, threatListUpdates.fetch yanıtının newClientState alanında döndürülür.)

Güvenli Tarama listeleri

threatTypes, platformTypes ve threatEntryTypes Güvenli Arama'yı tanımlamak (adını vermek) için Listelere göz atma. Ö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 bölümüne bakın).

Tehdit karması ön ekleri

TehditEntries dizisi, kontrol etmek istediğiniz URL'lerin karma ön eklerini içerir. hash alanı, yerel veritabanında bulunan karma oluşturma ön ekini tam olarak içermelidir. Örneğin, Örneğin, yerel karma öneki 4 bayt uzunluğundaysa tehdit girişi 4 bayt uzunluğunda olmalıdır. Yerel karma ön eki 7 bayta uzatıldıysa tehdit girişi 7 bayt uzunluğunda olmalıdır.

Örnekte istek üç karma ön ek içeriyor. Üç ön ek de karşılaştırılacaktır. karşılaştırabilirsiniz.

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

HTTP POST yanıtı

Aşağıdaki örnekte yanıt, eşleştirme verilerini Güvenli Tarama listesine göre düzenlenmiş olarak döndürür. önbellek ve bekleme süreleri gösterilir.

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 çekilmelidir (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 uzunluktaki karmalar, varsa meta verileri ve önbellek sürelerini içerir. Örnekte, yanıt metni minimum bekleme süresini de içerir. Daha fazla bilgi için fullHashes.find yanıt gövdesine ve kod örneğinin ardından gelen 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"
}
Eşleşmeler

Eşleşmeler nesnesi, karma ön eklerinden ikisi için eşleşen tam uzunluktaki bir karma döndürür. Bu karma oluşturma işlemlerine karşılık gelen URL'ler güvenli değildir. Üçüncü karma ön ekiyle eşleşen bir sonuç bulunamadı. Bu nedenle, hiçbir şey döndürülmez. Bu karma ön ekiyle ilişkili URL güvenli kabul edilir.

Bu örneğin, tam uzunluktaki bir karmayı bir karma önekiyle eşleştirdiğini unutmayın. ancak aynı karma ön eki ile eşlenen birden çok tam karma oluşturmalıdır.

Meta veri

threatEntryMetadata alanı isteğe bağlıdır ve tehdit eşleşmesi hakkında ek bilgiler sağlar. Şu anda meta veriler, Güvenli Tarama'daki MALWARE/WINDOWS/URL listesi için kullanılabilir (Meta Veriler bölümüne bakın).

Önbellek süreleri

cacheDuration ve negativeCacheDuration alanları, tutarı belirtir karmaların bu içeriklerin güvenli olmadığı kabul edilir (Önbelleğe alma bölümüne bakın).

Minimum bekleme süreleri

minimumWaitDuration alanı, istemcinin önce 300 saniye (5 dakika) beklemesi gerektiğini belirtir başka bir fullHashes isteği gönderiliyor. Yanıtta bekleme süresinin yer alıp almayabileceğini göz önünde bulundurun (bkz. İstek Sıklığı).