Menggunakan Submission API

Dokumen ini menjelaskan cara mengirimkan URL yang Anda duga tidak aman ke Safe Browsing untuk dianalisis, dan memeriksa hasil pengiriman ini secara asinkron. URL yang dikonfirmasi melanggar Kebijakan Safe Browsing akan ditambahkan ke layanan Safe Browsing.

Sebelum memulai

Hubungi bagian penjualan atau customer engineer Anda untuk mendapatkan akses ke fitur ini.

Praktik terbaik

Baca Kebijakan Safe Browsing

Web Risk Submission API memvalidasi bahwa URL yang dikirim menampilkan konten yang melanggar kebijakan Safe Browsing. Developer API harus memastikan bahwa URL yang dikirimkan memiliki bukti yang jelas tentang pelanggaran kebijakan ini. Contoh berikut menunjukkan bukti pelanggaran kebijakan:

Konten manipulasi psikologis yang meniru merek online yang sah (nama merek, logo, tampilan dan nuansa), pemberitahuan sistem, menggunakan URL yang menipu, atau meminta pengguna memasukkan kredensial sensitif seperti nama pengguna atau sandi.
Situs yang menghosting file yang dapat dieksekusi malware yang diketahui.

Jangan kirimkan jenis URL berikut karena kemungkinan tidak akan ditambahkan ke daftar blokir Safe Browsing:

Survei palsu, situs belanja, atau scam lainnya yang tidak menunjukkan phishing (seperti scam mata uang kripto).
Spam yang berisi perjudian, kekerasan, atau konten dewasa yang bukan phishing atau malware.

Meningkatkan deteksi

Sebaiknya gunakan kolom ThreatInfo dan ThreatDiscovery untuk memberikan informasi tambahan tentang pengiriman. Tindakan ini dapat membantu meningkatkan deteksi. Untuk mengetahui informasi selengkapnya, lihat Praktik terbaik untuk menggunakan Submission API.

Penargetan taksonomi dan merek

Anda dapat memberikan laporan penyalahgunaan yang lebih akurat dan mendetail dengan menggunakan komponen opsional berikut dalam objek ThreatInfo: abuseSubtype dan targetedBrand. Kolom ini membantu Web Risk menganalisis entitas yang ditargetkan dengan lebih akurat dan meningkatkan model deteksi.

`abuseSubtype`

Kolom abuseSubtype memberikan klasifikasi ancaman yang terperinci. Pastikan kolom ini ditetapkan hanya jika abuseType utama adalah SOCIAL_ENGINEERING; jika tidak, error akan ditampilkan.

Nilai abuseSubtype yang didukung mencakup berikut ini:

BANK_PHISHING: Phishing yang menyamar sebagai bank atau entitas keuangan tepercaya.
CRYPTO_EXCHANGE_PHISHING: Phishing yang menyamar sebagai platform perdagangan mata uang kripto.
SOCIAL_MEDIA_PLATFORM_PHISHING: Phishing yang menyamar sebagai platform media sosial.
RETAIL_PHISHING: Phishing yang menyamar sebagai platform retail yang sudah mapan.
EMAIL_PROVIDER_PHISHING: Phishing yang menyamar sebagai layanan email.
ENTERTAINMENT_PHISHING: Phishing yang menyamar sebagai layanan hiburan.
GOVERNMENT_AGENCY_PHISHING: Phishing yang menyamar sebagai lembaga pemerintah untuk mendapatkan informasi identitas pribadi (PII), seperti nomor Jaminan Sosial atau nomor identifikasi wajib pajak.
PACKAGE_TRACKING_SCAM: Meniru layanan pengiriman untuk mendapatkan PII atau detail pembayaran.
FAKE_SUPPORT_SCAM: Situs penipu yang mengklaim masalah perangkat palsu untuk menipu pengguna agar membagikan PII atau menghubungi penipu.
GOVERNMENT_FINE_SCAM: Konten penipuan yang mengklaim bahwa denda pelanggaran hukum harus dibayar.
FAKE_PRIZE_SCAM: Halaman penipuan yang menawarkan reward atau hadiah yang tidak realistis.
OTHER_PHISHING / OTHER_SCAM: Serangan rekayasa sosial yang tidak termasuk dalam kategori lain yang disebutkan di sini.

`targetedBrand`

Objek targetedBrand mengidentifikasi entitas yang menjadi target kampanye phishing dan manipulasi psikologis.

brandName: Nama merek atau perusahaan yang ditiru identitasnya yang mudah dikenali (misalnya, Altostrat).
domain: Domain sah merek yang identitasnya dipalsukan (misalnya, altostrat.com).

Catatan penting untuk peserta pratinjau

Konsistensi dalam taksonomi: Phishing tetap dikategorikan dalam jenis ancaman SOCIAL_ENGINEERING (bukan jenis induk PHISHING terpisah) untuk memastikan konsistensi di seluruh rangkaian Web Risk dan Safe Browsing API.
Kategori yang dikecualikan: Subkategori untuk MALWARE dan UNWANTED_SOFTWARE dikecualikan dari rilis ini.
Menangani ancaman yang tidak tercantum: Jika kiriman Anda tidak sesuai dengan subtipe tertentu, gunakan OTHER_PHISHING atau OTHER_SCAM. Sebaiknya gunakan kolom comments di ThreatJustification untuk mendeskripsikan serangan.
Opsional, tetapi disarankan: Mengisi kolom ini membantu Web Risk memprioritaskan dan meningkatkan kualitas model kecerdasan ancaman terkait.
Fase pratinjau: Nilai dan perilaku enum untuk fitur ini dapat berubah.

Mengirimkan URL

Untuk mengirimkan URL, kirim permintaan HTTP POST ke metode projects.uris.submit.

Submission API mendukung satu URL per permintaan. Untuk memeriksa beberapa URL, Anda harus mengirim permintaan terpisah untuk setiap URL.
URL harus valid, tetapi tidak perlu dikanonisasi. Untuk mengetahui informasi selengkapnya, lihat RFC 2396.
Respons HTTP POST menampilkan long-running operation. Untuk mengetahui informasi selengkapnya tentang cara mengambil hasil pengiriman dan memeriksa status pengiriman, lihat Operasi yang berjalan lama.

Contoh

Metode HTTP dan URL:

POST https://webrisk.googleapis.com/v1/projects/project-id/uris:submit

Meminta isi JSON:

{
  "submission": {
    "uri": "https://www.example.com/login.html"
  }
}

Untuk mengirim permintaan Anda, pilih salah satu opsi berikut:

curl

Catatan: Perintah berikut mengasumsikan bahwa Anda telah login ke gcloud CLI menggunakan akun pengguna Anda dengan menjalankan gcloud init atau gcloud auth login, atau dengan menggunakan Cloud Shell, yang secara otomatis membuat Anda login ke gcloud CLI. Anda dapat memeriksa akun yang saat ini aktif dengan menjalankan gcloud auth list.

Simpan isi permintaan dalam file bernama request.json, dan jalankan perintah berikut:

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://webrisk.googleapis.com/v1/projects/project-id/uris:submit"

PowerShell

Catatan: Perintah berikut mengasumsikan bahwa Anda telah login ke gcloud CLI menggunakan akun pengguna Anda dengan menjalankan gcloud init atau gcloud auth login. Anda dapat memeriksa akun yang saat ini aktif dengan menjalankan gcloud auth list.

Simpan isi permintaan dalam file bernama request.json, dan jalankan perintah berikut:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://webrisk.googleapis.com/v1/projects/project-id/uris:submit" | Select-Object -Expand Content

Anda akan melihat respons JSON seperti berikut:

{
  "name": "projects/project-number/operations/operation-id",
}

Memeriksa status pengajuan

Gunakan project-number dan operation-id dari respons untuk memeriksa status pengiriman. Status berada di kolom metadata.state operasi yang ditampilkan.

Status yang mungkin mencakup RUNNING, SUCCEEDED, dan CLOSED. Untuk mengetahui informasi selengkapnya tentang status ini, lihat Memahami Status Operasi dalam panduan Operasi yang Berjalan Lama.