Google Safe Browsing API: Cara Pakai, Endpoint, dan Kode Integrasi

Google Safe Browsing API adalah layanan verifikasi keamanan URL dari Google yang memungkinkan aplikasi memeriksa apakah suatu tautan masuk dalam daftar hitam situs berbahaya, mencakup malware, rekayasa sosial (phishing), dan perangkat lunak tidak diinginkan (unwanted software). Respons API ini bersifat biner: jika URL aman, Google mengembalikan payload JSON kosong ({}); jika berbahaya, Google mengembalikan detail ancaman beserta platform targetnya.

Metode: Lookup API vs Update API

Google menyediakan dua arsitektur utama untuk Safe Browsing API v4:

Langkah Mendapatkan Kredensial API

1. Buka Google Cloud Console (console.cloud.google.com).
2. Buat project baru atau pilih project yang sudah ada.
3. Buka menu APIs & Services > Library.
4. Cari Safe Browsing API (pilih Safe Browsing API v4), lalu klik Enable.
5. Buka menu Credentials, pilih Create Credentials > API Key.
6. Batasi akses key (API Restrictions) khusus untuk Safe Browsing API guna mencegah penyalahgunaan kuota.

Struktur Request HTTP POST (Lookup API)

Pemeriksaan URL dilakukan dengan mengirimkan request HTTP POST ke endpoint resmi berikut:

POST https://safebrowsing.googleapis.com/v4/threatMatches:find?key=YOUR_API_KEY
Content-Type: application/json

Berikut adalah payload JSON standar untuk memeriksa satu atau beberapa tautan sekaligus:

{
  "client": {
    "clientId": "security-checker-app",
    "clientVersion": "1.0.0"
  },
  "threatInfo": {
    "threatTypes": [
      "MALWARE",
      "SOCIAL_ENGINEERING",
      "UNWANTED_SOFTWARE",
      "POTENTIALLY_HARMFUL_APPLICATION"
    ],
    "platformTypes": ["ANY_PLATFORM"],
    "threatEntryTypes": ["URL"],
    "threatEntries": [
      {"url": "http://testsafebrowsing.appspot.com/s/malware.html"},
      {"url": "https://google.com"}
    ]
  }
}

Format Respons dari Google

Jika ditemukan indikasi bahaya, Google merespons dengan HTTP 200 dan daftar ancaman:

{
  "matches": [
    {
      "threatType": "MALWARE",
      "platformType": "ANY_PLATFORM",
      "threat": {
        "url": "http://testsafebrowsing.appspot.com/s/malware.html"
      },
      "cacheDuration": "300s",
      "threatEntryType": "URL"
    }
  ]
}

Jika seluruh URL yang dikirim berstatus bersih, response body hanya berupa objek JSON kosong: {}.

Implementasi Kode Python

Berikut adalah script Python siap pakai menggunakan library requests untuk memvalidasi keamanan tautan secara otomatis:

import requests
import json

def check_url_safety(api_key, target_url):
    endpoint = f"https://safebrowsing.googleapis.com/v4/threatMatches:find?key={api_key}"
    
    payload = {
        "client": {
            "clientId": "antigravity-monitor",
            "clientVersion": "1.0.0"
        },
        "threatInfo": {
            "threatTypes": [
                "MALWARE",
                "SOCIAL_ENGINEERING",
                "UNWANTED_SOFTWARE",
                "POTENTIALLY_HARMFUL_APPLICATION"
            ],
            "platformTypes": ["ANY_PLATFORM"],
            "threatEntryTypes": ["URL"],
            "threatEntries": [{"url": target_url}]
        }
    }
    
    response = requests.post(endpoint, json=payload, timeout=10)
    
    if response.status_code != 200:
        raise Exception(f"Request gagal: {response.status_code} - {response.text}")
        
    data = response.json()
    
    # Jika data kosong ({}), URL bersih
    if not data:
        return {"safe": True, "threats": []}
    
    threats = [match["threatType"] for match in data.get("matches", [])]
    return {"safe": False, "threats": threats}

# Eksekusi Pengujian
if __name__ == "__main__":
    API_KEY = "AIzaSyYOUR_ACTUAL_API_KEY_HERE"
    test_url = "http://testsafebrowsing.appspot.com/s/malware.html"
    
    result = check_url_safety(API_KEY, test_url)
    if result["safe"]:
        print(f"[AMAN] {test_url}")
    else:
        print(f"[BAHAYA] {test_url} terdeteksi sebagai: {', '.join(result['threats'])}")

Kategori Ancaman (Threat Types)

Regulasi Kuota dan Praktik Optimal

• Batas Permintaan Gratis: Penggunaan Google Safe Browsing API v4 gratis hingga kuota default sekitar 10.000 request per hari pada GCP standard. Untuk kebutuhan komersial skala masif atau ISP, Google menyarankan migrasi ke Web Risk API.
• Wajib Canonicalization: Pastikan URL dinormalisasi sebelum dikirim (misalnya menghapus whitespace berlebih, mengonversi huruf besar pada hostname ke lowercase, dan melakukan decoding karakter heksadesimal yang tidak perlu).
• Hormati Cache-Control: Nilai cacheDuration pada respons ancaman wajib dipatuhi. Simpan hasil URL berbahaya di Redis/in-memory cache lokal selama durasi tersebut untuk menghemat panggilan API dan mengurangi beban latency aplikasi backend.