Skip to content

raw-audit.md

Latest commit

 

History

History
174 lines (126 loc) · 8.4 KB

raw-audit.md

File metadata and controls

174 lines (126 loc) · 8.4 KB

gog <group> raw — Sensitive Field Audit

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.