Search

This document explains how you can use the Backstory Search API to programmatically access your security data directly through API calls to the Google Security Operations platform, which stores and processes that data. This is the same security data presented in the Google SecOps UI through your Google SecOps customer account.

The capability to access security data through API calls lets you develop new applications or modify existing applications to retrieve and process all your security data stored in Google SecOps.

Examples (in Python) for making OAuth authenticated requests to the Backstory API are provided for each API call referenced in this document.

Get 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 Backstory 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 the Google Developer Service Account Credential and Backstory 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/

Search API query submission rate limits

The Search API enforces limits on the number of requests that you can send to the Google SecOps platform. If you reach or exceed the query submission rate limit, the Backstory API server returns HTTP 429 (RESOURCE_EXHAUSTED) to the caller. When developing applications for the Backstory API, Google SecOps recommends that you enforce query submission rate limits within your system to avoid resource exhaustion. These limits apply to all Backstory APIs, including Search, Customer Management, and Tooling.

The following query submission rate limits are enforced, measured in queries per second (QPS) or queries per hour (QPH):

See the detailed list of the Backstory API query limits.

UDM search timeout limits

The query timeout limit for a UDM search is different when you send it using the UI or an API. UDM search timeout limits:

• Timeout for queries sent from the UI: 1 hour
• Timeout for queries sent from an API: 10 minutes

If your search query reaches the timeout limit, you need to reduce the scope of the search. The simplest way to do this is by reducing the time range.

Frequently asked questions

How Do You Specify Time?

For the methods requiring time values, enter time using the time standard defined in RFC 3339. Time is represented by the span of UTC time since Unix epoch 1970-01-01T00:00:00Z.

What is the Page Size Property?

For each API call, you can specify the page_size property to limit the maximum number of returned results. As there's no next page token, to limit the volume of data returned, specify a narrower time range.

What Is an Artifact?

An artifact is an identifier like a website domain, file hash, or IP address that is used to identify a malicious website, file, or computer system that might be contacted or used by a device in your environment.

Artifacts can be any of the following:

• Domain name
• Destination IP address
• File hash (MD5, SHA1, SHA256)

What is an Asset?

An asset is a system within your enterprise that might have been affected by a security incident. Assets are identified by any of the following:

• Hostname
• IP address
• MAC address
• Product ID

Regional Endpoints

Google SecOps provides regional endpoints for each API.

• São Paulo—https://southamerica-east1-backstory.googleapis.com
• Canada—https://northamerica-northeast2-backstory.googleapis.com
• Dammam—https://me-central2-backstory.googleapis.com
• Doha—https://me-central1-backstory.googleapis.com
• Europe Multi-Region—https://europe-backstory.googleapis.com
• Frankfurt—https://europe-west3-backstory.googleapis.com
• Jakarta—https://asia-southeast2-backstory.googleapis.com
• Johannesburg—https://africa-south1-backstory.googleapis.com
• London—https://europe-west2-backstory.googleapis.com
• Mumbai—https://asia-south1-backstory.googleapis.com
• Paris—https://europe-west9-backstory.googleapis.com
• Warsaw—https://europe-central2-backstory.googleapis.com
• Singapore—https://asia-southeast1-backstory.googleapis.com
• Sydney—https://australia-southeast1-backstory.googleapis.com
• Tel Aviv—https://me-west1-backstory.googleapis.com
• Tokyo—https://asia-northeast1-backstory.googleapis.com
• Turin—https://europe-west12-backstory.googleapis.com
• United States Multi-Region—https://backstory.googleapis.com
• Zurich—https://europe-west6-backstory.googleapis.com

The following example shows the Europe multi-region endpoint for the listalerts method:

https://europe-backstory.googleapis.com/v1/alert/listalerts

Strings in APIs require URL-encoding

All special characters in string-type API