gog raw

May 4, 2026 · View on GitHub

This document records the security audit performed before shipping the gog <group> raw <id> subcommands, which dump the canonical Google API response as JSON for programmatic / LLM consumption.

Redaction rule

raw applies field-level redaction only when the user did not explicitly name a field via --fields. Rationale:

The default (implicit fields=* for Drive, or no mask for the other APIs) pulls in capability URLs and third-party–stashed metadata that callers rarely want and can leak if piped into an LLM, shared in a bug report, or committed to a repo.
When a caller writes --fields "id,name,thumbnailLink", they named thumbnailLink deliberately. Redacting a user-named field would be surprising and user-hostile.

Summary: redact what the user didn't ask for; honor what they did.

Per-endpoint Findings: Workspace Content

1. `docs.Documents.Get` — `gog docs raw`

REST ref: https://developers.google.com/docs/api/reference/rest/v1/documents/get Go type: https://pkg.go.dev/google.golang.org/api/docs/v1#Document

Field	Risk	Default handling
`inlineObjects.*.embeddedObject.imageProperties.contentUri`	Short-lived (~30 min) bearer-style authenticated image URL	Ship as-is
`inlineObjects.*.embeddedObject.imageProperties.sourceUri`	May reference private source URLs	Ship as-is

Why not redact: the Docs API has no field mask, so the principled "redact only what the user didn't name" rule has no escape hatch. These image URIs are short-lived (~30 min) and require the caller's auth anyway — substantially lower risk than Drive's thumbnailLink. The lossless guarantee is valued more than the marginal hardening.

No credentials, tokens, or OAuth metadata in the response.

2. `sheets.Spreadsheets.Get` — `gog sheets raw`

REST ref: https://developers.google.com/sheets/api/reference/rest/v4/spreadsheets/get Go type: https://pkg.go.dev/google.golang.org/api/sheets/v4#Spreadsheet

Field	Risk	Default handling
`developerMetadata`	Third-party apps may stash arbitrary KV including secrets	Warn on stderr if present, do not redact
`sheets[].data.rowData.values[].userEnteredValue.formulaValue` (only with `--include-grid-data`)	Formulas can embed API keys via `IMPORTRANGE`, hardcoded tokens in cells	Warn on stderr when `--include-grid-data` is set, do not redact

--include-grid-data is off by default because grid payloads can be multi-MB and are the primary leakage vector.

No redaction applied to Sheets output; warnings only. Redacting cell content would defeat the purpose of a lossless dump.

3. `slides.Presentations.Get` — `gog slides raw`

REST ref: https://developers.google.com/slides/api/reference/rest/v1/presentations/get Go type: https://pkg.go.dev/google.golang.org/api/slides/v1#Presentation

Field	Risk	Default handling
`slides[].pageElements[].image.contentUrl`	Short-lived authenticated image URL (same class as Docs `contentUri`)	Ship as-is
`slides[].pageElements[].image.sourceUrl`	Possibly private origin URL	Ship as-is
`slides[].pageElements[].video.url`	Drive video refs may carry signed access	Ship as-is

Same rationale as Docs: no field mask, short-lived URLs, auth-gated, lower risk than Drive. Lossless guarantee preferred.

4. `drive.Files.Get` with `fields=` — `gog drive raw` (highest risk)*

REST ref: https://developers.google.com/drive/api/reference/rest/v3/files/get Go type: https://pkg.go.dev/google.golang.org/api/drive/v3#File

Field	Risk	Default handling
`thumbnailLink`	Time-limited signed URL that bypasses normal auth for ~hours. Classic leak vector.	Redact
`webContentLink`	Direct download URL; capability URL	Redact
`exportLinks`	Per-MIME authenticated export URLs	Redact
`resourceKey`	Capability token for link-shared files; effectively a shared secret	Redact
`appProperties`	Arbitrary app-stashed KV; apps commonly misuse for secrets	Redact
`properties`	Public custom properties, still frequently (mis)used for tokens	Redact
`contentHints.thumbnail.image`	Base64 thumbnail bytes; large and unnecessary	Redact
`permissions[].emailAddress`, `owners[].emailAddress`, `sharingUser`, `lastModifyingUser`, `trashingUser`	Non-collaborator emails (PII) when `fields=*` enumerates full ACL	Not redacted — caller already has access to the file; enumeration is a conscious `--fields` choice

Reminder: all of the above are redacted only when --fields is not set. Passing --fields "id,name,thumbnailLink" returns thumbnailLink verbatim — the user named it.

Per-endpoint Findings: Other Services

5. `gmail.Users.Messages.Get` — `gog gmail raw`

REST ref: https://developers.google.com/gmail/api/reference/rest/v1/users.messages/get Go type: https://pkg.go.dev/google.golang.org/api/gmail/v1#Message

The subcommand name "raw" collides with Gmail's native format=raw (base64url-encoded RFC822 blob). gog gmail raw defaults to format=FULL (full parsed Message struct) and exposes --format full|metadata|minimal|raw for users who want Gmail's RAW. Help text documents both senses.

Field	Risk	Default handling
`payload.body.data` (base64url)	Email body; user already has read access	Ship as-is
`payload.headers`	May contain `Received-SPF`, `DKIM-Signature`, routing metadata	Ship as-is
`raw` (when `--format=raw`)	Full RFC822 source including original attachments	Ship as-is — user asked for it

No credential leakage risk. Caller already holds the Gmail scope.

6. `calendar.Events.Get` — `gog calendar raw`

REST ref: https://developers.google.com/calendar/api/v3/reference/events/get Go type: https://pkg.go.dev/google.golang.org/api/calendar/v3#Event

Field	Risk	Default handling
`attendees[].email`	Attendee emails (PII)	Ship as-is — caller already on the event ACL
`conferenceData.entryPoints[].uri`	Meeting URLs (Meet/Zoom) including passwords in params	Ship as-is — user asked for the event
`extendedProperties.private` / `extendedProperties.shared`	App-stashed KV; third-party apps may use for secrets	Ship as-is (same rationale as Sheets `developerMetadata`)

No redaction. The risk surface here is fundamentally the same as simply reading the event in the Calendar UI.

7. `people.People.Get` — `gog people raw` / `gog contacts raw`

REST ref: https://developers.google.com/people/api/rest/v1/people/get Go type: https://pkg.go.dev/google.golang.org/api/people/v1#Person

Both gog people raw and gog contacts raw call the same underlying people.Get endpoint. Requires --person-fields (Google's field mask for the People API, required on every request).

Field	Risk	Default handling
`emailAddresses`, `phoneNumbers`, `addresses`, `biographies`	PII; user's own contacts	Ship as-is
`userDefined[]`	Arbitrary KV custom fields; may store secrets	Ship as-is
`metadata.sources[].profileMetadata.userTypes`	Account type disclosure	Ship as-is

8. `tasks.Tasks.Get` — `gog tasks raw`

REST ref: https://developers.google.com/tasks/reference/rest/v1/tasks/get Go type: https://pkg.go.dev/google.golang.org/api/tasks/v1#Task

Field	Risk	Default handling
`notes`	User-entered free text	Ship as-is
`links[].link`	External URLs attached to a task	Ship as-is

No sensitivity concerns beyond the caller's own task data.

9. `forms.Forms.Get` — `gog forms raw`

REST ref: https://developers.google.com/forms/api/reference/rest/v1/forms/get Go type: https://pkg.go.dev/google.golang.org/api/forms/v1#Form

Field	Risk	Default handling
`items[].questionItem.question.grading`	Correct answers for graded forms	Ship as-is — caller is the form owner
`linkedSheetId`	ID of the responses spreadsheet	Ship as-is

No redaction. The form owner already has access to everything here.

Cross-cutting observations

Google APIs never return OAuth access tokens, refresh tokens, or client secrets in resource responses. The risk is capability URLs and app-stashed custom metadata, not credential disclosure in the API contract itself.
gog drive raw is the most dangerous command; the others are modest in comparison.
This audit covers all currently shipped raw subcommands.