Best practices for using the Submission API

This document describes the recommended implementation for the Submission API:

  • Submit complete URLs: Provide the full, direct URL to the malicious content, not just the domain.
  • Submit only active URLs: Submit live URLs only. Offline or unreachable sites can't be processed.

  • Include policy violations: Only submit URLs that you have reason to believe are unsafe and violate Google Safe Browsing Policies.

  • Programmatic submission: Use the Submission API to automate high-volume reports from external sources like Security Operations Center teams or end-user reports.

  • Include additional metadata: To help improve the speed and accuracy of threat detection, provide metadata with your submissions. For more information, see Improve detection with ThreatInfo and ThreatDiscovery.

Improve detection with ThreatInfo and ThreatDiscovery

We recommend using the following ThreatInfo and ThreatDiscovery fields to provide additional information about submissions, which can improve detection and increase the chances of a submission being blocked.

  • Use ThreatInfo to provide more information about why the URI is being submitted.
  • Use ThreatDiscovery to provide more information about how the threat was found.

Example

An attacker launches a credential phishing site targeting clients of a bank based in Italy. Targeted clients begin receiving deceptive text messages from that attacker with a link to a fake login page. The bank receives reports from clients that received the texts, launches an investigation, and confirms that the site is phishing for credentials.

To help protect their clients, the bank submits the phishing site to Web Risk with the following request body:

{
  "submission": {
    "uri": "http://example.com/login.html"
  },
  "threatDiscovery": {
    "platform": "ANDROID",
    "regionCodes": "IT"
  },
  "threatInfo": {
    "abuseType": "SOCIAL_ENGINEERING",
    "abuseSubtype": "BANK_PHISHING",
    "threatJustification": {
      "labels": ["USER_REPORT", "MANUAL_VERIFICATION"],
      "comments": "Site is impersonating a bank and phishing for login credentials"
    },
    "threatConfidence": {
      "level": "HIGH"
    },
    "targetedBrand": {
      "brandName": "Altostrat",
      "domain": "altostrat.com"
    }
  }
}

When the bank checks the status of the submission with the operation name returned by the Submission API, the status is SUCCEEDED. This status indicates that the submitted URL was added to the Safe Browsing block list.

What's next

  • View the API reference for ThreatInfo and ThreatDiscovery (RPC, REST).