Google Workspace Alerts collector

[ 1 Configuration requirements ] [ 2 Overview ] [ 3 Devo collector features ] [ 4 Data sources ] [ 5 Vendor setup ] [ 6 Accepted authentication methods ] [ 7 Run the collector ] [ 8 Collector services detail ] [ 9 Collector operations ] [ 10 Change log ]

Configuration requirements

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

Configuration	Details

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 Google documentation to know how to do it.

More information

Refer to the Vendor setup section to know more about these configurations.

Overview

Workspace is Google’s suite of products that includes email, calendar, driver, meet, and other collaboration solutions. This collector provides the possibility to integrate Google Workspace with the Devo Platform making it easy to query and analyze the relevant data from Workspace, view it in the pre-configured Activeboards, or customize them to enable Enterprise IT and Cybersecurity teams to make impactful data-driven decisions.

This collector will retrieve alerts on potential issues within your domain. Apps you develop can use Google’s Alert Center API to retrieve alerts in order to respond to them. Apps can also use the API to create and retrieve alert feedback. For example, a monitoring app could retrieve new alerts, prioritize them, and then notify members of your organization when action is needed. The collector processes the API responses and sends them to the Devo platform which then categorizes all data received on tables along rows and columns in your Devo domain.

Devo collector features

Feature	Details

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

Data sources

Data Source	Description	API Endpoint	Collector service name	Devo Table	Available from release

Data Source	Description	API Endpoint	Collector service name	Devo Table	Available from release
Customer takeout initiated	DomainWideTakeoutInitiated \| Google Workspace Alert Center API \| Google Developers	`https://alertcenter.googleapis.com/v1beta1/alerts` Parameter `alert_type = Customer takeout initiated`	`customer_takeout_initiated`	`cloud.gsuite.alerts.customer_takeout_initiated`	`v1.0.0`
Misconfigured whitelist	BadWhitelist \| Google Workspace Alert Center API \| Google Developers	`https://alertcenter.googleapis.com/v1beta1/alerts` Parameter `alert_type = Misconfigured whitelist`	`misconfigured_whitelist`	`cloud.gsuite.alerts.misconfigured_whitelist`	`v1.0.0`
Malware reclassification	MailPhishing \| Google Workspace Alert Center API \| Google Developers	`https://alertcenter.googleapis.com/v1beta1/alerts` Parameter `alert_type = Malware reclassification`	`malware_reclassification`	`cloud.gsuite.alerts.malware_reclassification`	`v1.0.0`
Phishing reclassification		`https://alertcenter.googleapis.com/v1beta1/alerts` Parameter `alert_type = Phishing reclassification`	`phishing_reclassification`	`cloud.gsuite.alerts.phishing_reclassification`	`v1.0.0`
Suspicious message reported		`https://alertcenter.googleapis.com/v1beta1/alerts` Parameter `alert_type = Suspicious message reported`	`suspicious_message_reported`	`cloud.gsuite.alerts.suspicious_message_reported`	`v1.0.0`
User reported phishing		`https://alertcenter.googleapis.com/v1beta1/alerts` Parameter `alert_type = User reported phishing`	`user_reported_phishing`	`cloud.gsuite.alerts.user_reported_phishing`	`v1.0.0`
User reported spam spike		`https://alertcenter.googleapis.com/v1beta1/alerts` Parameter `alert_type = User reported spam spike`	`user_reported_spam_spike`	`cloud.gsuite.alerts.user_reported_spam_spike`	`v1.0.0`
Leaked password	AccountWarning \| Google Workspace Alert Center API \| Google Developers	`https://alertcenter.googleapis.com/v1beta1/alerts` Parameter `alert_type = Leaked password`	`leaked_password`	`cloud.gsuite.alerts.leaked_password`	`v1.0.0`
Suspicious login		`https://alertcenter.googleapis.com/v1beta1/alerts` Parameter `alert_type = Suspicious login`	`suspicious_login`	`cloud.gsuite.alerts.suspicious_login`	`v1.0.0`
Suspicious login (less secure app)		`https://alertcenter.googleapis.com/v1beta1/alerts` Parameter `alert_type = Suspicious login (less secure app)`	`suspicious_login_less_secure_app`	`cloud.gsuite.alerts.suspicious_login_less_secure_app`	`v1.0.0`
Suspicious programmatic login		`https://alertcenter.googleapis.com/v1beta1/alerts` Parameter `alert_type = Suspicious programmatic login`	`suspicious_programmatic_login`	`cloud.gsuite.alerts.suspicious_programmatic_login`	`v1.0.0`
User suspended		`https://alertcenter.googleapis.com/v1beta1/alerts` Parameter `alert_type = User suspended`	`user_suspended`	`cloud.gsuite.alerts.user_suspended`	`v1.0.0`
User suspended (spam)		`https://alertcenter.googleapis.com/v1beta1/alerts` Parameter `alert_type = User suspended (spam)`	`user_suspended_spam`	`cloud.gsuite.alerts.user_suspended_spam`	`v1.0.0`
User suspended (spam through relay)		`https://alertcenter.googleapis.com/v1beta1/alerts` Parameter `alert_type = User suspended (spam through relay)`	`user_suspended_spam_through_relay`	`cloud.gsuite.alerts.user_suspended_spam_through_relay`	`v1.0.0`
User suspended (suspicious activity)		`https://alertcenter.googleapis.com/v1beta1/alerts` Parameter `alert_type = User suspended (suspicious activity)`	`user_suspended_suspicious_activity`	`cloud.gsuite.alerts.user_suspended_suspicious_activity`	`v1.0.0`
Google Operations	GoogleOperations \| Google Workspace Alert Center API \| Google Developers	`https://alertcenter.googleapis.com/v1beta1/alerts` Parameter `alert_type = Google Operations`	`google_operations`	`cloud.gsuite.alerts.google_operations`	`v1.0.0`
Government attack warning	StateSponsoredAttack \| Google Workspace Alert Center API \| Google Developers	`https://alertcenter.googleapis.com/v1beta1/alerts` Parameter `alert_type = Government attack warning`	`government_attack_warning`	`cloud.gsuite.alerts.government_attack_warning`	`v1.0.0`
Device compromised	DeviceCompromised \| Google Workspace Alert Center API \| Google Developers	`https://alertcenter.googleapis.com/v1beta1/alerts` Parameter `alert_type = Device compromised`	`device_compromised`	`cloud.gsuite.alerts.device_compromised`	`v1.0.0`
Suspicious activity	SuspiciousActivity \| Google Workspace Alert Center API \| Google Developers	`https://alertcenter.googleapis.com/v1beta1/alerts` Parameter `alert_type = Suspicious activity`	`suspicious_activity`	`cloud.gsuite.alerts.suspicious_activity`	`v1.0.0`
AppMaker Default Cloud SQL setup	AppMakerSqlSetupNotification \| Google Workspace Alert Center API \| Google Developers	`https://alertcenter.googleapis.com/v1beta1/alerts` Parameter `alert_type = AppMaker Default Cloud SQL setup`	`appmaker_default_cloud_sql_setup`	`cloud.gsuite.alerts.appmaker_default_cloud_sql_setup`	`v1.0.0`
Activity Rule	ActivityRule \| Google Workspace Alert Center API \| Google Developers	`https://alertcenter.googleapis.com/v1beta1/alerts` Parameter `alert_type = Activity Rule`	`activity_rule`	`cloud.gsuite.alerts.activity_rule`	`v1.0.0`
Configuration Problem	https://developers.google.com/admin-sdk/alertcenter/reference/rest/v1beta1/VoiceMisconfiguration	`https://alertcenter.googleapis.com/v1beta1/alerts` Parameter `alert_type = Configuration problem`	`configuration_problem`	`cloud.gsuite.alerts`	`v1.0.0`
Data Loss Prevention	DlpRuleViolation \| Google Workspace Alert Center API \| Google Developers	`https://alertcenter.googleapis.com/v1beta1/alerts` Parameter `alert_type = Data Loss Prevention`	`data_loss_prevention`	`cloud.gsuite.alerts.data_loss_prevention`	`v1.3.0`
Apps outage	AppsOutage \| Google Workspace Alert Center API \| Google Developers	`https://alertcenter.googleapis.com/v1beta1/alerts` Parameter `alert_type = Apps outage`	`apps_outage`	`cloud.gsuite.alerts`	`v1.3.0`
Primary admin changed	SensitiveAdminAction \| Google Workspace Alert Center API \| Google Developers	`https://alertcenter.googleapis.com/v1beta1/alerts` Parameter `alert_type = Primary admin changed`	`primary_admin_changed`	`cloud.gsuite.alerts`	`v1.3.0`
SSO profile added		`https://alertcenter.googleapis.com/v1beta1/alerts` Parameter `alert_type = SSO profile added`	`sso_profile_added`	`cloud.gsuite.alerts`	`v1.3.0`
SSO profile updated		`https://alertcenter.googleapis.com/v1beta1/alerts` Parameter `alert_type = SSO profile updated`	`sso_profile_updated`	`cloud.gsuite.alerts`	`v1.3.0`
SSO profile deleted		`https://alertcenter.googleapis.com/v1beta1/alerts` Parameter `alert_type = SSO profile deleted`	`sso_profile_deleted`	`cloud.gsuite.alerts`	`v1.3.0`
Super admin password reset		`https://alertcenter.googleapis.com/v1beta1/alerts` Parameter `alert_type = Super admin password reset`	`super_admin_password_reset`	`cloud.gsuite.alerts.super_admin_password_reset`	`v1.3.0`

For more information on how the events are parsed, visit our page.

Vendor setup

There are minimal requirements to setup this collector:

GPC console access: Credentials are required to access the GCP console.
Owner or Administrator permissions within the GCP console.
Have a delegated email.

In order to retrieve the data, we need to create and authorize a Service account to authenticate the collector.

Login to Google APIs console.
In the search bar, search Create a Project.
Click on Create a Project.
Fill in the required fields.
Click on Create.

Login to Google APIs console.
In the search bar, search Workspace Alert Center API.
Click on Google Workspace Alert Center API.
Click on Enable to activate the API.

In the search bar, search Credentials.
Click on Credentials (APIs & Services).
In the Service Accounts section, click on Manage service accounts.
Click on the + Create service account button.
Enter a Service account name and click Done.
Click on the Email field of the created service account to access its details.
Copy and save the Unique ID of the created service account.
Click on the Keys tab.
Click on Add key button.
Click on Create new key. A pop-up window will open to select the details of the key.
In key type select JSON.
Click on the Create button.
The file with the credentials will be downloaded automatically.
Rename the file credentials.json.
Save the file in <any_directory>/devo-collectors/gsuite-google-workspace-alerts/credentials/
Convert the content of the credentials.json to base64. Recommended method using Python version higher or equal 3.6
1. Copy the Python script below:
  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()
2. Save the script to <any_directory>/devo-collectors/gsuite-google-workspace-alerts/credentials/.
3. Rename it to b64encoder.py.
4. Run the command below in the <any_directory>/devo-collectors/gsuite-google-workspace-alerts/credentials/ directory.
  $ python b64encoder.py
5. The script will output a line starting with Base64 encoded credentials.json: Copy the base64 value as this will be required for the collector configuration.
Copy the content of the json file. You can use any free software to convert the content of the json file to base64.
Paste it into a base64 encoder and copy the result.

Save base64 value

It is important to save the base64 value to later run the collector on-premise and in the collector server.

Unique ID

The Unique ID (step 7) will be used later in the domain delegation.

Once the service account is created and with credentials, it is necessary to authorize it through Domain Wide Delegation.

Login in the google administration console: https://admin.google.com/.
In the left menu select Security → Access and data control → API controls.
Click Manage domain wide delegation in the Domain wide delegation section.
Click on Add new. A pop-up window will open to enter the details.
1. In Client ID field enter the previously copied Service Account Unique ID.
2. In OAuth scopes field add the following: https://www.googleapis.com/auth/apps.alerts.
Finally click on Authorize.

You will need to provide a valid email address belonging to a user account. The user account must have appropriate permissions, such as alert viewing. Refer to Google documentation to know how to do it.

Minimum configuration required for basic pulling

Although this collector supports advanced configuration, the fields required to retrieve data with basic configuration are defined below.

Setting	Details

Setting	Details
`filename_value`	This parameter is the name that you want to give to the token generated by the Collector. For example: `token.pickle`
`content_base64`	This parameter is the credentials in base64 format. To know how to obtain this value review the section Vendor setup.
`delegated_email`	This parameter is the email of the user whose domain is delegated to authorize the service account to access the alerts. To know how to obtain this value review the section Vendor setup.
`source_id_value`	This parameter will be used when {source_id} placeholder is present when using custom tags. Please use "abc" value when not used.

Accepted authentication methods

Depending on how did you obtain your credentials, you will have to either fill or delete the following properties on the JSON credentials configuration block.

Authentication Method	Filename	Base64 credentials	Delegated email

Authentication Method	Filename	Base64 credentials	Delegated email
Service Account with Base64	REQUIRED	REQUIRED	REQUIRED

Download the Docker image

The collector should be deployed as a Docker container. Download the Docker image of the collector as a .tgz file by clicking the link in the following table:

Collector Docker image	SHA-256 hash

Collector Docker image	SHA-256 hash
collector-google_workspace_alerts_if-docker-image-1.9.0	`19607f4289db449eaf7a58853a0f7f57de3fcd1113e12e89a4dccdd381874ab4`

Use the following command to add the Docker image to the system:

gunzip -c <image_file>-<version>.tgz | docker load

Once the Docker image is imported, it will show the real name of the Docker image (including version info). Replace <image_file> and <version> with a proper value.

The Docker image can be deployed on the following services:

Docker

Execute the following command on the root directory <any_directory>/devo-collectors/<product_name>/

Replace <product_name>, <image_name> and <version> with the proper values.

Docker Compose

The following Docker Compose file can be used to execute the Docker container. It must be created in the <any_directory>/devo-collectors/<product_name>/ directory.

To run the container using docker-compose, execute the following command from the <any_directory>/devo-collectors/<product_name>/ directory:

Replace <product_name>, <image_name> and <version> with the proper values.

Run the collector

Once the data source is configured, you can either send us the required information if you want us to host and manage the collector for you (Cloud collector), or deploy and host the collector in your own machine using a Docker image (On-premise collector).

Collector services detail

This section is intended to explain how to proceed with specific actions for services.

Devo categorization and destination

The alerts are ingested in the Devo tables with the format cloud.gsuite.alerts.<alert_type> when alert_type is the alert type of the Alert Center. The alert types are listed below:

Alert type	Devo Table

Alert type	Devo Table
`customer_takeout_initiated`	`cloud.gsuite.alerts.customer_takeout_initiated`
`misconfigured_whitelist`	`cloud.gsuite.alerts.misconfigured_whitelist`
`malware_reclassification`	`cloud.gsuite.alerts.malware_reclassification`
`phishing_reclassification`	`cloud.gsuite.alerts.phishing_reclassification`
`suspicious_message_reported`	`cloud.gsuite.alerts.suspicious_message_reported`
`user_reported_phishing`	`cloud.gsuite.alerts.user_reported_phishing`
`user_reported_spam_spike`	`cloud.gsuite.alerts.user_reported_spam_spike`
`leaked_password`	`cloud.gsuite.alerts.leaked_password`
`suspicious_login`	`cloud.gsuite.alerts.suspicious_login`
`suspicious_login_less_secure_app`	`cloud.gsuite.alerts.suspicious_login_less_secure_app`
`suspicious_programmatic_login`	`cloud.gsuite.alerts.suspicious_programmatic_login`
`user_suspended`	`cloud.gsuite.alerts.user_suspended`
`user_suspended_spam`	`cloud.gsuite.alerts.user_suspended_spam`
`user_suspended_spam_through_relay`	`cloud.gsuite.alerts.user_suspended_spam_through_relay`
`user_suspended_suspicious_activity`	`cloud.gsuite.alerts.user_suspended_suspicious_activity`
`google_operations`	`cloud.gsuite.alerts.google_operations`
`government_attack_warning`	`cloud.gsuite.alerts.government_attack_warning`
`device_compromised`	`cloud.gsuite.alerts.device_compromised`
`suspicious_activity`	`cloud.gsuite.alerts.suspicious_activity`
`appmaker_default_cloud_sql_setup`	`cloud.gsuite.alerts.appmaker_default_cloud_sql_setup`
`activity_rule`	`cloud.gsuite.alerts.activity_rule`
`configuration_problem`	`cloud.gsuite.alerts`
`data_loss_prevention`	`cloud.gsuite.alerts.data_loss_prevention`
`apps_outage`	`cloud.gsuite.alerts`
`primary_admin_changed`	`cloud.gsuite.alerts`
`sso_profile_added`	`cloud.gsuite.alerts`
`sso_profile_updated`	`cloud.gsuite.alerts`
`sso_profile_deleted`	`cloud.gsuite.alerts`
`super_admin_password_reset`	`cloud.gsuite.alerts.super_admin_password_reset`

Events service

Collector operations

This section is intended to explain how to proceed with specific operations of this collector.

Change log

Release	Released on	Release type	Details	Recommendations

Release	Released on	Release type	Details	Recommendations
`v1.9.0`	Nov 21, 2024	IMPROVEMENT BUG FIX	Improvements Updated DCSDK from 1.12.4 to 1.13.1 Upgraded Base Docker Image to 1.3.1 Bug Fix Fixed ingestion stoppage issue	`Recommended version`
`v1.8.0`	Sep 16, 2024	IMPROVEMENT	Improvements Updated DCSDK from 1.10.2 to 1.12.4 Upgraded Base Docker Image to 1.3.0	`Recommended version`
`v1.7.0`	Nov 17, 2023	IMPROVEMENTNEW FEATURE	Improvements Updated DCSDK from 1.8.0 to 1.10.2 New features: Added new alert types: Access Approvals request APNS certificate is expiring soon APNS certificate has expired MSA Billing MSA Legal MSA Product MSA Security Customer abuse detected Drive settings changed Email settings changed Mobile settings changed New user Added Suspended user made active User deleted User granted Admin privilege Users Admin privilege revoked Users password changed Reporting Rule Account suspension warning Chrome devices auto-update expiration warning	`Update`
`v1.6.0`	Jun 15, 2023	IMPROVEMENT	Improvements: Updated DCSDK from 1.4.1 to 1.8.0.	`Update`
`v1.5.0`	Sep 8, 2022	IMPROVEMENT	Improvements: The Google Workspace Collector has been divided into two: Google Workspace Alerts and Google Workspace Reports to improve the user experience. Added base64 validation: Validates whether the credentials token is in the correct base64 format.	`Update`
`v1.4.2`	Aug 12, 2023	BUG FIX	Bugs fixes: Fixed a bug that prevented Syslog output from being enabled.	`Update`
`v1.4.1`	Aug 12, 2022	IMPROVEMENT	Improvements: Upgraded underlay Devo Collector SDK from v1.1.4 to v1.4.1. The resilience has been improved with a new feature that restart the collector when the Devo connections is lost and it cannot be recovered. When an exception is raised by the Collector Setup, the collector retries after 5 seconds. For consecutive exceptions, the waiting time is multiplied by 5 until hits 1800 seconds, which is the maximum waiting time allowed. No maximum retries are applied. When an exception is raised by the Collector Pull method, the collector retries after 5 seconds. For consecutive exceptions, the waiting time is multiplied by 5 until hits 1800 seconds, which is the maximum waiting time allowed. No maximum retries are applied. When an exception is raised by the Collector pre-pull method, the collector retries after 30 seconds. No maximum retries are applied. Updated the underlying DevoSDK package to v3.6.4 and dependencies, this upgrade increases the resilience of the collector when the connection with Devo or the Syslog server is lost. The collector is able to reconnect in some scenarios without running the self-kill feature. Support for stopping the collector when a GRACEFULL_SHUTDOWN system signal is received. Re-enabled the logging to devo.collector.out for Input threads. Improved self-kill functionality behavior. Added more details in log traces. Added log traces for knowing system memory usage.	`Update`
`v1.3.0`	May 26, 2022	NEW FEATURE	New features: Added new alert types: Data Loss Prevention Apps outage Primary admin changed SSO profile added SSO profile updated SSO profile deleted Super admin password reset	`Update`
`v1.2.0`	Apr 29, 2022	NEW FEATURE IMPROVEMENT	New features: We added to the Alerts puller the feature to restart the persistence when the config `start_time` is updated at service level. Improvements: The performance has been improved after switching the internal delivery method. The events are delivered in batches instead of one by one.	`Update`