Google Security Operations BigQuery Access API

Caution: From December 31, 2024, the managed BigQuery data lake for export won't be accessible to Google Security Operations customers except for customers in the Enterprise Plus Tier. The managed BigQuery resources and API keys associated with the chronicle-tla Google Cloud project will be fully deprecated by March 31, 2025.

You can use the Google Security Operations BigQuery Access API to programmatically give users self-service access to Google Security Operations data in BigQuery.

How to authenticate with the Google Security Operations API

This Google Security Operations API uses the OAuth 2.0 protocol for authentication and authorization. Your application can complete these tasks using either of the following implementations:

• Using the Google API Client Library for your computer language.

• Directly interfacing with the OAuth 2.0 system using HTTP.

Note: Server-to-server authentication requires that your application creates and cryptographically signs JSON Web Tokens (JWTs). Exercise caution with this type of implementation, because any mishandling of authentication might significantly affect the security of the application. It's a best practice to use the Google Authentication libraries when accessing Google APIs. These libraries abstract the cryptography from your application code.

See the reference documentation for the Google Authentication library in Python.

Google Authentication libraries are a subset of the Google API client libraries. See other language implementations.

Getting API authentication credentials

Your Google Security Operations representative will provide you with a Google Developer Service Account Credential to enable the API client to communicate with the API.

You also must provide the Auth Scope when initializing your API client. OAuth 2.0 uses a scope to limit an application's access to an account. When an application requests a scope, the access token issued to the application is limited to the scope granted.

Use the following scope to initialize your Google API client:

https://www.googleapis.com/auth/chronicle-backstory

Python example

The following Python example demonstrates how to use the OAuth2 credentials and HTTP client using google.oauth2 and googleapiclient.

# Imports required for the sample - Google Auth and API Client Library Imports.
# Get these packages from https://pypi.org/project/google-api-python-client/ or run $ pip
# install google-api-python-client from your terminal
from google.auth.transport import requests
from google.oauth2 import service_account

SCOPES = ['https://www.googleapis.com/auth/chronicle-backstory']

# The apikeys-demo.json file contains the customer's OAuth 2 credentials.
# SERVICE_ACCOUNT_FILE is the full path to the apikeys-demo.json file
# ToDo: Replace this with the full path to your OAuth2 credentials
SERVICE_ACCOUNT_FILE = '/customer-keys/apikeys-demo.json'

# Create a credential using Google Developer Service Account Credential and Google Security Operations API
# Scope.
credentials = service_account.Credentials.from_service_account_file(SERVICE_ACCOUNT_FILE, scopes=SCOPES)

# Build a requests Session Object to make authorized OAuth requests.
http_session = requests.AuthorizedSession(credentials)

# Your endpoint GET|POST|PATCH|etc. code will vary below

# Reference List example (for US region)
url = 'https://backstory.googleapis.com/v2/lists/COLDRIVER_SHA256'

# You might need another regional endpoint for your API call; see
# https://cloud.google.com/chronicle/docs/reference/ingestion-api#regional_endpoints

# requests GET example
response = http_session.request("GET", url)

# POST example uses json
body = {
  "foo": "bar"
}
response = http_session.request("POST", url, json=body)

# PATCH example uses params and json
params = {
  "foo": "bar"
}
response = http_session.request("PATCH", url, params=params, json=body)

# For more complete examples, see:
# https://github.com/chronicle/api-samples-python/

Chronicle API query limits

The Chronicle API enforces limits on the volume of requests that can be made by any one customer against the Google Security Operations platform. If you reach or exceed the query limit, the Chronicle API server returns HTTP 429 (RESOURCE_EXHAUSTED) to the caller. When developing applications using the Chronicle API, enforce rate limits within your system to avoid resource exhaustion. These limits apply to all of the Chronicle APIs, including the BigQuery Access API.

The BigQuery Access API enforces the following limits, which are measured in queries per second (QPS):

Google SecOps API	API Endpoint	Limit
BigQuery Access	Update BigQuery Access	4 QPS

BigQuery Access API reference

This section describes the endpoints for the BigQuery Access API.

All requests must be made using authenticated Google API Client Libraries as described in How to authenticate with the Chronicle API. All responses are provided in JSON format.

Update BigQuery Access

Google Security Operations supports self-service access to Google Security Operations data (both SIEM and SOAR) in BigQuery. You can use the Google Security Operations CLI to grant Identity and Access Management (IAM) roles that give the following permissions for a user email:

• roles/bigquery.dataViewer
• roles/bigquery.jobUser
• roles/storage.objectViewer

The email must be a Google Accounts and ID Administration (GAIA) user email address of a Google SecOps customer.

For more information about these roles, see Exporting table data.

Request

PATCH https://backstory.googleapis.com/v1/tools/bigqueryAccess:update

Request body

{
  "email": string
}

Body parameters

Field	Type	Required	Description
email	string	Required	A user email address. The email address must be a Google Accounts and ID Administration (GAIA) user email address of a Google Security Operations customer.

Request example

PATCH https://backstory.googleapis.com/v1/tools/bigqueryAccess:update
{
  "email": "[e-mail]"
}

Response example

This is an example of the response returned for the request example above.

{
  "email": "[e-mail]",
  "roles": "bigquery.dataViewer, bigquery.jobUser, storage.objectViewer"
}