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 |
For more information about sources and types, visit the G Suite Alert Center API documentation.
Setup
The G Suite Alerts collector needs to be configured on Google APIs Console and the G Suite Admin Console for getting credentials and for giving the G Suite Alert Center API the right permissions so that the collector data retrieves alerts properly. Follow the instructions below to learn how to configure the services.
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.
- Create a project in the Google APIs console.
Go to the Library, search for G Suite Alert Center API, and enable it.
- Go to the Credentials section, then click on Manage service accounts.
Click Create service account, download the credentials file in JSON format and move it to
<any_directory>/devo-collector/gsuite-alerts/credentials
in the directory.
G Suite Admin Console
Grant domain access to the application in G Suite:
- Go to the G Suite Admin Console.
- Click Security and select Advanced Settings.
- Go to Authentication → Manage API client.
- Add the previously created service account. Enter the Service Account Client ID as the Client Name and in the One or More API Scopes field, enter https://www.googleapis.com/auth/apps.alerts
Grant access to the Alert Center to the user who will delegate the permissions.
Go to the G Suite Admin Console.
Click Admin Roles and select Create a new role.
Search for Alert Center in the privileges list and scroll down to view the View Access checkbox. Check it and save the new role.
Search the user and assign the new role to it.
Run the 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):
<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.
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"
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. Click here to download the Docker image of the collector as a .tgz file.
Use the following command to add the Docker image to the system:
gunzip -c collector-gsuite-docker-image.tgz | docker load
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
Execute the following command on the root directory <any_directory>/devo-collectors/gsuite-alerts/
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>
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.
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:
IMAGE_VERSION=<version> docker-compose up -d
Replace <version>
with the proper version.
Activeboards
Click here to download a preconfigured Activeboard that makes use of this collector and try in your Devo domain.
To start working with it, follow these instructions:
Create a new Activeboard in your domain. Learn how to do it here.
In Edit mode, click the ellipsis button and select Edit raw configuration.
Open the downloaded file, select all the text, and copy it into the clipboard.
Paste the contents of the file in the raw editor. Make sure you replace the existing configuration completely.
Click Save changes. The Activeboard should show up immediately.
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.