Versions Compared

Version Old Version 2 New Version 3
Changes made by

Former user

Former user

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Table of Contents
maxLevel2
typeflat

Service description

The G Suite Alert Center manages alerts on potential issues within your domain. Apps you develop can use the 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.

Data source description

The G Suite API generates account activities for these applications and sources. The G suite collector that we provide processes the Google API responses and sends them to the Devo platform. Data will be categorized in different tables in your Devo domain, as you can check in the following table.

G Suite Alert Center

Listed in the table below are the alerts sources, types, the data that G Suite classifies and how Devo platform treats it.

Alert source

Alert type

Devo data tables

Domain wide takeout

Customer takeout initiated

cloud.gsuite.alerts.customer_takeout_initiated

Gmail phishing

Malware reclassification

cloud.gsuite.alerts.malware_reclassification

Misconfigured whitelist

cloud.gsuite.alerts.misconfigured_whitelist

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

Google identity

Leaked password

cloud.gsuite.alerts.eaked_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

Google Operations

cloud.gsuite.alerts.google_operations

State Sponsored Attack

Government attack warning

cloud.gsuite.alerts.government_attack_warning

Mobile device management

Device compromised

cloud.gsuite.alerts.device_compromised

Suspicious activity

cloud.gsuite.alerts.suspicious_activity

AppMaker Editor

AppMaker Default Cloud SQL setup

cloud.gsuite.alerts.appmaker_default_cloud_sql_setup

Security Center rules

Activity Rule

cloud.gsuite.alerts.activity_rules

...

Anchor
enabling
enabling
Enabling Google Workspace Alert Center 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.

  1. Go to the Google Cloud Platform APIs console.

  2. Go to the Library section.

  3. Search Google Workspace Alert Center API in the search box.

  4. Click Enable.

  5. Go to the Credentials section (You can type credentials api services on the search box or choose the section from the left panel).

  6. Then, click Manage Service Accounts.

  7. Click Create Service Account and fill in the required fields (the optional steps can be omitted).

  8. Click on the previously created Service Account and make sure you are in the DETAILS section.

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

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

  11. Rename the downloaded file to credentials-gsuite-alerts.json and move it to the collector credentials directory (<any_directory>/devo-collector/gsuite-alerts/credentials/).

...

  1. Go to the Google admin console.

  2. From your Google Workspace domain’s Admin console, go to Main menu → Security → API Controls.

  3. In the Domain wide delegation pane, select Manage Domain Wide Delegation.

  4. Click Add new.

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

  6. In the OAuth scopes (comma-delimited) field, enter the next scope : https://www.googleapis.com/auth/apps.alerts

  7. Click Authorize.

...

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
titleCloud 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
titleOn-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):

Code Block
<any_directory>
└── devo-collectors/
    └── gsuite-alerts/
          ├── certs/
          │   ├── chain.crt
          │   ├── <your_domain>.key
          │   └── <your_domain>.crt
          ├── credentials/
          │   └── credentials-gsuite-alerts.json
          └── config/
                  └── config-gsuite-alerts.yaml

Devo credentials

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

Editing the config-gsuite-alerts.yaml file

In the config-gsuite-alerts.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.

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

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.2.0.tgz

e0e0f60d58c265f1e7f1d16976fe547caa0e38d830f5a7182131bc9adfcb7ed0

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

Code Block
gunzip -c collector-gsuite-docker-image.<version>.tgz | docker load
Info

Once the Docker image is imported, it will show the real name of the Docker image (including version info).

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/gsuite-alerts/

Code Block
docker run \
--name collector-gsuite-alerts \
--volume $PWD/certs:/devo-collector/certs \
--volume $PWD/config:/devo-collector/config \
--volume $PWD/state:/devo-collector/state \
--env CONFIG_FILE=config-gsuite-alerts.yaml \
--rm -it docker.devo.internal/collector/gsuite:<version>
Note

Replace <version> with the proper version.

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/gsuite-alerts/ directory.

Code Block
version: '3'
services:
  collector-gsuite-alerts:
    build:
      context: .
      dockerfile: Dockerfile
    image: docker.devo.internal/collector/gsuite:${IMAGE_VERSION:-latest}
    container_name: collector-gsuite-alerts
    volumes:
      - ./certs:/devo-collector/certs
      - ./config:/devo-collector/config
      - ./state:/devo-collector/state
    environment:
      - CONFIG_FILE=${CONFIG_FILE:-config-gsuite-alerts.yaml}

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

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

Replace <version> with the proper version.

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 these limits are exceeded, the server returns an HTTP 503 status code.