Google Chronicle Search

Google Chronicle Search is a security analytics platform that provides advanced threat detection and investigation capabilities.

Google Chronicle is a cloud-native security analytics platform designed to help organizations detect, investigate, and respond to cyber threats. The Google Chronicle Search connector enables seamless integration with Swimlane Turbine, allowing users to automate the retrieval of alerts, threat intelligence, and indicators of compromise (IoCs) from Google Chronicle. This integration enhances security operations by providing comprehensive threat visibility and actionable insights, enabling faster incident response and improved threat detection capabilities.

Prerequisites

Before you can use the Google Chronicle Search connector for Turbine, you'll need access to the Google Chronicle API. This requires the following:

OAuth2.0 authentication using the following parameters:

Service Account Info: JSON key file for service account authentication.

URL: Endpoint URL for accessing Google Chronicle services.

Scopes: Permissions required for accessing specific Google Chronicle APIs.

Capabilities

This connector provides the following capabilities:

List Alerts

List IoCs

List IoC Details

UDM Search

Asset Setup

The CEE provided credential json needs to be passed in the asset input Service Account Info as a Base64 encoded string. Failure to do so will result in the incorrect padding error.

Regional Endpoints

Chronicle provides regional endpoints for each API.

Region	Endpoint
European Multi-Region	https://europe-backstory.googleapis.com/
Tel Aviv	https://me-west1-backstory.googleapis.com/
London	https://europe-west2-backstory.googleapis.com/
Singapore	https://asia-southeast1-backstory.googleapis.com/
Sydney	https://australia-southeast1-backstory.googleapis.com/
United States Multi-Region	https://backstory.googleapis.com/

Action Setup

For the List IoC Details action, either Domain Name or Destination IP Address parameters must be specified. Both parameters must not be used at the same time.

Notes

For more information on Chronicle:

Chronicle Main Site Link

Search API Documentation

Additional Documentation

Google Chronicle Search Connector Documentation

Google Chronicle Search API Documentation

Configurations

Asset

OAuth2.0 authentication for Google Chronicle.

Configuration Parameters

Parameter	Description	Type	Required
b64_service_info	Base64-encoded bk_credentials JSON authentication file contents.	string	Required
url	Server API Address.	string	Required
scopes	Scope to be used for authentication.	array	Required
verify_ssl	Verify SSL certificate	boolean	Optional
http_proxy	A proxy to route requests through.	string	Optional

Actions

List Alerts

Retrieve asset-based and user-based alerts from Google Chronicle Search within a specified time range, requiring start_time and end_time parameters.

Endpoint

URL: v1/alert/listalerts

Method: GET

Input

Argument Name	Type	Required	Description
parameters.start_time	string	Required	RFC 3339 formatted date and time string which is the earliest event timestamp of alerts returned.
parameters.end_time	string	Required	RFC 3339 formatted date and time string which is the latest event timestamp of the alerts returned.
parameters.page_size	number	Optional	Specify the maximum number of alerts to return. You can specify between 1 and 100,000. The default is 10,000.

Input Example

{"parameters":{"start_time":"string","end_time":"string","page_size":123}}

Output

Parameter	Type	Description
alerts	array	Output field: alerts
alerts.asset	object	Output field: alerts.asset
alerts.asset.hostname	string	Name of the resource
alerts.alertInfos	array	Output field: alerts.alertInfos
alerts.alertInfos.name	string	Name of the resource
alerts.alertInfos.sourceProduct	string	Output field: alerts.alertInfos.sourceProduct
alerts.alertInfos.severity	string	Output field: alerts.alertInfos.severity
alerts.alertInfos.timestamp	string	Output field: alerts.alertInfos.timestamp
alerts.alertInfos.rawLog	string	Output field: alerts.alertInfos.rawLog
alerts.alertInfos.uri	array	Output field: alerts.alertInfos.uri
alerts.alertInfos.udmEvent	object	Output field: alerts.alertInfos.udmEvent
alerts.alertInfos.udmEvent.metadata	object	Response data
alerts.alertInfos.udmEvent.metadata.eventTimestamp	string	Response data
alerts.alertInfos.udmEvent.metadata.eventType	string	Response data
alerts.alertInfos.udmEvent.metadata.vendorName	string	Response data
alerts.alertInfos.udmEvent.metadata.productName	string	Response data
alerts.alertInfos.udmEvent.metadata.productEventType	string	Response data
alerts.alertInfos.udmEvent.metadata.description	string	Response data
alerts.alertInfos.udmEvent.metadata.urlBackToProduct	string	Response data
alerts.alertInfos.udmEvent.metadata.ingestedTimestamp	string	Response data
alerts.alertInfos.udmEvent.principal	object	Output field: alerts.alertInfos.udmEvent.principal
alerts.alertInfos.udmEvent.principal.hostname	string	Name of the resource
alerts.alertInfos.udmEvent.target	object	Output field: alerts.alertInfos.udmEvent.target
alerts.alertInfos.udmEvent.target.file	object	Output field: alerts.alertInfos.udmEvent.target.file
alerts.alertInfos.udmEvent.securityResult	array	Result of the operation

Output Example

{"alerts":[{"asset":{},"alertInfos":[]}],"userAlerts":[{"user":{},"alertInfos":[]}]}

List IoC Details

Retrieve threat intelligence for a specified artifact from enterprise security systems and Google IOC partners.

Endpoint

URL: v1/artifact/listiocdetails

Method: GET

Input

Argument Name	Type	Required	Description
parameters.artifact.domain_name	string	Optional	Domain name.
parameters.artifact.destination_ip_address	string	Optional	Destination IP address.

Input Example

{"parameters":{"artifact.domain_name":"Example Name","artifact.destination_ip_address":"string"}}

Output

Parameter	Type	Description
sources	array	Output field: sources
sources.sourceName	string	Name of the resource
sources.sourceUrl	string	URL endpoint for the request
sources.confidenceScore	object	Unique identifier
sources.confidenceScore.strRawConfidenceScore	string	Unique identifier
sources.rawSeverity	string	Output field: sources.rawSeverity
sources.category	string	Output field: sources.category
sources.addresses	array	Output field: sources.addresses
sources.addresses.port	array	Output field: sources.addresses.port
sources.addresses.domain	string	Output field: sources.addresses.domain
sources.firstActiveTime	string	Time value
sources.lastActiveTime	string	Time value
uri	array	Output field: uri

Output Example

{"sources":[{"sourceName":"ET Intelligence Rep List","sourceUrl":"http://tools.emergingthreats.net/docs/ET%20Intelligence%20Rep%20List%20Tech%20De...","confidenceScore":{},"rawSeverity":"Medium","category":"Bitcoin Mining and related","addresses":[],"firstActiveTime":"2020-07-19T00:00:00Z","lastActiveTime":"2022-04-20T00:00:00Z"}],"uri":["https://sample.backstory.chronicle.security/domainResults?domain=altostrat.com&s..."]}

List IoCs

Retrieve a list of Indicators of Compromise (IoCs) found across your enterprise for a specified time range. Requires the start_time parameter.

Endpoint

URL: v1/ioc/listiocs

Method: GET

Input

Argument Name	Type	Required	Description
parameters.start_time	string	Required	Start time for your request.
parameters.page_size	number	Optional	Specify the maximum number of IoCs to return. You can specify between 1 and 10,000. The default is 10,000.

Input Example

{"parameters":{"start_time":"string","page_size":123}}

Output

Parameter	Type	Description
done	boolean	Output field: done
response	object	Output field: response
response.@type	string	Type of the resource
response.matches	array	Output field: response.matches
response.matches.artifact	object	Output field: response.matches.artifact
response.matches.artifact.domainName	string	Name of the resource
response.matches.firstSeenTime	string	Time value
response.matches.iocIngestTime	string	Time value
response.matches.lastSeenTime	string	Time value
response.matches.sources	array	Output field: response.matches.sources
response.matches.sources.category	string	Output field: response.matches.sources.category
response.matches.sources.confidenceScore	object	Unique identifier
response.matches.sources.confidenceScore.intRawConfidenceScore	number	Unique identifier
response.matches.sources.confidenceScore.normalizedConfidenceScore	string	Unique identifier
response.matches.sources.rawSeverity	string	Output field: response.matches.sources.rawSeverity
response.matches.sources.source	string	Output field: response.matches.sources.source
response.matches.uri	array	Output field: response.matches.uri
response.moreDataAvailable	boolean	Response data

Output Example

{"done":true,"response":{"@type":"type.googleapis.com/chronicle.backstory.v1.ListIoCsResponse","matches":[{}],"moreDataAvailable":true}}

UDM Search

Execute a UDM Search query in Google Chronicle to retrieve matching events based on the provided 'query' parameter.

Endpoint

URL: v1/events:udmSearch

Method: GET

Input

Argument Name	Type	Required	Description
parameters.query	string	Required	Parameters for the UDM Search action
parameters.time_range.start_time	string	Optional	Parameters for the UDM Search action
parameters.time_range.end_time	string	Optional	Parameters for the UDM Search action
parameters.limit	number	Optional	Parameters for the UDM Search action

Input Example

{"parameters":{"query":"metadata.event_type+%3D+%22NETWORK_CONNECTION%22+and+principal.hostname%3D%22jdx%22","time_range.start_time":"2022-10-01T20:51:11.907461Z","time_range.end_time":"2022-12-01T20:51:11.907461Z","limit":100}}

Output

Parameter	Type	Description
status_code	number	HTTP status code of the response
reason	string	Response reason phrase
data	object	Response data
data.events	array	Response data
data.events.name	string	Response data
data.events.udm	object	Response data
data.events.udm.metadata	object	Response data
data.events.udm.metadata.eventTimestamp	string	Response data
data.events.udm.metadata.eventType	string	Response data
data.events.udm.metadata.ingestedTimestamp	string	Response data
data.events.udm.metadata.id	string	Response data
data.events.udm.principal	object	Response data
data.events.udm.principal.ip	array	Response data
data.events.udm.target	object	Response data
data.events.udm.target.ip	array	Response data
data.events.udm.target.port	number	Response data

Output Example

{"status_code":200,"response_headers":{"content-length":"140","content-type":"application/json","Date":"Wed, 23 Aug 2023 20:37:23 GMT"},"reason":"OK","data":{"events":[{},{}]}}

Response Headers

Header	Description	Example
content-length	The length of the response body in bytes	140
content-type	The media type of the resource	application/json
Date	The date and time at which the message was originated	Wed, 23 Aug 2023 20:37:23 GMT