Welcome to Google Workspace For Splunk App’s documentation!

About Google Workspace For Splunk


Author	Kyle Smith
App Version	1.7.3
App Build	466
Release Date	2025-08-04
Vendor Products	Google Workspace, using Service Accounts
Has index-time operations	false
Creates an index	false
Implements summarization	Currently, the app does not generate summaries

Google Workspace For Splunk allows a Splunk Enterprise administrator to interface with Google Workspace, consuming the usage and administrative logs provided by Google. The limitations on collection times are specified: https://support.google.com/a/answer/7061566 .

Scripts and binaries

This App provides the following scripts:


ga.py	This python file controls the modular input for Admin Reports
ga_alerts.py	This Python controls the modular input for Alert Center
ga_usage.py	This Python controls the modular input for Admin Usage Reports
ga_classroom.py	This python controls the modular input for Google Classroom Reports
google_client.py	This contains the classes for use with the modular inputs
ga_bigquery.py	This contains the classes required for the Big Query inputs.
ga_ss.py	This contains the classes required for Spreadsheet inputs.
ga_forms.py	This contains the classes required for Google Form inputs.
ga_analytics.py	This contains the items required for Google Analytics Consumption.
Diag.py	Allows diag-targeted collection of information.
ModularInput.py	Inheritable Class to create Modular Inputs
Utilities.py	Allows utility interactions with Splunk Endpoints
version.py	This is used for localized variables.
ga_display_checkpoints.py	This is an endpoint to read and display the localized checkpoints.
googleworkspace-write-big-query.py	This is the alert action file to write to big query.
googleworkspace-pubsub.py	This is the alert action file to read/write from pubsub
ga_cmd_natural_language.py	This is an experimental command to use the Google Natural Language API.
ga_spreadsheets.py	This is used to interact with Google Sheets.
googleworkspace-vault-hold.py	This is an experimental alert action to work with the Google Vault.
googleworkspace-vault-matter.py	This is an experimental alert action to work with the Google Vault.
google_constants.py	This file holds configurations common to all Google knowledge objects and scripts
google_alert_action.py	This is the base class for alert actions in this extension
google_workspace_for_splunk.py	This is the base script file for the extension.
google_utilities.py	This holds various utility needs to interface with Splunk.
cim_actions.py	This is related to CIM and Adaptive Response.
AlertAction.py	This is the base alert action class.
__init__.py	Module init.
google_custom_command.py	This is the base custom command class.
ga_analytics_metadata.py	This interacts with the Google Analytics API
six.py	Six.
ga_forms_get.py	This interacts with the Google Forms API.
app_properties.py	This contains several properties for use in python files.
KennyLoggins.py	An updated and enhanced logging class.
_paths.py	Global import to target `lib` folder.

About this release

Version 1.7.3 of Google Workspace For Splunk is compatible with:


Splunk Enterprise versions	9.0, 8.2, 8.1, 8.0
Platforms	Splunk Enterprise, Splunk Cloud (if vetted)

Compatability

Known Issues

Version 1.7.3 of Google Workspace For Splunk has the following known issues:

According to stackoverflow, there are indications that the Google Apps Admin API has an unspecified delay introduced into the events that are collected. This is most likely due to how Google collects the events and the global nature of the events. To mitigate this issue, the Google Workspace For Splunk Modular Input has a built-in delay in the consumption of events. If you run the modular input at 30 minutes, there will be a 30 minute delay of events. If you run at 1 hour, there will be a 1 hour delay in events.
References
https://support.google.com/a/answer/7061566
http://stackoverflow.com/questions/27389354/minimal-delay-when-listing-activities-using-the-reports-api
http://stackoverflow.com/questions/30850838/what-is-the-delay-between-a-event-happens-and-it-is-reflected-in-admin-reports-a
These are the currently used scopes. Not all scopes are required to be used.
https://www.googleapis.com/auth/admin.reports.audit.readonly
https://www.googleapis.com/auth/admin.reports.usage.readonly
https://www.googleapis.com/auth/admin.directory.user.readonly
https://www.googleapis.com/auth/admin.directory.device.chromeos.readonly
https://www.googleapis.com/auth/drive.metadata.readonly
https://www.googleapis.com/auth/bigquery
https://www.googleapis.com/auth/cloud-platform
https://www.googleapis.com/auth/drive.readonly
https://www.googleapis.com/auth/spreadsheets
https://www.googleapis.com/auth/classroom.courses.readonly
https://www.googleapis.com/auth/classroom.rosters.readonly
https://www.googleapis.com/auth/classroom.coursework.students.readonly
https://www.googleapis.com/auth/classroom.announcements.readonly
https://www.googleapis.com/auth/classroom.guardianlinks.students.readonly
https://www.googleapis.com/auth/apps.alerts

User Guide

Key concepts for Google Workspace For Splunk

You must have enabled the Google Workspace APIs at https://console.developers.google.com
You must have configured a credential for use with this App at https://console.developers.google.com.
You must enable Domain Wide Delegation for the credential.
You must have a G Suite User with permissions to the correct API scopes. This user will be impersonated.
Scopes Defined are here: https://developers.google.com/identity/protocols/googlescopes

Create Service Account.

Navigate to https://console.cloud.google.com/iam-admin/serviceaccounts
Create/Select a Project
Click Create service account button.
Fill out the information required, and finish creation of the Service Account.
Once created, edit the Service Account.
Note: Google Analytics consumption is non-standard from this point. Please see documentation further down for specifics.
Find the Show domain-wide delegation section, and show the section.
Click the check box to enable G Suite Domain-wide Delegation.
If you did not previously have a key created, find the Keys tab and create a new JSON private key for the Service Account
SAVE THIS FILE FOR THE NEXT STEPS
MAKE NOTE OF THE CLIENT ID OF THIS CREDENTIAL
Enable the following APIS while in the console. (As Needed)
1. Admin SDK API
2. Audit API
3. Google Classroom API
4. Google Workspace Alert Center API
5. Google Sheets API
6. BigQuery API
7. Cloud Pub/Sub API
8. Google Forms API
9. Analytics Reporting API
10. Google Analytics Data API
11. Google Analytics API
12. Google Analytics Admin API
13. Gmail API

Configure Google Workspaces

Navigate to https://admin.google.com/ac/users
Create a new user that has permissions to access the above enabled APIS (some sort of Admin level)
MAKE A NOTE OF THIS USER FOR A LATER STEP
Navigate to https://admin.google.com/ac/owl/domainwidedelegation
Click the Add New button
Enter the client id from above, and any scopes you require.

Configure Google Workspace Credentials.

Navigate to the Application Configuration dashboard.
Navigate to the Google Workspace Credentials tab.
Download/have on hand the JSON file from the Developers Console for the Service Account Credentials.
Click the + sign at the top right of the table.
Fill out the form, upload the JSON file, and click the checkmark to the left of the row.
The Entire contents of the JSON file will be stored in the encrypted credential store.

Configure the Admin Reports Inputs

Requires
Audit API

Each API endpoint has individual APIs that need to be enabled within https://console.developers.google.com.

For each Report that would like to be consumed, configure a new row for that report. One report per credential per row.
1. Lookback - this setting will consume that many days back from the API. This is a first-run-to-completion flag only.
2. Interval - Each report has a slightly different recommended interval.
  1. Please review https://support.google.com/a/answer/7061566 and schedule the input service interval accordingly.

Configure the Admin Usage Inputs

Requires
- Admin SDK API

GMail API (for Directory based Email Forwarding Settings Consumption)

Each API endpoint has individual APIs that need to be enabled within https://console.developers.google.com.

For each Report that would like to be consumed, configure a new row for that report. One report per credential per row.
1. Lookback - this setting will consume that many days back from the API. This is a first-run-to-completion flag only.
2. Interval - Each report has a slightly different recommended interval.
  1. Please review https://support.google.com/a/answer/7061566 and schedule the input service interval accordingly.
Usage - User, Customer, Directory
1. These should be scheduled for cron expressions to prevent massive data ingest. Typically 1 (once) per day per input.
Directory
1. If the status of email forwarding would like to be consumed, click the corresponding checkbox.
2. The forwarding address settings will be found in mail.settings.forwardingAddresses item of the directory user event.

Configure the Alert Center Inputs

Requires
Google Workspace Alert Center API

For each alert center, configure a row in the table to pull the information desired. View more information at https://developers.google.com/admin-sdk/alertcenter/reference/alert-types .

Configure Classroom Inputs

Requires
Google Classroom API

NOTE: Checking the Write Courses Data checkbox for ANY input will cause the input to write out ALL course metadata each pull. To keep the data down to a reasonable level, only configure 1 input to consume that data.
CourseIDs are a comma separated list of specific course ids. If empty, all will be consumed.
Most, if not all, of these could be fine at a 86400 interval.

Configure Big Query Inputs

Requires
BigQuery API

For GMail Headers: Documentation From Google
Fill out the fields for the project, dataset, table. If all tables are required from a single dataset, enter an asterisk. *
The Ingest Type is one of Row, Query, Time.
1. Row: is a full pull of the rows from the table. Be careful using on dynamic tables, if any rows are deleted, this will not work as expected.
2. Query: Place your SQL query in the Enrichment Field column. You can support checkpointing by using TIMESTAMP in the Query String. The timestamp is a 10 digit integer and is based on the last execution time of the input. THIS MAY INCUR COSTS.
3. Time: This is a very simple query. Uses a checkpoint time, and the “Time field” that is in the Enrichment Field ( iso_time for example). It will consume all fields and columns from the data. THIS MAY INCUR COSTS.
4. Virtual Row: is a pull of all the rows of VIEW, but checkpointed per vuew. This allows for a virtual table to be pulled while respecting the row counts of the larger table. This should be used with GMail Audit Logs. Dataset and Project required, any VIEWS will be queried and checkpointed. THIS MAY INCUR COSTS.
The Starting Index is a “first time only” setting. Consumption will start from that row line, and will be checkpointed after first run. This can also be a timestamp for Ingest Types of Time and Query (10 digit)
Highly environmentally dependent for speed of consumption. Work with max_rows setting to determine proper messages per interval. Default is 250,000.

<div class="note"> Query, Virtual Row, and Time ingest types are EXPENSIVE. I AM NOT LIABLE FOR YOUR SPENDING. Queries (on-demand) \$5 per TB The first 1 TB per month is free. </div>

Configure PubSub Inputs

Requires:

Cloud Pub/Sub API

Fill out the row with appropriate settings. Work with Max Messages to determine proper messages per interval setting for the environment.

<div class="note"> Pubsub requires the use of grpcio binaries. Only a “many linux x64” file is included with this app. Please follow these instructions if you see any errors with the search: </div>

index=_internal log_level=ERROR sourcetype=``google:workspaces:modularinput:pubsub''error_filename=``ga_pubsub.py'' | stats values(error_*) as error_* by input_guid input_name

Consult The Project Page and download the file that matches Python 3.7 and your filesystem. Download it to \$SPLUNK_HOME/etc/apps/google_workspace_for_splunk/lib
Cd to that same folder, and execute unzip -n \<package>.whl, or an equivalent command on the OS required.
This will install the .so file to the location required for the Scripts to work.

Configure Spreadsheet Inputs

Requires
- Google Drive API

Google Sheets API

Select the credential that you want to use.
Select the “Spreadsheet” dropdown. This should auto-populate with the spreadsheets that are allowed for the impersonation user configured on the credential.
Select the Sheets (multiple allowed) to consume.
Set the destination
1. KVStore
  1. Takes the sheets, and places the data into KVStore lookups.
  2. Ordered: Keeps row and column placements for a true “re-structure” of the data.
  3. UnOrdered: consumes each column as a “key value” into the lookup.
2. CSV
  1. Takes the sheets, and places the data into CSV lookups.
  2. Ordered: Keeps row and column placements for a true “re-structure” of the data.
  3. UnOrdered: consumes each column as a “key value” into the lookup.
3. Indexed
  1. Takes the contents of the sheets, and places the data into an index.

Configure Vault Inputs

TBD - maybe.

Configure Forms Inputs

Requires
Google Forms API

Scopes
- https://www.googleapis.com/auth/forms.body.readonly

Select the credential that you want to use.
Select the “Form” dropdown. This should auto-populate with the forms that are allowed for the impersonation user configured on the credential.
Set the destination
1. KVStore
  1. Takes the form data, and places the data into KVStore lookups.
  2. Ordered: Keeps row and column placements for a true “re-structure” of the data.
  3. UnOrdered: consumes each column as a “key value” into the lookup.
2. CSV
  1. Takes the form data, and places the data into CSV lookups.
  2. Ordered: Keeps row and column placements for a true “re-structure” of the data.
  3. UnOrdered: consumes each column as a “key value” into the lookup.
3. Indexed
  1. Takes the contents of the form data, and places the data into an index.

Google Workspace for Splunk

0