How to Export and Review Google Workspace Audit Logs

Summary

A practical guide to exporting Google Workspace audit logs through the Admin console or Reports API, including a Python example, access requirements, retention limits, troubleshooting, and events to review for suspicious activity.

Key points

Audit logs can be exported from Reporting → Audit and investigation or retrieved as JSON using the Admin SDK Reports API's activities.list method.
The guide provides a Python example for repeatable exports, including pagination, using a service account with domain-wide delegation.
The service account should use a read-only scope; the article cautions that domain-wide delegation is powerful and recommends protecting the key file and removing delegation when finished.
Most Workspace audit logs are retained for about six months, and newly generated events may take minutes to hours to appear.
Suggested review targets include suspicious logins, third-party OAuth grants, admin role changes, weakened 2-Step Verification settings, and Drive sharing changes.
Gmail message logs are not available through the Reports API; the article points to Email Log Search or, for eligible editions, BigQuery export.

Article Details

Defense Focus: Export and review Google Workspace audit logs to investigate sign-ins, OAuth access, administrative changes, and external sharing.
Detection Methods: Review login logs for bursts of login_failure events and suspicious_login events.
Inspect token authorize events to identify third-party apps granted scopes and assess what they can access.
Review admin logs for role assignments, user creation, and 2-Step Verification policy changes.
Check Drive access and visibility changes, especially sharing with external users or anyone with the link.
Review user_accounts events for 2-Step Verification being disabled or passwords being changed.
Data Sources: Google Workspace Login, Admin, Drive, token/OAuth, and user_accounts audit logs
Email Log Search or BigQuery export for Gmail message logs
Cloud Logging organization-level audit logs, when Workspace data is shared with Google Cloud
Defensive Actions: Export the required logs through the Admin console or Admin SDK Reports API; run exports separately for each needed applicationName.
Use a super admin or an admin role with the Reports privilege.
For repeatable exports, use only the read-only audit scope; keep the service-account key file out of shared drives and remove domain-wide delegation when finished.
Follow pagination with pageToken or list_next to avoid stopping at the first 1,000 events.
Account for event delays of minutes to hours and the approximately six-month retention period when choosing export dates.
Upload the JSONL export to LogTotal for review, as described in the article.

MITRE ATT&CK

T1078.004 · Cloud AccountsThe article says Prime Core detection rules are mapped to abuse of cloud accounts under this technique.T1114.003 · Email Forwarding RuleThe article identifies mail forwarding to outside addresses as a detection use case mapped to this technique.T1528 · Steal Application Access TokenThe article identifies malicious OAuth grants as a detection use case mapped to this technique.

Vendors

GoogleIn the Google Admin console, Reporting → Audit and investigation holds the logs (Login, Admin, Drive, OAuth and more), and each can be exported from there.

Products

BigQueryFor those, use Email Log Search in the Admin console, or the BigQuery export if your edition has it.Google CloudCan I get these logs through Google Cloud instead?Google WorkspacePrime Core has {N} detection rules for Google Workspace data, mapped to {M} MITRE ATT&CK techniques.LogTotalUpload, sanitize and review in LogTotal Prime CorePrime Core has {N} detection rules for Google Workspace data, mapped to {M} MITRE ATT&CK techniques.