Google Chronicle Detection Engine

Google Chronicle Detection Engine is a cloud-based security analytics platform that provides advanced threat detection capabilities.

Google Chronicle Detection Engine is a powerful threat detection platform that leverages Google's infrastructure to provide comprehensive security insights. This connector allows Swimlane Turbine users to seamlessly integrate with Google Chronicle, enabling automated retrieval and management of detection rules and alerts. By integrating with Google Chronicle, Swimlane Turbine users can enhance their threat detection capabilities, streamline incident response processes, and gain real-time insights into security threats, all without writing a single line of code.

Prerequisites

Before you can use the Google Chronicle Detection Engine 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 resources within Google Chronicle.

Capabilities

This connector provides the following capabilities:

List Detections of All Versions and All Rules

List Detections of All Versions of a Rule ID

List Detections by Version ID

List Detections of latest Vesions of a Rule ID

List Rules

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.

https://backstory.googleapis.com/

https://europe-backstory.googleapis.com/

https://europe-west2-backstory.googleapis.com/

https://asia-southeast1-backstory.googleapis.com/

Notes

For more information on Chronicle: Chronicle Main Site Detection Engine API Documentation

Additional Documentation

Google Chronicle Detection Engine Connector Documentation

Google Chronicle Detection Engine 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 Curated Detections All Versions All Rules

Retrieve a comprehensive list of curated detections across all versions and rules from Google Chronicle.

Endpoint

URL: v2/detect/curatedRules/-/detections

Method: GET

Input

Argument Name	Type	Required	Description
parameters.alert_state	string	Optional	Parameters for the List Curated Detections All Versions All Rules action
parameters.start_time	string	Optional	Parameters for the List Curated Detections All Versions All Rules action
parameters.end_time	string	Optional	Parameters for the List Curated Detections All Versions All Rules action
parameters.list_basis	string	Optional	Parameters for the List Curated Detections All Versions All Rules action
parameters.page_size	number	Optional	Parameters for the List Curated Detections All Versions All Rules action
parameters.page_token	string	Optional	Parameters for the List Curated Detections All Versions All Rules action

Input Example

{"parameters":{"alert_state":"ALERTING","start_time":"","end_time":"","list_basis":"DETECTION_TIME","page_size":100,"page_token":""}}

Output

Parameter	Type	Description
data	object	Response data
data.curatedRuleDetections	array	Response data
data.curatedRuleDetections.type	string	Response data
data.curatedRuleDetections.detection	array	Response data
data.curatedRuleDetections.detection.ruleName	string	Response data
data.curatedRuleDetections.detection.summary	string	Response data
data.curatedRuleDetections.detection.description	string	Response data
data.curatedRuleDetections.detection.severity	string	Response data
data.curatedRuleDetections.detection.urlBackToProduct	string	Response data
data.curatedRuleDetections.detection.ruleId	string	Response data
data.curatedRuleDetections.detection.alertState	string	Response data
data.curatedRuleDetections.detection.ruleType	string	Response data
data.curatedRuleDetections.detection.ruleLabels	array	Response data
data.curatedRuleDetections.detection.ruleLabels.key	string	Response data
data.curatedRuleDetections.detection.ruleLabels.value	string	Response data
data.curatedRuleDetections.detection.ruleSet	string	Response data
data.curatedRuleDetections.detection.ruleSetDisplayName	string	Response data
data.curatedRuleDetections.createdTime	string	Response data
data.curatedRuleDetections.lastUpdatedTime	string	Response data
data.curatedRuleDetections.id	string	Response data
data.curatedRuleDetections.timeWindow	object	Response data
data.curatedRuleDetections.timeWindow.startTime	string	Response data
data.curatedRuleDetections.timeWindow.endTime	string	Response data
data.curatedRuleDetections.collectionElements	array	Response data
data.curatedRuleDetections.collectionElements.references	array	Response data

Output Example

{"data":{"curatedRuleDetections":[{},{}],"nextPageToken":"CgwIrdncnQYQ6OqRkwISCwiosvKXBhDQ-74JGidkZV8wNDZjZmY0YS1jM2ZkLTM5YWEtYmUyYS0wZTU2..."}}

List Detections All Verisons All Rules

Retrieve a comprehensive list of detections across all versions and rules from the Google Chronicle Detection Engine.

Endpoint

URL: v2/detect/rules/-/detections

Method: GET

Input

Argument Name	Type	Required	Description
parameters.alert_state	string	Optional	Filter detections on if they are "ALERTING" or "NOT_ALERTING".
parameters.start_time	string	Optional	Time to begin returning detections, filtering by the detection field specified in the List Basis parameter. If not specified, the start time is treated as open-ended.
parameters.end_time	string	Optional	Time to stop returning detections, filtering by the detection field specified by the List Basis parameter. If not specified, the end time is treated as open-ended.
parameters.list_basis	string	Optional	Sort detections by "DETECTION_TIME" or by "CREATED_TIME". If not specified, it defaults to "DETECTION_TIME". Detections are returned in descending order of the timestamp.
parameters.page_size	number	Optional	Specify the maximum number of detections to return (range is 1 through 1,000). The default is 100.
parameters.page_token	string	Optional	Use to retrieve another page of detections.
timeout	integer	Optional	Maximum number of seconds to wait for the search to complete before timing out. Default is 600 seconds (10 minutes).

Input Example

{"parameters":{"alert_state":"string","start_time":"string","end_time":"string","list_basis":"string","page_size":123,"page_token":"string"},"timeout":600}

Output

Parameter	Type	Description
detections	array	Output field: detections
detections.type	string	Type of the resource
detections.detection	array	Output field: detections.detection
detections.detection.ruleName	string	Name of the resource
detections.detection.urlBackToProduct	string	URL endpoint for the request
detections.detection.ruleId	string	Unique identifier
detections.detection.ruleVersion	string	Output field: detections.detection.ruleVersion
detections.detection.alertState	string	Output field: detections.detection.alertState
detections.detection.ruleType	string	Type of the resource
detections.createdTime	string	Time value
detections.id	string	Unique identifier
detections.timeWindow	object	Output field: detections.timeWindow
detections.timeWindow.startTime	string	Time value
detections.timeWindow.endTime	string	Time value
detections.collectionElements	array	Output field: detections.collectionElements
detections.collectionElements.references	array	Output field: detections.collectionElements.references
detections.collectionElements.references.event	object	Output field: detections.collectionElements.references.event
detections.collectionElements.references.event.metadata	object	Response data
detections.collectionElements.references.event.principal	object	Output field: detections.collectionElements.references.event.principal
detections.collectionElements.references.event.target	object	Output field: detections.collectionElements.references.event.target
detections.collectionElements.references.event.securityResult	array	Result of the operation
detections.collectionElements.references.event.network	object	Output field: detections.collectionElements.references.event.network
detections.collectionElements.label	string	Output field: detections.collectionElements.label
detections.detectionTime	string	Time value
nextPageToken	string	Output field: nextPageToken

Output Example

{"detections":[{"type":"RULE_DETECTION","detection":[],"createdTime":"2020-12-03T19:19:19.720174Z","id":"de_69d1ff3c-3528-6171-fb48-28ee813ec3ec","timeWindow":{},"collectionElements":[],"detectionTime":"2020-12-03T16:59:55.124243Z"},{"type":"RULE_DETECTION","detection":[],"createdTime":"2020-12-03T19:19:19.720174Z","id":"de_ec2bc52b-a522-aeaf-6a94-f7c7ce0eff15","timeWindow":{},"collectionElements":[],"detectionTime":"2020-12-03T16:59:48.916995Z"}],"nextPageToken":"CgsIkdvj_gUQ2M2IXBIMCISzpP4FELj...

List Detections All Versions by Rule ID

Retrieve all detection versions linked to a specific rule ID in Google Chronicle Detection Engine. Requires ruleID as a path parameter.

Endpoint

URL: v2/detect/rules/{{ruleID}}@-/detections

Method: GET

Input

Argument Name	Type	Required	Description
path_parameters.ruleID	string	Required	Unique identifier for a rule, defined and returned by the server. Use the following format to specify the rule - ru_{UUID}.
parameters.alert_state	string	Optional	Filter detections on if they are "ALERTING" or "NOT_ALERTING".
parameters.start_time	string	Optional	Time to begin returning detections, filtering by the detection field specified in the List Basis parameter. If not specified, the start time is treated as open-ended.
parameters.end_time	string	Optional	Time to stop returning detections, filtering by the detection field specified by the List Basis parameter. If not specified, the end time is treated as open-ended.
parameters.list_basis	string	Optional	Sort detections by "DETECTION_TIME" or by "CREATED_TIME". If not specified, it defaults to "DETECTION_TIME". Detections are returned in descending order of the timestamp.
parameters.page_size	number	Optional	Specify the maximum number of detections to return (range is 1 through 1,000). The default is 100.
parameters.page_token	string	Optional	Use to retrieve another page of detections.
timeout	integer	Optional	Maximum number of seconds to wait for the search to complete before timing out. Default is 600 seconds (10 minutes).

Input Example

{"path_parameters":{"ruleID":"string"},"parameters":{"alert_state":"string","start_time":"string","end_time":"string","list_basis":"string","page_size":123,"page_token":"string"},"timeout":600}

Output

Parameter	Type	Description
detections	array	Output field: detections
detections.type	string	Type of the resource
detections.detection	array	Output field: detections.detection
detections.detection.ruleName	string	Name of the resource
detections.detection.urlBackToProduct	string	URL endpoint for the request
detections.detection.ruleId	string	Unique identifier
detections.detection.ruleVersion	string	Output field: detections.detection.ruleVersion
detections.detection.alertState	string	Output field: detections.detection.alertState
detections.detection.ruleType	string	Type of the resource
detections.createdTime	string	Time value
detections.id	string	Unique identifier
detections.timeWindow	object	Output field: detections.timeWindow
detections.timeWindow.startTime	string	Time value
detections.timeWindow.endTime	string	Time value
detections.collectionElements	array	Output field: detections.collectionElements
detections.collectionElements.references	array	Output field: detections.collectionElements.references
detections.collectionElements.references.event	object	Output field: detections.collectionElements.references.event
detections.collectionElements.references.event.metadata	object	Response data
detections.collectionElements.references.event.principal	object	Output field: detections.collectionElements.references.event.principal
detections.collectionElements.references.event.target	object	Output field: detections.collectionElements.references.event.target
detections.collectionElements.references.event.securityResult	array	Result of the operation
detections.collectionElements.references.event.network	object	Output field: detections.collectionElements.references.event.network
detections.collectionElements.label	string	Output field: detections.collectionElements.label
detections.detectionTime	string	Time value
nextPageToken	string	Output field: nextPageToken

Output Example

List Detections by Version ID

Retrieve detections associated with a specified versionID in Google Chronicle Detection Engine.

Endpoint

URL: v2/detect/rules/{{versionID}}/detections

Method: GET

Input

Argument Name	Type	Required	Description
path_parameters.versionID	string	Required	Unique identifier for a specific version of a rule, defined and returned by the server. Use the following format to specify the rule - {ruleId}@v_{int64}_{int64}.
parameters.alert_state	string	Optional	Filter detections on if they are "ALERTING" or "NOT_ALERTING".
parameters.start_time	string	Optional	Time to begin returning detections, filtering by the detection field specified in the List Basis parameter. If not specified, the start time is treated as open-ended.
parameters.end_time	string	Optional	Time to stop returning detections, filtering by the detection field specified by the List Basis parameter. If not specified, the end time is treated as open-ended.
parameters.list_basis	string	Optional	Sort detections by "DETECTION_TIME" or by "CREATED_TIME". If not specified, it defaults to "DETECTION_TIME". Detections are returned in descending order of the timestamp.
parameters.page_size	number	Optional	Specify the maximum number of detections to return (range is 1 through 1,000). The default is 100.
parameters.page_token	string	Optional	Use to retrieve another page of detections.
timeout	integer	Optional	Maximum number of seconds to wait for the search to complete before timing out. Default is 600 seconds (10 minutes).

Input Example

{"path_parameters":{"versionID":"string"},"parameters":{"alert_state":"string","start_time":"string","end_time":"string","list_basis":"string","page_size":123,"page_token":"string"},"timeout":600}

Output

Parameter	Type	Description
detections	array	Output field: detections
detections.type	string	Type of the resource
detections.detection	array	Output field: detections.detection
detections.detection.ruleName	string	Name of the resource
detections.detection.urlBackToProduct	string	URL endpoint for the request
detections.detection.ruleId	string	Unique identifier
detections.detection.ruleVersion	string	Output field: detections.detection.ruleVersion
detections.detection.alertState	string	Output field: detections.detection.alertState
detections.detection.ruleType	string	Type of the resource
detections.createdTime	string	Time value
detections.id	string	Unique identifier
detections.timeWindow	object	Output field: detections.timeWindow
detections.timeWindow.startTime	string	Time value
detections.timeWindow.endTime	string	Time value
detections.collectionElements	array	Output field: detections.collectionElements
detections.collectionElements.references	array	Output field: detections.collectionElements.references
detections.collectionElements.references.event	object	Output field: detections.collectionElements.references.event
detections.collectionElements.references.event.metadata	object	Response data
detections.collectionElements.references.event.principal	object	Output field: detections.collectionElements.references.event.principal
detections.collectionElements.references.event.target	object	Output field: detections.collectionElements.references.event.target
detections.collectionElements.references.event.securityResult	array	Result of the operation
detections.collectionElements.references.event.network	object	Output field: detections.collectionElements.references.event.network
detections.collectionElements.label	string	Output field: detections.collectionElements.label
detections.detectionTime	string	Time value
nextPageToken	string	Output field: nextPageToken

Output Example

List Detections Latest Version by Rule ID

Retrieve the latest version of detections for a given rule in Google Chronicle using the specified ruleID.

Endpoint

URL: v2/detect/rules/{{ruleID}}/detections

Method: GET

Input

Argument Name	Type	Required	Description
path_parameters.ruleID	string	Required	Unique identifier for a rule, defined and returned by the server. Use the following format to specify the rule - ru_{UUID}.
parameters.alert_state	string	Optional	Filter detections on if they are "ALERTING" or "NOT_ALERTING".
parameters.start_time	string	Optional	Time to begin returning detections, filtering by the detection field specified in the List Basis parameter. If not specified, the start time is treated as open-ended.
parameters.end_time	string	Optional	Time to stop returning detections, filtering by the detection field specified by the List Basis parameter. If not specified, the end time is treated as open-ended.
parameters.list_basis	string	Optional	Sort detections by "DETECTION_TIME" or by "CREATED_TIME". If not specified, it defaults to "DETECTION_TIME". Detections are returned in descending order of the timestamp.
parameters.page_size	number	Optional	Specify the maximum number of detections to return (range is 1 through 1,000). The default is 100.
parameters.page_token	string	Optional	Use to retrieve another page of detections.
timeout	integer	Optional	Maximum number of seconds to wait for the search to complete before timing out. Default is 600 seconds (10 minutes).

Input Example

{"path_parameters":{"ruleID":"string"},"parameters":{"alert_state":"string","start_time":"string","end_time":"string","list_basis":"string","page_size":123,"page_token":"string"},"timeout":600}

Output

Parameter	Type	Description
detections	array	Output field: detections
detections.type	string	Type of the resource
detections.detection	array	Output field: detections.detection
detections.detection.ruleName	string	Name of the resource
detections.detection.urlBackToProduct	string	URL endpoint for the request
detections.detection.ruleId	string	Unique identifier
detections.detection.ruleVersion	string	Output field: detections.detection.ruleVersion
detections.detection.alertState	string	Output field: detections.detection.alertState
detections.detection.ruleType	string	Type of the resource
detections.createdTime	string	Time value
detections.id	string	Unique identifier
detections.timeWindow	object	Output field: detections.timeWindow
detections.timeWindow.startTime	string	Time value
detections.timeWindow.endTime	string	Time value
detections.collectionElements	array	Output field: detections.collectionElements
detections.collectionElements.references	array	Output field: detections.collectionElements.references
detections.collectionElements.references.event	object	Output field: detections.collectionElements.references.event
detections.collectionElements.references.event.metadata	object	Response data
detections.collectionElements.references.event.principal	object	Output field: detections.collectionElements.references.event.principal
detections.collectionElements.references.event.target	object	Output field: detections.collectionElements.references.event.target
detections.collectionElements.references.event.securityResult	array	Result of the operation
detections.collectionElements.references.event.network	object	Output field: detections.collectionElements.references.event.network
detections.collectionElements.label	string	Output field: detections.collectionElements.label
detections.detectionTime	string	Time value
nextPageToken	string	Output field: nextPageToken

Output Example

List Rules

Retrieve the latest versions of all detection rules from the Google Chronicle Detection Engine.

Endpoint

URL: /v2/detect/rules

Method: GET

Input

Argument Name	Type	Required	Description
parameters.page_size	number	Optional	Specify the maximum number of rules to return (range is 1 through 1,000). The default is 100.
parameters.page_token	string	Optional	Page token received from a previous call. Use to retrieve the next page.
parameters.state	string	Optional	List rules based on their state.
timeout	integer	Optional	Maximum number of seconds to wait for the search to complete before timing out. Default is 600 seconds (10 minutes).

Input Example

{"parameters":{"page_size":100,"page_token":" ","state":"ACTIVE"}}

Output

Parameter	Type	Description
rules	array	Output field: rules
rules.ruleId	string	Unique identifier
rules.versionId	string	Unique identifier
rules.ruleName	string	Name of the resource
rules.metadata	object	Response data
rules.metadata.type	string	Response data
rules.metadata.data_source	string	Response data
rules.metadata.platform	string	Response data
rules.metadata.severity	string	Response data
rules.metadata.priority	string	Response data
rules.metadata.author	string	Response data
rules.metadata.description	string	Response data
rules.ruleText	string	Output field: rules.ruleText
rules.versionCreateTime	string	Time value
rules.compilationState	string	Output field: rules.compilationState
rules.ruleType	string	Type of the resource
rules.lastAlertStatusChangeTime	string	Status value
rules.liveRuleEnabled	boolean	Output field: rules.liveRuleEnabled
rules.alertingEnabled	boolean	Output field: rules.alertingEnabled
nextPageToken	string	Output field: nextPageToken

Output Example

{"rules":[],"nextPageToken":"string"}

Response Headers

Header	Description	Example
Content-Type	The media type of the resource	application/json
Date	The date and time at which the message was originated	Thu, 01 Jan 2024 00:00:00 GMT