Google Chronicle — Integration Setup

Prerequisites

A Google Chronicle (part of Google Security Operations) instance
A Google Cloud service account with Chronicle API read access, or an equivalent long-lived Chronicle API credential
CMDash Essentials tier or above

Beta, and not yet verified against the live Chronicle API. Google documents two Chronicle APIs (the legacy Backstory API and the newer chronicle.googleapis.com API with v1alpha paths), and this connector's host, paths, scope and alert field names have not been confirmed against either one. The paging and the service-account sign-in are tested against a fixture written from the vendor's description, not against a real Chronicle instance. If a sync returns nothing or fails with a 404, 403 or an unexpected-field error, tell us; the connector's status stays Beta until it has been checked against a real instance.

Step 1: Create a Service-Account Key

In Google Cloud Console, create (or reuse) a service account in the project linked to your Chronicle instance.
Grant it a Chronicle read-only role (e.g., Chronicle API Viewer or your organization's equivalent custom role covering chronicle.alerts.list and chronicle.detections.list-style permissions), and make sure the Chronicle API is enabled for it.
Under Keys, create a new JSON key and download the key file.

CMDash signs a short-lived assertion with that key and exchanges it with Google for an access token (scope https://www.googleapis.com/auth/chronicle-backstory) on every sync, so the connection runs unattended and nothing needs refreshing by hand.

Step 2: Connect in CMDash

Navigate to Integrations in your CMDash dashboard.
Find Google Chronicle and click Connect.
Enter:
- API key: paste the entire contents of the service-account JSON key file, unedited
- Region (e.g., us; defaults to us if left blank — use the region prefix matching your Chronicle instance, such as europe or asia-southeast1)
Click Save & Test Connection.

The key is stored encrypted, like every other CMDash credential. It is used only to sign the assertion sent to Google's token endpoint; Chronicle itself only ever sees the short-lived access token.

Older connections: a connection made before this change holds a pasted access token. It keeps working as it did (and still expires within about an hour). Edit the connection and paste the service-account JSON key to make it self-renewing.

What Syncs

Data Type	Chronicle API	Sync Frequency
Incidents (alerts, last 24 hours)	`GET /v1/alert/listalerts`	Every 4 hours by default (configurable per connection)
Incidents (rule detections, last 24 hours)	`GET /v2/detect/rules:listDetections`	Every 4 hours by default (configurable per connection)

Both alerts and detections are normalized into CMDash's Incident model (there is no separate vulnerability feed from Chronicle today). Each call is scoped to the trailing 24 hours. Alerts are read in windows of up to 1,000: while Chronicle reports more data is available, CMDash re-opens the window at the newest alert it has read (the boundary alert is de-duplicated). Detections follow Chronicle's nextPageToken. Both stop after 20 requests; if Chronicle still has more, or reports tooManyAlerts, the sync is recorded as partial with a warning rather than as a clean success.

Troubleshooting

Token exchange failed (HTTP 400 / 401): The service-account key is invalid, was deleted or disabled, or is not the complete JSON file. Create a new key and paste it again. (A connection that still holds a pasted access token reports 401 once that token expires.)
403 Forbidden: The service account/credential lacks the Chronicle read role needed for the alerting/detection APIs.
Wrong region / no data: Chronicle's API is regionalized (https://{region}-chronicle.googleapis.com); confirm the Region field matches where your Chronicle instance actually lives.
Only 24 hours of history: Both the alerts and detections queries are hardcoded to look back 24 hours from "now" — there's no backfill of older activity on first connect.

Rate Limits & Sync Behavior

Setting	Value
Sync frequency	Every 4 hours by default (`syncInterval` is configurable per connection)
First sync	Only the trailing 24 hours of alerts and detections — not full history
Rate limit handling	Every outbound request is paced through CMDash's shared per-tenant token bucket for this provider, and a vendor `429` (with its `Retry-After`) holds that tenant's budget until the vendor says it is ready (#507)
Failed sync retry	Job queue retries 3 times with exponential backoff (starting at 30s) — see docs/developers/dead-letter.md

Credential Rotation

Rotate the service-account key in Google Cloud on your normal schedule. There is no access token to refresh.

To rotate:

Create a new JSON key for the service account in Google Cloud, then delete the old one after the next successful sync.
In CMDash: Settings → Integrations → Google Chronicle → Edit.
Paste the new key file's contents into API key and Save.

Multiple Instances / Multi-Site

If you operate more than one Chronicle instance (e.g., separate instances per region or subsidiary), each instance needs its own CMDash connection.

To add another instance:

Obtain a credential for the additional instance following Step 1.
In CMDash: Settings → Integrations → Add Integration → Google Chronicle.
Enter the access token and region for the additional instance.
Give the connection a descriptive name (e.g., Chronicle - EU, Chronicle - APAC).
Click Save & Test Connection.

Compliance Framework Coverage

The Google Chronicle integration provides evidence for the following controls. Coverage is automatically mapped when data is synced.

Framework	Control	Description
PCI DSS	10.2	Event log monitoring — Chronicle alerts and detections mapped to log review evidence
HITRUST	09.ab	Monitoring system use — SIEM alert and detection telemetry
CMMC L2	SI.1.210	System monitoring — continuous alerting via Chronicle detections
SOC 2	CC7.1	Threat detection — Chronicle alerts feed the threat-detection evidence bucket
SOC 2	CC7.2	Anomaly identification — rule-based detections mapped to anomaly evidence