Reference Lists API

How to authenticate with the Chronicle API

This Chronicle 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.

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 Chronicle representative will provide you with a Google Developer Service Account Credential to enable the API client to communicate with the API.

You also need to 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.oauth2 import service_account
from googleapiclient import _auth

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 Chronicle API
# Scope.
credentials = service_account.Credentials.from_service_account_file(SERVICE_ACCOUNT_FILE, scopes=SCOPES)

# Build an HTTP client to make authorized OAuth requests.
http_client = _auth.authorized_http(credentials)

# <your code continues here>

Chronicle Reference Lists API

A reference list is a list of values that customers can create and use within the Chronicle platform. For example, you might have a list of commonly used IP addresses or a list of hostnames that should never appear in your network.

  • Reference lists can be used within the Detection Engine to help to simplify the structure of rules.
  • Reference lists enable you to avoid using long chains of if statements within rules.

Python samples for using the Reference Lists API can be found on (https://github.com/chronicle/api-samples-python/tree/master/lists)

This section describes the Chronicle Reference Lists API methods.

Note: All requests must be made using authenticated Google API client libraries as described in [How Do You Authenticate with the Chronicle Search API?] All responses are provided in JSON.

CreateReferenceList

Creates a list.

Note: CreateList uses the POST method.

Request

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>"],
}
Parameters
Parameter Name Type Description
name string Unique name for the list.
description string Description of the list.
lines []string List of line items.
Sample Request
https://backstory.googleapis.com/v2/lists
{
  "name": "list_name",
  "description": "description of the list",
  "lines": ["line_item_1", "// comment", "line_item_2"],
}
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",
}

GetReferenceList

Returns the specified list.

Note: GetList uses the GET method.

Request

https://backstory.googleapis.com/v2/lists
Request Body
{
  "name": "<list name here>",
  "view": "<view enum here>",
}
Parameters
Parameter Name Type Description
name string Unique name for the list.
view enum 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 Request
https://backstory.googleapis.com/v2/lists
{
  "name": "list_name",
  "view": "BASIC",
}
Sample Response
{
  "name": "list_name",
  "description": "description of the list",
  // Note that "lines" is NOT included in the BASIC view.
  "create_time": "2020-11-20T17:18:20.409247Z",
}

ListReferenceLists

Enumerates lists.

Note: ListReferenceLists uses the GET method.

Request

https://backstory.googleapis.com/v2/lists
Request Body
{
  "page_size": <max page size here>,
  "page_token": "<page token here>",
  "view": "<view enum here>",
}
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 Page token, copied from a previous response, enabling you paginate through lists, starting from where the previous page left off.
view enum 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
{
  "page_size": 2,
  "page_token": "EgwIh4W4gwYQmK-BvAEaA3ExMA==",
}
Sample Response
{
  "next_page_token": "EgwI3YO4gwYQmLDprwMaAnE4",

  "lists": [
    {
      "createTime": "2020-11-20T17:18:20.409247Z",
      "description": "description of list 1",
      "name": "list_name_1"
    },
    {
      "createTime": "2020-11-20T16:18:20.409247Z",
      "description": "description of list 2",
      "name": "list_name_2"
    }
  ]
}

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

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>"],
}

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)
Sample Request
https://backstory.googleapis.com/v2/lists?update_mask=list.description,list.lines
{
"name": "list_name",
"description": "description of the list",
"lines": ["line_item_1", "// comment", "line_item_2"],
}

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",
}