Chronicle RBAC API

This document explains how you can use the Chronicle RBAC API to programmatically access your security data directly through API calls to the Google Security Operations platform, which stores and processes that data. This is the same security data presented in the Google SecOps UI through your Google SecOps 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 Google SecOps.

Authenticate with the Chronicle API

This document describes how the Chronicle API uses the OAuth 2.0 protocol for authentication and authorization. Your application can handle this using one of the following methods:

Use the Chronicle API client library for your programming 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 Chronicle API client libraries. See other language implementations.

Get 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 Chronicle 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 the Google Developer Service Account Credential and Chronicle 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/

Frequently asked questions

Does the API endpoint vary depending on the region?

Yes. Your API endpoint will vary depending on where your customer account is provisioned:

São Paulo—https://southamerica-east1-backstory.googleapis.com
Canada—https://northamerica-northeast2-backstory.googleapis.com
Dammam—https://me-central2-backstory.googleapis.com
Doha—https://me-central1-backstory.googleapis.com
Europe Multi-Region—https://europe-backstory.googleapis.com
Frankfurt—https://europe-west3-backstory.googleapis.com
London—https://europe-west2-backstory.googleapis.com
Mumbai—https://asia-south1-backstory.googleapis.com
Paris—https://europe-west9-backstory.googleapis.com
Singapore—https://asia-southeast1-backstory.googleapis.com
Sydney—https://australia-southeast1-backstory.googleapis.com
Tel Aviv—https://me-west1-backstory.googleapis.com
Tokyo—https://asia-northeast1-backstory.googleapis.com
Turin—https://europe-west12-backstory.googleapis.com
United States Multi-Region—https://backstory.googleapis.com
Zurich—https://europe-west6-backstory.googleapis.com

Chronicle RBAC API Reference

Role-based access control (RBAC) enables you to tailor access to Google SecOps features based on an employee's role in your organization.

This section describes the Chronicle RBAC API methods.

ListRoles

Retrieves all roles.

Request

GET https://backstory.googleapis.com/v1/roles

Parameters

None

Sample Request

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

Response

Sample Response

{
   "roles": [
      {
        "name": "Test",
        "title": "Test role",
        "description": "The test role",
        "isDefault": false,
        "permissions": [
          {
            "name": "Test",
            "title": "Test permission",
            "description": "The test permission",
            "createTime": "yyyy-mm-ddThh:mm:ss.ssssssZ",
          },
          ...
        ]
      },
      ...
    ],
}

UpdateRole

Updates a role to specify whether it is the default role.

Request

PATCH https://backstory.googleapis.com/v1/roles/Administrator

Body Parameters

Parameter Name	Type	Required	Description
isDefault	bool	Yes	Whether this role should be the default role.

Sample Request

https://backstory.googleapis.com/v1/roles/Administrator

{
    "isDefault": true
}

Response

Sample Response

{
   "role": {
        "name": "Test",
        "title": "Test role",
        "description": "The test role",
        "isDefault": true,
        "permissions": [
          {
            "name": "Test",
            "title": "Test permission",
            "description": "The test permission",
            "createTime": "yyyy-mm-ddThh:mm:ss.ssssssZ",
          },
          ...
        ]
      },
      ...
    },
}

CreateSubject

Creates a subject and assigns the given role.

Request

POST https://backstory.googleapis.com/v1/subjects

Body Parameters

Parameter Name	Type	Required	Description
`name`	`string`	Yes	The ID of the subject to be created.
`type`	`string`	Yes	The type of the subject, e.g., SUBJECT_TYPE_ANALYST (an analyst) or SUBJECT_TYPE_IDP_GROUP (a group).
`roles`	`string`	Yes	The role(s) the created subject must have.

Sample Request

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

{
  "name": "test@test.com",
  "type": "SUBJECT_TYPE_ANALYST",
  "roles": [
    {
      "name": "Test",
    }
    ...
  ]
}

Response

Sample Response

{
  "subject": {
    "name": "test@test.com",
    "type": "SUBJECT_TYPE_ANALYST",
    "roles": [
      {
        "name": "Test",
        "title": "Test role",
        "description": "The test role",
        "createTime": "yyyy-mm-ddThh:mm:ss.ssssssZ",
        "isDefault": false,
        "permissions": [
          {
            "name": "Test",
            "title": "Test permission",
            "description": "The test permission",
            "createTime": "yyyy-mm-ddThh:mm:ss.ssssssZ",
          },
          ...
        ]
      },
      ...
    ]
  }
}

GetSubject

Retrieves a subject.

Request

GET https://backstory.googleapis.com/v1/subjects/{subject_id}

URL Parameters

Parameter Name	Type	Required	Description
subject_id	string	Yes	Unique identifier for the subject.

Sample Request

https://backstory.googleapis.com/v1/subjects/test@test.com

Response

Sample Response

{
  "subject": {
    "name": "test@test.com",
    "type": "SUBJECT_TYPE_ANALYST",
    "roles": [
      {
        "name": "Test",
        "title": "Test role",
        "description": "The test role",
        "createTime": "yyyy-mm-ddThh:mm:ss.ssssssZ",
        "isDefault": false,
        "permissions": [
          {
            "name": "Test",
            "title": "Test permission",
            "description": "The test permission",
            "createTime": "yyyy-mm-ddThh:mm:ss.ssssssZ",
          },
          ...
        ]
      },
      ...
    ]
  }
}

ListSubjects

Retrieves all subjects.

Request

GET https://backstory.googleapis.com/v1/subjects

URL Parameters

Parameter Name	Type	Required	Description
page_size	integer	Optional	Specify the maximum number of subjects to return (range is 1 through 1,000). The default is 100.
page_token	string	Optional	Page token received from a previous call. Use to retrieve the next page.

Sample Request

https://backstory.googleapis.com/v1/subjects?page_size=10&page_token=abc

Response

Sample Response

{
  "subjects": [
{
    "name": "test@test.com",
    "type": "SUBJECT_TYPE_ANALYST",
    "roles": [
      {
        "name": "Test",
        "title": "Test role",
        "description": "The test role",
        "createTime": "yyyy-mm-ddThh:mm:ss.ssssssZ",
        "isDefault": false,
        "permissions": [
          {
            "name": "Test",
            "title": "Test permission",
            "description": "The test permission",
            "createTime": "yyyy-mm-ddThh:mm:ss.ssssssZ",
          },
          ...
        ]
      },
      ...
    ]
  }
….
    ],
    "nextPageToken": "NEXT_PAGE_TOKEN",
}

UpdateSubject

Updates the role of the specified subject.

Request

PATCH https://backstory.googleapis.com/v1/subjects/{subject_id}

Body Parameters

Parameter Name	Type	Required	Description
`roles`	`string`	Yes	The role(s) the subject must have after the update.

Sample Request

https://backstory.googleapis.com/v1/subjects/test@test.com
{
  "subject": {
    "name": "test@test.com",
    "type": "SUBJECT_TYPE_ANALYST",
    "roles": [
      {
        "name": "Test",
      }
      ...
    ]
  }
}

Response

Sample Response

{
  "subject": {
    "name": "test@test.com",
    "type": "SUBJECT_TYPE_ANALYST",
    "roles": [
      {
        "name": "Test",
        "title": "Test role",
        "description": "The test role",
        "createTime": "yyyy-mm-ddThh:mm:ss.ssssssZ",
        "isDefault": false,
        "permissions": [
          {
            "name": "Test",
            "title": "Test permission",
            "description": "The test permission",
            "createTime": "yyyy-mm-ddThh:mm:ss.ssssssZ",
          },
          ...
        ]
      },
      ...
    ]
  }
}

DeleteSubject

Deletes a subject.

Request

DELETE https://backstory.googleapis.com/v1/subjects/{subject_id}

URL Parameters

Parameter Name	Type	Required	Description
subject_id	string	Yes	Unique identifier for the subject.

Sample Request

https://backstory.googleapis.com/v1/subjects/test@test.com

Response

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