使用 Submission API

本文档介绍了如何向“安全浏览”功能提交您怀疑不安全的网址以供分析，以及如何异步检查这些提交的结果。任何经确认违反安全浏览政策的网址都会添加到安全浏览服务中。

Web Risk Submission API 的主要变化

  • 不再接受新订单和扩展：我们不再接受 Web Risk Submission API 的新合约或扩展。
  • 功能冻结生效：API 处于正式的功能冻结状态。我们不再推出新功能或增强功能。
  • 最终续订：现有合同的最终续订日期为 2026 年 12 月 31 日。所有续订的最长期限均为一年。
  • 服务可用性：在有效合同期结束之前，现有服务将继续运行，并提供关键 bug 修复、安全更新和标准支持。全面弃用时间不会晚于 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：冒充配送服务来获取个人身份信息或支付信息。
  • 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 字段来描述攻击。
  • 可选，但建议提供：提供这些字段有助于 Web 风险优先处理并改进相关的威胁情报模型。
  • 预览阶段：此功能的枚举值和行为可能会发生变化。

提交网址

如要提交网址，请向 projects.uris.submit 方法发送 HTTP POST 请求。

  • Submission API 支持每个请求使用 1 个网址。如要检查多个网址，您需要对每个网址发送单独的请求。

  • 网址必须有效，但无需进行规范化处理。如需了解详情，请参阅 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。如需详细了解这些状态，请参阅长时间运行的操作指南中的了解操作状态。