Using gcloud for Google Workspace Investigations (The Investigator’s Way)

Up until now, most Google Workspace investigations start in one of two places:

• The Admin Console

• Or Workspace APIs

  
  

Both are useful. Both have limits.

At some point though, especially in larger or more mature environments, logs don’t just live inside Workspace anymore — they’re exported into Google Cloud. And once that happens, the Admin Console alone isn’t enough.

That’s where gcloud comes in.

------------------------------------------------------------------------------------------------------

What gcloud Actually Is (And What It Isn’t)

Let’s clear this up first.

gcloud is not some hacking tool or special DFIR-only utility. It’s the official command-line interface for Google Cloud, bundled as part of the Google Cloud SDK.

Think of it as:

The terminal version of Google Cloud Console

It works on:

• Windows

• macOS

• Linux

And it’s designed for:

• Automation

• Scripting

• Command-line access to Cloud services

What it’s not designed for:

• Being embedded into applications

• Acting like a full SDK inside other tools

For investigators, that’s perfect — because we want read-only, controlled, scriptable access.

------------------------------------------------------------------------------------------------------

Why Use gcloud Instead of the Web Console?

You can view logs in the Google Cloud web UI. That works fine for quick checks.

But gcloud gives us a few big advantages:

• Better control over log extraction

• Easier time-based filtering

• Clean JSON output (huge win for DFIR)

• Works well from isolated IR workstations

• Easy to feed into tools like SOF-ELK

If you’re doing serious timeline reconstruction or long-range log analysis, gcloud is simply more practical.

----------------------------------------------------------------------------------------------------------

Authentication: Who Is gcloud Acting As?

Before gcloud can do anything, it needs an identity.

You have two main options:

1. Service Account

Good for automation, repeatable workflows, and controlled access.

2. User Account

More common during investigations, especially when speed matters.

In both cases, OAuth is used to authorize access to Google Cloud.

And here’s the key permission you need to remember:

Private Logs Viewer

----------------------------------------------------------------------------------------------------------

Why “Private Logs Viewer” Matters

Google Cloud has two commonly confused roles:

• Logs Viewer

• Private Logs Viewer

For investigations, Logs Viewer is not enough.

Private Logs Viewer gives you access to:

• Audit logs

• Logs containing IP addresses

• Sensitive user activity metadata

That’s exactly what we care about during IR.

The good news? Both roles are read-only. You cannot modify or delete logs with either.

So you get visibility without risk.

----------------------------------------------------------------------------------------------------------

Installing and Preparing gcloud

https://docs.cloud.google.com/sdk/docs/install-sdk

Once you install the gcloud CLI on your investigation host, there are three things you always need to tell it:

1. Which project you’re working in

2. Who you are (authentication)

   

3. What logs you want

Projects matter because logs live inside Google Cloud Projects, not “Workspace” directly.

Workspace just sends logs there.

----------------------------------------------------------------------------------------------------------

Logging Buckets: Where Your Logs Actually Live

In Google Cloud, logs are stored in Logging Buckets.

Buckets are not sized by data volume — they’re sized by retention days.

In almost every project, you’ll see at least:

• _Required

• _Default

Anything beyond that was created intentionally by admins.

As an investigator, one field becomes very important here:

retention_days

Because it defines:

• How far back you can go

• Whether old evidence still exists

----------------------------------------------------------------------------------------------------------

Narrowing Down to Google Workspace Logs

Not all logs in Google Cloud are Workspace logs.

So instead of searching everything, we filter by service name.

Workspace-related logs usually come from:

• admin.googleapis.com

• cloudidentity.googleapis.com

• login.googleapis.com

• oauth2.googleapis.com

This alone removes a ton of noise.

----------------------------------------------------------------------------------------------------------

Time Ranges: Never Forget This (Seriously)

This is one of those gcloud “gotchas” that burns people.

If you don’t specify a time range, gcloud will:

Return only 10 log entries

Not 10 pages. Not 10 minutes. Just 10 lines.

So every serious query must include a timestamp filter.

----------------------------------------------------------------------------------------------------------

Pulling Logs the Right Way (And Why JSON Matters)

When we extract logs, we don’t want pretty output — we want machine-consumable evidence.

That’s why we force JSON output.

Here’s what a real-world Workspace log pull looks like:

gcloud logging read "protoPayload.serviceName=(admin.googleapis.com OR cloudidentity.googleapis.com OR login.googleapis.com OR oauth2.googleapis.com) AND timestamp>=\"2026-01-01T00:00:00Z\" AND timestamp<=\"2026-01-30T00:00:00Z\"" --format=json > gws_logs_in_gcp.json

What’s happening here:

• We limit results to Workspace-related services

• We define a clear investigation window

• We output everything as JSON

• We write it to a file for offline analysis

----------------------------------------------------------------------------------------------------------

Why gcloud Is So Useful in DFIR

The real value of gcloud isn’t just “getting logs”.

It’s that you can:

• Re-run queries consistently

• Adjust time windows precisely

• Preserve raw evidence

• Avoid UI-based filtering mistakes

• Work even when the web console feels slow or limited

And once authenticated, gcloud can do anything your account is authorized to do — we just happen to care about logs.

----------------------------------------------------------------------------------------------------------

One Last Thing: Logging Out Matters

This sounds basic, but it’s important.

When you authenticate with gcloud, you’re opening an active API session.

Google Cloud has no way of knowing you’re “done” unless you explicitly log out.

From an investigation hygiene perspective:

• Always revoke or log out

• Especially on shared IR systems

• Especially after admin-level access

----------------------------------------------------------------------------------------------------------

Final Thoughts

Using gcloud for Google Workspace investigations is one of those skills that feels optional — until it suddenly isn’t.

When logs move to Google Cloud:

• The Admin Console becomes secondary

• APIs don’t always give full visibility

• CLI access becomes your best friend

----------------------------------------Dean------------------------------------------------------------