---
title: "Google Workspace Alerts collector"
canonical: "https://docs.devo.com/space/latest/94656004/Google%20Workspace%20Alerts%20collector"
format: markdown
---
> Macro (excerpt-include)



> Macro (toc)

## Purpose

An analyst wants to detect suspicious login activities and data loss prevention violations in [Google Workspace](https://workspace.google.com/). Using the Google Workspace Alerts collector to send security alerts to Devo, the analyst will find potentially compromised accounts and unauthorized access attempts. As a result, the analyst will quickly revoke suspicious access tokens, preventing attackers from exfiltrating sensitive corporate data.

## Example tables

| **Table** | **Description** |
| --- | --- |
| cloud.gsuite.alerts.suspicious_login | Suspicious login attempts to Google Workspace accounts |
| cloud.gsuite.alerts.suspicious_login_less_secure_app | Suspicious logins from less secure applications |
| cloud.gsuite.alerts.suspicious_programmatic_login | Suspicious API-based login attempts |
| cloud.gsuite.alerts.leaked_password | Alerts for passwords found in data breaches |
| cloud.gsuite.alerts.government_attack_warning | Warnings about state-sponsored attacks |
| cloud.gsuite.alerts.suspicious_activity | Unusual activity detected in Google Workspace |
| cloud.gsuite.alerts.device_compromised | Alerts for potentially compromised devices |
| cloud.gsuite.alerts.data_loss_prevention | Data loss prevention rule violations |
| cloud.gsuite.alerts.malware_reclassification | Messages reclassified as containing malware |
| cloud.gsuite.alerts.phising_reclassification | Messages reclassified as phishing attempts |
| cloud.gsuite.alerts.suspicious_message_reported | Messages reported as suspicious by users |
| cloud.gsuite.alerts.user_reported_phising | Phishing attempts reported by users |
| cloud.gsuite.alerts.user_suspended | User account suspensions |
| cloud.gsuite.alerts.super_admin_password_reset | Admin account password reset events |
| cloud.gsuite.alerts | General Google Workspace alerts |

## Configuration requirements

To run this collector, there are some configurations detailed below that you need to take into account.

| **Configuration** | **Details** |
| --- | --- |
| **GCP console** | You have the right credentials to access the GCP console. |
| **Permissions** | You have to be the owner of the account or have administrator’s permissions in the GCP console. |
| **Delegated email** | You need to have a delegated email with the right permissions. Refer to <u>[Google documentation](https://support.google.com/mail/answer/138350#zippy=,add-a-delegate)</u> to know how to do it. |

## Authorize it

1. Log in to the **Google Cloud Console** with an administrative account.
2. Create a **new project** or select an existing one.
3. Enable the **Alert Center API **for your project.
4. Create a service account in the **IAM & Admin** section.
5. Assign the service account appropriate roles for reading alerts (Security Center Admin Viewer).
6. Create and download a **JSON key** file for the service account.
7. Use Python environment to convert the content of the JSON file (`credentials.json`) to base64:

```
import base64

def main():
    with open('credentials.json', 'r') as credentials:
        creds_as_bytes = credentials.read().encode('utf-8')
        base64creds = base64.b64encode(creds_as_bytes).decode("utf-8")
        print(f'Base64 encoded credentials.json: {base64creds}')

if __name__ == '__main__':
    main()
```

8. Run the command below in your directory.
9. Copy the **base64-encoded token** **value** output by the script for your collector configuration.
10. In the Google Workspace Admin Console, go to **Security > API controls**.
11. In the Domain-wide Delegation section, add the service account **client ID**.
12. Grant the following **OAuth scope**s to the service account:
  1. [https://www.googleapis.com/auth/apps.alerts](https://www.googleapis.com/auth/apps.alerts)
  2. [https://www.googleapis.com/auth/admin.reports.audit.readonly](https://www.googleapis.com/auth/admin.reports.audit.readonly)
13. Click in **“Authorize“**.

## Run it

In the Cloud Collector App, [create](https://devodocs.atlassian.net/wiki/spaces/latest/pages/409305131) a **Google Workspace Alerts **collector instance.  Insert this parameters template, replacing the values enclosed in `< >`.  The `id` must be a unique [five digit number](https://www.random.org/integers/?num=1&min=10000&max=99999&col=5&base=10&format=html&rnd=new).

```
{
  "global_overrides": {},
  "inputs": {
    "gsuite_alerts": {
      "id": "<FIVE_UNIQUE_DIGITS>",
      "services": {
        "access_approvals": {},
        "account_suspension_warn": {},
        "activity_rule": {},
        "apns_cert_expiring": {},
        "apns_cert_expired": {},
        "appmaker_default_cloud_sql_setup": {},
        "apps_outage": {},
        "calendar_changed": {},
        "chrome": {},
        "configuration_problem": {},
        "customer_abuse": {},
        "customer_takeout_initiated": {},
        "data_loss_prevention": {},
        "device_compromised": {},
        "drive_changed": {},
        "email_changed": {},
        "google_operations": {},
        "government_attack_warning": {},
        "leaked_password": {},
        "malware_reclassification": {},
        "misconfigured_whitelist": {},
        "msa_billing": {},
        "msa_legal": {},
        "msa_product": {},
        "msa_security": {},
        "mobile_changed": {},
        "new_user": {},
        "phishing_reclassification": {},
        "primary_admin_changed": {},
        "reporting_rule": {},
        "sso_profile_added": {},
        "sso_profile_updated": {},
        "sso_profile_deleted": {},
        "super_admin_password_reset": {},
        "suspended_user_active": {},
        "suspicious_activity": {},
        "suspicious_login": {},
        "suspicious_login_less_secure_app": {},
        "suspicious_message_reported": {},
        "suspicious_programmatic_login": {},
        "user_admin_revoked": {},
        "user_deleted": {},
        "user_granted_admin": {},
        "user_password_changed": {},
        "user_reported_phishing": {},
        "user_reported_spam_spike": {},
        "user_suspended": {},
        "user_suspended_alert": {},
        "user_suspended_spam": {},
        "user_suspended_spam_through_relay": {},
        "user_suspended_suspicious_activity": {}
      },
      "credentials": {
        "filename": "<FILENAME_VALUE>",
        "content_base64": "<CONTENT_BASE64_VALUE>",
        "delegated_email": "<DELEGATED_EMAIL_VALUE>",
        "source_id": "<SOURCE_ID_VALUE>"
      }
    }
  }
}
```

## Secure it

Devo [Exchange](https://docs.devo.com/space/latest/158236705/Devo+Exchange+repository) provides these resources:

**Alert pack:**

- [Valid Accounts (MITRE Att&ck Technique: T1078)](https://docs.devo.com/space/latest/325222844/Mitre+alert+packs+T1000-1099#Valid-Accounts)
- Google Workspace

## Monitor it

Create an [inactivity alert](https://devodocs.atlassian.net/wiki/spaces/latest/pages/95126785) to detect interruptions of transfer of data from the source  using the query:

```xquery
from cloud.gsuite.alerts 
where toktains(hostchain,"collector-") 
select split(hostchain,"-",1) as collector_id
```

Set the inactivity alert to keep track of the `collector_id`.

## Parameters

### Example

```
{
  "global_overrides": {
    "debug": <debug_status>
  },
  "inputs": {
    "gsuite_alerts": {
      "id": "<short_unique_id>",
      "enabled": <input_status>,
      "requests_per_second": <requests_per_second_value>,
      "environment": "<environment_value>"
      "credentials": {
        "filename": "<filename_value>",
        "content_base64": "<content_base64_value>",
        "delegated_email": "<delegated_email_value>",
        "source_id": "<source_id_value>"
      },
      "services": {
        "<collector_service_name>": {
          "request_period_in_seconds": <request_period_in_seconds_value>,
          "start_time": "<start_time_override_value>",
          "tag": "<custom_tag>"
        }
      }
    }
  }
}
```

### Details

|  |  |  |  |
| --- | --- | --- | --- |
| **Parameter** | **Data type** | **Necessity** | **Details** |
| `debug_status` | boolean | Mandatory | If the value is `true`, the debug logging traces will be enabled when running the collector. If the value is `false`, only the `info`, `warning` and `error` logging levels will be printed. |
| `id` | integer | Mandatory | Unique id to this input service. |
| `input_status` | boolean | Mandatory | Use this param to enable or disable the given input logic when running the collector. If the value is `true`, the input will be run. If the value is `false`, it will be ignored. |
| `requests_per_second` | integer | Optional | Customize the maximum number of API requests per second. If not used, the default setting will be used: `100000` requests/sec. |
| `environment` | string | Optional | This parameter is used to create the Devo tag. It corresponds to the sixth level of the tag:  
`cloud.gsuite.alerts.<alert_type>.<format_version>.<environment>`. If this parameter is removed, the sixth level of the tag will have the value `unknown`. |
| `filename` | string | Mandatory | This parameter is the name that you want to give to the token generated by the Collector. For example: `token.pickle` |
| `content_base64` | string | Mandatory | This parameter is the credentials in base64 format. |
| `delegated_email` | string | Mandatory | This parameter is the email of the user whose domain is delegated to authorize the Service Account to access the alerts. |
| `source_id` | string | Mandatory | This parameter will be used when {source_id} placeholder is present when using custom tags. Please use `"abc"` value when not used. |
| `collector_service_name` | string | Mandatory | This parameter can be set to any collector service.<br>For example:<br>```
"services": {
    "customer_takeout_initiated": {
        "request_period_in_seconds": 60
    },
     "misconfigured_whitelist": {
         "request_period_in_seconds": 60
    }
}
``` |
| `request_period_in_seconds` | integer | Optional | Period in seconds used between each data pulling, this value will overwrite the default value (60 seconds) |
| `start_time_override` | string | Optional | This allows downloading historical data (1 month back for example) before downloading new events. Format: `YYYY-mm-ddTHH:MM:SS.sssZ` |
| `custom_tag` | string | Optional | It is used to override the default tag with a new customer defined tag. |

## Troubleshooting

This collector has different security layers that detect both an invalid configuration and abnormal operation. This table will help you detect and resolve the most common errors. Contact [Devo Support](https://devo.my.site.com/support/login?ec=302&startURL=%2Fsupport%2Fs%2F) for internal or persistent issues.

| Error type | Error Id | Error Message | Cause | Solution |
| --- | --- | --- | --- | --- |
| SetupError | 100 | File does not exist. Please, learn how to generate a token pickle on: [https://docs.devo.com/confluence/ndt/latest/sending-data-to-devo/collectors/g-suite-collectors/g-suite-alerts-collector](https://docs.devo.com/confluence/ndt/latest/sending-data-to-devo/collectors/g-suite-collectors/g-suite-alerts-collector) | This error is raised when token.pickle does not exist. | Regenerate the token.json and save it in the file devo-collector-gsuite-google-workspace-alerts/credentials/. |
| SetupError | 101 | Error | This error is raised when unknown error occurs while loading token.pickle | Check that the token.pickle is in the correct format and if not, regenerate it again. |
| SetupError | 102 | HTTP error: <error_message> | This error is raised when an HTTP error appears during setup. | The solution depends on the type of error. |
| SetupError | 103 | Unable to refresh token or client Auth was deleted. Detail: <error_message> | This error is raised when the token cannot be refreshed. The reason may be that it has been deleted. | Regenerate the token.json and save it in the file devo-collector-gsuite-google-workspace-alerts/credentials/. |
| SetupError | 104 | Operation timed out: <error_message> | This error is raised when the maximum time to wait for the connection has been exceeded. | Check that the connection is working properly. |
| SetupError | 105 | HTTP/1.1 503 Service Unavailable at moment - Retrying reconnection: <error_message> | This error is raised when the service is not available. | This is an internal issue. |
| SetupError | 106 | DefaultCredentials: <error_message> | This error is raised when credentials cannot be automatically determined. | This is an internal issue. |
| InitVariablesError | 1 | start_time is not set as per the datetime_format | Start time in config is not as per right format | Put start time in the correct format. |
| InitVariablesError | 2 | Date {initial_start_time_str} is in the future | Start time in config is in future | Put start time less than the current UTC time. |
| PullError | 300 | Operation timed out: <error_message> | This error is raised when the maximum time to wait for the connection has been exceeded. | Check that the connection is working properly. |
| PullError | 301 | Could not automatically determine credentials. | This error is raised when credentials are not loaded successfully. | This is an internal issue. |
| PullError | 302 | The <next_timestamp> value cannot be calculated, please check the related error logs. | This error is raised when timestamp is invalid. | This is an internal issue. |
| PullError | 303 | HTTP/1.1 503 Service Unavailable at moment - Retrying reconnection: <error_message> | This error is raised when the service is not available. | This is an internal issue. |
| PullError | 304 | DefaultCredentialsError | DefaultCredentialsError | This is an internal issue. |
| PullError | 305 | Error detected -> {e.**class**}: {e.**str**()} | Some error occurred during the pull cycle. | This is an internal issue. |

## API Endpoints

| **Endpoint** | **Service** | **Table** |
| --- | --- | --- |
| `https://alertcenter.googleapis.com/v1beta1/alerts`<br>Parameter `alert_type = Customer takeout initiated` | `customer_takeout_initiated` | `cloud.gsuite.alerts.customer_takeout_initiated` |
| `https://alertcenter.googleapis.com/v1beta1/alerts`<br>Parameter `alert_type = Misconfigured whitelist` | `misconfigured_whitelist` | `cloud.gsuite.alerts.misconfigured_whitelist` |
| `https://alertcenter.googleapis.com/v1beta1/alerts`<br>Parameter `alert_type = Malware reclassification` | `malware_reclassification` | `cloud.gsuite.alerts.malware_reclassification` |
| `https://alertcenter.googleapis.com/v1beta1/alerts`<br>Parameter `alert_type = Phishing reclassification` | `phishing_reclassification` | `cloud.gsuite.alerts.phishing_reclassification` |
| `https://alertcenter.googleapis.com/v1beta1/alerts`<br>Parameter `alert_type = Suspicious message reported` | `suspicious_message_reported` | `cloud.gsuite.alerts.suspicious_message_reported` |
| `https://alertcenter.googleapis.com/v1beta1/alerts`<br>Parameter `alert_type = User reported phishing` | `user_reported_phishing` | `cloud.gsuite.alerts.user_reported_phishing` |
| `https://alertcenter.googleapis.com/v1beta1/alerts`<br>Parameter `alert_type = User reported spam spike` | `user_reported_spam_spike` | `cloud.gsuite.alerts.user_reported_spam_spike` |
| `https://alertcenter.googleapis.com/v1beta1/alerts`<br>Parameter `alert_type = Leaked password` | `leaked_password` | `cloud.gsuite.alerts.leaked_password` |
| `https://alertcenter.googleapis.com/v1beta1/alerts`<br>Parameter `alert_type = Suspicious login` | `suspicious_login` | `cloud.gsuite.alerts.suspicious_login` |
| `https://alertcenter.googleapis.com/v1beta1/alerts`<br>Parameter `alert_type = Suspicious login (less secure app)` | `suspicious_login_less_secure_app` | `cloud.gsuite.alerts.suspicious_login_less_secure_app` |
| `https://alertcenter.googleapis.com/v1beta1/alerts`<br>Parameter `alert_type = Suspicious programmatic login` | `suspicious_programmatic_login` | `cloud.gsuite.alerts.suspicious_programmatic_login` |
| `https://alertcenter.googleapis.com/v1beta1/alerts`<br>Parameter `alert_type = User suspended` | `user_suspended` | `cloud.gsuite.alerts.user_suspended` |
| `https://alertcenter.googleapis.com/v1beta1/alerts`<br>Parameter `alert_type = User suspended (spam)` | `user_suspended_spam` | `cloud.gsuite.alerts.user_suspended_spam` |
| `https://alertcenter.googleapis.com/v1beta1/alerts`<br>Parameter `alert_type = User suspended (spam through relay)` | `user_suspended_spam_through_relay` | `cloud.gsuite.alerts.user_suspended_spam_through_relay` |
| `https://alertcenter.googleapis.com/v1beta1/alerts`<br>Parameter `alert_type = User suspended (suspicious activity)` | `user_suspended_suspicious_activity` | `cloud.gsuite.alerts.user_suspended_suspicious_activity` |
| `https://alertcenter.googleapis.com/v1beta1/alerts`<br>Parameter `alert_type = Google Operations` | `google_operations` | `cloud.gsuite.alerts.google_operations` |
| `https://alertcenter.googleapis.com/v1beta1/alerts`<br>Parameter `alert_type = Government attack warning` | `government_attack_warning` | `cloud.gsuite.alerts.government_attack_warning` |
| `https://alertcenter.googleapis.com/v1beta1/alerts`<br>Parameter `alert_type = Device compromised` | `device_compromised` | `cloud.gsuite.alerts.device_compromised` |
| `https://alertcenter.googleapis.com/v1beta1/alerts`<br>Parameter `alert_type = Suspicious activity` | `suspicious_activity` | `cloud.gsuite.alerts.suspicious_activity` |
| `https://alertcenter.googleapis.com/v1beta1/alerts`<br>Parameter `alert_type = AppMaker Default Cloud SQL setup` | `appmaker_default_cloud_sql_setup` | `cloud.gsuite.alerts.appmaker_default_cloud_sql_setup` |
| `https://alertcenter.googleapis.com/v1beta1/alerts`<br>Parameter `alert_type = Activity Rule` | `activity_rule` | `cloud.gsuite.alerts.activity_rule` |
| `https://alertcenter.googleapis.com/v1beta1/alerts`<br>Parameter `alert_type = Configuration problem` | `configuration_problem` | `cloud.gsuite.alerts` |
| `https://alertcenter.googleapis.com/v1beta1/alerts`<br>Parameter `alert_type = Data Loss Prevention` | `data_loss_prevention` | `cloud.gsuite.alerts.data_loss_prevention` |
| `https://alertcenter.googleapis.com/v1beta1/alerts`<br>Parameter `alert_type = Apps outage` | `apps_outage` | `cloud.gsuite.alerts` |
| `https://alertcenter.googleapis.com/v1beta1/alerts`<br>Parameter `alert_type = Primary admin changed` | `primary_admin_changed` | `cloud.gsuite.alerts` |
| `https://alertcenter.googleapis.com/v1beta1/alerts`<br>Parameter `alert_type = SSO profile added` | `sso_profile_added` | `cloud.gsuite.alerts` |
| `https://alertcenter.googleapis.com/v1beta1/alerts`<br>Parameter `alert_type = SSO profile updated` | `sso_profile_updated` | `cloud.gsuite.alerts` |
| `https://alertcenter.googleapis.com/v1beta1/alerts`<br>Parameter `alert_type = SSO profile deleted` | `sso_profile_deleted` | `cloud.gsuite.alerts` |
| `https://alertcenter.googleapis.com/v1beta1/alerts`<br>Parameter `alert_type = Super admin password reset` | `super_admin_password_reset` | `cloud.gsuite.alerts.super_admin_password_reset` |

## Devo collector features

| **Feature** | **Details** |
| --- | --- |
| Allow parallel downloading (`multipod`) | - `Not allowed` |
| Running environments | - `Collector server` |
| Populated Devo events | - `Table` |
| Flattening preprocessing | - `No` |

## Release Notes

- v1.10.0 (2025-04-10)
  - Improved DCSDK from 1.13.1 to 1.15.0. Fixed concurrency issue with credential file access.
- v1.9.0 (2024-11-21)
  - Updated DCSDK to 1.13.1, upgraded Base Docker Image to 1.3.1, fixed ingestion stoppage issue.
- v1.8.0 (2024-09-16)
  - Updated DCSDK to 1.12.4, upgraded Base Docker Image to 1.3.0.
- v1.7.0 (2023-11-17)
  - Updated DCSDK to 1.10.2, added support for multiple new alert types including Access Approvals request, APNS certificate alerts, MSA Billing/Legal/Product/Security alerts, and various user management alerts.
- v1.6.0 (2023-06-15)
  - Updated DCSDK from 1.4.1 to 1.8.0.
- v1.5.0 (2022-09-08)
  - Split Google Workspace Collector into Alerts and Reports collectors, added base64 validation for credentials token.
- v1.4.2 (2023-08-12)
  - Fixed bug preventing Syslog output from being enabled.
- v1.4.1 (2022-08-12)
  - Upgraded Devo Collector SDK to v1.4.1, improved resilience with auto-restart, enhanced retry logic, and added various monitoring improvements.
- v1.3.0 (2022-05-26)
  - Added support for new alert types including Data Loss Prevention, Apps outage, Primary admin changed, SSO profile events, and Super admin password reset.
- v1.2.0 (2022-04-29)
  - Added feature to restart persistence when config start_time is updated, improved performance with batch event delivery.