> For the complete documentation index, see [llms.txt](https://surecloud.gitbook.io/surecloud-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://surecloud.gitbook.io/surecloud-docs/integrations/ccm-and-evidence-collection-integrations/google-cloud/google-chronicle.md).

# Google chronicle

SureCloud connects to Google Chronicle to retrieve log feed inventory, unified data model (UDM) ingestion status, detection rule configurations, and alert findings. This allows SureCloud to verify that Chronicle is actively ingesting security-relevant log sources, that detection rules are configured and enabled, and that the platform is retaining data within the required period — providing evidence that your cloud-native SIEM and threat detection controls are operating continuously.

## Authentication and setup

Google Chronicle uses a service account with a JSON key for API authentication. SureCloud authenticates using a dedicated service account granted read-only access to your Chronicle instance.

{% stepper %}
{% step %}

### Create a service account in Google Cloud

In the Google Cloud project associated with your Chronicle instance, navigate to **IAM & Admin → Service Accounts** and click **Create Service Account**. Name it `surecloud-chronicle` and click **Create and Continue**.
{% endstep %}

{% step %}

### Assign the Chronicle API Viewer role

In the **Grant this service account access to project** step, assign the role **Chronicle API Viewer** (or the equivalent read-only Chronicle role available in your organisation). Click **Continue** and then **Done**.
{% endstep %}

{% step %}

### Generate a JSON key

Select the new service account, navigate to the **Keys** tab, and click **Add Key → Create New Key**. Choose **JSON** and click **Create**. The key file will be downloaded automatically.
{% endstep %}

{% step %}

### Upload the key in SureCloud

Navigate to **SureCloud → Integrations → Google Chronicle → Connect**. Enter your Chronicle instance region (e.g. `us`, `eu`, `asia-southeast1`) and upload the service account JSON key file. Click **Save** and then **Test Connection**.
{% endstep %}
{% endstepper %}

{% hint style="warning" %}
The service account JSON key provides persistent access to Chronicle. Store it securely. SureCloud encrypts it at rest, but treat it as a sensitive credential. Rotate the key annually or sooner if it may have been exposed, and update it in **SureCloud → Integrations → Google Chronicle → Edit Connection**.
{% endhint %}

## Endpoints

Chronicle exposes data via both its Ingestion API and its Detection Engine API. SureCloud uses the following:

| API Call             | Use Case                                                                        |
| -------------------- | ------------------------------------------------------------------------------- |
| `GET /v1/feeds`      | Enumerate configured log feed sources to confirm coverage                       |
| `GET /v1/feeds/{id}` | Retrieve individual feed status including last successful ingestion time        |
| `GET /v1/logtypes`   | List log types being ingested via the Chronicle UDM                             |
| `GET /v1/rules`      | List detection rules to confirm threat detection is configured                  |
| `GET /v1/rules/{id}` | Retrieve individual rule detail including enabled state and last triggered time |
| `GET /v1/detections` | Retrieve recent detection alerts generated by Chronicle rules                   |
| `GET /v1/settings`   | Retrieve Chronicle instance settings including data retention configuration     |

## Pagination

`GET /v1/rules` and `GET /v1/detections` use page token pagination. SureCloud passes the `pageToken` from each response as the `page_token` parameter in the next request, continuing until no `pageToken` is returned.

```json
GET /v1/detections?pageSize=1000&pageToken=<value_from_previous_response>
```

`GET /v1/feeds` and `GET /v1/logtypes` return complete result sets in a single response for most Chronicle instances.

## Required permissions

SureCloud requires a service account with the following Chronicle IAM roles or equivalent permissions:

| Role / Permission    | Purpose                                                          |
| -------------------- | ---------------------------------------------------------------- |
| Chronicle API Viewer | Read access to feeds, log types, rules, detections, and settings |

No data ingestion, rule creation, or administrative permissions are required.

## Polling frequency

| Data Type                                     | Interval       |
| --------------------------------------------- | -------------- |
| Log feed inventory and ingestion status       | Every 24 hours |
| Detection rule configuration                  | Every 24 hours |
| Detection alerts                              | Every 4 hours  |
| Instance settings and retention configuration | Every 24 hours |

## Troubleshooting

<details>

<summary>Connection test fails with "PERMISSION_DENIED"</summary>

The service account does not have the Chronicle API Viewer role, or the Chronicle API has not been enabled in the Google Cloud project. Navigate to **Google Cloud Console → APIs & Services → Enabled APIs** and confirm the Chronicle API is enabled. Then check **IAM & Admin → IAM** to verify the service account has the correct role.

</details>

<details>

<summary>Feed list returns empty despite log sources being configured in Chronicle</summary>

Feeds configured via the Chronicle UI may use a different API surface than the programmatic feeds API. If your organisation configured log ingestion via Chronicle's forwarder or direct API ingestion rather than the managed feeds feature, those sources will not appear in `GET /v1/feeds`. SureCloud will still collect detection rules and alerts in this case. Check with your Chronicle administrator to confirm the ingestion method in use.

</details>

<details>

<summary>Detection alerts are missing or appear incomplete</summary>

Chronicle detection alerts are only generated when detection rules are enabled and have matched UDM events. If no rules are enabled, the detections endpoint will return empty results. Confirm that rules are enabled in the Chronicle console under **Detection Engine → Rules**. Also verify that the lookback window for the SureCloud collection aligns with your alert volume.

</details>

<details>

<summary>Wrong region causes API calls to fail</summary>

Chronicle API endpoints are region-specific. Using the wrong region in SureCloud will result in 404 or connection errors. Confirm your Chronicle instance region in the Chronicle console URL or with your Google account team, and update the region setting in **SureCloud → Integrations → Google Chronicle → Edit Connection**.

</details>


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://surecloud.gitbook.io/surecloud-docs/integrations/ccm-and-evidence-collection-integrations/google-cloud/google-chronicle.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.