API Pembaruan Safe Browsing (v4)

Ringkasan

Update API memungkinkan aplikasi klien Anda mendownload versi hash daftar Safe Browsing untuk disimpan di database lokal. URL kemudian dapat diperiksa secara lokal. Hanya jika kecocokan ditemukan dalam database lokal, klien perlu mengirim permintaan ke server Safe Browsing untuk memverifikasi apakah URL disertakan dalam daftar Safe Browsing.

Sebelum menggunakan Update API, Anda perlu menyiapkan database lokal. Safe Browsing menyediakan paket Go yang dapat Anda gunakan untuk memulai. Untuk mengetahui detail lebih lanjut, lihat bagian Penyiapan Database di bagian Database Lokal.

Memperbarui database lokal

Agar tetap mendapatkan informasi terbaru, klien diwajibkan untuk memperbarui daftar Safe Browsing secara berkala di database lokal mereka. Untuk menghemat bandwidth, klien mendownload awalan hash URL, bukan URL mentah. Misalnya, jika "www.badurl.com/" ada dalam daftar Safe Browsing, klien akan mendownload awalan hash SHA256 URL tersebut, bukan URL itu sendiri. Pada umumnya, awalan hash panjangnya adalah 4 byte, yang berarti biaya rata-rata bandwidth untuk mendownload satu entri daftar adalah 4 byte sebelum kompresi.

Untuk memperbarui daftar Safe Browsing di database lokal, kirim permintaan POST HTTP ke metode threatListUpdates.fetch:

  • Permintaan POST HTTP menyertakan nama daftar yang akan diupdate beserta berbagai batasan klien untuk memperhitungkan batasan memori dan bandwidth.
  • Respons POST HTTP menampilkan update lengkap atau update sebagian. Respons mungkin juga menampilkan durasi tunggu minimum.

Contoh: ancamanListUpdates.fetch

Permintaan POST HTTP

Pada contoh berikut, pembaruan untuk satu daftar Safe Browsing diminta.

Header permintaan

Header permintaan mencakup URL permintaan dan jenis konten. Jangan lupa mengganti kunci API Anda dengan API_KEY di URL.

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

Isi permintaan

Isi permintaan mencakup informasi klien (ID dan versi) dan informasi update (nama daftar, status daftar, dan batasan klien). Untuk mengetahui detail selengkapnya, lihat isi permintaan threatListUpdates.fetch dan penjelasan yang mengikuti contoh kode.

{
  "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"]
    }
  }]
}
Informasi klien

Kolom clientID dan clientVersion harus mengidentifikasi implementasi klien secara unik, bukan pengguna individual. (Informasi klien digunakan dalam logging sisi server. Anda dapat memilih nama apa pun untuk client ID, tetapi sebaiknya pilih nama yang mewakili identitas sebenarnya klien, seperti nama perusahaan Anda, yang ditampilkan sebagai satu kata, dalam huruf kecil semua.)

Daftar Safe Browsing

Kolom threatType, platformType, dan threatEntryType digabungkan untuk mengidentifikasi (nama) daftar Safe Browsing. Dalam contoh ini, satu daftar diidentifikasi: MALWARE/WINDOWS/URL. Sebelum mengirim permintaan, pastikan kombinasi jenis yang Anda tentukan valid (lihat Daftar Safe Browsing).

Status klien

Kolom state menyimpan status klien saat ini dari daftar Safe Browsing. (Status klien ditampilkan di kolom newClientState pada respons threatListUpdates.fetch.) Untuk pembaruan awal, kosongkan kolom state.

Batasan ukuran

Kolom maxUpdateEntries menentukan jumlah total update yang dapat dikelola klien (dalam contoh, 2048). Kolom maxDatabaseEntries menentukan jumlah total entri yang dapat dikelola database lokal (misalnya, 4096). Klien harus menetapkan batasan ukuran untuk melindungi batasan memori dan bandwidth serta melindungi dari pertumbuhan daftar. Untuk mengetahui informasi selengkapnya, (lihat Memperbarui Batasan).

Kompresi yang didukung

Kolom supportedCompressions mencantumkan jenis kompresi yang didukung klien. Misalnya, klien hanya mendukung data mentah dan belum dikompresi. Namun, Safe Browsing mendukung jenis kompresi tambahan (lihat Kompresi).

Respons POST HTTP

Dalam contoh ini, respons menampilkan update sebagian untuk daftar Safe Browsing menggunakan jenis kompresi yang diminta.

Header respons

Header respons mencakup kode status HTTP dan jenis konten. Klien yang menerima kode status selain HTTP/200 harus memasuki mode back-off (lihat Frekuensi Permintaan).

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

Isi respons

Isi respons mencakup informasi update (nama daftar, jenis respons, penambahan dan penghapusan yang akan diterapkan ke database lokal, status klien baru, dan checksum). Dalam contoh, respons juga menyertakan durasi tunggu minimum. Untuk mengetahui detail selengkapnya, lihat isi respons threatListUpdates.fetch dan penjelasan yang mengikuti contoh kode.

{
  "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"
}
Pembaruan database

Kolom responseType akan menunjukkan update sebagian atau lengkap. Dalam contoh ini, pembaruan parsial ditampilkan, sehingga responsnya mencakup penambahan dan penghapusan. Mungkin ada beberapa kumpulan tambahan, tetapi hanya satu kumpulan penghapusan (lihat Update Database).

Status klien baru

Kolom newClientState menyimpan status klien baru untuk daftar Safe Browsing yang baru diperbarui. Klien harus menyimpan status klien baru untuk permintaan update selanjutnya (kolom state di permintaan threatListUpdates.fetch atau kolom clientStates di permintaan fullHashes.find).

{i>Checksum<i}

Checksum memungkinkan klien memverifikasi bahwa {i>database<i} lokal tidak mengalami kerusakan. Jika checksum tidak cocok, klien harus menghapus database dan menerbitkan ulang update dengan kolom state kosong. Namun, klien dalam situasi ini tetap harus mengikuti interval waktu untuk pembaruan (lihat Frekuensi Permintaan).

Durasi tunggu minimum

Kolom minimumWaitDuration menunjukkan bahwa klien harus menunggu 593,44 detik (9,89 menit) sebelum mengirimkan permintaan update lainnya. Perlu diperhatikan bahwa periode tunggu mungkin disertakan atau tidak disertakan dalam respons (lihat Frekuensi Permintaan).

Memeriksa URL

Untuk memeriksa apakah URL ada dalam daftar Safe Browsing, klien harus terlebih dahulu menghitung awalan hash dan hash URL (lihat URL dan Hashing). Klien kemudian mengkueri database lokal untuk menentukan apakah ada kecocokan. Jika awalan hash tidak ada dalam database lokal, berarti URL tersebut dianggap aman (tidak ada dalam daftar Safe Browsing).

Jika awalan hash ada dalam database lokal (tumbukan awalan hash), klien harus mengirim awalan hash ke server Safe Browsing untuk verifikasi. Server akan menampilkan semua hash SHA 256 lengkap yang berisi awalan hash yang diberikan. Jika salah satu hash lengkap tersebut cocok dengan hash lengkap dari URL yang dimaksud, URL tersebut akan dianggap tidak aman. Jika tidak ada hash berdurasi penuh yang cocok dengan hash lengkap dari URL yang dimaksud, maka URL tersebut dianggap aman.

Google tidak akan mempelajari URL yang Anda periksa. Google mempelajari awalan hash URL, tetapi awalan hash tersebut tidak memberikan banyak informasi tentang URL yang sebenarnya.

Untuk memeriksa apakah URL berada dalam daftar Safe Browsing, kirim permintaan POST HTTP ke metode fullHashes.find:

  • Permintaan POST HTTP dapat mencakup hingga 500 entri ancaman.
  • Permintaan POST HTTP mencakup awalan hash URL yang akan diperiksa. Klien dianjurkan untuk mengelompokkan beberapa entri ancaman ke dalam satu permintaan untuk menurunkan penggunaan bandwidth.
  • Respons POST HTTP menampilkan hash lengkap yang cocok beserta durasi cache positif dan negatif. Respons mungkin juga menampilkan durasi tunggu minimum.

Contoh: fullHashes.find

Permintaan POST HTTP

Pada contoh berikut, nama dua daftar Safe Browsing dan tiga awalan hash dikirim untuk perbandingan dan verifikasi.

Header permintaan

Header permintaan mencakup URL permintaan dan jenis konten. Jangan lupa mengganti kunci API Anda dengan API_KEY di URL.

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

Isi permintaan

Isi permintaan mencakup informasi klien (ID dan versi), status klien, dan informasi ancaman (nama daftar dan awalan hash). Untuk permintaan JSON, awalan hash harus dikirim dalam bentuk berenkode base64. Untuk mengetahui detail selengkapnya, lihat isi permintaan fullHashes.find dan penjelasan yang mengikuti contoh kode.

{
  "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=="}
    ]
  }
}
Informasi klien

Kolom clientID dan clientVersion harus mengidentifikasi implementasi klien secara unik, bukan pengguna individual. (Informasi klien digunakan dalam logging sisi server. Anda dapat memilih nama apa pun untuk client ID, tetapi sebaiknya pilih nama yang mewakili identitas klien yang sebenarnya, seperti nama perusahaan Anda, yang ditampilkan sebagai satu kata, dalam huruf kecil semua.)

Semua status klien

Kolom clientStates menyimpan status klien untuk semua daftar Safe Browsing di database lokal klien. (Status klien ditampilkan di kolom newClientState pada respons threatListUpdates.fetch.)

Daftar Safe Browsing

Kolom threatTypes, platformTypes, dan threatEntryTypes digabungkan untuk mengidentifikasi (nama) daftar Safe Browsing. Pada contoh, dua daftar diidentifikasi: MALWARE/WINDOWS/URL dan SOCIAL_EngineERING/WINDOWS/URL. Sebelum mengirim permintaan, pastikan kombinasi jenis yang Anda tentukan valid (lihat Daftar Safe Browsing).

Awalan hash ancaman

Array ancamanEntries berisi awalan hash URL yang ingin Anda periksa. Kolom hash harus berisi awalan hash yang sama persis dengan yang ada di database lokal. Misalnya, jika panjang awalan hash lokal adalah 4 byte, panjang entri ancaman harus sepanjang 4 byte. Jika awalan hash lokal diperpanjang hingga 7 byte, panjang entri ancaman harus sepanjang 7 byte.

Dalam contoh, permintaan mencakup tiga awalan hash. Ketiga awalan akan dibandingkan dengan setiap daftar Safe Browsing untuk menentukan apakah ada hash lengkap yang cocok atau tidak.

Catatan: Update API dan metode fullHashes.find harus selalu menggunakan kolom hash, bukan kolom URL (lihat ThreatEntry).

Respons POST HTTP

Pada contoh berikut, respons menampilkan data yang cocok, yang diatur berdasarkan daftar Safe Browsing, beserta durasi tunggu dan cache.

Header respons

Header respons mencakup kode status HTTP dan jenis konten. Klien yang menerima kode status selain HTTP/200 harus melakukan back-off (lihat Frekuensi Permintaan).

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

Isi respons

Isi respons menyertakan informasi kecocokan (nama daftar dan hash panjang lengkapnya, metadata, jika tersedia, dan durasi cache). Dalam contoh, isi respons juga menyertakan durasi tunggu minimum. Untuk mengetahui detail selengkapnya, lihat isi respons fullHashes.find dan penjelasan yang mengikuti contoh kode.

{
  "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"
}
Kecocokan

Objek Matches menampilkan hash lengkap yang cocok untuk dua awalan hash. URL yang terkait dengan hash ini dianggap tidak aman. Tidak ditemukan kecocokan untuk awalan hash ketiga, sehingga tidak ada yang ditampilkan. URL yang sesuai dengan awalan hash ini dianggap aman.

Perhatikan bahwa contoh ini cocok dengan satu hash panjang penuh dengan satu awalan hash; namun, bisa saja ada beberapa hash lengkap yang dipetakan ke awalan hash yang sama.

Metadata

Kolom threatEntryMetadata bersifat opsional dan memberikan informasi tambahan tentang pencocokan ancaman. Saat ini, metadata tersedia untuk daftar Safe Browsing MALWARE/WINDOWS/URL (lihat Metadata).

Durasi cache

Kolom cacheDuration dan negativeCacheDuration menunjukkan durasi waktu hash harus dianggap tidak aman atau aman (lihat Pembuatan cache).

Durasi tunggu minimum

Kolom minimumWaitDuration menunjukkan bahwa klien harus menunggu 300 detik (5 menit) sebelum mengirim permintaan fullHashes lainnya. Perlu diperhatikan bahwa periode tunggu mungkin disertakan atau tidak disertakan dalam respons (lihat Frekuensi Permintaan).