Overview

Giriş

Not: Bu doküman şu anda hâlâ geliştirme aşamasındadır. Yakın gelecekte iyileştirmeler yapılabilir.

Google Güvenli Tarama v5, Google Güvenli Tarama v4'ün geliştirilmiş bir sürümüdür. v5'te yapılan iki önemli değişiklik, veri güncelliği ve IP gizliliğidir. Ayrıca API yüzeyi esnekliği ve verimliliği artıracak, şişmeyi azaltacak şekilde iyileştirildi. Ayrıca Google Güvenli Tarama v5, sürüm 4'ten taşımayı kolaylaştırmak için tasarlanmıştır.

Şu anda Google hem v4 hem de v5 sürümünü sunmaktadır ve bunların her ikisi de üretime hazır olarak kabul edilir. v4 veya v5'i kullanabilirsiniz. Sürüm 4'ün kullanımdan kaldırılacağı tarihi açıklamadık; bunu yaparsak en az bir yıllık bildirimde bulunacağız. Bu sayfada v5 ve v4'ten v5'e geçiş rehberi açıklanmaktadır. v4 belgelerinin tamamı kullanılabilir.

Veri Güncelliği

Google Güvenli Tarama v5'in v4'e (özellikle v4 Güncelleme API'si) kıyasla önemli bir iyileştirmesi, verilerin güncelliği ve kapsamıdır. Koruma büyük ölçüde istemci tarafından yönetilen yerel veritabanına bağlı olduğundan, korumanın gözden kaçmasının başlıca nedeni yerel veritabanı güncellemesinin gecikmesi ve boyutudur. v4'te, tipik bir istemcinin tehdit listelerinin en güncel sürümünü alması 20 ila 50 dakika sürer. Maalesef kimlik avı saldırıları çok hızlı yayılıyor: 2021 itibarıyla saldırılar gerçekleştiren sitelerin% 60'ı 10 dakikadan daha kısa süre yaşıyor. Analizlerimiz, kimlik avı korumasının eksik olmasının yaklaşık% 25-30'unun bu tür verilerin eski olmasından kaynaklandığını göstermektedir. Ayrıca bazı cihazlar, zaman içinde büyümeye devam eden Google Güvenli Tarama tehdit listelerinin tamamını yönetecek donanıma sahip değildir.

v5'te gerçek zamanlı koruma olarak bilinen bir çalışma modunu kullanıma sunduk. Bu yöntem, yukarıdaki veri eskiliği sorununu atlar. v4'te istemcilerin yerel bir veritabanı indirip sürdürmesi, yerel olarak indirilen tehdit listelerine göre kontroller gerçekleştirmesi ve kısmi bir önek eşleşmesi olduğunda karmanın tamamını indirmek için bir istek gerçekleştirmesi beklenir. v5'te istemcilerin, tehdit listelerinin yerel veritabanını indirip saklamaya devam etmesi gerekse de, istemcilerin artık iyi durumda olma olasılığı yüksek sitelerin bir listesini (Genel Önbellek olarak adlandırılır) indirmeleri, hem bu Genel Önbellek için yerel bir denetim hem de bir yerel tehdit listesi kontrolü gerçekleştirmesi ve son olarak, tehdit listeleri için kısmi bir önek eşleşmesi veya Genel Önbellek'te eşleşme olmaması durumunda, karmaların tamamını indirmek için bir istek gerçekleştirmesi beklenmektedir. (Müşterinin talep ettiği yerel işlemlerle ilgili ayrıntılar için lütfen aşağıda verilen prosedüre bakın.) Bu, web'de tehditlerin daha hızlı yayılmasına karşı korumayı iyileştiren varsayılan olarak izin ver ayarından varsayılan olarak denetle seçeneğine geçişi temsil etmektedir. Başka bir deyişle bu, neredeyse gerçek zamanlı koruma sağlamak için tasarlanmış bir protokoldür: Müşterilerin daha güncel Google Güvenli Tarama verilerinden yararlanmasını amaçlarız.

IP Gizliliği

Google Güvenli Tarama (v4 veya v5), isteklerin yerine getirilmesi sırasında kullanıcının kimliğiyle ilişkili hiçbir şeyi işlemez. Çerezler gönderilirse yoksayılır. Google, isteklerin kaynak IP adreslerini tanır, ancak Google bu IP adreslerini yalnızca temel ağ ihtiyaçları (ör. yanıt göndermek için) ve DoS karşıtı amaçlarla kullanır.

v5 ile eş zamanlı olarak Güvenli Tarama Oblivious HTTP Gateway API'si olarak bilinen tamamlayıcı bir API'yi kullanıma sunduk. Bu ayarda, son kullanıcıların IP adreslerini Google'dan gizlemek için Oblivious HTTP (Oblivious HTTP) kullanılıyor. Kullanıcı isteğinin şifrelenmiş bir sürümünü işlemesi ve ardından bunu Google'a iletmesi için gizli bir üçüncü tarafa sahip olarak çalışır. Dolayısıyla, üçüncü taraf yalnızca IP adreslerine, Google ise yalnızca isteğin içeriğine erişebilir. Üçüncü taraf, bir Habersiz HTTP Geçişi çalıştırır (Fastly'nin sunduğu bu hizmet gibi) ve Google, Oblivious HTTP Ağ Geçidi'ni çalıştırır. Bu, isteğe bağlı bir tamamlayıcı API'dir. Bu özelliği Google Güvenli Tarama ile birlikte kullandığınızda, son kullanıcıların IP adresleri artık Google'a gönderilmez.

Uygun Kullanım

İzin Verilen Kullanım

Güvenli Tarama API'si yalnızca ticari olmayan kullanıma yöneliktir ("satış veya gelir oluşturma amaçlı değildir"). Ticari amaçlarla bir çözüme ihtiyacınız varsa lütfen Web Risk'e bakın.

Fiyatlandırma

Tüm Google Güvenli Tarama API'leri ücretsizdir.

Kotalar

Güvenli Tarama API'sini etkinleştiren geliştiricilere varsayılan kullanım kotası ayrılır. Mevcut tahsis ve kullanım Google Developer Console'da görüntülenebilir. Şu anda size ayrılan kotadan daha fazlasını kullanmayı bekliyorsanız Developer Console'un Kota arayüzünden ek kota isteyebilirsiniz. Hizmet kullanılabilirliğimizin tüm kullanıcıların gereksinimlerini karşıladığından emin olmak için bu istekleri inceler ve kota artışı için başvururken sizinle iletişime geçilmesini zorunlu tutarız.

Uygun URL'ler

Google Güvenli Tarama, tarayıcının adres çubuğunda görüntülenecek URL'ler üzerinde işlem yapacak şekilde tasarlanmıştır. Alt kaynakları (JavaScript veya HTML dosyası tarafından başvurulan resim ya da JavaScript tarafından başlatılan WebSocket URL'si gibi) kontrol etmek için tasarlanmamıştır. Bu tür alt kaynak URL'leri, Google Güvenli Tarama ile kontrol edilmemelidir.

Bir URL'nin ziyaret edilmesi yönlendirme ile sonuçlanıyorsa (HTTP 301 gibi), yönlendirilen URL'nin Google Güvenli Tarama ile kontrol edilmesi uygundur. İstemci tarafı URL değişikliği (ör. History.pushState), yeni URL'lerin Google Güvenli Tarama ile karşılaştırılmasıyla sonuçlanmaz.

Kullanıcı Uyarıları

Google Güvenli Tarama'yı belirli web sayfalarındaki riskler konusunda kullanıcıları uyarmak için kullanıyorsanız aşağıdaki yönergeler geçerlidir.

Bu yönergeler, sayfanın güvenli olmayan bir web kaynağı olduğunun% 100 kesinlikle bilinmediğini ve uyarıların yalnızca olası riski tanımladığını açıkça belirterek sizin ve Google’ın yanlış anlamalardan korunmasına yardımcı olur.

• Kullanıcılarınızın görebileceği uyarınızda, kullanıcıları söz konusu sayfanın hiç şüphesiz güvenli olmayan bir web kaynağı olduğuna inandırmamalısınız. Tanımlanan sayfadan veya sayfanın kullanıcılar için oluşturabileceği potansiyel risklerden bahsederken, şüpheli, potansiyel, olası, olası, olabilir gibi ifadeler kullanarak uyarının nitelendirilmesi gerekir.
• Uyarınız, kullanıcının Google'ın çeşitli tehdit tanımını inceleyerek daha fazla bilgi edinmesini sağlamalıdır. Aşağıdaki bağlantılar önerilir:
  • Sosyal Mühendislik: https://developers.google.com/search/docs/monitor-debug/security/social-engineering
  • Kötü Amaçlı ve İstenmeyen Yazılımlar: https://developers.google.com/search/docs/monitor-debug/security/malware
  • Zararlı Olabilecek Uygulamalar (yalnızca Android): https://developers.google.com/android/play-protect/potentially-harmful-applications
• Güvenli Tarama Hizmeti tarafından riskli olarak tanımlanan sayfalar için uyarı gösterdiğinizde, Güvenli Tarama Uyarısı'nın bağlantısını içeren "Google tarafından sağlanan tavsiye" satırını ekleyerek Google'a atıfta bulunmanız gerekir. Ürününüzde başka kaynaklara dayalı olarak da uyarılar gösteriliyorsa Google dışı verilerden elde edilen uyarılara Google ilişkilendirmesini dahil etmemeniz gerekir.

• Ürün dokümanlarınızda, kullanıcılara Google Güvenli Tarama'nın sunduğu korumanın mükemmel olmadığını bildiren bir bildirim sağlamanız gerekir. Kullanıcılara hem yanlış pozitif (riskli olarak işaretlenmiş güvenli siteler) hem de yanlış negatif (işaretli olmayan riskli siteler) olasılığı olduğunu bildirmelidir. Aşağıdaki dili kullanmanızı öneririz:

  Google, güvenli olmayan web kaynakları hakkında en doğru ve güncel bilgileri sağlamak için çalışır. Ancak Google, bilgilerinin kapsamlı ve hatasız olduğunu garanti edemez: Bazı riskli siteler tanımlanmayabilir ve bazı güvenli siteler hatalı olarak tanımlanabilir.

Çalışma Modları

Google Güvenli Tarama v5, istemcilerin üç çalışma modundan birini seçmesine olanak tanır.

Gerçek Zamanlı Mod

İstemciler Google Güvenli Tarama v5'i gerçek zamanlı modda kullanmayı seçtiklerinde, istemciler yerel veritabanlarında şunları tutar: (i) ana makine-sonu/yol ön eki URL ifadelerinin SHA256 karmaları olarak biçimlendirilmiş olası iyi siteler için Genel Önbellek, (ii) ana makine-sonek/yol ön eki URL ifadelerinin SHA256 karma önekleri olarak biçimlendirilmiş bir dizi tehdit listesi. Üst düzey fikir şudur: Müşteri belirli bir URL'yi kontrol etmek istediğinde, Genel Önbellek kullanılarak yerel bir kontrol yapılır. Bu denetim başarılı olursa yerel tehdit listeleri denetimi gerçekleştirilir. Aksi takdirde, istemci aşağıda ayrıntılı olarak açıklandığı gibi gerçek zamanlı karma kontrolüne devam eder.

İstemci, yerel veritabanının yanı sıra yerel bir önbellek de tutar. Bu tür bir yerel önbelleğin kalıcı depolama alanında olması gerekmez ve bellek yetersizliği durumunda temizlenebilir.

Prosedürle ilgili ayrıntılı spesifikasyonları aşağıda bulabilirsiniz.

Yerel Liste Modu

İstemciler bu modda Google Güvenli Tarama v5'i kullanmayı seçtiklerinde, istemci davranışı v5'in iyileştirilmiş API yüzeyini kullanma dışında v4 Update API'ye benzerdir. İstemciler, yerel veritabanlarında ana makine-sonek/yol ön eki URL ifadelerinin SHA256 karma önekleri olarak biçimlendirilmiş bir dizi tehdit listesi tutar. İstemci belirli bir URL'yi denetlemek istediğinde yerel tehdit listesi kullanılarak kontrol gerçekleştirilir. Yalnızca eşleşme varsa istemci kontrole devam etmek için sunucuya bağlanır.

Yukarıda da olduğu gibi, istemci kalıcı depolama alanında olmaması gereken yerel bir önbellek de tutacaktır.

Gerçek Zamanlı Depolama Alanı Yok Modu

İstemciler Google Güvenli Tarama v5'i depolama alanı olmayan gerçek zamanlı modda kullanmayı seçtiğinde, istemcinin herhangi bir yerel veritabanını yönetmesi gerekmez. İstemci belirli bir URL'yi kontrol etmek istediğinde denetim yapmak için her zaman sunucuya bağlanır. Bu mod, v4 Lookup API istemcilerine benzer.

URL'leri kontrol etme

Bu bölümde, istemcilerin URL'leri nasıl kontrol ettiğiyle ilgili ayrıntılı spesifikasyonlar yer almaktadır.

URL'leri standartlaştırma

Herhangi bir URL kontrol edilmeden önce, istemcinin bu URL'de bazı standartlaştırma gerçekleştirmesi beklenir.

Başlangıç olarak, istemcinin URL'yi ayrıştırdığını ve RFC 2396'ya göre geçerli hale getirdiğini varsayıyoruz. URL, uluslararası bir alan adı (IDN) kullanıyorsa, istemci URL'yi ASCII Punycode gösterimine dönüştürmelidir. URL bir yol bileşeni içermelidir. Yani, alan adından sonra en az bir eğik çizgi gelmelidir (http://google.com yerine http://google.com/).

Öncelikle, sekme (0x09), CR (0x0d) ve LF (0x0a) karakterlerini URL'den kaldırın. Bu karakterler için kaçış dizilerini kaldırmayın (ör. %0a).

İkinci olarak, URL parçayla bitiyorsa parçayı kaldırın. Örneğin, http://google.com/#frag kelimesini http://google.com/ şeklinde kısaltın.

Üçüncü olarak, URL'de artık yüzde-çıkış karakterleri kalmayıncaya kadar URL'de art arda yüzde-çıkış iptali bulunur. (Bu, URL'yi geçersiz hale getirebilir.)

Ana makine adını standartlaştırmak için:

URL'den ana makine adını çıkarın ve ardından:

1. Baştaki ve sondaki tüm noktaları kaldırın.
2. Ardışık noktaları tek bir noktayla değiştirin.
3. Ana makine adı IPv4 adresi olarak ayrıştırılabiliyorsa 4 noktayla ayrılmış ondalık değere normalleştirin. İstemci, sekizlik, onaltılık ve dörtten az bileşen de dahil olmak üzere tüm yasal IP adresi kodlamalarını işlemelidir.
4. Ana makine adı, köşeli parantez içine alınmış bir IPv6 adresi olarak ayrıştırılabiliyorsa, bileşenlerdeki gereksiz başlangıçtaki sıfırları kaldırarak ve çift noktalı söz dizimini kullanarak sıfır bileşenlerini daraltarak ana makine adını normalleştirin. Örneğin [2001:0db8:0000::1], [2001:db8::1] biçimine dönüştürülmelidir. Ana makine adı aşağıdaki iki özel IPv6 adres türünden biriyse bunları IPv4'e dönüştürün:
   • 1.2.3.4 biçimine dönüştürülmesi gereken [::ffff:1.2.3.4] gibi, IPv4 ile eşlenmiş bir IPv6 adresi;
   • İyi bilinen 64:ff9b::/96 ön ekini (ör. [64:ff9b::1.2.3.4]) kullanan ve 1.2.3.4 biçimine dönüştürülmesi gereken bir NAT64 adresi.
5. Dizenin tamamını küçük harfle yazın.

Yolu standartlaştırmak için:

1. /./ değerini / ile değiştirerek ve önceki yol bileşeniyle birlikte /../'ı kaldırarak yoldaki /../ ve /./ dizilerini çözümleyin.
2. Art arda gelen eğik çizgileri tek bir eğik çizgi karakteriyle değiştirin.

Bu yol standartlaştırmalarını sorgu parametrelerine uygulamayın.

URL'de <= ASCII 32, >= 127, # veya % olan tüm karakterlerde yüzde çıkışı kullanılmamalıdır. Çıkışlar büyük on altılık karakterler kullanmalıdır.

Ana Makine-Sonek Yol-Önek İfadeleri

URL standartlaştırıldıktan sonra, sıradaki adım son ek/önek ifadeleri oluşturmaktır. Her son ek/önek ifadesi, bir ana makine soneki (veya tam ana makine) ve bir yol ön ekinden (veya tam yol) oluşur.

İstemci, 30 farklı ana makine son eki ve yol ön eki kombinasyonu oluşturur. Bu kombinasyonlar, URL'nin yalnızca ana makine ve yol bileşenlerini kullanır. Şema, kullanıcı adı, şifre ve bağlantı noktası silinir. URL, sorgu parametreleri içeriyorsa en az bir kombinasyon tam yolu ve sorgu parametrelerini içerir.

Ana makine için istemci en çok beş farklı dizeyi dener. Bunlar:

• Ana makine adı IPv4 veya IPv6 sabit değeri değilse eTLD+1 alanıyla başlayıp art arda gelen bileşenler eklenerek en fazla dört ana makine adı oluşturulur. eTLD+1'in belirlenmesinde Genel Son Ek Listesi temel alınmalıdır. Örneğin a.b.example.com, example.com eTLD+1 alanının yanı sıra ek bir ana makine bileşeni b.example.com ile sonuçlanır.
• URL'deki tam ana makine adı. Önceki örneğe göre, a.b.example.com kontrol edilir.

Yol için, istemci en çok altı farklı dize dener. Bunlar:

• Sorgu parametreleri dahil URL'nin tam yolu.
• Sorgu parametreleri olmadan URL'nin tam yolu.
• Kökten (/) başlayıp sondaki eğik çizgi dahil olmak üzere sırayla yol bileşenlerinin eklenmesiyle oluşturulan dört yol.

Aşağıdaki örneklerde denetleme davranışı gösterilmektedir:

İstemci, http://a.b.com/1/2.html?param=1 URL'si için şu olası dizeleri dener:

a.b.com/1/2.html?param=1
a.b.com/1/2.html
a.b.com/
a.b.com/1/
b.com/1/2.html?param=1
b.com/1/2.html
b.com/
b.com/1/

İstemci, http://a.b.c.d.e.f.com/1.html URL'si için şu olası dizeleri dener:

a.b.c.d.e.f.com/1.html
a.b.c.d.e.f.com/
c.d.e.f.com/1.html
c.d.e.f.com/
d.e.f.com/1.html
d.e.f.com/
e.f.com/1.html
e.f.com/
f.com/1.html
f.com/

(Not: Yalnızca son beş ana makine adı bileşenini ve tam ana makine adını alacağımızdan b.c.d.e.f.com işlemini atlayın.)

İstemci, http://1.2.3.4/1/ URL'si için şu olası dizeleri dener:

1.2.3.4/1/
1.2.3.4/

İstemci, http://example.co.uk/1 URL'si için şu olası dizeleri dener:

example.co.uk/1
example.co.uk/

Karma oluşturma

Google Güvenli Tarama, karma işlevi olarak yalnızca SHA256'yı kullanır. Bu karma işlevi, yukarıdaki ifadelere uygulanmalıdır.

Tam 32 baytlık karma, koşullara bağlı olarak 4 bayt, 8 veya 16 bayt olarak kısaltılır:

• hashes.search yöntemini kullanırken, şu anda istekteki karmaların tam olarak 4 bayta kısaltılması gerekmektedir. Bu istekte ek bayt göndermek kullanıcı gizliliğini tehlikeye atar.

• hashList.get yöntemi veya hashLists.batchGet yöntemi kullanılarak yerel veritabanı için listeler indirilirken, sunucu tarafından gönderilen karmaların uzunluğu, hem listenin yapısından hem de istemcinin desired_hash_length parametresiyle iletilen karma uzunluğu tercihinden etkilenir.

Gerçek Zamanlı URL Kontrol Yordamı

Bu prosedür, istemci gerçek zamanlı çalışma modunu seçtiğinde kullanılır.

Bu prosedür tek bir URL (u) alır ve SAFE, UNSAFE veya UNSURE sonucunu döndürür. SAFE sonucunu döndürürse URL, Google Güvenli Tarama tarafından güvenli olarak kabul edilir. UNSAFE döndürürse, URL Google Güvenli Tarama tarafından potansiyel olarak güvenli olmadığı kabul edilir ve uygun işlem yapılmalıdır: Son kullanıcıya bir uyarı göstermek, alınan bir iletiyi spam klasörüne taşımak veya devam etmeden önce kullanıcının ek onayı istemesi. UNSURE değerini döndürürse daha sonra aşağıdaki yerel kontrol prosedürü kullanılmalıdır.

1. expressions, u URL'si tarafından oluşturulan son ek/önek ifadeleri listesi olsun.
2. expressionHashes öğesinin, expressions içindeki her ifadenin SHA256 karmaları olduğu bir liste olsun.
3. Her expressionHashes hash için:
   1. hash genel önbellekte bulunabilirse UNSURE değerini döndürün.
4. expressionHashPrefixes öğesinin, expressionHashes içindeki her bir karmanın ilk 4 baytı olduğu bir liste olsun.
5. Her expressionHashPrefixes expressionHashPrefix için:
   1. Yerel önbellekte expressionHashPrefix araması yapın.
   2. Önbelleğe alınan giriş bulunursa:
      1. Geçerli zamanın, geçerlilik süresinden daha uzun olup olmadığını belirleyin.
      2. Daha büyükse:
         1. Bulunan önbelleğe alınmış girişi yerel önbellekten kaldırın.
         2. Döngüyle devam edin.
      3. Değer daha büyükse:
         1. Bu expressionHashPrefix öğesini expressionHashPrefixes öğesinden kaldırın.
         2. Önbelleğe alınan girişte expressionHashes içinde karşılık gelen tam karmanın bulunup bulunmadığını kontrol edin.
         3. Bulunursa UNSAFE mesajını döndürün.
         4. Bulunamazsa döngüye devam edin.
   3. Önbelleğe alınmış giriş bulunamazsa döngüye devam edin.
6. RPC SearchHashes veya REST yöntemini hashes.search kullanarak Google Güvenli Tarama v5 sunucusuna expressionHashPrefixes gönderin. Bir hata oluşursa (ağ hataları, HTTP hataları vb. dahil) UNSURE döndürün. Aksi takdirde yanıt, SB sunucusundan alınan response bilgi olsun. Bu, tehdidin niteliğini (sosyal mühendislik, kötü amaçlı yazılım vb.) tanımlayan bazı yardımcı bilgilerle birlikte tam karmaların bir listesi ve önbellek geçerlilik süresinin expiration olduğu bir tam karmadır.
7. Her response fullHash için:
   1. fullHash kodunu expiration ile birlikte yerel önbelleğe ekleyin.
8. Her response fullHash için:
   1. expressionHashes öğesinde fullHash bulmanın sonucu isFound olsun.
   2. isFound Yanlış ise döngüye devam edin.
   3. isFound Doğru ise UNSAFE değerini döndürün.
9. Dönüş SAFE.

LocalThreat List URL Check Prosedure (Yerel Tehdit Listesi URL'lerini Kontrol Etme Yordamı)

Bu prosedür, istemci yerel liste çalışma modunu tercih ettiğinde kullanılır. Ayrıca, yukarıdaki RealTimeCheck prosedürü istemcisi UNSURE değerini döndürdüğünde de kullanılır.

Bu prosedür tek bir URL (u) alır ve SAFE veya UNSAFE değerini döndürür.

1. expressions, u URL'si tarafından oluşturulan son ek/önek ifadeleri listesi olsun.
2. expressionHashes öğesinin, expressions içindeki her ifadenin SHA256 karmaları olduğu bir liste olsun.
3. expressionHashPrefixes öğesinin, expressionHashes içindeki her bir karmanın ilk 4 baytı olduğu bir liste olsun.
4. Her expressionHashPrefixes expressionHashPrefix için:
   1. Yerel önbellekte expressionHashPrefix araması yapın.
   2. Önbelleğe alınan giriş bulunursa:
      1. Geçerli zamanın, geçerlilik süresinden daha uzun olup olmadığını belirleyin.
      2. Daha büyükse:
         1. Bulunan önbelleğe alınmış girişi yerel önbellekten kaldırın.
         2. Döngüyle devam edin.
      3. Değer daha büyükse:
         1. Bu expressionHashPrefix öğesini expressionHashPrefixes öğesinden kaldırın.
         2. Önbelleğe alınan girişte expressionHashes içinde karşılık gelen tam karmanın bulunup bulunmadığını kontrol edin.
         3. Bulunursa UNSAFE mesajını döndürün.
         4. Bulunamazsa döngüye devam edin.
   3. Önbelleğe alınmış giriş bulunamazsa döngüye devam edin.
5. Her expressionHashPrefixes expressionHashPrefix için:
   1. Yerel tehdit listesi veritabanında expressionHashPrefix araması yapın.
   2. expressionHashPrefix, yerel tehdit listesi veritabanında bulunamazsa expressionHashPrefixes hizmetinden kaldırın.
6. RPC SearchHashes veya REST yöntemini hashes.search kullanarak Google Güvenli Tarama v5 sunucusuna expressionHashPrefixes gönderin. Bir hata oluşursa (ağ hataları, HTTP hataları vb. dahil) SAFE döndürün. Aksi takdirde yanıt, SB sunucusundan alınan response bilgi olsun. Bu, tehdidin niteliğini (sosyal mühendislik, kötü amaçlı yazılım vb.) tanımlayan bazı yardımcı bilgilerle birlikte tam karmaların bir listesi ve önbellek geçerlilik süresinin expiration olduğu bir tam karmadır.
7. Her response fullHash için:
   1. fullHash kodunu expiration ile birlikte yerel önbelleğe ekleyin.
8. Her response fullHash için:
   1. expressionHashes öğesinde fullHash bulmanın sonucu isFound olsun.
   2. isFound Yanlış ise döngüye devam edin.
   3. isFound Doğru ise UNSAFE değerini döndürün.
9. Dönüş SAFE.

Yerel Veritabanı Olmadan Gerçek Zamanlı URL Kontrol Prosedürü

Bu prosedür, istemci depolama alanı olmayan gerçek zamanlı çalışma modunu seçtiğinde kullanılır.

Bu prosedür tek bir URL (u) alır ve SAFE veya UNSAFE değerini döndürür.

1. expressions, u URL'si tarafından oluşturulan son ek/önek ifadeleri listesi olsun.
2. expressionHashes öğesinin, expressions içindeki her ifadenin SHA256 karmaları olduğu bir liste olsun.
3. expressionHashPrefixes öğesinin, expressionHashes içindeki her bir karmanın ilk 4 baytı olduğu bir liste olsun.
4. Her expressionHashPrefixes expressionHashPrefix için:
   1. Yerel önbellekte expressionHashPrefix araması yapın.
   2. Önbelleğe alınan giriş bulunursa:
      1. Geçerli zamanın, geçerlilik süresinden daha uzun olup olmadığını belirleyin.
      2. Daha büyükse:
         1. Bulunan önbelleğe alınmış girişi yerel önbellekten kaldırın.
         2. Döngüyle devam edin.
      3. Değer daha büyükse:
         1. Bu expressionHashPrefix öğesini expressionHashPrefixes öğesinden kaldırın.
         2. Önbelleğe alınan girişte expressionHashes içinde karşılık gelen tam karmanın bulunup bulunmadığını kontrol edin.
         3. Bulunursa UNSAFE mesajını döndürün.
         4. Bulunamazsa döngüye devam edin.
   3. Önbelleğe alınmış giriş bulunamazsa döngüye devam edin.
5. RPC SearchHashes veya REST yöntemini hashes.search kullanarak Google Güvenli Tarama v5 sunucusuna expressionHashPrefixes gönderin. Bir hata oluşursa (ağ hataları, HTTP hataları vb. dahil) SAFE döndürün. Aksi takdirde yanıt, SB sunucusundan alınan response bilgi olsun. Bu, tehdidin niteliğini (sosyal mühendislik, kötü amaçlı yazılım vb.) tanımlayan bazı yardımcı bilgilerle birlikte tam karmaların bir listesi ve önbellek geçerlilik süresinin expiration olduğu bir tam karmadır.
6. Her response fullHash için:
   1. fullHash kodunu expiration ile birlikte yerel önbelleğe ekleyin.
7. Her response fullHash için:
   1. expressionHashes öğesinde fullHash bulmanın sonucu isFound olsun.
   2. isFound Yanlış ise döngüye devam edin.
   3. isFound Doğru ise UNSAFE değerini döndürün.
8. Dönüş SAFE.

Yerel Veritabanı Bakımı

Google Güvenli Tarama v5, istemcinin Depolama Alanı Yok Gerçek Zamanlı Modunu seçtiği durumlar haricinde, istemcinin yerel bir veritabanı tutmasını bekler. Bu yerel veritabanının biçimine ve depolamasına istemci bağlıdır. Bu yerel veritabanının içeriği, kavramsal olarak dosya şeklinde çeşitli listeler içeren bir klasör olarak düşünülebilir. Bu dosyaların içeriği, SHA256 karmaları veya karma önekleridir.

Veritabanı Güncellemeleri

İstemci, veritabanını güncellemek için düzenli olarak hashList.get yöntemini veya hashLists.batchGet yöntemini çağırır. Tipik bir müşteri aynı anda birden çok listeyi güncellemek isteyeceğinden hashLists.batchGet yönteminin kullanılması önerilir.

Listeler farklı adlarıyla tanımlanır. Adlar, birkaç karakter uzunluğunda kısa ASCII dizeleridir.

Listelerin tehdit türü, platform türü, tehdit girişi türü de dahil olmak üzere tanımlandığı V4’ten farklı olarak v5 listeleri yalnızca adla tanımlanır. Bu, birden fazla v5 listesinin aynı tehdit türünü paylaşabileceği durumlarda esneklik sağlar. Platform türleri ve tehdit giriş türleri v5'te kaldırılmıştır.

Liste için bir ad seçildikten sonra, bu liste hiçbir zaman yeniden adlandırılmaz. Dahası, bir liste göründüğünde hiçbir zaman kaldırılmaz (liste artık yararlı değilse, boş hale gelir ancak var olmaya devam eder). Bu nedenle, bu adları Google Güvenli Tarama istemci koduna sabit bir şekilde kodlamak uygundur.

Hem hashList.get yöntemi hem de hashLists.batchGet yöntemi artımlı güncellemeleri destekler. Artımlı güncellemeleri kullanmak bant genişliğinden tasarruf etmenizi sağlar ve performansı artırır. Artımlı güncellemeler, istemcinin liste sürümü ile listenin en son sürümü arasında bir delta sunarak çalışır. (Bir istemci yeni dağıtıldıysa ve kullanılabilir bir sürümü yoksa tam bir güncelleme mevcuttur.) Artımlı güncelleme, kaldırma dizinlerini ve eklemeleri içerir. İlk olarak istemcinin, belirtilen dizinlerdeki girişleri yerel veritabanından kaldırması ve ardından eklemeleri uygulaması beklenir.

Son olarak, bozulmayı önlemek için istemci, depolanan verileri sunucu tarafından sağlanan sağlama toplamıyla kontrol etmelidir. Sağlama eşleşmediğinde, istemci tam bir güncelleme yapmalıdır.

Liste İçeriğinin Kodunu Çözme

Tüm listeler, boyutu küçültmek için özel bir kodlama kullanılarak yayınlanır. Bu kodlama, Google Güvenli Tarama listelerinin kavramsal olarak rastgele tam sayılardan istatistiksel olarak ayırt edilemeyen bir karmalar veya karma önekler kümesi içerdiğini algılayarak çalışır. Bu tam sayıları sıralayıp bitişik farklarını alırsak, bu bitişik farkın bir anlamda "küçük" olması beklenir. Daha sonra Golomb-Rice kodlaması, bu küçüklüğü kötüye kullanır.

Google Güvenli Tarama sürüm 5, 4 bayt, 8 bayt, 16 ve 32 baytlık verileri işlemek için 4 farklı türe sahiptir. Sayısal olarak ardışık üç 4 baytlık tam sayının kodlandığı bir örneği inceleyelim. k ile belirtilen Pirinç parametresinin değeri 3 olsun. Kodlamanın bölüm bölümü, k bit tarafından sağa kaydırılmış bitişik fark değeridir. Verilen tam sayılar ardışık olduğundan, bitişik farkları 1'dir ve 3 bit yer değiştirdikten sonra bölme kısmı sıfır olur. En az anlamlı k bitler 001'dir. Sıfır bölümü, tek bir 0 bit olarak kodlanır. Kalan değer 1'dir ve 100 olarak kodlanır. Bu işlem tekrarlanarak 01000100 bit akışını oluşturur. Ortaya çıkan bit akışı, 00100010 gibi küçük endian kullanılarak kodlanır. Dolayısıyla aşağıdaki verilere karşılık gelir:

rice_parameter: 3
entries_count: 2
encoded_data: "\x22"

32 bit tam sayılar için yukarıdaki kod çözme adımından sonra sonuç doğrudan kaldırma dizinleri veya eklemeler olarak kullanılabilir. v4 sürümünden farklı olarak, daha sonra bir bayt değiştirme işlemi gerçekleştirmenize gerek yoktur.

Kullanılabilir Listeler

v5alpha1'de aşağıdaki listelerin kullanılması önerilir:

Liste Adı	Karşılık gelen v4 ThreatType Enum	Açıklama
gc	Yok	Bu liste bir Genel Önbellek listesidir. Bu, yalnızca Gerçek Zamanlı çalışma modunda kullanılan özel bir listedir.
se	SOCIAL_ENGINEERING	Bu liste, SOCIAL_ENGINEERING tehdit türünde tehditler içeriyor.
mw	MALWARE	Bu liste, masaüstü platformlar için KÖTÜ AMAÇLI YAZILIM tehdit türündeki tehditleri içermektedir.
uws	UNWANTED_SOFTWARE	Bu liste, masaüstü platformlar için UNWANTED_SOFTWARE tehdit türü tehditleri içeriyor.
uwsa	UNWANTED_SOFTWARE	Bu liste, Android platformları için UNWANTED_SOFTWARE tehdit türü tehditleri içeriyor.
pha	POTENTIALLY_HARMFUL_APPLICATION	Bu liste, Android platformları için POTENTIALLY_HARMFUL_APPLICATION tehdit türü tehditleri içeriyor.

Daha sonraki bir tarihte ek listeler kullanıma sunulacak ve bu tarihte yukarıdaki tablo genişletilecektir.

Güncelleme Sıklığı

İstemci, sunucunun minimum_wait_duration alanında döndürülen değerini incelemeli ve veritabanının bir sonraki güncellemesini planlamak için bunu kullanmalıdır. Bu değer büyük olasılıkla sıfırdır. Bu durumda, istemci hemen başka bir güncelleme gerçekleştirmelidir.

Örnek İstekler

Bu bölümde, Google Güvenli Tarama'ya erişmek için doğrudan HTTP API'nin kullanılmasına ilişkin bazı örnekler açıklanmaktadır. Kodlama ve kod çözme işlemlerini otomatik olarak kolay bir şekilde halledeceği için genellikle oluşturulmuş bir dil bağlamanın kullanılması önerilir. Lütfen bu bağlamayla ilgili dokümanlara bakın.

hashes.search yöntemini kullanan bir HTTP isteği örneğini burada bulabilirsiniz:

GET https://safebrowsing.googleapis.com/v5/hashes:search?key=INSERT_YOUR_API_KEY_HERE&hashPrefixes=WwuJdQ

Yanıt gövdesi, daha sonra kodunu çözebileceğiniz protokol arabelleği biçimlendirilmiş bir yüktür.

hashLists.batchGet yöntemini kullanan bir örnek HTTP isteği aşağıda verilmiştir:

GET https://safebrowsing.googleapis.com/v5alpha1/hashLists:batchGet?key=INSERT_YOUR_API_KEY_HERE&names=se&names=mw

Yanıt gövdesi de yine, daha sonra kodunu çözebileceğiniz protokol-arabelleği biçimlendirilmiş bir yüktür.

Taşıma Rehberi

Şu anda v4 Update API'yi kullanıyorsanız yerel veritabanını sıfırlamak veya silmek zorunda kalmadan v4'ten v5'e sorunsuz bir taşıma yolu mevcuttur. Bu bölümde, bunun nasıl yapılacağı açıklanmaktadır.

Liste Güncellemelerini Dönüştürme

v4'te listeler indirmek için threatListUpdates.fetch yöntemi kullanılır. v5'te, hashLists.batchGet yöntemine geçilir.

İstekte aşağıdaki değişiklikler yapılmalıdır:

1. v4 ClientInfo nesnesini tamamen kaldırın. İstemcinin kimliğini özel bir alan kullanarak sağlamak yerine bilinen Kullanıcı Aracısı üstbilgisini kullanabilirsiniz. Bu üstbilgide istemci kimliğini sağlamak için belirlenmiş bir biçim olmasa da, orijinal istemci kimliğini ve istemci sürümünü boşluk veya eğik çizgi karakteriyle ayrılmış olarak eklemenizi öneririz.
2. Her bir v4 ListUpdateRequest nesnesi için:
   • Yukarıdaki tabloda ilgili v5 listesinin adını arayın ve v5 isteğinde bu adı sağlayın.
   • threat_entry_type veya platform_type gibi gereksiz alanları kaldırın.
   • v4'teki state alanı, v5 versions alanıyla doğrudan uyumludur. v4'te state alanı kullanılarak sunucuya gönderilecek olan bayt dizesinin aynısı, versions alanı kullanılarak v5'te de gönderilebilir.
   • v5 kısıtlamaları için SizeConstraints adlı basitleştirilmiş bir sürüm kullanır. region gibi ek alanlar atlanmalıdır.

Yanıtta aşağıdaki değişiklikler yapılmalıdır:

1. v4 enum ResponseType, partial_update adlı bir boole alanıyla değiştirilir.
2. minimum_wait_duration alanı artık sıfır olabilir veya atlanabilir. Etkinse müşterinin hemen başka bir istekte bulunması istenir. Bu durum yalnızca istemci, SizeConstraints için maksimum güncelleme boyutunda maksimum veritabanı boyutundan daha küçük bir kısıtlama belirlediğinde ortaya çıkar.
3. 32 bit tam sayılar için Pirinç kod çözme algoritmasının ayarlanması gerekir. Aralarındaki fark, kodlanmış verilerin farklı bir bitiş değeriyle kodlanmış olmasıdır. 32 bitlik karma önekler hem v4 hem de v5'te sözlüksel olarak sıralanır. Ancak v4'te bu önekler sıralandıklarında küçük endian olarak, v5'te ise sıralandıklarında büyük endian olarak değerlendirilir. Sözlüksel sıralama, büyük endian ile sayısal sıralama ile aynı olduğundan, müşterinin herhangi bir sıralama yapmasına gerek yoktur. Chromium sürüm 4 uygulamasındaki bu sıralamanın bir örneğini burada bulabilirsiniz. Bu tür sıralama kaldırılabilir.
4. Diğer karma uzunlukları için Pirinç kod çözme algoritmasının uygulanması gerekir.

Karma Aramalarını Dönüştürme

v4 sürümünde, tam karmaları almak için fullHashes.find yöntemi kullanılır. v5'teki eşdeğer yöntem hashes.search yöntemidir.

İstekte aşağıdaki değişiklikler yapılmalıdır:

1. Kodu, yalnızca tam olarak 4 bayt uzunluğundaki karma önekleri gönderecek şekilde yapılandırın.
2. v4 ClientInfo nesnelerini tamamen kaldırın. İstemcinin kimliğini özel bir alan kullanarak sağlamak yerine bilinen Kullanıcı Aracısı üstbilgisini kullanabilirsiniz. Bu üstbilgide istemci kimliğini sağlamak için belirlenmiş bir biçim olmasa da, orijinal istemci kimliğini ve istemci sürümünü boşluk veya eğik çizgi karakteriyle ayrılmış olarak eklemenizi öneririz.
3. client_states alanını kaldırın. Buna artık gerek yoktur.
4. Artık threat_types ve benzer alanların eklenmesine gerek yoktur.

Yanıtta aşağıdaki değişiklikler yapılmalıdır:

1. minimum_wait_duration alanı kaldırıldı. Müşteri, gerektiğinde yeni bir istek gönderebilir.
2. v4 ThreatMatch nesnesi FullHash nesnesi olarak basitleştirildi.
3. Önbelleğe alma, tek bir önbellek süresi halinde basitleştirilmiştir. Önbellekle etkileşime geçmek için yukarıdaki yordamlara bakın.