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ş halidir. 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ırmak, fazlalıkları azaltmak için iyileştirildi. Ayrıca Google Güvenli Tarama sürüm 5, v4'ten taşımayı kolaylaştırmak için tasarlanmıştır.

Şu anda Google hem v4 hem de v5'i sunmaktadır ve bunların her ikisi de üretime hazır olarak kabul edilmektedir. v4 veya v5 sürümünü kullanabilirsiniz. v4'ün kullanımdan kaldırılacağı tarihi duyurmadık; bunu yaparsak en az bir yıl önceden 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, veri 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, eksik korumanın ana nedeni yerel veritabanı güncellemesinin gecikmesi ve boyutudur. Sürüm 4'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ı hızla yayılıyor: 2021 itibarıyla saldırı gönderen sitelerin% 60'ı 10 dakikadan daha kısa süre yayında. Analizlerimiz, kimlik avına karşı korumada eksikliklerin 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, yukarıdaki veri eskiliği sorununu atlatmaktadır. v4'te, müşterilerin yerel veritabanı indirip bakımını, yerel olarak indirilen tehdit listeleriyle karşılaştırmalı olarak kontroller yapmaları ve kısmi ön ek eşleşmesi olduğunda tam karmayı indirme isteği gerçekleştirmesi beklenir. v5'te, müşterilerin tehdit listelerinden oluşan yerel bir veritabanını indirip barındırmaya devam etmesi gerekse de, müşterilerin artık kötü niyetli sitelerin bir listesini (Global Önbellek adı verilir) indirmeleri, bu Global Önbellek için yerel bir denetim ile yerel tehdit listesi kontrolü gerçekleştirmeleri ve son olarak, tehdit listeleri için kısmi bir ön ek eşleşmesi veya Genel Önbellek'te bir eşleşme olmaması durumunda, karmaların tamamını indirmek için bir istek gerçekleştirmesi beklenir. (Müşterinin gerektirdiği yerel işleme ayrıntıları için lütfen aşağıda sağlanan prosedüre bakın.) Bu, "varsayılan olarak izin ver"den varsayılan olarak kontrol et"e geçişi temsil eder. Bu da tehditlerin web'de daha hızlı yayılması halinde korumayı iyileştirebilir. 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çlıyoruz.

IP Gizliliği

Google Güvenli Tarama (v4 veya v5), istekleri sunarken kullanıcının kimliğiyle ilgili hiçbir şeyi işlemez. Gönderildiği takdirde çerezler yok sayılır. İsteklerin kaynak IP adresleri Google tarafından bilinse de Google, bu IP adreslerini yalnızca temel ağ ihtiyaçları (ör. yanıt gönderme) ve DoS karşıtı amaçlar için kullanır.

v5 ile eşzamanlı olarak, Safe Browsing Oblivious HTTP Gateway API'si olarak bilinen tamamlayıcı API'yi kullanıma sunduk. Bu özellik, son kullanıcıların IP adreslerini Google'dan gizlemek için Zorunlu HTTP'yi kullanır. Bu yöntem, kullanıcı isteğinin şifrelenmiş bir sürümünü işlemesi ve ardından bunu Google'a iletmesi için işbirliği yapmayan bir üçüncü tarafa sahip olmasıyla çalışır. Dolayısıyla üçüncü taraf yalnızca IP adreslerine erişebilir, Google ise yalnızca isteğin içeriğine erişebilir. Üçüncü taraf, habersiz HTTP geçişini (Fastly'nin sunduğu bu hizmet gibi) çalıştırır ve Google, habersiz HTTP ağ geçidini çalıştırır. Bu, isteğe bağlı bir tamamlayıcı API'dir. Google Güvenli Tarama ile birlikte kullanıldığında 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ım içindir ("satış veya gelir oluşturma amacıyla değil"). Ticari amaçlarla kullanıma yönelik bir çözüme ihtiyacınız varsa lütfen Web Riski'ne bakın.

Fiyatlandırma

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

Kotalar

Geliştiricilere, Safe Browsing API'yi etkinleştirdikten sonra varsayılan bir kullanım kotası verilir. Mevcut tahsis ve kullanım Google Developer Console'da görüntülenebilir. Şu anda ayrılan kotadan daha fazla kota kullanmayı düşünüyorsanız Developer Console'un Kota arayüzünden ek kota talep edebilirsiniz. Bu istekleri inceleriz ve kota artışına başvururken, hizmet kullanılabilirliğimizin tüm kullanıcıların ihtiyaçlarını karşıladığından emin olmak için bir kişiyle iletişim kurulması gerekir.

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 (HTML dosyası tarafından başvurulan JavaScript veya resim ya da JavaScript tarafından başlatılan bir WebSocket URL'si gibi) ile karşılaştırma yapmak için kullanılmak üzere tasarlanmamıştır. Bu tür alt kaynak URL'leri, Google Güvenli Tarama'da kontrol edilmemelidir.

Bir URL'nin ziyaret edilmesi yönlendirmeyle (HTTP 301 gibi) sonuçlanıyorsa yönlendirilen URL'nin Google Güvenli Tarama'da kontrol edilmesi uygundur. History.pushState gibi istemci tarafı URL manipülasyonları, yeni URL'lerin Google Güvenli Tarama'ya göre kontrol edilmesine yol açmaz.

Kullanıcı Uyarıları

Kullanıcıları belirli web sayfalarındaki riskler hakkında uyarmak için Google Güvenli Tarama'yı kullanırsanız aşağıdaki yönergeler geçerli olur.

Bu yönergeler, sayfanın güvenli olmayan bir web kaynağı olarak% 100 kesinlikle bilinmediğini ve uyarıların yalnızca olası riski tanımladığını göstererek hem sizin hem de Google'ın yanlış anlaşılmalara karşı korunmasına yardımcı olur.

• Kullanıcılar tarafından görülebilen uyarınızda, kullanıcıları söz konusu sayfanın güvenli olmayan bir web kaynağı olduğuna inandırmaya yönlendirmemeniz gerekir. Tanımlanan sayfadan veya bu sayfanın kullanıcılara oluşturabileceği potansiyel risklerden bahsettiğinizde, uyarının niteliğini şu gibi terimlerle belirtmeniz gerekir: şüpheli, potansiyel, olası, muhtemel, olabilir.
• Aldığınız uyarı, Google'ın çeşitli tehditler tanımını inceleyerek kullanıcının 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
  • Potansiyel Zararlı 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ı bağlantısını içeren "Google tarafından sağlanan Uyarı" satırını ekleyerek Google'a atıfta bulunmanız gerekir. Ürününüz başka kaynaklara dayalı olarak da uyarılar gösteriyorsa Google'a ait olmayan verilerden türetilen 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ı bildirmek için bir bildirim sunmanız gerekir. Kuruluş, hem yanlış pozitif (riskli olarak işaretlenmiş güvenli siteler) hem de yanlış negatif (riskli siteler işaretlenmemiş) olma ihtimalinin 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. Bununla birlikte, Google, sağladığı bilgilerin kapsamlı ve hatasız olduğunu garanti edemez: Bazı riskli siteler tespit edilmeyebilir ve bazı güvenli siteler yanlışlıkla tespit edilebilir.

Çalışma Şekilleri

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çtiğinde, müşteriler yerel veritabanlarında şunları muhafaza eder: (i) SHA256 ana makine-sonek/yol ön eki URL ifadeleri karmaları olarak biçimlendirilmiş iyi huylu sitelerin Genel Önbelleği, (ii) ana makine-ek eki/yol ön eki URL ifadelerinin SHA256 karma önekleri olarak biçimlendirilmiş bir dizi tehdit listesi. Üst düzey fikir, müşteri belirli bir URL'yi kontrol etmek istediğinde, Genel Önbellek kullanılarak yerel bir denetim yapılmasıdır. Bu kontrol başarılı olursa yerel tehdit listesi kontrolü 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ı bir spesifikasyonu aşağıda bulabilirsiniz.

Yerel Liste Modu

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

Yukarıda olduğu gibi istemci de kalıcı depolama alanında olması gerekmeyen yerel bir önbellek sağlar.

Depolama Yok Gerçek Zamanlı Modu

İstemciler Google Güvenli Tarama v5'i depolama alanı yok gerçek zamanlı modunda kullanmayı seçtiğinde, istemcinin kalıcı bir yerel veritabanı tutması gerekmez. Ancak, istemcinin yine de yerel bir önbelleği tutması beklenir. Bu tür bir yerel önbelleğin, kalıcı depolama alanında olması gerekmez ve bellek yetersizliği durumunda temizlenebilir.

İstemci belirli bir URL'yi kontrol etmek istediğinde, istemci kontrol gerçekleştirmek için her zaman sunucuya bağlanır. Bu mod, v4 Lookup API istemcilerinin kullanabileceğine benzer.

Gerçek Zamanlı Mod'la karşılaştırıldığında, bu mod daha fazla ağ bant genişliği kullanabilir ancak istemcinin kalıcı yerel durumu sürdürmesi uygun değilse daha uygun olabilir.

URL'ler kontrol ediliyor

Bu bölümde, müşterilerin URL'leri nasıl kontrol ettiğine dair ayrıntılı spesifikasyonlar yer almaktadır.

URL'leri standartlaştırma

Herhangi bir URL kontrol edilmeden önce, müşterinin bu URL'de birtakım 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 varsayarız. URL, uluslararası hale getirilmiş bir alan adı (IDN) kullanıyorsa, istemci, URL'yi ASCII Punycode temsiline dönüştürmelidir. URL, bir yol bileşeni içermelidir. Yani alan adından sonra en az bir eğik çizgi içermelidir (http://google.com yerine http://google.com/).

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

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

Üçüncü olarak, daha fazla yüzde çıkış değeri kalmayana kadar URL'de tekrar tekrar yüzde çıkış karakteri kullanın. (Bu, URL'yi geçersiz hale getirebilir.)

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

Ana makine adını URL'den çı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 noktayla ayrılmış 4 ondalık değere göre normalleştirin. İstemci; sekizlik, onaltılık ve dörtten az bileşen dahil olmak üzere tüm yasal IP adresi kodlamalarını işlemelidir.
4. Ana makine adı köşeli parantezli bir IPv6 adresi olarak ayrıştırılabiliyorsa bileşenlerdeki gereksiz baştaki sıfırları kaldırarak ve iki nokta üst üste söz dizimini kullanarak sıfır bileşenleri daraltarak 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 adresi 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 eşlenmiş bir IPv6 adresi;
   • [64:ff9b::1.2.3.4] gibi bilinen ön eki 64:ff9b::/96 kullanan ve 1.2.3.4 biçimine dönüştürülmesi gereken bir NAT64 adresi.
5. Tüm dizeyi küçük harfle yazın.

Yolu standartlaştırmak için:

1. /./ öğesini / ile değiştirip /../ öğesini önceki yol bileşeniyle birlikte kaldırarak yoldaki /../ ve /./ sıralarını çözümleyin.
2. Art arda eğik çizgi sayısını 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 kaçış karakteri ekleyin. Kod dışına alma karakterleri büyük harfli onaltılık karakterler kullanmalıdır.

Ana Makine-Sonek Yol-Önek İfadeleri

URL standartlaştırıldıktan sonraki adım sonek/önek ifadelerini oluşturmaktır. Her son ek/önek ifadesi, bir ana makine son ekinden (veya tam ana makine) ve bir yol ön ekinden (veya tam yoldan) oluşur.

İstemci en fazla 30 farklı olası ana makine son eki ve yol öneki kombinasyonu oluşturur. Bu kombinasyonlar, yalnızca URL'nin 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 yol ve sorgu parametrelerini içerir.

Ana makine için istemci en fazla beş farklı dize dener. Bunlar:

• Ana makine adı bir IPv4 veya IPv6 hazır değeri değilse eTLD+1 alanıyla başlayıp art arda öncü 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 bir ek ana makine bileşeni b.example.com olan ana makineyle 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 fazla altı farklı dize dener. Bunlar:

• URL'nin sorgu parametreleri dahil tam yolu.
• URL'nin sorgu parametreleri olmadan tam yolu.
• Kökten (/) başlayıp ardından gelen eğik çizgi dahil olmak üzere yol bileşenlerini ekleyerek oluşturulan dört yol.

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

http://a.b.com/1/2.html?param=1 URL'si için istemci ş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/

http://a.b.c.d.e.f.com/1.html URL'si için istemci ş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.)

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

1.2.3.4/1/
1.2.3.4/

http://example.co.uk/1 URL'si için istemci ş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.

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

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

• hashList.get yöntemini veya hashLists.batchGet yöntemini kullanarak yerel veritabanı için listeleri indirirken, sunucu tarafından gönderilen karmaların uzunluğu hem listenin yapısından hem de istemcinin desired_hash_length parametresi tarafından iletilen karma uzunluğu tercihinden etkilenir.

Gerçek Zamanlı URL Kontrol Prosedürü

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 değerini döndürür. SAFE sonucunu döndürürse URL, Google Güvenli Tarama tarafından güvenli kabul edilir. UNSAFE değerini döndürürse URL, Google Güvenli Tarama tarafından güvenli olmayabileceği kabul edilir ve uygun işlem yapılır. Örneğin, son kullanıcıya uyarı gösterebilir, alınan bir iletiyi spam klasörüne taşıyabilir veya devam etmeden önce kullanıcıdan ek onay alınmasını zorunlu kılabilirsiniz. UNSURE değerini döndürürse daha sonra aşağıdaki yerel kontrol prosedürü uygulanmalıdır.

1. expressions öğesinin, u URL'si tarafından oluşturulan sonek/önek ifadelerinin bir listesi olmasına izin verin.
2. expressionHashes öğesinin, expressions içindeki her ifadenin SHA256 karmaları olduğu bir liste olsun.
3. Her bir expressionHashes/hash için:
   1. Genel önbellekte hash 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 bir expressionHashPrefixes/expressionHashPrefix için:
   1. Yerel önbellekte expressionHashPrefix araması yapın.
   2. Önbelleğe alınan giriş bulunursa:
      1. Geçerli zamanın, son kullanma zamanından 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üye devam edin.
      3. Bu değer daha yüksek değilse:
         1. Bu expressionHashPrefix öğesini expressionHashPrefixes öğesinden kaldırın.
         2. expressionHashes öğesindeki karşılık gelen tam karmanın, önbelleğe alınan girişte bulunup bulunmadığını kontrol edin.
         3. Bulunursa UNSAFE sonucunu döndürün.
         4. Bulunamazsa döngüye devam edin.
   3. Önbelleğe alınan giriş bulunamazsa döngüyle devam edin.
6. expressionHashPrefixes öğesini, RPC Arama Karmalarını veya hashes.search REST yöntemini kullanarak Google Güvenli Tarama v5 sunucusuna gönderin. Bir hata oluşursa (ağ hataları, HTTP hataları vb. dahil) UNSURE değerini döndürün. Aksi takdirde, SB sunucusundan alınan response yanıtı, tehdidin yapısını (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üresi (expiration) olsun.
7. Her bir response/fullHash için:
   1. fullHash öğesini expiration ile birlikte yerel önbelleğe ekleyin.
8. Her bir response/fullHash için:
   1. isFound, expressionHashes içinde fullHash öğesini bulmanın sonucu olsun.
   2. isFound, Yanlış değerine ayarlanırsa döngüyle devam edin.
   3. isFound Doğru ise UNSAFE değerini döndürün.
9. Dönüş SAFE.

Bu protokol, istemcinin expressionHashPrefixes dosyasını sunucuya ne zaman göndereceğini belirtse de protokol, bunların nasıl gönderileceğini kasıtlı olarak tam olarak belirtmez. Örneğin, istemcinin tüm expressionHashPrefixes öğelerini tek bir istekte göndermesi kabul edilebilir olduğu gibi, istemcinin de expressionHashPrefixes içindeki her ön eki sunucuya ayrı isteklerde göndermesi (örneğin paralel olarak devam etmesi) da kabul edilebilir. Ayrıca, tek bir istekte gönderilen karma öneklerinin sayısı 30'u aşmadığı sürece, istemcinin expressionHashPrefixes içindeki karma ön ekleriyle birlikte alakasız veya rastgele oluşturulmuş karma öneklerini göndermesi de kabul edilebilir.

Yerel Tehdit Listesi URL'si Kontrol Prosedürü

Bu prosedür, istemci yerel liste çalışma modunu tercih ettiğinde kullanılır. Yukarıdaki RealTimeCheck prosedürü, 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 öğesinin, u URL'si tarafından oluşturulan sonek/önek ifadelerinin bir listesi olmasına izin verin.
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 bir expressionHashPrefixes/expressionHashPrefix için:
   1. Yerel önbellekte expressionHashPrefix araması yapın.
   2. Önbelleğe alınan giriş bulunursa:
      1. Geçerli zamanın, son kullanma zamanından 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üye devam edin.
      3. Bu değer daha yüksek değilse:
         1. Bu expressionHashPrefix öğesini expressionHashPrefixes öğesinden kaldırın.
         2. expressionHashes öğesindeki karşılık gelen tam karmanın, önbelleğe alınan girişte bulunup bulunmadığını kontrol edin.
         3. Bulunursa UNSAFE sonucunu döndürün.
         4. Bulunamazsa döngüye devam edin.
   3. Önbelleğe alınan giriş bulunamazsa döngüyle devam edin.
5. Her bir expressionHashPrefixes/expressionHashPrefix için:
   1. Yerel tehdit listesi veritabanında expressionHashPrefix araması yapın.
   2. expressionHashPrefix, yerel tehdit listesi veritabanında bulunamazsa bunu expressionHashPrefixes öğesinden kaldırın.
6. expressionHashPrefixes öğesini, RPC Arama Karmalarını veya hashes.search REST yöntemini kullanarak Google Güvenli Tarama v5 sunucusuna gönderin. Bir hata oluşursa (ağ hataları, HTTP hataları vb. dahil) SAFE değerini döndürün. Aksi takdirde, SB sunucusundan alınan response yanıtı, tehdidin yapısını (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üresi (expiration) olsun.
7. Her bir response/fullHash için:
   1. fullHash öğesini expiration ile birlikte yerel önbelleğe ekleyin.
8. Her bir response/fullHash için:
   1. isFound, expressionHashes içinde fullHash öğesini bulmanın sonucu olsun.
   2. isFound, Yanlış değerine ayarlanırsa döngüyle 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ı yok" 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 öğesinin, u URL'si tarafından oluşturulan sonek/önek ifadelerinin bir listesi olmasına izin verin.
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 bir expressionHashPrefixes/expressionHashPrefix için:
   1. Yerel önbellekte expressionHashPrefix araması yapın.
   2. Önbelleğe alınan giriş bulunursa:
      1. Geçerli zamanın, son kullanma zamanından 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üye devam edin.
      3. Bu değer daha yüksek değilse:
         1. Bu expressionHashPrefix öğesini expressionHashPrefixes öğesinden kaldırın.
         2. expressionHashes öğesindeki karşılık gelen tam karmanın, önbelleğe alınan girişte bulunup bulunmadığını kontrol edin.
         3. Bulunursa UNSAFE sonucunu döndürün.
         4. Bulunamazsa döngüye devam edin.
   3. Önbelleğe alınan giriş bulunamazsa döngüyle devam edin.
5. expressionHashPrefixes öğesini, RPC Arama Karmalarını veya hashes.search REST yöntemini kullanarak Google Güvenli Tarama v5 sunucusuna gönderin. Bir hata oluşursa (ağ hataları, HTTP hataları vb. dahil) SAFE değerini döndürün. Aksi takdirde, SB sunucusundan alınan response yanıtı, tehdidin yapısını (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üresi (expiration) olsun.
6. Her bir response/fullHash için:
   1. fullHash öğesini expiration ile birlikte yerel önbelleğe ekleyin.
7. Her bir response/fullHash için:
   1. isFound, expressionHashes içinde fullHash öğesini bulmanın sonucu olsun.
   2. isFound, Yanlış değerine ayarlanırsa döngüyle devam edin.
   3. isFound Doğru ise UNSAFE değerini döndürün.
8. Dönüş SAFE.

Gerçek Zamanlı URL Kontrol Prosedürü'nde olduğu gibi, bu prosedür de karma ön eklerin sunucuya tam olarak nasıl gönderileceğini belirtmez. Örneğin, istemcinin tüm expressionHashPrefixes öğelerini tek bir istekte göndermesi kabul edilebilir olduğu gibi, istemcinin de expressionHashPrefixes içindeki her ön eki sunucuya ayrı isteklerde göndermesi (örneğin paralel olarak devam etmesi) da kabul edilebilir. Ayrıca, tek bir istekte gönderilen karma öneklerinin sayısı 30'u aşmadığı sürece, istemcinin expressionHashPrefixes içindeki karma ön ekleriyle birlikte alakasız veya rastgele oluşturulmuş karma öneklerini göndermesi de kabul edilebilir.

Yerel Veritabanı Bakımı

Google Güvenli Tarama v5, istemcinin Depolama Yok Gerçek Zamanlı Modu'nu seçmediği durumlar dışında, istemcinin yerel bir veritabanını tutmasını bekler. Bu yerel veritabanının biçimi ve depolaması istemciye bağlıdır. Bu yerel veritabanının içeriği kavramsal olarak çeşitli listeleri dosya olarak 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öntemini kullanmanız önerilir.

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

Listelerin tehdit türü, platform türü, tehdit girişi türü grubuna göre tanımlandığı V4'ün aksine, v5'teki listelerde yalnızca ada göre tanımlanır. Böylece, birden fazla v5 listesinin aynı tehdit türünü paylaşabileceği durumlarda esneklik sağlanır. Platform türleri ve tehdit girişi türleri v5'te kaldırıldı.

Liste için bir ad seçildikten sonra, liste hiçbir zaman yeniden adlandırılmaz. Ayrıca, bir liste görüntülendikten sonra hiçbir zaman kaldırılmaz (liste artık kullanışlı değilse boş olur ancak var olmaya devam eder). Bu nedenle, bu adları Google Güvenli Tarama istemci koduna sabit bir şekilde kodlamanız önerilir.

Hem hashList.get yöntemi hem de hashLists.batchGet yöntemi artımlı güncellemeleri destekler. Artımlı güncellemelerin kullanılması bant genişliğinden tasarruf 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 sağlayarak çalışır. (Bir istemci yeni dağıtılmışsa ve kullanılabilir herhangi bir sürümü yoksa tam güncelleme mevcuttur.) Artımlı güncelleme, kaldırma dizinlerini ve eklemeleri içerir. Önce 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ğlamayla karşılaştırarak kontrol etmelidir. Sağlama eşleşmediğinde istemci tam güncelleme yapmalıdır.

Liste İçeriğinin Kodunu Çözme

Karmaların ve Karma Ön Eklerinin 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 dizi karma veya karma ön eki içerdiğini tanıyarak çalışır. Bu tam sayıları sıralayıp bitişik farklarını alırsak, bu tür bitişik farkların bir anlamda "küçük" olması beklenir. Golomb-Rice kodlaması, bu küçüklüğü istismar eder.

a.example.com/, b.example.com/ ve y.example.com/ olmak üzere üç ana makine-sonek yol ön eki ifadesinin 4 baytlık karma ön ekleri kullanılarak iletildiğini varsayalım. Ayrıca, k ile gösterilen Pirinç parametresinin 30 olarak seçildiğini varsayalım. Sunucu, bu dizelerin tam karma değerini hesaplayarak başlar. Bunlar sırasıyla:

291bc5421f1cd54d99afcc55d166e2b9fe42447025895bf09dd41b2110a687dc  a.example.com/
1d32c5084a360e58f1b87109637a6810acad97a861a7769e8f1841410d2a960c  b.example.com/
f7a502e56e8b01c6dc242b35122683c9d25d07fb1f532d9853eb0ef3ff334f03  y.example.com/

Ardından sunucu yukarıdakilerin her biri için 4 baytlık karma önekler oluşturur. Bunlar, 32 baytlık tam karmanın ilk 4 baytıdır ve büyük uç 32 bit tamsayıları olarak yorumlanır. Büyük endianite, tam karmanın ilk baytının, 32 bitlik tam sayının en önemli baytı haline geldiği gerçeğini ifade eder. Bu adım 0x291bc542, 0x1d32c508 ve 0xf7a502e5 tam sayılarıyla sonuçlanır.

Sunucunun bu üç karma önekini sözlüksel olarak (büyük endiandaki sayısal sıralamaya eşdeğerdir) sıralaması gerekir ve bu sıralamanın sonucu 0x1d32c508, 0x291bc542, 0xf7a502e5 olur. İlk karma ön eki first_value alanında değiştirilmeden depolanır.

Daha sonra sunucu, bitişik iki farkı (sırasıyla 0xbe9003a ve 0xce893da3) hesaplar. k değeri 30 olarak seçildiğinde, sunucu bu iki sayıyı sırasıyla 2 ve 30 bit uzunluğundaki bölüm bölümlerine ve kalan bölümlere ayırır. İlk sayının bölme kısmı sıfır, kalan kısmı 0xbe9003a'dır. İkinci sayı için bölme bölümü 3'tür. Çünkü en önemli iki bit ikili sayı olarak 11, kalan kısmı da 0xe893da3'tür. Belirli bir q bölümü için tam olarak 1 + q bit kullanılarak (1 << q) - 1 biçiminde; kalan kısım ise k bit kullanılarak doğrudan kodlanır. Birinci sayının bölme kısmı 0, kalan kısmı 001011111010010000000000111010 ikili değeri; ikinci sayının bölmesi 0111 ve kalan kısmı 00111010001010101010101 olarak kodlanır.

Bu sayılar bir bayt dizesine dönüştürüldüğünde küçük endian kullanılır. Kavramsal olarak, en az anlamlı bitlerden başlayarak uzun bir bit dizesinin oluştuğunu düşünmek daha kolay olabilir: İlk sayının bölüm kısmını alırız ve ilk sayının kalan kısmını başa getiririz. Sonra da ikinci sayının bölme kısmını da başa ekleriz ve kalan bölümün başına ekleriz. Bu durumda, şu sayıda olacaktır (satır sonları ve yorumlar daha anlaşılır hale getirilmelidir):

001110100010010011110110100011 # Second number, remainder part
0111 # Second number, quotient part
001011111010010000000000111010 # First number, remainder part
0 # First number, quotient part

Tek bir satır halinde yazılırsa

00111010001001001111011010001101110010111110100100000000001110100

Elbette bu sayı, tek bir baytta bulunan 8 biti çok aşıyor. Daha sonra, küçük endian kodlaması bu sayıdaki en az anlamlı 8 biti alır ve bu biti ilk bayt olarak, yani 01110100 olarak çıkarır. Açıklık sağlaması açısından, yukarıdaki bit dizesini en az anlamlı bitlerden başlayarak sekizlik gruplar halinde gruplandırabiliriz:

0 01110100 01001001 11101101 00011011 10010111 11010010 00000000 01110100

Daha sonra, küçük endian kodlaması sağdan her baytı alır ve bir bayt dizesine yerleştirir:

01110100
00000000
11010010
10010111
00011011
11101101
01001001
01110100
00000000

Burada, yeni bölümleri kavramsal olarak soldaki büyük sayının başına prepend (yani daha önemli bitler eklediğimizden) ancak sağdan (en az anlamlı bitler) kodlama yaptığımızdan, kodlama ve kod çözme işlemi aşamalı olarak gerçekleştirilebilir.

Bu da nihayet şuna yol açar:

additions_four_bytes {
  first_value: 489866504
  rice_parameter: 30
  entries_count: 2
  encoded_data: "t\000\322\227\033\355It\000"
}

İstemci sadece karma öneklerinin kodunu çözmek için yukarıdaki adımları tersten izler. v4'ün aksine, karma ön eki tam sayıları büyük endyan olarak yorumlandığından sonda bayt değişimi yapmaya gerek yoktur.

Kaldırma Dizinlerinin Kodunu Çözme

Kaldırma dizinleri, 32 bit tam sayılar kullanılarak yukarıdakiyle tamamen aynı teknik kullanılarak kodlanır. Kaldırma dizinlerinin kodlanması ve kodunun çözülmesi, v4 ve v5 arasında değişmemiştir.

Kullanılabilir Listeler

Aşağıdaki listelerin v5alpha1 sürümünde kullanılması önerilir:

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

Ek listeler daha sonraki bir tarihte kullanıma sunulacaktır. Bu tarihte yukarıdaki tablo genişletilecektir.

İstemcinin yukarıdaki listelerin bir kısmını veya tamamını almak ve ardından istemcinin proxy sunucuyla iletişim kurmasını sağlamak için önbelleğe alma proxy sunucusunu çalıştırmasına izin verilir. Bu durumda beş dakika gibi kısa bir önbellek süresi öneriyoruz. İleride bu önbellek süresi, standart Cache-Control HTTP başlığı kullanılarak iletilebilir.

Güncelleme Sıklığı

İstemci, minimum_wait_duration alanında sunucunun döndürdüğü değeri 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 (minimum_wait_duration alanı tamamen eksiktir). Bu durumda, istemci hemen başka bir güncelleme gerçekleştirmesi GEREKİR.

Örnek İstekler

Bu bölümde, Google Güvenli Tarama'ya erişmek için doğrudan HTTP API'yi kullanmaya ilişkin bazı örnekler gösterilmektedir. Kodlama ve kod çözme işlemlerini uygun bir şekilde otomatik olarak gerçekleştireceği için genellikle oluşturulmuş bir dil bağlaması kullanmanız önerilir. Lütfen bu bağlantı için dokümanları inceleyin.

Aşağıda, hashes.search yöntemini kullanan örnek bir HTTP isteği verilmiştir:

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çiminde bir yüktür.

Aşağıda, hashLists.batchGet yöntemini kullanan örnek bir HTTP isteği 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 kodunu çözebileceğiniz, protokol arabelleği biçiminde bir yüktür.

Taşıma Rehberi

Şu anda v4 Update API'yi kullanıyorsanız yerel veritabanını sıfırlamanıza veya silmenize gerek kalmadan v4'ten v5'e sorunsuz bir geçiş vardır. Bu bölümde bunun nasıl yapılacağı açıklanmaktadır.

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

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

İstekte aşağıdaki değişikliklerin yapılması gerekir:

1. v4 ClientInfo nesnesini tamamen kaldırın. İstemcinin kimliğini özel bir alan kullanarak sağlamak yerine, bilinen User-Agent üstbilgisini kullanmanız yeterlidir. Bu üstbilgide istemci kimliğini sağlamak için belirli bir biçim olmasa da orijinal istemci kimliğini ve istemci sürümünü boşluk karakteriyle veya eğik çizgi karakteriyle ayrılmış şekilde eklemenizi öneririz.
2. Her bir v4 ListUpdateRequest nesnesi için:
   • Yukarıdaki tabloda karşılık gelen v5 liste adını bulun ve v5 isteğinde bu adı belirtin.
   • threat_entry_type veya platform_type gibi gereksiz alanları kaldırın.
   • v4'teki state alanı, v5 versions alanıyla doğrudan uyumludur. v4'teki state alanı kullanılarak sunucuya gönderilecek olan aynı bayt dizesi, v5'te versions alanı kullanılarak gönderilebilir.
   • v5, v4 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şikliklerin yapılması gerekir:

1. v4 enum ResponseType, partial_update adlı bir boole alanı ile değiştirilir.
2. minimum_wait_duration alanı artık sıfır olabilir veya atlanabilir. Böyle bir durumda, müşteriden hemen başka bir istekte bulunması istenir. Bu durum yalnızca istemci SizeConstraints ürününde maksimum güncelleme boyutunda maksimum veritabanı boyutundan daha küçük bir kısıtlama belirttiğinde gerçekleşir.
3. 32 bit tam sayılar için pirinç kod çözme algoritmasının ayarlanması gerekir. Aradaki fark, kodlanmış verilerin farklı bir endianlık düzeyiyle kodlanmasıdır. Hem v4 hem de v5'te 32 bit karma önekleri sözlüksel olarak sıralanır. Ancak v4'te bu önekler sıralandığında küçük endian olarak, v5'te ise sıralandığında bu önekler büyük endian olarak ele alınır. Sözlüksel sıralama, büyük endian içeren sayısal sıralamayla aynı olduğundan istemcinin herhangi bir sıralama yapması gerekmez. v4'ün Chromium uygulamasındaki bu sıralama örneğini burada bulabilirsiniz. Bu tür sıralamalar kaldırılabilir.
4. Diğer karma uzunlukları için pirinç kodu çözme algoritmasının uygulanması gerekir.

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

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

İstekte aşağıdaki değişikliklerin yapılması gerekir:

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 User-Agent üstbilgisini kullanmanız yeterlidir. Bu üstbilgide istemci kimliğini sağlamak için belirli bir biçim olmasa da orijinal istemci kimliğini ve istemci sürümünü boşluk karakteriyle veya eğik çizgi karakteriyle ayrılmış şekilde eklemenizi öneririz.
3. client_states alanını kaldırın. Artık gerekli değildir.
4. Artık threat_types ve benzer alanların eklenmesine gerek yoktur.

Yanıtta aşağıdaki değişikliklerin yapılması gerekir:

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ştirilmiştir.
3. Önbelleğe alma, tek bir önbellek süresi olacak şekilde basitleştirildi. Önbellekle etkileşim için yukarıdaki prosedürlere bakın.