Chronicle Google Cloud Threat Intelligence API

The Chronicle Google Cloud Threat Intelligence (GCTI) API enables customers to programmatically access their security data directly through API calls to the Chronicle Platform that stores and processes the data. This is the same security data presented in the Chronicle UI through your Chronicle customer account.

This capability enables you to develop new applications or modify existing applications to retrieve and process all your security data currently stored in Chronicle.

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>

GCTI API Programming Environment

Complete the following to call the GCTI API:

  1. Follow the instructions in the README.md file on Chronicle's github repository:

    https://github.com/chronicle/api-samples-python/blob/master/README.md

  2. The GCTI github repository is located here:

    https://github.com/chronicle/api-samples-python/tree/master/uppercase

Regional Endpoints

Chronicle provides regional endpoints for each API. For example:

https://backstory.googleapis.com/v1/uppercaseAlerts/
https://europe-backstory.googleapis.com/v1/uppercaseAlerts/
https://asia-southeast1-backstory.googleapis.com/v1/uppercaseAlerts/

GCTI API reference

GetAlert

Return the specified GCTI alert.

Request

https://backstory.googleapis.com/v1/uppercaseAlerts/{alert_id}

Body Parameter

Parameter Name Type Description
alert_id string Unique identifier for an alert, defined and returned by the server. You can specify exactly one rule identifier using the following format: {UUID}
Sample Request
https://backstory.googleapis.com/v1/uppercaseAlerts/2840
Sample Response
{
    'alertId': 2840,
    'createTime': '2020-10-06T17:49:36.880061088Z',
    'eventGroups': [
        {
            'assets': ['asset2'],
            'events': [
                {
                    'metadata': {
                        'eventTimestamp': '2020-04-07T19:24:04Z',
                        'eventType': 'GENERIC_EVENT',
                        'productEventType': 'module_load',
                        'productName': 'Unknown'
                    },
                    'principal': {
                        'assetId': '200',
                        'hostname': 'asset2',
                        'process': {
                            'file': {'fullPath': 'c:\\windows\\explorer.exe'},
                             'pid': '2000',
                             'productSpecificProcessId': '00000-00000-00002'
                        }
                    },
                    'target': {
                        'file': {
                            'fullPath': 'c:\\program '
                            'md5': '343536373839303132333d3d'
                        }
                    }
                }
            ]
        }
    ],
    'resolutionState': {'closureState': 'OPEN'},
    'updateTime': '2020-10-06T17:55:43.816145373Z'
}

Response Fields

Field Name Type Description
alertId string Id for the GCTI alert.
createTime string Time the alert was created.
description string Description of the alert.
eventGroups list Group of events that trigger the alert.
correspondence list Additional information.
resolutionState.closureState enum Current status of the alert.
resolutionState.accuracyState enum Estimated accuracy of the alert.
updateTime string Last time the alert was updated.

Python Sample Code

 def get_alert(self, alert_id):
   r"""Call the GetAlert RPC.
   Args:
     alert_id: Alert id string
   Returns:
   {
     'GCTI alert information': '',
   }
   """
   url = "{}/uppercaseAlerts/{}".format(self.backstory_api_url, alert_id)
   _LOGGER_.info("get alert: %s ", url)

   # Make a request
   response = self.client.request(url, "GET")
   return self._parse_response(response)

ListAlerts

List all of the GCTI alerts tracked within your enterprise for the specified time range. Both the parsed alerts and their corresponding raw alert logs are returned.

Request

https://backstory.googleapis.com/v1/uppercaseAlerts/

Parameters

Parameter Name Type Description
pageToken string Use to retrieve another page of detections.
pageSize integer Specify the limit on the number of pages of detections to display.
Sample Request
https://backstory.googleapis.com/v1/uppercaseAlerts/
Sample Response
{
    'uppercaseAlerts': [
        {
            'alertId': 2840,
            'createTime': '2020-10-06T17:49:36.880061088Z',
            'eventGroups': [
                {
                    'assets': ['asset2'],
                    'events': [
                        {
                            'metadata': {
                                'eventTimestamp': '2020-04-07T19:24:04Z',
                                'eventType': 'GENERIC_EVENT',
                                'productEventType': 'module_load',
                                'productName': 'Unknown'
                            },
                            'principal': {
                                'assetId': '200',
                                'hostname': 'asset2',
                                'process': {
                                    'file': {'fullPath': 'c:\\windows\\explorer.exe'},
                                     'pid': '2000',
                                     'productSpecificProcessId': '00000-00000-00002'
                                }
                            },
                            'target': {
                                'file': {
                                    'fullPath': 'c:\\program '
                                    'md5': '343536373839303132333d3d'
                                }
                            }
                        }
                    ]
                }
            ],
            'resolutionState': {'closureState': 'OPEN'},
            'updateTime': '2020-10-06T17:55:43.816145373Z'
        }
        {
            'alertId': '00',
            'correspondence': [
                {
                    'author': 'GCTI',
                    'content': 'first correspondence',
                    'createTime': '2020-09-29T23:21:50.750926871Z',
                    'resolutionState': {}
                },
                {
                    'author': 'external',
                    'content': 'second correspondence',
                    'createTime': '2020-09-29T23:23:14.047105821Z',
                    'resolutionState': {'closureState': 'CLOSED'}
                },
                {
                    'author': 'external',
                    'content': 'third correspondence',
                    'createTime': '2020-09-29T23:28:01.653171106Z',
                    'resolutionState': {'accuracyState': 'TRUE_POSITIVE'}
                }
            ],
            'createTime': '2020-09-21T21:32:40.336784166Z',
            'description': 'GCTI found suspect activity in the following assets:',
            'resolutionState': {
                'accuracyState': 'TRUE_POSITIVE',
                'closureState': 'CLOSED'
            },
            'updateTime': '2020-09-29T23:28:01.653318418Z'
        }
    ]
}
'nextPageToken': 'CgsIkdvj_gUQ2M2IXBIMCISzpP4FELj3oLUDGidkZV9lYzJiYzUyYi1hNTIyLWFlYWYtNmE5NC1mN2M3Y2UwZWZmMTU='

Python Sample Code

 def list_alerts(self, page_size=0, page_token=""):
   """Call the ListAlerts RPC.
   Returns:
     {'alerts': [
         {
           'all the alert stuff': '',
         }, ... ]
     }
   """
   url = "{}/uppercaseAlerts?page_size={}&page_token={}".format(
       self.backstory_api_url, page_size, page_token)
   _LOGGER_.info("list alerts: %s ", url)

   # Make a request
   response = self.client.request(url, "GET")
   return self._parse_response(response)