Overview

This article explains how to ingest your Gsuite Activities and Alerts logs to Hunters. Following the guide bellow will allow Hunters to collect your Gsuite logs and ingest them to our database in a predefined schema, and then use these logs in our dedicated hunting mechanism.

Supported data types

  • Gsuite Activities: logs for various Gsuite applications (admin, calendar, drive etc.). Full list of applications can be found here.

  • Gsuite Alerts: alerts created by Gsuite (e.g. 'Spike in user reported spam', 'Suspicious device activity'). Full list can be found here.

  • Gsuite Directory Users: a snapshot of all users in the Gsuite account (schema can be found here).

Sending data to Hunters

Prerequisites

In order to enable Hunters' collection & ingestion of Gsuite for your account, follow the next steps:

  1. Create a new Google Project, named 'Hunters Gsuite Ingesion', following Steps 1-3 in this guide. In particular, during Step 2 enable the 2 APIs: Admin SDK API & Google Workspace Alert Center API.

  2. In this project, create a new Service Account by following Step 4 in the same guide.

  3. Following this guide, add the following Scopes to the Service account: https://www.googleapis.com/auth/apps.alerts

    https://www.googleapis.com/auth/admin.reports.audit.readonly

    https://www.googleapis.com/auth/admin.directory.user.readonly

    https://www.googleapis.com/auth/admin.directory.group.member.readonly

    https://www.googleapis.com/auth/admin.directory.rolemanagement.readonly

    https://www.googleapis.com/auth/admin.directory.orgunit.readonly

    https://www.googleapis.com/auth/admin.directory.domain.readonly

    https://www.googleapis.com/auth/admin.directory.group.readonly

  4. Generate a credentials file for the service account in a JSON format and supply Hunters this file.

  5. This is an example of the JSON credentials file that you will download in step 4. In this example, everything in capital letters will be replaced with valid unique values for your account. Everything in lower case letters is generic for all accounts.

    {  "type": "service_account",
       "project_id": "GOOGLE_PROJECT_ID",
       "private_key_id": "PRIVATE_KEY_ID",
       "private_key": "-----BEGIN PRIVATE KEY-----\nPRIVATE_KEY_BLOB\n-----END PRIVATE KEY-----\n",
       "client_email": "SERVICE_ACCOUNT_CLIENT_EMAIL",
       "client_id": "GOOGLE_CLIENT_ID",
       "auth_uri": "https://accounts.google.com/o/oauth2/auth",
       "token_uri": "https://oauth2.googleapis.com/token",
       "auth_provider_x509_cert_url": "https://www.googleapis.com/oauth2/v1/certs",
       "client_x509_cert_url": "CLIENT_X590_CERT_URL" }
    CODE
  6. The Gsuite Service Account requires an impersonation email address to be used in the API querying. Hence, please also provide an email address only (WITHOUT credentials) of a google account that has Admin privileges in your Gsuite account. For sustainability purposes, this email account should be permanent and not deleted in the future.

Data Collection Hermeticity

According to various sources (e.g. here), the internal reporting mechanism in several Google Applications has a delay. To cope with this issue, we collect the events using the API with an inherent 1 hour delay. Even so, the ingestion may result in gaps in the ingested data.