Using the Submission API

This document describes how to submit URLs that you suspect are unsafe to Safe Browsing for analysis, and asynchronously check the results of these submissions. Any URLs that are confirmed to violate the Safe Browsing Policies are added to the Safe Browsing service.

Before you begin

Contact sales or your customer engineer to obtain access to this feature.

Best practices

Read the Safe Browsing Policies

The Web Risk Submission API validates that the submitted URLs render content violating Safe Browsing policies. API developers must ensure that the submitted URLs have clear evidence of violating these policies. The following examples show evidence of violation of policies:

• Social engineering content that mimics a legitimate online brand (brand name, logo, look and feel), system alerts, uses deceptive URLs, or requests users to enter sensitive credentials such as a username or password.
• A site that is hosting a known malware executable.

Don't submit the following types of URLs because they're unlikely to be added to the Safe Browsing blocklist:

• Fake surveys, shopping sites, or other scams that don't demonstrate phishing (such as cryptocurrency scams).
• Spam containing gambling, violence, or adult content that is not phishing or malware.

Improve detection

We recommend using ThreatInfo and ThreatDiscovery fields to provide additional information about submissions. Doing so might help improve detection. For more information, see Best practices for using the Submission API.

Taxonomy and brand targeting

Preview

This product or feature is subject to the "Pre-GA Offerings Terms" in the General Service Terms section of the Service Specific Terms. Pre-GA products and features are available "as is" and might have limited support. For more information, see the launch stage descriptions.

You can provide more accurate and detailed abuse reports by using the following optional components in the ThreatInfo object: abuseSubtype and targetedBrand. These fields help Web Risk more accurately analyze the targeted entities and improve detection models.

abuseSubtype

The abuseSubtype field provides a granular classification of the threat. Make sure that this field is set only when the primary abuseType is SOCIAL_ENGINEERING; otherwise, an error is returned.

The supported abuseSubtype values include the following:

• BANK_PHISHING: Phishing posing as a bank or trusted financial entity.
• CRYPTO_EXCHANGE_PHISHING: Phishing posing as a cryptocurrency trading platform.
• SOCIAL_MEDIA_PLATFORM_PHISHING: Phishing posing as a social media platform.
• RETAIL_PHISHING: Phishing posing as an established retail platform.
• EMAIL_PROVIDER_PHISHING: Phishing posing as an email service.
• ENTERTAINMENT_PHISHING: Phishing posing as an entertainment service.
• GOVERNMENT_AGENCY_PHISHING: Phishing posing as a government agency to obtain personally identifiable information (PII), such as a Social Security number or taxpayer identification number.
• PACKAGE_TRACKING_SCAM: Mimicking a shipping service to obtain PII or payment details.
• FAKE_SUPPORT_SCAM: Deceptive websites claiming false device problems to trick users into sharing PII or contacting scammers.
• GOVERNMENT_FINE_SCAM: Deceptive content claiming an outstanding civic fine must be paid.
• FAKE_PRIZE_SCAM: Deceptive pages offering unrealistic rewards or prizes.
• OTHER_PHISHING / OTHER_SCAM: Social engineering attacks that don't belong to the other categories named here.

targetedBrand

The targetedBrand object identifies the entity targeted by phishing and social engineering campaigns.

• brandName: The recognizable name of the brand or company being impersonated (for example, Altostrat).
• domain: The legitimate domain of the brand being impersonated (for example, altostrat.com).

Important notes for preview participants

• Consistency in taxonomy: Phishing remains categorized under the SOCIAL_ENGINEERING threat type (rather than a separate PHISHING parent type) to ensure consistency across the Web Risk and Safe Browsing API suite.
• Excluded categories: Subcategories for MALWARE and UNWANTED_SOFTWARE are excluded from this release.
• Handling unlisted threats: If your submission doesn't map to a specific subtype, use OTHER_PHISHING or OTHER_SCAM. We recommend using the comments field in ThreatJustification to describe the attack.
• Optional but encouraged: Providing these fields helps Web Risk prioritize and enhance the associated threat intelligence models.
• Preview phase: Enum values and behavior for this feature are subject to change.

Submit URLs

To submit a URL, send an HTTP POST request to the projects.uris.submit method.

• The Submission API supports one URL per request. To check multiple URLs, you need to send a separate request for each URL.

• The URL must be valid but it doesn't need to be canonicalized. For more information, see RFC 2396.

• The HTTP POST response returns a long-running operation. For more information about how to retrieve the submission result and check the status of a submission, see Long-running operations.

Example

HTTP method and URL:

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

Request JSON body:

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

To send your request, choose one of these options:

curl

Note: The following command assumes that you have logged in to the gcloud CLI with your user account by running gcloud init or gcloud auth login , or by using Cloud Shell, which automatically logs you into the gcloud CLI . You can check the currently active account by running gcloud auth list.

Save the request body in a file named request.json, and execute the following command:

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

Note: The following command assumes that you have logged in to the gcloud CLI with your user account by running gcloud init or gcloud auth login . You can check the currently active account by running gcloud auth list.

Save the request body in a file named request.json, and execute the following command:

$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

You should receive a JSON response similar to the following:

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

Check the submission status

Use the project-number and operation-id from the response to check the submission status. The status is located in the metadata.state field of the returned operation.

The possible states include RUNNING, SUCCEEDED, and CLOSED. For more information about these states, see Understanding Operation Status in the Long-running Operations guide.