Google Chronicle Backstory Streaming API

Use the Google SecOps Streaming API integration to ingest detections created by both user-created rules and Google SecOps Rules as XSOAR incidents.

Analytics & SIEM · Google SecOps

Details

ID	`Google Chronicle Backstory Streaming API`
Provider	Google
Category	Analytics & SIEM
From Version	6.10.0
Docker Image	`demisto/googleapi-python3:1.0.0.11185775`
Supported Modules	Agentix XSIAM

README

Overview

Use the Google SecOps Streaming API integration to ingest detections created by both user-created rules and Google SecOps Rules as XSOAR incidents.
This integration was integrated and tested with version 2 of Google Chronicle Backstory Streaming API (Detection Engine API) and v1 Alpha of Google SecOps Streaming API.

Troubleshoot

Note: The streaming mechanism will do up to 7 internal retries with a gap of 2, 4, 8, 16, 32, 64, and 128 seconds (exponentially) between the retries.

Problem #1

Duplication of rule detection incidents when fetched from Google SecOps.

Solution #1

To avoid duplication of incidents with duplicate detection ids and to drop them, XSOAR provides inbuilt features of Pre-process rules.
End users must configure this setting in the XSOAR platform independently, as it is not included in the integration pack.
Pre-processing rules enable users to perform certain actions on incidents as they are ingested into XSOAR.
Using these rules, users can filter incoming incidents and take specific actions, such as dropping all incidents or dropping and updating them based on certain conditions.
Please refer for information on Pre-Process rules.

Configure Google SecOps Streaming API in Cortex

Parameter	Description	Required
User’s Service Account JSON	Your Customer Experience Engineer (CEE) will provide you with a Google Developer Service Account Credential to enable the Google API client to communicate with the Backstory API.	True
Use V1 Alpha API	Select this option to use the V1 Alpha API. Note: If this option is selected, Update the Region and provide the v1 Alpha API supported Service Account JSON and Project Instance ID.	False
API URL Format	Select the API URL format to use for API requests. Default value is ‘<chronicle>.<REGION>.<rep.googleapis.com>’. Only applicable if the “Use V1 Alpha API” parameter is selected.	False
Google SecOps Project Instance ID	Provide the Project Instance ID of the Google SecOps. Only applicable if the “Use V1 Alpha API” parameter is selected. Note: User can retrieve the Customer ID(Project Instance ID) in the Profile section of the Google SecOps page.	False
Google SecOps Project Number	Provide the Project Number of the Google SecOps. Only applicable if the “Use V1 Alpha API” parameter is selected. Note: User can retrieve the Project Number in the Profile section of the Google SecOps page. If Project Number is not provided, then Project ID(from Service Account JSON) will be used.	False
Region	Select the region based on the location of the Google SecOps instance. If the region is not listed in the dropdown, choose the “Other” option and specify the region in the “Other Region” text field.	False
Other Region	Specify the region based on the location of the Google SecOps instance. Only applicable if the “Other” option is selected in the Region dropdown.	False
Incident type		False
First fetch time	The date or relative timestamp from where to start fetching detections. Default will be the current time. Note: The API is designed to retrieve data for the past 7 days only. Requests for data beyond that timeframe will result in errors. Supported formats: N minutes, N hours, N days, N weeks, yyyy-mm-dd, yyyy-mm-ddTHH:MM:SSZ For example: 10 minutes, 5 hours, 6 days, 1 week, 2024-12-31, 01 Mar 2024, 01 Feb 2024 04:45:33, 2024-04-17T14:05:44Z	False
Max Fetch	Maximum number of detections to fetch in a single batch. Available options are 100, 75, 50, 25 and 10 (If not selected, defaults to 100).	False
Google SecOps Alert Type	Select Google SecOps Alert types to be considered for Fetch Incidents. Available options are Curated Rule Detection Alerts and Rule Detection Alerts (If not selected, fetches all detections).	False
Severity of Detection	Select the severity of detections to be considered for Fetch Incidents. Available options are ‘Critical’, ‘High’, ‘Medium’, ‘Low’, ‘Informational’ and ‘Unspecified’ (If not selected, fetches all detections).	False
Rule Names for Detection Ingestion	Only detections with the given rule names will be allowed for ingestion.	False
If selected, detections with the above rule names will be denied for ingestion.		False
Rule IDs for Detection Ingestion	Only the detections with the given rule IDs will be allowed for ingestion.	False
If selected, detections with above rule IDs will be denied for ingestion.		False
Default Severity of Incident	Select the default severity for incident when detection does not specify a severity. Available options are ‘Critical’, ‘High’, ‘Medium’, ‘Low’, ‘Informational’ and ‘Unspecified’ (If not selected, defaults to Unspecified).	False
Trust any certificate (not secure)		False
Use system proxy settings		False

Generic Notes

This integration would only ingest the detections created by both user-created rules and Google SecOps Rules.
Also, It only ingests the detections created by rules whose alerting status was enabled at the time of detection.
Enable alerting using the Google SecOps UI by setting the Alerting option to enabled.
- For user-created rules, use the Rules Dashboard to enable each rule’s alerting status.
- For Google SecOps Rules, enable alerting status of the Rule Set to get detections created by corresponding rules.
You are limited to a maximum of 10 simultaneous streaming integration instances for the particular Service Account Credential (your instance will receive a 429 error if you attempt to create more).
For more, please check out the Google SecOps reference doc.

Configuration parameters

credentials — (required)
use_v1_alpha — Use V1 Alpha API
url_format — API URL Format
project_instance_id — Google SecOps Project Instance ID
project_number — Google SecOps Project Number
region — Region
other_region — Other Region
incidentType — Incident type
first_fetch — First fetch time
max_fetch — Max Fetch
longRunning — Long running instance
alert_type — Google SecOps Alert Type
detection_severity — Severity of Detection
rule_names — Rule Names for Detection Ingestion
exclude_rule_names — If selected, detections with the above rule names will be denied for ingestion.
rule_ids — Rule IDs for Detection Ingestion
exclude_rule_ids — If selected, detections with above rule IDs will be denied for ingestion.
default_severity — Default Severity of Incident
insecure — Trust any certificate (not secure)
proxy — Use system proxy settings

Commands (0)

This integration defines no commands.

Source

GoogleChronicleBackstoryStreamingAPI.py GoogleChronicleBackstoryStreamingAPI_test.py GoogleChronicleBackstoryStreamingAPI.yml GoogleChronicleBackstoryStreamingAPI_description.md

Download History Raw

category: Analytics & SIEM
provider: Google
sectionorder:
- Connect
- Collect
commonfields:
  id: Google Chronicle Backstory Streaming API
  version: -1
configuration:
- displaypassword: User's Service Account JSON
  name: credentials
  hiddenusername: true
  required: true
  type: 9
  section: Connect
- section: Connect
  display: Use V1 Alpha API
  name: use_v1_alpha
  defaultvalue: "false"
  type: 8
  required: false
  additionalinfo: |-
    Select this option to use the V1 Alpha API.

    Note: If this option is selected, Update the Region and provide the v1 Alpha API supported Service Account JSON and Project Instance ID.
- display: API URL Format
  additionalinfo: "Select the API URL format to use for API requests. Default value is '<chronicle>.<REGION>.<rep.googleapis.com>'. Only applicable if the \"Use V1 Alpha API\" parameter is selected."
  name: url_format
  required: false
  type: 15
  options:
  - "<REGION>-<chronicle.googleapis.com>"
  - "<chronicle>.<REGION>.<rep.googleapis.com>"
  section: Connect
- section: Connect
  display: Google SecOps Project Instance ID
  name: project_instance_id
  type: 0
  required: false
  additionalinfo: |-
    Provide the Project Instance ID of the Google SecOps. Only applicable if the "Use V1 Alpha API" parameter is selected.

    Note: User can retrieve the Customer ID(Project Instance ID) in the Profile section of the Google SecOps page.
- display: Google SecOps Project Number
  additionalinfo: |-
    Provide the Project Number of the Google SecOps. Only applicable if the "Use V1 Alpha API" parameter is selected.
    
    Note: User can retrieve the Project Number in the Profile section of the Google SecOps page. If Project Number is not provided, then Project ID(from Service Account JSON) will be used.
  name: project_number
  required: false
  type: 0
  section: Connect
- additionalinfo: Select the region based on the location of the Google SecOps instance. If the region is not listed in the dropdown, choose the "Other" option and specify the region in the "Other Region" text field.
  defaultvalue: General
  display: Region
  name: region
  options:
  - General
  - Europe
  - Asia
  - Europe-west2
  - Africa-south1
  - Asia-northeast1
  - Asia-south1
  - Asia-southeast1
  - Asia-southeast2
  - Australia-southeast1
  - EU
  - Europe-west3
  - Europe-west6
  - Europe-west9
  - Europe-west12
  - ME-central1
  - ME-central2
  - ME-west1
  - Northamerica-northeast2
  - Southamerica-east1
  - US
  - Other
  type: 15
  section: Connect
- additionalinfo: Specify the region based on the location of the Google SecOps instance. Only applicable if the "Other" option is selected in the Region dropdown.
  display: Other Region
  hidden: false
  name: other_region
  required: false
  type: 0
  section: Connect
- display: Incident type
  name: incidentType
  type: 13
  section: Connect
  required: false
- additionalinfo: |-
    The date or relative timestamp from where to start fetching detections. Default will be the current time.

    Note: The API is designed to retrieve data for the past 7 days only. Requests for data beyond that timeframe will result in errors.

    Supported formats: N minutes, N hours, N days, N weeks, yyyy-mm-dd, yyyy-mm-ddTHH:MM:SSZ

    For example: 10 minutes, 5 hours, 6 days, 1 week, 2024-12-31, 01 Mar 2024, 01 Feb 2024 04:45:33, 2024-04-17T14:05:44Z
  defaultvalue: now
  display: First fetch time
  name: first_fetch
  type: 0
  section: Collect
  required: false
- additionalinfo: Maximum number of detections to fetch in a single batch. Available options are 100, 75, 50, 25 and 10 (If not selected, defaults to 100).
  display: Max Fetch
  name: max_fetch
  type: 15
  section: Collect
  defaultvalue: '100'
  advanced: true
  options:
  - '100'
  - '75'
  - '50'
  - '25'
  - '10'
  required: false
- defaultvalue: 'true'
  display: Long running instance
  hidden: true
  name: longRunning
  type: 8
  section: Connect
  required: false
- additionalinfo: Select Google SecOps Alert types to be considered for Fetch Incidents. Available options are Curated Rule Detection Alerts and Rule Detection Alerts (If not selected, fetches all detections).
  display: Google SecOps Alert Type
  name: alert_type
  options:
  - Curated Rule Detection Alerts
  - Rule Detection Alerts
  type: 16
  section: Collect
  advanced: true
  required: false
- additionalinfo: Select the severity of detections to be considered for Fetch Incidents. Available options are 'Critical', 'High', 'Medium', 'Low', 'Informational' and 'Unspecified' (If not selected, fetches all detections).
  display: Severity of Detection
  name: detection_severity
  options:
  - Critical
  - High
  - Medium
  - Low
  - Informational
  - Unspecified
  type: 16
  section: Collect
  advanced: true
  required: false
- additionalinfo: Only detections with the given rule names will be allowed for ingestion.
  display: Rule Names for Detection Ingestion
  name: rule_names
  type: 16
  section: Collect
  advanced: true
  required: false
- display: If selected, detections with the above rule names will be denied for ingestion.
  name: exclude_rule_names
  type: 8
  section: Collect
  advanced: true
  required: false
- additionalinfo: Only the detections with the given rule IDs will be allowed for ingestion.
  display: Rule IDs for Detection Ingestion
  name: rule_ids
  type: 16
  section: Collect
  advanced: true
  required: false
- display: If selected, detections with above rule IDs will be denied for ingestion.
  name: exclude_rule_ids
  type: 8
  section: Collect
  advanced: true
  required: false
- additionalinfo: Select the default severity for incident when detection does not specify a severity. Available options are 'Critical', 'High', 'Medium', 'Low', 'Informational' and 'Unspecified' (If not selected, defaults to Unspecified).
  display: Default Severity of Incident
  name: default_severity
  type: 15
  section: Collect
  defaultvalue: Unspecified
  advanced: true
  options:
  - Critical
  - High
  - Medium
  - Low
  - Informational
  - Unspecified
  required: false
- display: Trust any certificate (not secure)
  name: insecure
  type: 8
  section: Connect
  advanced: true
  required: false
- display: Use system proxy settings
  name: proxy
  type: 8
  section: Connect
  advanced: true
  required: false
description: Use the Google SecOps Streaming API integration to ingest detections created by both user-created rules and Google SecOps Rules as XSOAR incidents.
display: Google SecOps Streaming API
name: Google Chronicle Backstory Streaming API
script:
  dockerimage: demisto/googleapi-python3:1.0.0.11185775
  longRunning: true
  isFetchSamples: true
  runonce: false
  script: '-'
  subtype: python3
  type: python
fromversion: 6.10.0
tests:
- No tests (auto formatted)
defaultmapperin: 'Chronicle-mapper'
defaultclassifier: 'Chronicle'