Setting up Web Risk

General setup

You must be whitelisted in order to gain access. Fill out the signup form.

Enable the API

Once you've received confirmation that you have been whitelisted, enable Web Risk.

  1. Sign in to your Google Account.

    If you don't already have one, sign up for a new account.

  2. In the Google Cloud Console, on the project selector page, select or create a Google Cloud project.

    Go to the project selector page

  3. Make sure that billing is enabled for your Cloud project. Learn how to confirm that billing is enabled for your project.

  4. Enable the Web Risk API.

    Enable the API

  5. Set up authentication:
    1. In the Cloud Console, go to the Create service account key page.

      Go to the Create Service Account Key page
    2. From the Service account list, select New service account.
    3. In the Service account name field, enter a name.
    4. From the Role list, select Project > Owner.

    5. Click Create. A JSON file that contains your key downloads to your computer.
  6. Set the environment variable GOOGLE_APPLICATION_CREDENTIALS to the path of the JSON file that contains your service account key. This variable only applies to your current shell session, so if you open a new session, set the variable again.

  7. Install and initialize the Cloud SDK.

Using the APIs

Before you begin, read our Service Level Agreement. Also, review and make sure you understand the Usage Limits for the Web Risk.

To start using Web Risk, see these topics:

Which API is right for me? Lookup or Update?

Web Risk provides two different APIs that you may integrate with. These APIs are the Lookup API and the Update API. Both of these APIs provide the same information. That is, whether a URL has been identified as malicious. The easiest to use is the Lookup API. Using the Lookup API, you will query Web Risk for every URL you wish to check.

The Update API is more complex but has some desirable properties. Using the Update API, you will maintain a local database. This database may be checked to see if a URL is malicious. This database acts as a bloom filter. That is, there may be false positives (a URL is identified as malicious but isn't) but there should not be any false negatives (a URL is identified as not malicious, but is). Because of this, the Web Risk servers are rarely contacted, and are only contacted to confirm matches and disambiguate false positives. In most cases, when checking a URL using the Update API you won't need to contact the Web Risk servers at all. You are expected to contact Web Risk servers only when updating the local database and when confirming a URL is harmful.

In summary, use the Lookup API if you want to get set up quickly and easily. Use the Update API if you need lower latency URL checking.

Choosing the Right Client Features

If you chose to use the Update API, you may not need to implement the entire specification. There are some features that were designed for widely distributed clients (like web browsers) that are over-optimizations in many enterprise cases.

There are some features that may be ignored for easier integration.

Here are the Web Risk integration solutions in order of complexity

  1. Use the LookUp API
  2. Basic Update API client
  3. Update API client using diffs
  4. Update API client using RICE compressed diffs

Using the Lookup API

Using the Lookup API has the lowest complexity. Whenever there is a potentially suspicious URL, simply call the Lookup API with the URL to see a verdict. Canonicalization and formatting the URL is handled by the Web Risk server. This solution should be valid for most clients unless average latency exceeds requirements.

Basic Update API client

TThe Update API requires the additional complexity of managing a local database and canonicalized URLs before queries.

In a typical client integration with Web Risk, a client will apply database diffs to remain up-to-date. The diff application logic may take some time to implement correctly, so in the simplest cases we recommend clients ignore diffs and request a full new database from Web Risk every cycle. This database will still be stored in memory for efficient querying. Requesting a full database reset is done by leaving the versionToken field empty in the threatLists.computeDiff request. This solution should be valid for clients unless bandwidth or database synchronization latency exceeds requirements.

Use the Update API and request diff updates

This solution has the added complexity of applying the diff logic to the local database. For more information, see Database Diffs. Using diffs will reduce bandwidth at the expense of complexity, compared to requesting a new database each cycle. A full database update may be on the order of a few megabytes. This solution should be sufficient for most enterprise clients.

Use the Update API and request RICE encoded diff updates

This solution is the most efficient client integration possible. RICE encoding compresses DIFF sizes and further reduces update bandwidth. This solution is intended to be used by the most bandwidth constrained customers. An example where this may be relevant is if Web Risk queries are built into a phone App. The users of such an app would surely appreciate a lower bandwidth solution if they needed to update the database over phone data. For more information, see Compression.