使用 Submission API

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

事前準備

如要取得這項功能的存取權，請聯絡銷售團隊或客戶工程師。

最佳做法

詳閱安全瀏覽政策

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：不實網站聲稱裝置有問題，誘騙使用者分享 PII 或聯絡詐騙集團。
  • 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 欄位說明攻擊。
  • 選填，但建議填寫：提供這些欄位有助於網頁風險排定優先順序，並強化相關的威脅情報模型。
  • 預先發布階段：這項功能的列舉值和行為可能會有所變更。

提交網址

如要提交網址，請將 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。如要進一步瞭解這些狀態，請參閱「長時間執行的作業」指南中的「瞭解作業狀態」。