Page Comparison

Table of Contents

maxLevel	2
type	flat

...

Overview

Workspace is Google’s suite of products that includes email, calendar, drivedriver, 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.

...

received on tables along rows and columns in your Devo domain.

Devo collector features

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

Data sources

The Google Workspace (formerly G Suite) API generates account activities for these applications and sources. The collector process the Google API responses and send them to the Devo platform that will categorize all information received on tables along rows and columns on your Devo domain.

Google Workspace Alert Center

Listed in the table below are the alert sources, types, the data that Google Workspace classifies, and how the Devo platform manages it.

...

Alert source

...

and send them to the Devo platform that will categorize all information received on tables along rows and columns on your Devo domain.

Data Source	Alert Type	Devo tables	Available from release
Domain wide takeout	Customer takeout initiated	`cloud.gsuite.alerts.customer_takeout_initiated`	`v1.2.0`
Gmail phishing	Malware reclassification	`cloud.gsuite.alerts.malware_reclassification`	`v1.2.0`
	Misconfigured whitelist	`cloud.gsuite.alerts.misconfigured_whitelist`	`v1.2.0`
	Phishing reclassification	`cloud.gsuite.alerts.phishing_reclassification`	`v1.2.0`
	Suspicious message reported	`cloud.gsuite.alerts.suspicious_message_reported`	`v1.2.0`
	User reported phishing	`cloud.gsuite.alerts.user_reported_phishing`	`v1.2.0`
	User reported spam spike	`cloud.gsuite.alerts.user_reported_spam_spike`	`v1.2.0`
Google identity	Leaked password	`cloud.gsuite.alerts.eaked_password`	`v1.2.0`
	Suspicious login	`cloud.gsuite.alerts.suspicious_login`	`v1.2.0`
	Suspicious login (less secure app)	`cloud.gsuite.alerts.suspicious_login_less_secure_app`	`v1.2.0`
	Suspicious programmatic login	`cloud.gsuite.alerts.suspicious_programmatic_login`	`v1.2.0`
	User suspended	`cloud.gsuite.alerts.user_suspended`	`v1.2.0`
	User suspended (spam)	`cloud.gsuite.alerts.user_suspended_spam`	`v1.2.0`
	User suspended (spam through relay)	`cloud.gsuite.alerts.user_suspended_spam_through_relay`	`v1.2.0`
	User suspended (suspicious activity)	cloud.gsuite.alerts.user_suspended_suspicious_activity	`v1.2.0`
Google Operations	Google Operations	`cloud.gsuite.alerts.google_operations`	`v1.2.0`
State Sponsored Attack	Government attack warning	`cloud.gsuite.alerts.government_attack_warning`	`v1.2.0`
Mobile device management	Device compromised	`cloud.gsuite.alerts.device_compromised`	`v1.2.0`
Mobile device management	Suspicious activity	`cloud.gsuite.alerts.suspicious_activity`	`v1.2.0`
AppMaker Editor	AppMaker Default Cloud SQL setup	`cloud.gsuite.alerts.appmaker_default_cloud_sql_setup`	`v1.2.0`
Security Center rules	Activity Rule	`cloud.gsuite.alerts.activity_rules`	`v1.2.0`
Data Loss Prevention	Data Loss Prevention	`cloud.gsuite.alerts.data_loss_prevention`	`v1.3.0`
Sensitive Admin Action	Super Admin Password Reset	`cloud.gsuite.alerts.super_admin_password_reset`	`v1.3.0`

For more information about Sources and Types, visit Google Alert Center API.

Devo collector features

...

Feature

...

Details

...

Allow parallel downloading (multipod)

...

Not allowed

...

Running environments

...

Collector Server, On Premise

...

Populated Devo events

...

standard events

Setup

The Google Workspace Alerts collector needs to be configured in the Google Cloud Platform APIs console and also in the Google Admin console.

In the Google Cloud Platform APIs console, you need to enable the Google Workspace Alert Center API (formerly G Suite Alert Center API) and create the proper credentials for the collector.
In the Google Admin console, you must give the proper permissions to the previously created credentials.

Follow the instructions below to learn how to configure the services and allow the required permissions:

Enabling Google Workspace Alert Center API and credentials creation
Assigning the required permissions to the credentials

...

Follow the next steps to create the Service Account that will be used to collect the alerts and enable the necessary API and scopes to use it.

Go to the Google Cloud Platform APIs console.
Go to the Library section.
Image Removed
Search Google Workspace Alert Center API in the search box.
Image Removed
Click Enable.
Image Removed
Go to the Credentials section (You can type credentials api services on the search box or choose the section from the left panel).
Image Removed
Then, click Manage Service Accounts.
Image Removed
Click Create Service Account and fill in the required fields (the optional steps can be omitted).
Click on the previously created Service Account and make sure you are in the DETAILS section.
Click on SHOW DOMAIN-WIDE DELEGATION, then enable the option called Enable Google Workspace Domain-wide Delegation. Click Save and copy the value in the Client ID box (this value will be used in the Assigning proper permissions to credentials section).
Once saved, go to KEYS section, click ADD KEY → Create new key and choose the JSON file type. Then, click CREATE (a .json file will be downloaded).
Rename the downloaded file to credentials-gsuite-alerts.json and move it to the collector credentials directory (<any_directory>/devo-collector/gsuite-alerts/credentials/).

...

Now, you must associate a scope to the previously created Client ID. Follow these steps to do it:

Note
You must have the proper admin permissions to follow the next steps.

Go to the Google admin console.
From your Google Workspace domain’s Admin console, go to Main menu → Security → API Controls.
In the Domain wide delegation pane, select Manage Domain Wide Delegation.
Click Add new.
In the Client ID field, enter the service account's Client ID. You can find your service account's client ID in the Service accounts page.
In the OAuth scopes (comma-delimited) field, enter the next scope : https://www.googleapis.com/auth/apps.alerts
Click Authorize.

...

Vendor setup

The Google Workspace Alerts collector needs to be configured in the Google Cloud Platform APIs console and also in the Google Admin console.

In the Google Cloud Platform APIs console, you need to enable the Google Workspace Alert Center API (formerly G Suite Alert Center API) and create the proper credentials for the collector.
In the Google Admin console, you must give the proper permissions to the previously created credentials.

Follow the instructions below to learn how to configure the services and allow the required permissions:

Enabling Google Workspace Alert API and credentials creation

Follow the next steps to create the Service Account that will be used to collect the alerts and enable the necessary API and scopes to use it.

Go to the Google Cloud Platform APIs console.
Go to the Library section.
Image Added
Search Google Workspace Alert Center API in the search box.
Image Added
Click Enable.
Go to the Credentials section (You can type credentials api services on the search box or choose the section from the left panel).
Image Added
Then, click Manage Service Accounts.
Image Added
Click Create Service Account and fill in the required fields (the optional steps can be omitted).
Click on the previously created Service Account and make sure you are in the DETAILS section.
Click on SHOW DOMAIN-WIDE DELEGATION, then enable the option called Enable Google Workspace Domain-wide Delegation. Click Save and copy the value in the Client ID box (this value will be used in the Assigning proper permissions to credentials section).
Once saved, go to KEYS section, click ADD KEY → Create a new key and choose the JSON file type. Then, click CREATE (a .json file will be downloaded).
Rename the downloaded file to credentials-gsuite-alerts.json and move it to the collector credentials directory (<any_directory>/devo-collector/gsuite-alerts/credentials/).

Assigning the required permissions to the credentials

Now, you must associate a scope to the previously created Client ID. Follow these steps to do it:

Note
You must have the proper admin permissions to follow the next steps.

Go to the Google admin console.
From your Google Workspace domain’s Admin console, go to Main menu → Security → API Controls.
In the Domain-wide delegation pane, select Manage Domain Wide Delegation.
Click Add new.
In the Client ID field, enter the service account's Client ID. You can find your service account's client ID in the Service accounts page.
In the OAuth scopes (comma-delimited) field, enter the next scope : https://www.googleapis.com/auth/apps.alerts
Click Authorize.

...

Accepted authentication methods with Google Oauth2

A service account is a method used by Google to make server-to-server connections instead of user-to-server. In Google Workspace Collector Alerts, a service account is used for the API connection to GCP. That is, it is a way to authenticate to work with GCP's own data. This uses delegation of authority to allow applications to access user data in your organization's Google Workspace environment. Google Workspace Collector Alerts use the following delegated credentials:

Code Block
CredentialsFile.load_credentials( credentials_filename, credentials_scopes=credentials_scopes, delegated_email=delegated_email

Note
`delegated_email` field should contain the email of an real user (you cannot use a Service Account here) with enough access to display the alerts in the Google WorkSpace Admin Console → Alert Center. (https://admin.google.com/ac/ac).

Refer to the Google documentation for more information.

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).

Rw ui tabs macro

Rw tab

title	Cloud collector

We use a piece of software called Collector Server to host and manage all our available collectors. If you want us to host this collector for you, get in touch with us and we will guide you through the configuration.

Rw tab

title	On-premise collector

This data collector can be run in any machine that has the Docker service available because it should be executed as a docker container. The following sections explain how to prepare all the required setup for having the data collector running.

Structure

The following directory structure will be required as part of the setup procedure (it can be created under any directory)should be created for being used when running the collector:

Code Block

<any_directory>
└── devo-collectors/
    └── <product_name>/
        ├── certs/
        │   ├── chain.crt
        │   ├── <your_domain>.key
        │   └── <your_domain>.crt
        ├── state/
        └── config/ 
            └── config-<product_name>.yaml

Note
Replace `<product_name>` with the required proper value.

Devo credentials

In Devo, go to to Administration → Credentials → X.509 Certificates, download the the Certificate, Private key and and Chain CA and save them in <anyin <product_directory>/devo-collectors/gsuite-alerts/name>/certs/. Learn more about security credentials in Devo here.

Image Removed

Editing the config.yaml file

In the config.yaml file, replace the <delegated_email_value> and <source_id_value> values and enter the ones that you got in the previous steps. In the <short_unique_identifier> placeholder, enter the value that you choose.about security credentials in Devo here.

Image Added

Note
Replace `<product_name>` with the proper value.

Editing the config.yaml file

Code Block

globals:
  debug: True                                                      # <- Setup as True or False for debugging mode
  id: not_used
  name: gsuite
  persistence:                                                     # <- Persistence setup filesystem
    type: filesystem
    config:
      directory_name: state                                        # <- Persistence directory
outputs:
  devo_1:
    type: devo_platform
    config:
      address: eu.elb.relay.logtrust.net                           # <- Devo platform address EU/US
      port: 443
      type: SSL
      chain: chain.crt
      cert: <your_domain>.crt                                      # <- Please, replace with the certificate from your Devo domain (Administration>Credentials>x.509)
      key: <your_domain>.key                                       # <- Please, replace with the certificate from your Devo domain (Administration>Credentials>x.509)
inputs:
  gsuite_alerts:
    id: <short_unique_identifier>                                  # <- "input_id", used for internal identifications
    enabled: true                                                   # <- G Suite alerts service enabled
    requests_per_second: 5                                          # <- Setting up requests per second. 5 recommended.                                         
    autoconfig:                                                     # <- "autoconfiguration" will be executed (connector doesn't support this attribute, set is "true" by default).
      enabled: true                                                 # <- Autocofig setting up - True or False
      refresh_interval_in_seconds: 180                              # <- Time wait in second between requests - 180s recommended.
    credentials:
      filename: credentials-gsuite-alerts.json                      # <- Service Account credentials json file that you named on the getting credentials section                 
      delegated_email: <delegated_email_value>                      # <- Email that will be used to delegate G Suite Alerts Viewer permissions to the Service Account
      source_id: <source_id_value>                                  # <- This value will be used for adding to message "tag" as fourth level
    services:                                                       # <- List with the Alerts that you want to collect
      customer_takeout_initiated:
        request_period_in_seconds: 60                               # <- Controls waiting time for to the next request 
        start_time: "9999-12-31T23:59:59.999Z"
      malware_reclassification:
        request_period_in_seconds: 60
        start_time: "9999-12-31T23:59:59.999Z"
      misconfigured_whitelist:
        request_period_in_seconds: 60
        start_time: "9999-12-31T23:59:59.999Z"
      phishing_reclassification:
        request_period_in_seconds: 60
        start_time: "9999-12-31T23:59:59.999Z"
      suspicious_message_reported:
        request_period_in_seconds: 60
        start_time: "9999-12-31T23:59:59.999Z"
      user_reported_phishing:
        request_period_in_seconds: 60
        start_time: "9999-12-31T23:59:59.999Z"
      user_reported_spam_spike:
        request_period_in_seconds: 60
        start_time: "9999-12-31T23:59:59.999Z"
      leaked_password:
        request_period_in_seconds: 60
        start_time: "9999-12-31T23:59:59.999Z"
      suspicious_login:
        request_period_in_seconds: 60
        start_time: "9999-12-31T23:59:59.999Z"
      suspicious_login_less_secure_app:
        request_period_in_seconds: 60
        start_time: "9999-12-31T23:59:59.999Z"
      suspicious_programmatic_login:
        request_period_in_seconds: 60
        start_time: "9999-12-31T23:59:59.999Z"
      user_suspended:
        request_period_in_seconds: 60
        start_time: "9999-12-31T23:59:59.999Z"
      user_suspended_spam:
        request_period_in_seconds: 60
        start_time: "9999-12-31T23:59:59.999Z"
      user_suspended_spam_through_relay:
        request_period_in_seconds: 60
        start_time: "9999-12-31T23:59:59.999Z"
      user_suspended_suspicious_activity:
        request_period_in_seconds: 60
        start_time: "9999-12-31T23:59:59.999Z"
      google_operations:
        request_period_in_seconds: 60
        start_time: "9999-12-31T23:59:59.999Z"
      government_attack_warning:
        request_period_in_seconds: 60
        start_time: "9999-12-31T23:59:59.999Z"
      device_compromised:
        request_period_in_seconds: 60
        start_time: "9999-12-31T23:59:59.999Z"
      suspicious_activity:
        request_period_in_seconds: 60
        start_time: "9999-12-31T23:59:59.999Z"
      appmaker_default_cloud_sql_setup:
        request_period_in_seconds: 60
        start_time: "9999-12-31T23:59:59.999Z"
      activity_rule:
        request_period_in_seconds: 60
        start_time: "9999-12-31T23:59:59.999Z"

Note

The start_time fields are optional. If you would like to establish any value, the required format is 0000-00-00T00:00:00.000Z

:59.999Z"

Note
The `start_time` fields are optional. If you would like to establish any value, the required format is 0000-00-00T00:00:00.000Z.

Note
`delegated_email` field should contain the email of an real user (you cannot use a Service Account here) with enough access to display the alerts in the Google WorkSpace Admin Console >> Alert Center (https://admin.google.com/ac/ac).

Info
All defined service entities will be executed by the collector. If you do not want to run any of them, just remove the entity from the `services` object.

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-gsuite-docker-image-1.4.1.tgz	`f6d28ea62d6fda48fc4e8604173ca6739a2da5df097592aa0b7aafd713494981`

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

Code Block
gunzip -c <image_name>file>-<version>.tgz \| docker load

Infonote
Once the Docker image is imported, it will show the real name of the Docker image (including version info).
Note
Replace Replace `<image_name>file>` and `<version>` with the required valuesa proper value.

The Docker image can be deployed on the following services:

Docker

Docker Compose

Docker

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

Code Block

docker run 
--name collector-<product_name> 
--volume $PWD/certs:/devo-collector/certs 
--volume $PWD/config:/devo-collector/config 
--volume $PWD/state:/devo-collector/state 
--env CONFIG_FILE=config.yaml 
--rm 
--interactive 
--tty 
<image_name>:<version>

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

Docker Compose

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

Code Block

version: '3'
services:
  collector-<product_name>:
    image: <image_name>:${IMAGE_VERSION:-latest}
    container_name: collector-<product_name>
    volumes:
      - ./certs:/devo-collector/certs
      - ./config:/devo-collector/config
      - ./credentials:/devo-collector/credentials
      - ./state:/devo-collector/state
    environment:
      - CONFIG_FILE=${CONFIG_FILE:-config.yaml}

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

Code Block
IMAGE_VERSION=<version> docker-compose up -d

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

Disclaimer

The API limits the number of requests for your APIs Console project. The API project's maximum number of requests per second (project QPS) is 5 QPS and the maximum number of requests per day (project QPD) is 150,000 QPD across the account. If If these limits are exceeded, the server returns an HTTP 503 status code.

Version	Old Version 7	New Version 8
Changes made by	Former user	Former user
Saved on	Sept 07, 2022	Sept 07, 2022

Versions Compared

Key

Overview

Devo collector features

Data sources

Google Workspace Alert Center

Devo collector features

Setup

Vendor setup

Enabling Google Workspace Alert API and credentials creation

Assigning the required permissions to the credentials

Accepted authentication methods with Google Oauth2

Run the collector

Structure

Devo credentials

Editing the config.yaml file

Editing the config.yaml file

Download the Docker image

Docker

Docker

Docker Compose

Disclaimer