使用 Submission API

本文說明如何將疑似不安全的網址提交給安全瀏覽進行分析，以及如何非同步檢查這些提交內容的結果。凡是確認違反安全瀏覽政策的網址，都會加入安全瀏覽服務。

Web Risk Submission API 的主要異動

  • 停止接受新訂單和擴展要求：我們不再接受 Web Risk Submission API 的新合約或擴展要求。
  • 功能凍結生效：API 已正式凍結功能。我們不會再推出新功能或強化功能。
  • 最後續約期限：現有合約的最後續約期限為 2026 年 12 月 31 日。所有續約的期限上限為一年。
  • 服務可用性：現有服務仍可運作，並提供重大錯誤修正、安全性更新和標準支援，直到有效合約到期為止。最晚將於 2027 年 12 月 31 日全面淘汰。

最佳做法

閱讀安全瀏覽政策

Web Risk Submission API 會驗證您提交的網址轉譯內容是否違反安全瀏覽政策。API 開發人員必須確保提交的網址有明確證據違反這些政策。以下是違反政策的證據示例：

  • 模仿正當線上品牌 (品牌名稱、標誌、外觀和風格)、系統警示、使用詐騙網址，或要求使用者輸入使用者名稱或密碼等私密憑證的社交工程內容。
  • 網站代管已知的惡意軟體可執行檔。

請勿提交下列類型的網址，因為這些網址不太可能加入安全瀏覽封鎖清單：

  • 假問卷調查、購物網站或其他未顯示網路釣魚的詐騙 (例如加密貨幣詐騙)。
  • 含有賭博、暴力或成人內容的垃圾郵件，但並非網路釣魚或惡意軟體。

改善偵測品質

建議使用 ThreatInfo 和 ThreatDiscovery 欄位，提供有關提交內容的額外資訊。這可能有助於提升偵測準確度。詳情請參閱「使用 Submission API 的最佳做法」。

分類架構和品牌指定目標

您可以在 ThreatInfo 物件中使用下列選用元件：abuseSubtype 和 targetedBrand，提供更準確詳細的濫用情形檢舉。這些欄位可協助 Web Risk 更準確地分析目標實體，並改良偵測模型。

abuseSubtype

abuseSubtype 欄位會提供威脅的精細分類。請確認只有在主要 abuseType 為 SOCIAL_ENGINEERING 時，才設定這個欄位，否則系統會傳回錯誤。

支援的 abuseSubtype 值包括：

  • BANK_PHISHING：網路釣魚冒充銀行或可信的金融機構。
  • CRYPTO_EXCHANGE_PHISHING：網路釣魚者假冒加密貨幣交易平台。
  • SOCIAL_MEDIA_PLATFORM_PHISHING：網路釣魚，偽裝成社群媒體平台。
  • RETAIL_PHISHING：網路釣魚，冒充知名零售平台。
  • EMAIL_PROVIDER_PHISHING：網路釣魚者假冒電子郵件服務。
  • ENTERTAINMENT_PHISHING：假冒娛樂服務的網路釣魚。
  • GOVERNMENT_AGENCY_PHISHING：網路釣魚，假冒政府機構來取得個人識別資訊 (PII)，例如社會安全號碼或納稅人識別號碼。
  • PACKAGE_TRACKING_SCAM：模仿運送服務，以取得 PII 或付款詳細資料。
  • FAKE_SUPPORT_SCAM：這類網站會宣稱裝置有問題，藉此誘騙使用者提供個人識別資訊或聯絡詐騙集團。
  • GOVERNMENT_FINE_SCAM：宣稱有未繳納的公民罰款，並要求支付的欺騙性內容。
  • FAKE_PRIZE_SCAM：提供不切實際的獎勵或獎品的欺騙性網頁。
  • OTHER_PHISHING / OTHER_SCAM：不屬於此處所列其他類別的社交工程攻擊。

targetedBrand

targetedBrand 物件會識別網路釣魚和社交工程廣告活動的目標實體。

  • brandName：遭冒用的品牌或公司名稱 (例如 Altostrat)。
  • domain：遭冒用品牌的合法網域 (例如 altostrat.com)。

公開測試計畫參與者須知

  • 分類法一致性：網路釣魚仍歸類在 SOCIAL_ENGINEERING 威脅類型 (而非獨立的 PHISHING 父項類型)，確保 Web Risk 和「安全瀏覽」API 系列的一致性。
  • 排除的類別：本次發布內容不包含 MALWARE 和 UNWANTED_SOFTWARE 的子類別。
  • 處理未列出的威脅：如果提交的內容未對應至特定子類型，請使用 OTHER_PHISHING 或 OTHER_SCAM。建議使用 ThreatJustification 中的 comments 欄位說明攻擊。
  • 選填，但建議填寫：提供這些欄位有助於 Web Risk 優先處理相關威脅情報模型，並提升模型效能。
  • 預覽階段：這項功能的列舉值和行為可能會有所變更。

提交網址

如要提交網址，請將 HTTP POST 要求傳送至 projects.uris.submit 方法。

  • Submission API 每個要求支援一個網址。如要檢查多個網址，請分別為每個網址提出要求。

  • 網址必須有效，但不必經過正規化。詳情請參閱 RFC 2396。

  • HTTP POST 回應會傳回 long-running operation。如要進一步瞭解如何擷取提交結果及檢查提交狀態，請參閱「長時間執行的作業」。

範例

HTTP 方法和網址：

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

JSON 要求內文：

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

如要傳送要求，請選擇以下其中一個選項：

curl

將要求主體儲存在名為 request.json 的檔案中，然後執行下列指令：

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

將要求主體儲存在名為 request.json 的檔案中，然後執行下列指令：

$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

您應該會收到如下的 JSON 回覆：

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

查看提交狀態

使用回應中的 project-number 和 operation-id檢查提交狀態。狀態位於傳回作業的 metadata.state 欄位中。

可能的狀態包括 RUNNING、SUCCEEDED 和 CLOSED。如要進一步瞭解這些狀態，請參閱「長時間執行的作業」指南中的「瞭解作業狀態」。