Stay organized with collections Save and categorize content based on your preferences.

UDM Search API

The Chronicle UDM Search API enables customers to programmatically complete a UDM Search query and retrieve matches. This is the same type of query which can be performed using the UDM Search Query feature in the Chronicle UI.

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

UDM Search API reference

The following section describe the Chronicle UDM Search API method.

Note: All requests must be made using authenticated Google API client libraries as described in

How to Authenticate with the Chronicle API. All responses are provided in JSON.

udmSearch

This method enables customers to programmatically complete a UDM Search query and retrieve matches.

Request

https://backstory.googleapis.com/v1/events:udmSearch?query=<query>&time_range.start_time=<start_time>&time_range.end_time=<end_time>&limit=<limit>
Parameters
Parameter Name Type Description
query string UDM search query.
time_range.start_time ISO 8601 format Inclusive start time.
time_range.end_time ISO 8601 format Exclusive end time.
limit integer (Optional) The maximum number of matched events to return. Must be less than or equal to 1,000.
Response Fields
Field Description
events List of matched UDM events.
moreDataAvailable Set to true if the limit was reached and more matches exist.
Sample Request
https://backstory.googleapis.com/v1/events:udmSearch?query=metadata.event_type+%3D+%22NETWORK_CONNECTION%22+and+principal.hostname%3D%22jdx%22&time_range.start_time=2022-08-04T00%3A00%3A00Z&time_range.end_time=2022-08-04T01%3A00%3A00Z&limit=100
Sample Response
{
  "events": [
    {
      "name": "00000000c5fd1146ce52d833659247f68b82009d000000000500000000000000",
      "udm": {
        "metadata": {
          "eventTimestamp": "2022-09-14T00:59:59.567051Z",
          "eventType": "NETWORK_CONNECTION",
          "ingestedTimestamp": "2022-09-14T01:00:20.783486Z",
          "id": "AAAAAMX9EUbOUtgzZZJH9ouCAJ0AAAAABQAAAAAAAAA="
        },
        "principal": {
          "ip": [
            "10.9.8.7"
          ],
        },
        "target": {
          "ip": [
            "74.125.197.190"
          ],
          "port": 443
        }
      }
    },
    {
      "name": "000000000f8e8dc25f873448a3b51ed3e81af0d900000000050000001c000000",
      "udm": {
        "metadata": {
          "eventTimestamp": "2022-09-14T00:59:59.567051Z",
          "eventType": "NETWORK_CONNECTION",
          "ingestedTimestamp": "2022-09-14T01:00:20.071428Z",
          "id": "AAAAAA+OjcJfhzRIo7Ue0+ga8NkAAAAABQAAABwAAAA="
        },
        "principal": {
          "ip": [
            "10.9.8.7"
          ]
        },
        "target": {
          "ip": [
            "74.125.135.103"
          ],
          "port": 443
        }
      }
    }
  ]
}

The API responds with a list of matched UDM events (up to the limit).