Stay organized with collections Save and categorize content based on your preferences.

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 in order 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 evidences of violation of policies:

  • Social engineering content that mimics system alerts, uses deceptive URLs, or contains fake login pages to phish credentials.
  • A site that is hosting a known Malware executable.

Only URLs confirmed to violate these policies are added to Safe Browsing blocklists.

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.phishingsite.com/"
  }
}

To send your request, choose one of these options:

curl

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

curl -X POST \
    -H "Authorization: Bearer $(gcloud auth application-default 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

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

$cred = gcloud auth application-default 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-id/operations/operation-id",
}

Java


import com.google.cloud.webrisk.v1.WebRiskServiceClient;
import com.google.webrisk.v1.CreateSubmissionRequest;
import com.google.webrisk.v1.Submission;
import java.io.IOException;
import java.util.concurrent.ExecutionException;
import java.util.concurrent.TimeUnit;
import java.util.concurrent.TimeoutException;

public class SubmitUri {

  public static void main(String[] args)
      throws IOException, ExecutionException, InterruptedException, TimeoutException {
    // TODO(developer): Replace these variables before running the sample.
    // The name of the project that is making the submission.
    String projectId = "GOOGLE_CLOUD_PROJECT";
    // The URI that is being reported for malicious content to be analyzed.
    String uri = "http://testsafebrowsing.appspot.com/s/malware.html";

    submitUri(projectId, uri);
  }

  // Submits a URI suspected of containing malicious content to be reviewed. Returns a
  // google.longrunning.Operation which, once the review is complete, is updated with its result.
  // If the result verifies the existence of malicious content, the site will be added to the
  // Google's Social Engineering lists in order to protect users that could get exposed to this
  // threat in the future. Only allow-listed projects can use this method during Early Access.
  public static void submitUri(String projectId, String uri)
      throws IOException, ExecutionException, InterruptedException, TimeoutException {
    // Initialize client that will be used to send requests. This client only needs to be created
    // once, and can be reused for multiple requests. After completing all of your requests, call
    // the `webRiskServiceClient.close()` method on the client to safely
    // clean up any remaining background resources.
    try (WebRiskServiceClient webRiskServiceClient = WebRiskServiceClient.create()) {

      Submission submission = Submission.newBuilder()
          .setUri(uri)
          .build();

      CreateSubmissionRequest submissionRequest =
          CreateSubmissionRequest.newBuilder()
              .setParent(String.format("projects/%s", projectId))
              .setSubmission(submission)
              .build();

      Submission submissionResponse = webRiskServiceClient.createSubmissionCallable()
              .futureCall(submissionRequest).get(3, TimeUnit.MINUTES);

      System.out.println("Submission response: " + submissionResponse);
    }
  }
}

Python

from google.cloud import webrisk_v1


def submit_uri(project_id: str, uri: str) -> None:
    """Submits a URI suspected of containing malicious content to be reviewed.

    Returns a google.longrunning.Operation which, once the review is complete, is updated with its result.
    If the result verifies the existence of malicious content, the site will be added to the
    Google's Social Engineering lists in order to protect users that could get exposed to this
    threat in the future. Only allow-listed projects can use this method during Early Access.

     Args:
         project_id: The name of the project that is making the submission.
         uri: The URI that is being reported for malicious content to be analyzed.
             uri = "http://testsafebrowsing.appspot.com/s/malware.html"
    """
    webrisk_client = webrisk_v1.WebRiskServiceClient()

    submission = webrisk_v1.Submission()
    submission.uri = uri

    request = webrisk_v1.CreateSubmissionRequest()
    request.parent = f"projects/{project_id}"
    request.submission = submission

    response = webrisk_client.create_submission(request)
    print(f"Submission response: {response}")

Check the submission status

You can check the status of the submission by using the project-id and operation-id values from the response.

SUCCEEDED indicates that the submitted URL was added to the Safe Browsing Blocklist.

CLOSED indicates that the submitted URL was not detected to violate the Safe Browsing Policies and was not added to the Safe Browsing Blocklist in the last 24 hours.