Chronicle DataTap Configuration API

DataTap Configuration API enables the transmission of normalized events to Cloud Pub/Sub. You can use this API to send normalized events or alert events and manage the topics where the events are to be sent.

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>

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

Regional Endpoints

Chronicle provides regional endpoints for each API. For example:

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

Before you begin

Give publisher role to publisher@chronicle-data-tap.iam.gserviceaccount.com on your Pub/Sub Topic.

Specifying Topic

When creating, updating, or deleting DataTap configurations, it's necessary to specify the Pub/Sub topic where the events are sent to. This is done by specifying the project, the project id, topic, and topic id in the request body of the Create, Update, and Delete APIs.

Specifying Filter

Filter defines which events are to be sent to customers. Valid values for filter include:

  • ALL_UDM_EVENTS : All events are sent to the topic.
  • ALERT_UDM_EVENTS : Only events that represent a significant alert (CBN Alerts) are sent to the topic.

Specifying serializationFormat

serializationFormat defines the format for sent events. Valid values for serializationFormat include:

  • JSON: Events are sent in JSON format.
  • MARSHALLED_PROTO: Events are sent in proto format.

The default value is MARSHALLED_PROTO.

Chronicle DataTap Configuration API Reference

This section describes the Chronicle DataTap Configuration API methods.

Create

Creates a DataTap configuration.

Request

POST https://backstory.googleapis.com/v1/dataTaps
URL parameters

None

Request Body

{
  "displayName": "<Name of the DataTap>",
  "cloudPubsubSink": {
    "topic": "<topicId>",
  },
  "filter": "<filter>",
  "serializationFormat": "<serializationFormat>"
}
Body Parameters
Parameter Name Type Required Description
displayName string Yes Name for the DataTap configuration being created.
topic string Yes

TopicId where events are to be sent.

Use the following format: projects/<project_id>/topics/<topicId>

filter enum Yes

ALL_UDM_EVENTS: Retrieve all normalized events.

ALERT_UDM_EVENTS: Retrieve all alert events.

serializationFormat enum No

JSON: Retrieve events in JSON format.

MARSHALLED_PROTO: Retrieve events in proto format.

Sample Request
https://backstory.googleapis.com/v1/dataTaps
{
  "displayName": "tap1",
  "cloudPubsubSink": {
    "topic": "projects/sample-project/topics/sample-topic",
  },
  "filter": "ALL_UDM_EVENTS",
  "serializationFormat": "JSON"
}

Response

Sample Response
{
  "customerId": "cccccccc-cccc-cccc-cccc-cccccccccccc",
  "tapId": "aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa",
  "displayName": "tap1",
  "cloudPubsubSink": {
    "topic": "projects/sample-project/topics/sample-topic",
  },
  "filter": "ALL_UDM_EVENTS",
  "serializationFormat": "JSON"
}

Update

Updates a DataTap configuration.

Request

PATCH https://backstory.googleapis.com/v1/dataTaps/<tapId>
URL parameters
Parameter Name Type Required Description
tapId string Yes tapId given in response when the DataTap configuration was created.

Request Body

{
  "name": "dataTaps/<tapId>",
  "displayName": "<Name of the DataTap>",
  "cloudPubsubSink": {
    "topic": "<topicId>",
  },
  "filter": "<filter>",
  "serializationFormat": "<serializationFormat>"
}
Body Parameters
Parameter Name Type Required Description
name string Yes

Use format: dataTaps/<tapId>

tapId given in response when the DataTap configuration was created.

displayName string Yes Name for the DataTap configuration being created.
topic string Yes

TopicId where events are to be sent.

Use the following format: projects/<project_id>/topics/<topicId>

filter enum Yes

ALL_UDM_EVENTS: Retrieve all normalized events.

ALERT_UDM_EVENTS: Retrieve all alert events.

serializationFormat enum No

JSON: Retrieve events in JSON format.

MARSHALLED_PROTO: Retrieve events in proto format.

Sample Request
https://backstory.googleapis.com/v1/dataTaps/aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa

{
  "name": "dataTaps/aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa",
  "displayName": "tap1",
  "cloudPubsubSink": {
    "topic": "projects/sample-project/topics/sample-topic",
  },
  "filter": "ALL_UDM_EVENTS",
  "serializationFormat": "JSON"
}

Response

Sample Response
{
  "customerId": "cccccccc-cccc-cccc-cccc-cccccccccccc",
  "tapId": "aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa",
  "displayName": "tap1",
  "cloudPubsubSink": {
    "topic": "projects/sample-project/topics/sample-topic",
  },
  "filter": "ALL_UDM_EVENTS",
  "serializationFormat": "JSON"
}

Delete

Deletes a DataTap configuration.

Request

DELETE https://backstory.googleapis.com/v1/dataTaps/<tapId>
URL parameters
Parameter Name Type Required Description
tapId string Yes tapId given in response when the DataTap configuration was created.

Request Body

{
  "name": "dataTaps/<tapId>",
}
Body Parameters
Parameter Name Type Required Description
name string Yes

Use the following format: dataTaps/<tapId>

tapId given in response when the DataTap configuration was created.

Sample Request
https://backstory.googleapis.com/v1/dataTaps/aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa

{
  "name": "dataTaps/aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa",
}

Response

Sample Response

Returns an empty JSON with 200 OK, indicating the operation has completed successfully.

Get

Get a specific DataTap configuration.

Request

GET https://backstory.googleapis.com/v1/dataTaps/<tapId>
URL parameters
Parameter Name Type Required Description
tapId string Yes tapId given in response when the DataTap configuration was created.

Request Body

{
  "name": "dataTaps/<tapId>",
}
Body Parameters
Parameter Name Type Required Description
name string Yes

Use format: dataTaps/<tapId>

tapId given in response when the DataTap configuration was created.

Sample Request
https://backstory.googleapis.com/v1/dataTaps/aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa

{
  "name": "dataTaps/aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa",
}

Response

Sample Response
{
  "customerId": "cccccccc-cccc-cccc-cccc-cccccccccccc",
  "tapId": "aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa",
  "displayName": "tap1",
  "cloudPubsubSink": {
    "topic": "projects/sample-project/topics/sample-topic",
  },
  "filter": "ALL_UDM_EVENTS",
  "serializationFormat": "MARSHALLED_PROTO"
}

List

List all the DataTap configurations of a customer.

Request

GET https://backstory.googleapis.com/v1/dataTaps
URL parameters

None

Request Body

Empty

Body Parameters

None

Sample Request
https://backstory.googleapis.com/v1/dataTaps

Response

Sample Response
[
  {
    "customerId": "cccccccc-cccc-cccc-cccc-cccccccccccc",
    "tapId": "aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa",
    "displayName": "tap1",
    "cloudPubsubSink": {
      "topic": "projects/sample-project/topics/sample-topic",
    },
    "filter": "ALL_UDM_EVENTS",
    "serializationFormat": "JSON"
  },
  {
    "customerId": "cccccccc-cccc-cccc-cccc-cccccccccccc",
    "tapId": "bbbbbbbb-bbbb-bbbb-bbbb-bbbbbbbbbbbb",
    "displayName": "tap2",
    "cloudPubsubSink": {
      "topic": "projects/sample-project/topics/sample-topic-2",
    },
  "filter": "ALERT_UDM_EVENTS",
  "serializationFormat": "MARSHALLED_PROTO"
  }
]