Google Cloud Web Risk Python Client

Common errors

• google.auth.exceptions.DefaultCredentialsError: Could not automatically determine credentials. Please set GOOGLE_APPLICATION_CREDENTIALS or provide a Google Cloud project ID.

  cause The application failed to find valid Google Cloud authentication credentials in the environment.
  fix Ensure the `GOOGLE_APPLICATION_CREDENTIALS` environment variable points to a valid service account key file, or use `gcloud auth application-default login` for local development. Alternatively, explicitly pass credentials to the client constructor.

• 404 Not Found: POST https://webrisk.googleapis.com/v1/projects/YOUR_PROJECT_ID/submissions:create: Method not found.

  cause Attempted to use the `submit_uri` method without the project being allowlisted for Early Access, or incorrect API endpoint/version used.
  fix Verify that your Google Cloud project has been allowlisted for the Web Risk Submission API. If not, only the `search_uris` method is generally available. Double-check the API endpoint and method signature in your code.

• ImportError: cannot import name 'WebRiskServiceClient' from 'google.cloud.webrisk' (/path/to/python/site-packages/google/cloud/webrisk/__init__.py)

  cause Attempted to import `WebRiskServiceClient` directly from `google.cloud.webrisk` instead of the versioned submodule `google.cloud.webrisk_v1`.
  fix Change your import statement to `from google.cloud.webrisk_v1 import WebRiskServiceClient`.

Warnings

• gotcha Authentication is required for all Google Cloud client library operations. Ensure `GOOGLE_APPLICATION_CREDENTIALS` environment variable is set or your environment is authenticated via `gcloud auth application-default login`.
  Fix: Set `GOOGLE_APPLICATION_CREDENTIALS` to a service account key JSON file or run `gcloud auth application-default login`.
• breaking The `submit_uri` method (for reporting suspicious URLs) is restricted to allowlisted projects only during Early Access. Attempts from non-allowlisted projects will fail.
  Fix: Contact Google Cloud Sales or your customer engineer to request allowlist access for your project if you need to use `submit_uri`.
• gotcha The Web Risk API client library officially supports Python 3.9 and newer. Older Python versions (3.8 and below) are unsupported.
  Fix: Upgrade your Python environment to version 3.9 or higher.
• gotcha Information returned by the Web Risk API must not be redistributed. Always refer to the official documentation for usage restrictions.
  Fix: Adhere to the Web Risk API Terms of Service, specifically regarding data redistribution limitations.
• gotcha The client library uses standard Python logging functionality, and logs may contain sensitive information. Access to these logs should be restricted.
  Fix: Configure appropriate log handling and access controls for any stored logs to prevent exposure of sensitive data. Do not rely on log message immutability.

Install

• pip install google-cloud-webrisk Install stable version

Imports

• WebRiskServiceClient

  from google.cloud.webrisk_v1 import WebRiskServiceClient

• ThreatType

  from google.cloud.webrisk_v1 import ThreatType

• SearchUrisRequest
  wrong:

  from google.cloud.webrisk_v1.types import SearchUrisRequest

  correct:

  from google.cloud.webrisk_v1 import SearchUrisRequest

  Types are directly available under the `_v1` namespace for convenience.

Quickstart

This quickstart demonstrates how to instantiate the WebRiskServiceClient and use the `search_uris` method to check a URL against various threat lists (MALWARE, SOCIAL_ENGINEERING, UNWANTED_SOFTWARE). It shows examples for both a safe and a known unsafe URI. Ensure your Google Cloud credentials are set up for the client to authenticate automatically.

import os
from google.cloud import webrisk_v1
from google.cloud.webrisk_v1 import WebRiskServiceClient, ThreatType

def search_uri(uri: str, threat_types: list[ThreatType]) -> dict:
    """Checks whether a URI is on a given threatList."""
    client = WebRiskServiceClient()
    request = webrisk_v1.SearchUrisRequest(
        uri=uri,
        threat_types=threat_types,
    )
    response = client.search_uris(request=request)
    return response.threat.to_dict() if response.threat else {"threatTypes": []}

if __name__ == "__main__":
    # Ensure GOOGLE_APPLICATION_CREDENTIALS is set, e.g.:
    # export GOOGLE_APPLICATION_CREDENTIALS="/path/to/your/keyfile.json"
    # or use `gcloud auth application-default login`
    # The client library will automatically find credentials if set.

    test_uri_safe = "http://example.com"
    # This is a known test URI for malware from Google Safe Browsing.
    test_uri_unsafe = "http://testsafebrowsing.appspot.com/s/malware.html"

    threat_types_to_check = [
        ThreatType.MALWARE,
        ThreatType.SOCIAL_ENGINEERING,
        ThreatType.UNWANTED_SOFTWARE,
    ]

    print(f"Checking safe URI: {test_uri_safe}")
    result_safe = search_uri(test_uri_safe, threat_types_to_check)
    print(f"Result for {test_uri_safe}: {result_safe}")

    print(f"\nChecking unsafe URI: {test_uri_unsafe}")
    result_unsafe = search_uri(test_uri_unsafe, threat_types_to_check)
    print(f"Result for {test_uri_unsafe}: {result_unsafe}")