Knowledge BaseCommunityRelease NotesTraining VideosRequest Demo
Search
⌃K
Links

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.

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.
For the steps below to yield a successful integration, 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, your user role must also have read user privileges.

Step 1: Create a new Google Workspace source in Panther

  1. 1.
    In the left sidebar menu of the Panther Console, click Configure > Log Sources.
  2. 2.
    Click Create New.
  3. 3.
    Select Google Workspace from the list of available log sources. Click Start Setup.
  4. 4.
    On the next screen, configure the following fields:
    1. 1.
      Name: Enter a descriptive name for the source e.g., My Google Workspace logs.
    2. 2.
      Applications to monitor: Select the Google Workspace applications you want to monitor.
    3. 3.
      Enable user profiles: Select to retrieve user profile information. (Note the prerequisites for enabling Google Workspace user profiles.)
      • Refresh period (min): Set the frequency at which you'd like to retrieve profile updates.
  5. 5.
    Click Setup.
  6. 6.
    On the Set Credentials page, copy the redirect URL and store it in a secure location. You will need this in the next steps.
    The top of the screen says "Set up the App credentials." Below, a link is provided, and the Copy button next to it is circled. The associated text reads, "Use the link below as the redirect URL in your App settings."
    ​

Step 2: Create a new app in Google Cloud

  1. 1.
    Log in to your Google Cloud console.
  2. 2.
    Click + Create project.
    In Google Cloud console, the "+Create Project" button appears at the top of the page under the search bar. In this image, there is a teal circle around it.
    ​
  3. 3.
    Enter a descriptive Project name (e.g. Panther Integration) and choose a Location.
  4. 4.
    Click Create.
    • It will take a few seconds to create the project. Once created, you will see a notification on the page.
  5. 5.
    On the left sidebar menu, click the three lines icon, then Cloud Overview > Dashboard.
  6. 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.
    At the top of the Google Cloud dashboard, there is a dropdown. "Panther integration test" has been selected, and the select box is circled.
    ​
  7. 7.
    In the top search bar, search for "OAuth consent screen," then select the matching result.
    The search bar at the top of Google Cloud Console has the search term "oauth consent screen" typed in it. the first result, "OAuth consent screen," is circled
    ​
  8. 8.
    On the OAuth consent screen page, for User Type, select Internal.
  9. 9.
    Click Create.

Step 3: Configure your new Google Cloud app and enable API

  1. 1.
    On the OAuth consent screen page, fill in the following information:
    • App name: Enter your project name or project ID.
    • User support email: Select your email address.
    • Developer contact information: Enter your email address.
    • Leave the other fields blank.
  2. 2.
    Click Save and continue.
  3. 3.
    On the Scopes page, click Add or remove scopes.
  4. 4.
    In the Manually add scopes section, paste https://www.googleapis.com/auth/admin.reports.audit.readonly
  5. 5.
    (Optional) if user profiles are desired also paste scope: https://www.googleapis.com/auth/admin.directory.user.readonly
  6. 6.
    Click Add to table and Update.
    In the Manually add scopes section of the Google Cloud page, a URL has been entered. There is an arrow pointing from the Add to table button to the Update button.
    ​
  7. 7.
    Click Save and continue.
  8. 8.
    At the bottom of the Summary page, click Back to dashboard.
  9. 9.
    In the lefthand navigation menu, click Enabled APIs & services.
  10. 10.
    In the search bar in the top of the page, search for "Admin SDK API," and select Admin SDK API.
    In the Google Cloud console, "Admin SDK API" has been entered into the search box. The result titled Admin SDK API has been circled.
    ​
  11. 11.
    On the Admin SDK API page, click Enable.
    In the Google Cloud console, an Admin SDK API page is shown. An Enable button is circled.
    ​
    • You will be redirected to another screen.

Step 4: Create OAuth credentials for your new Google Cloud app

  1. 1.
    In the lefthand navigation menu, click Credentials.
  2. 2.
    At the top of the page, click +Create Credentials.
  3. 3.
    Click OAuth client ID.
    In Google Cloud console, the Credentials link in the left sidebar is highlighted. There is an arrow pointing from it to the "+ Create Credentials" link. There is an arrow pointing from "+ Create Credentials" to one of the dropdown options, "OAuth Client ID"
    ​
    • You will be redirected to a different page.
  4. 4.
    On the Create OAuth client ID page, in the Application type field, select Web application and type in a friendly Name, e.g., Panther.
  5. 5.
    Scroll down to the Authorized redirect URIs section, and click + Add URI.
  6. 6.
    In the URIs 1 field, paste the redirect URL provided in the Panther Console on the log source's Set Credentials page. You should have obtained this value earlier in the documentation while creating the log source in the Panther Console.
    There is an "Authorized Redirect URIs" header. There is a field labeled "URIs 1". At the bottom, there is a blue "Create" button.
    ​
  7. 7.
    Click Create.
  8. 8.
    A pop up modal will display a Client ID and Client Secret. Using a secure method, make note of the ClientID and Client Secret. You will need to provide them in the Panther Console to pull your reports.

Step 5: Finish Google Workspace source setup in Panther

  1. 1.
    Open the browser window or tab where you began the log source setup in the Panther Console earlier in this documentation.
  2. 2.
    On the Set Credentials page, enter the Client ID and Client Secret provided in your Google Cloud console.
    • If you did not save these values during the previous steps, you can find them in the Google Cloud console under APIs & Services > Credentials > OAuth 2.0 Client IDs.
  3. 3.
    Click Setup.
  4. 4.
    Click Grant Access.
    • This will prompt you to authorize the Google Workspace App you created earlier to pull Google Workspace logs from your account.
    • Click Allow.
      ​
      A Google prompt is titled "Panther integration app wants to access your Google Account." Below, it says, "This will allow Panther integration app to: View audit reports for your G Suite domain." Below, there are Allow and Cancel buttons.
      ​
  5. 5.
    You will be directed back to the Panther Console, where you will see a success screen:
The success screen reads, "Everything looks good! Panther will now automatically pull & process logs from your account"
  • You can optionally enable one or more Detection Packs.
  • 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.
    The "Trigger an alert when no events are processed" toggle is set to YES. The "How long should Panther wait before it sends you an alert that no events have been processed" setting is set to 1 Day

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 mapped to both the GSuite.ActivityEvent and GSuite.Reports log types— while these two schemas contain the same data, we recommend using Gsuite.ActivityEvent because it flattens the events, making the fields easier to reference in queries and detections.

GSuite.ActivityEvent

Contains the activity events for a specific account and application, such as the Admin console application or the Google Drive application.
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.
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
Previous
GitLab Logs
Next
Heroku Logs (Beta)
Last modified 30d ago