Reference Lists API

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/

Google Security Operations Reference Lists API

This document describes the Google Security Operations Reference List API methods. See Reference Lists for more information about how Reference Lists work.

Python samples for using the Reference Lists API can be found in this GitHub repo.

Note: All requests must be made using authenticated Google API client libraries as mentioned above.

CreateReferenceList

Creates a list.

Note: CreateList uses the POST method.

Request

POST https://backstory.googleapis.com/v2/lists

Request Body

{
  "name": "<list name here>",
  "description": "<list description here>",
  "lines": ["<line item 1>", "<line item 2>", ..., "<line item n>"],
  "content_type": "<list content type>",
}

Parameters

Parameter Name	Type	Description
name	string	Unique name for the list.
description	string	Description of the list.
lines	[]string	List of line items.
content_type	enum	(optional) Type of list content: "CONTENT_TYPE_DEFAULT_STRING", "REGEX", "CIDR". If omitted, defaults to "CONTENT_TYPE_DEFAULT_STRING".

Sample Request

https://backstory.googleapis.com/v2/lists
{
  "name": "list_name",
  "description": "description of the list",
  "lines": ["line_item_1", "// comment", "line_item_2"],
  // omit content_type, which lets it default to "CONTENT_TYPE_DEFAULT_STRING".
}

Sample Response

{
  "name": "list_name",
  "description": "description of the list",
  "lines": ["line_item_1", "// comment", "line_item_2"],
  "create_time": "2020-11-20T17:18:20.409247Z",
  // content_type is omitted, which indicates the type is CONTENT_TYPE_DEFAULT_STRING.
}

GetReferenceList

Returns the specified reference list.

Note: GetReferenceList uses the GET method.

Request

Specify the name of the list to retrieve:

GET https://backstory.googleapis.com/v2/lists/{list_name}

The view parameter specifies how much of each reference list to view:

GET https://backstory.googleapis.com/v2/lists/{list_name}?view={view}

Parameters

Parameter Name	Type	Description
list_name	string	Unique name for the list.
view	enum	(Optional) How much of each reference list to view. BASIC returns the metadata for the list, but not the full contents. FULL returns everything. FULL is the default.

Sample Response

{
  "name": "sample_ref_list",
  "description": "description of the list",
  // Note that "lines" is NOT included in the BASIC view.
  "create_time": "2020-11-20T17:18:20.409247Z",
  // content_type is omitted, which indicates the type is CONTENT_TYPE_DEFAULT_STRING.
}

ListReferenceLists

Enumerates lists.

Note: ListReferenceLists uses the GET method.

Request

Get a list of reference lists:

GET https://backstory.googleapis.com/v2/lists

The page_size parameter controls the maximum number of reference lists to retrieve in a single request:

GET https://backstory.googleapis.com/v2/lists?page_size={page_size}

The page_token parameter specifies the page token received from the previous call, which is then used to retrieve the subsequent page:

GET https://backstory.googleapis.com/v2/lists?page_token={page_token}

The view parameter specifies how much of each reference list to view:

GET https://backstory.googleapis.com/v2/lists?view={view}

Parameters

Parameter Name	Type	Description
page_size	int	(Optional) Maximum number of lists to return in this page of reference lists. The default is 100.
page_token	string	(Optional) Page token received from a previous call. Use to retrieve the next page.
view	enum	(Optional) How much of each reference list to view. BASIC returns the metadata for the list, but not the full contents. FULL returns everything. BASIC is the default.

Sample Request

https://backstory.googleapis.com/v2/lists

Sample Response

{
  "next_page_token": "EgwI3YO4gwYQmLDprwMaAnE4",

  "lists": [
    {
      "createTime": "2020-11-20T17:18:20.409247Z",
      "description": "description of list 1",
      "name": "list_name"
      // content_type is omitted, which indicates the type is CONTENT_TYPE_DEFAULT_STRING.
    },
    {
      "createTime": "2020-11-20T16:18:20.409247Z",
      "description": "description of list 2",
      "name": "regex_list_name"
      "content_type": "REGEX",
    }
  ]
}

UpdateReferenceList

Updates an existing list.

Note: UpdateReferenceList uses the PATCH method. It requires the use of field masks. For more information, see: https://api.dev/134

Request

PATCH https://backstory.googleapis.com/v2/lists?update_mask=<update_mask>

Request Body

{
"name": "<list name here>",
"description": "<list description here>",
"lines": ["<line item 1>", "<line item 2>", ..., "<line item n>"],
"content_type": "<list content type>",
}

Parameters

Parameter Name	Type	Description
name	string	Unique name for the list.
description	string	Description of the list.
lines	[]string	List of line items.
update_mask	[]string	Mask that identifies which fields on the list to update.The following fields are valid: list.lines (Required) list.description (Optional)
content_type	enum	(optional) Type of list content: "CONTENT_TYPE_DEFAULT_STRING", "REGEX", "CIDR". Must match the type of the existing list you are updating. If omitted, defaults to "CONTENT_TYPE_DEFAULT_STRING".

Sample Request

https://backstory.googleapis.com/v2/lists?update_mask=list.description,list.lines
{
"name": "list_name",
"description": "description of the list",
"lines": ["1.2.3.4/24", "// comment", "5.6.7.8/24"],
"content_type": "CIDR",
}

Sample Response

{
"name": "list_name",
"description": "description of the list",
"lines": ["1.2.3.4/24", "// comment", "5.6.7.8/24"],
"create_time": "2020-11-20T17:18:20.409247Z",
"content_type": "CIDR",
}

VerifyReferenceList

Validates list content and returns line errors, if any.

Note: VerifyReferenceList uses the POST method.

Request

POST https://backstory.googleapis.com/v2/lists:verifyReferenceList

Request Body

{
"content_type": "<list content type>",
"lines": ["<line item 1>", "<line item 2>", ..., "<line item n>"],
}

Parameters

Parameter Name	Type	Description
content_type	enum	(optional) Type of list content: "CONTENT_TYPE_DEFAULT_STRING", "REGEX", "CIDR". If omitted, defaults to "CONTENT_TYPE_DEFAULT_STRING".
lines	[]string	List of line items.

Sample Request

https://backstory.googleapis.com/v2/lists:verifyReferenceList
{
"content_type": "CIDR",
"lines": ["invalidCIDR", "1.2.3.4/24"]
}

Sample Response

{
  "errors": [
    {
      "lineNumber": 1,
      "errorMessage": "invalid cidr pattern invalidCIDR"
    }
  ]
}