Google Workspace Logs

Panther supports pulling logs directly from Google Workspace

Overview

Panther can fetch Google Workspace (known formerly as G Suite) log events by querying the Google Workspace Reports API. Panther will query the Reports API for new events every 60 seconds.

Google Workspace applications Panther pulls logs for

Panther pulls Google Workspace logs for the following applications:

• Access Transparency

• Admin

• Calendar

• Chat

• Chrome

• Context-Aware Access

• Data Studio (Looker Studio)

• Drive

• GCP

• Gmail

• Groups

• Groups Enterprise

• Keep

• Login

• Meet

• Mobile

• Rules

• SAML

• User Accounts

• Token

How to onboard Google Workspace logs to Panther

In order for Panther to access the Google Workspace Reports API, you need to create and configure a Google Cloud app, and provide its credentials to Panther.

Prerequisites

To complete the steps below, your Google user must:

• Be authorized to read your organization's activity records

  • If your user does not have this privilege, follow these Google Workspace instructions to create a new role with Reports access and assign the role to your user.

• (If you plan to enable pulling Google Workspace user profiles) have read user privileges

Step 1: Create a new Google Workspace source in Panther

1. In the left sidebar menu of the Panther Console, click Configure > Log Sources.

2. Click Create New.

3. Search for “Google Workspace,” then click its tile.

4. On the slide-out panel, click Start Setup.

5. On the Configuration page, configure the following field:

   • Name: Enter a descriptive name for the source e.g., My Google Workspace logs.

6. Click Setup.

Step 2: Create and configure a Google Cloud app

Before setting up a Google Cloud app, you'll need to choose an authentication method. You can use a service account or OAuth —see the top-level tabs below.

Service account authentication

1. Create a new app in Google Cloud:

   1. Log in to your Google Cloud console.

   2. Click + Create project.

   3. Enter a descriptive Project name (e.g. Panther Integration) and choose a Location.

   4. Click Create.

      • It will take a few seconds to create the project. Once created, you will see a notification on the page.

   5. On the left sidebar menu, click the three lines icon, then Cloud Overview > Dashboard.

   6. If the project you just created is not already selected in the dropdown at the top of the page, open the dropdown and select it.

2. Enable the Admin SDK API:

   1. In the search bar, enter"Admin SDK API," and select Admin SDK API.

   2. On the Admin SDK API page, click Enable.

      • You will be redirected to a new screen.

3. Create a new Google Cloud service account.

4. Generate a JSON key file for the service account:

   1. In the IAM & Admin section, click Service Accounts.

   2. On the row of the service account you just created, click Actions, then Manage keys.

      
   3. Click Add Key > Create new key.

      
   4. Under Key type, select JSON, then click Create.

      • A JSON file will be downloaded.

   Keep this file in a safe place—it contains the credentials for this service account.

5. Enable Domain-wide delegation:

   1. On the row of the service account you just created, click Actions, then Manage details.

      
   2. Click Advanced settings, then copy the Client ID.

      
   3. Click View Google Workspace Admin Console.

   4. Sign in with an Administrator account.

   5. Click Security → Access and data control → API controls.

   6. Click Manage Domain-wide delegations.

   7. Click Add new.

   8. Fill in the fields:

      1. Client ID: enter the Client ID you copied above.

      2. OAuth scopes (comma-separated, no spaces): enter https://www.googleapis.com/auth/admin.reports.audit.readonly

         • (Optional) If user profiles are desired, also enter (separated by a comma) https://www.googleapis.com/auth/admin.directory.user.readonly

   9. Click Authorize.

6. Finish the source setup in Panther:

   1. Under Provide pulling configuration & JSON Keyfile, upload your JSON key file.

   2. In the Admin User Email field, enter the email address for which you enabled Domain-wide delegation.

   3. On the Enrichment page, if you would like to enable Google Workspace User Profiles, to the right of User Profiles, click the toggle ON.

      • Note the prerequisites for enabling Google Workspace profiles.

      • If you toggled User Profiles ON, also set a Refresh period (min). This represents the cadence at which Panther will update profile data with what is stored in Google Workspace.

   4. Click Setup. You will be directed to a success screen:

      

      • You can optionally enable one or more Detection Packs.

      • If you have not done so already, click Attach or Infer Schemas to attach one or more schemas to the source.

      • The Trigger an alert when no events are processed setting defaults to YES. We recommend leaving this enabled, as you will be alerted if data stops flowing from the log source after a certain period of time. The timeframe is configurable, with a default of 24 hours.

OAuth authentication

Panther-managed detections

See Panther-managed rules for Google Workspace in the panther-analysis GitHub repository (in directories prefixed with gsuite_).

Supported log types

Panther pulls data from Google's Reports Activities API which includes admin activity, login activity, token activity, Google Drive activity, and more.

This data gets stored as both GSuite.ActivityEvent and GSuite.Reports log types—while these two schemas contain the same data, it's recommended to use Gsuite.ActivityEvent because it flattens the events, making the fields easier to reference in queries and detections.

While both schemas capture the same data, they store it differently in the data lake. For example, GSuite.Reports may have a slightly smaller number of logs in the data lake because multiple events are wrapped in one payload. In GSuite.ActivityEvent, however, each event becomes a single event in Panther. More information about this behavior can be found in the Knowledge Base article: What is the difference between the Panther log types GSuite.Reports and GSuite.ActivityEvent?

While Google Workspace logs are stored in both the GSuite.ActivityEvent and GSuite.Reports tables in your data lake, the data is only counted once against your ingestion quota.

GSuite.ActivityEvent

Contains the activity events for a specific account and application, such as the Admin console application or the Google Drive application.

Reference: Google Workspace Documentation on Reports API Activities List.

fields:
    - name: id
      required: true
      description: Unique identifier for each activity record.
      type: object
      fields:
        - name: applicationName
          description: Application name to which the event belongs.
          type: string
        - name: customerId
          description: The unique identifier for a Google Workspace account.
          type: string
        - name: time
          description: Time of occurrence of the activity.
          type: timestamp
          timeFormat: rfc3339
          isEventTime: true
        - name: uniqueQualifier
          description: Unique qualifier if multiple events have the same time.
          type: string
    - name: actor
      description: User doing the action.
      type: object
      fields:
        - name: email
          description: The primary email address of the actor. May be absent if there is no email address associated with the actor.
          type: string
          indicators:
            - email
        - name: profileId
          description: The unique Google Workspace profile ID of the actor. May be absent if the actor is not a Google Workspace user.
          type: string
        - name: callerType
          description: The type of actor.
          type: string
        - name: key
          description: Only present when callerType is KEY. Can be the consumer_key of the requestor for OAuth 2LO API requests or an identifier for robot accounts.
          type: string
    - name: kind
      required: true
      description: The type of API resource. For an activity report, the value is reports#activities.
      type: string
    - name: ownerDomain
      description: This is the domain that is affected by the report's event. For example domain of Admin console or the Drive application's document owner.
      type: string
      indicators:
        - domain
    - name: ipAddress
      description: IP address of the user doing the action. This is the Internet Protocol (IP) address of the user when logging into Google Workspace which may or may not reflect the user's physical location. For example, the IP address can be the user's proxy server's address or a virtual private network (VPN) address. The API supports IPv4 and IPv6.
      type: string
      indicators:
        - ip
    - name: type
      description: Type of event. The Google Workspace service or feature that an administrator changes is identified in the type property which identifies an event using the eventName property. For a full list of the API's type categories, see the list of event names for various applications above in applicationName.
      type: string
    - name: name
      description: Name of the event. This is the specific name of the activity reported by the API. And each eventName is related to a specific Google Workspace service or feature which the API organizes into types of events.
      type: string
    - name: parameters
      description: Parameter value pairs for various applications. For more information about eventName parameters, see the list of event names for various applications above in applicationName.
      type: json

GSuite.Reports

We recommend using GSuite.ActivityEvent instead of GSuite.Reports. While both schemas contain the same data, the structure of GSuite.ActivityEvent is flatter, and therefore easier to reference in queries and detections.

Contains the activity events for a specific account and application, such as the Admin console application or the Google Drive application.

Reference: Google Workspace Documentation on Reports API Activities List.

schema: GSuite.Reports
description: 
referenceURL: https://developers.google.com/admin-sdk/reports/v1/reference/activities/list#response
fields:
    - name: id
      required: true
      description: Unique identifier for each activity record.
      type: object
      fields:
        - name: applicationName
          description: Application name to which the event belongs.
          type: string
        - name: customerId
          description: The unique identifier for a Google Workspace account.
          type: string
        - name: time
          description: Time of occurrence of the activity.
          type: timestamp
          timeFormat: rfc3339
          isEventTime: true
        - name: uniqueQualifier
          description: Unique qualifier if multiple events have the same time.
          type: string
    - name: actor
      description: User doing the action.
      type: object
      fields:
        - name: email
          description: The primary email address of the actor. May be absent if there is no email address associated with the actor.
          type: string
          indicators:
            - email
        - name: profileId
          description: The unique Google Workspace profile ID of the actor. May be absent if the actor is not a Google Workspace user.
          type: string
        - name: callerType
          description: The type of actor.
          type: string
        - name: key
          description: Only present when callerType is KEY. Can be the consumer_key of the requestor for OAuth 2LO API requests or an identifier for robot accounts.
          type: string
    - name: kind
      required: true
      description: The type of API resource. For an activity report, the value is reports#activities.
      type: string
    - name: ownerDomain
      description: This is the domain that is affected by the report's event. For example domain of Admin console or the Drive application's document owner.
      type: string
      indicators:
        - domain
    - name: ipAddress
      description: IP address of the user doing the action. This is the Internet Protocol (IP) address of the user when logging into Google Workspace which may or may not reflect the user's physical location. For example, the IP address can be the user's proxy server's address or a virtual private network (VPN) address. The API supports IPv4 and IPv6.
      type: string
      indicators:
        - ip
    - name: events
      description: Activity events in the report.
      type: array
      element:
        type: object
        fields:
            - name: type
              description: Type of event. The Google Workspace service or feature that an administrator changes is identified in the type property which identifies an event using the eventName property. For a full list of the API's type categories, see the list of event names for various applications above in applicationName.
              type: string
            - name: name
              description: Name of the event. This is the specific name of the activity reported by the API. And each eventName is related to a specific Google Workspace service or feature which the API organizes into types of events.
              type: string
            - name: parameters
              description: Parameter value pairs for various applications. For more information about eventName parameters, see the list of event names for various applications above in applicationName.
              type: array
              element:
                type: object
                fields:
                    - name: name
                      description: The name of the parameter.
                      type: string
                    - name: value
                      description: String value of the parameter.
                      type: string
                    - name: intValue
                      description: Integer value of the parameter.
                      type: bigint
                    - name: boolValue
                      description: Boolean value of the parameter.
                      type: boolean
                    - name: multiValue
                      description: String values of the parameter.
                      type: array
                      element:
                        type: string
                    - name: multiIntValue
                      description: Integer values of the parameter.
                      type: array
                      element:
                        type: bigint
                    - name: messageValue
                      description: 'Nested parameter value pairs associated with this parameter. Complex value type for a parameter are returned as a list of parameter values. For example, the address parameter may have a value as [{parameter: [{name: city, value: abc}]}]'
                      type: json
                    - name: multiMessageValue
                      description: List of messageValue objects.
                      type: array
                      element:
                        type: json