Gws Skill

Google Workspace admin and investigation tool via service account + domain-wide delegation. Covers Vault (eDiscovery email search), Gmail (read any inbox), Directory (users/groups/OUs), Reports (audit logs, logins, Drive activity), Drive (file search), Calendar (events), Sheets (read data), Docs (read content), and People (contacts/directory). Use when querying any user's email, searching org-wide email content, checking login activity, listing users/groups, reading Drive files, viewing calendars, or pulling spreadsheet/doc data across a Google Workspace domain.

Unified Google Workspace admin and investigation tool. All scripts in scripts/ relative to this file.

Security

• Never log, echo, or output credentials — service account key and tokens stay in memory only
• Never send raw email body content to chat unprompted — always summarize unless explicitly asked for full content
• Impersonation is logged — every DWD call specifies which account is being impersonated
• Read-only access — no write scopes are granted; cannot send email, create events, or modify files
• Credential storage — service account key at ~/.config/gws/service-account.json (chmod 600, outside any repo)
• No secrets in code — key path loaded from env var GWS_SERVICE_ACCOUNT_PATH or default path

Auth

All scripts use scripts/auth.py — loads service account key and impersonates users via domain-wide delegation.

• Default admin: configured via GWS_ADMIN_EMAIL env var
• Domain: configured via GWS_DOMAIN env var
• Impersonate another user: pass their email to --user flag

Scripts

vault.py — Email Investigation (org-wide content search)

Search anyone's email content. Creates temporary matter → runs query → returns results → auto-deletes matter.

bash

python3 scripts/vault.py --accounts [e-mail] --terms "from:[e-mail]" --start "2026-03-01T00:00:00Z" --end "2026-03-26T23:59:59Z"
python3 scripts/vault.py --org-unit <orgUnitId> --terms "subject:confidential"
python3 scripts/vault.py --accounts [e-mail] --terms "from:[e-mail]" --export

Search terms use Gmail operators: from:, to:, subject:, has:attachment, filename:, newer_than:, older_than:, etc.

gmail.py — Read Any User's Inbox

bash

# Metadata summary
python3 scripts/gmail.py --user [e-mail] --query "from:acme.com newer_than:7d" --max 10 --mode summary
# Full email body
python3 scripts/gmail.py --user [e-mail] --query "from:acme.com" --max 5 --mode full
# Single message by ID
python3 scripts/gmail.py --user [e-mail] --query "" --mode read --message-id <id>

Investigation workflow: Vault count → Gmail summary → Gmail full content.

directory.py — Users, Groups, OUs

bash

python3 scripts/directory.py users [--query "name:Jared"] [--max 100]
python3 scripts/directory.py user [e-mail]
python3 scripts/directory.py groups
python3 scripts/directory.py members [e-mail]
python3 scripts/directory.py orgunits

reports.py — Audit Logs & Activity

bash

python3 scripts/reports.py login [--user [e-mail]] [--event login_failure] [--start ISO] [--end ISO]
python3 scripts/reports.py admin [--max 25]
python3 scripts/reports.py drive [--user [e-mail]]
python3 scripts/reports.py token [--user [e-mail]]
python3 scripts/reports.py gmail [--user [e-mail]]

drive.py — Search & Read Files

bash

python3 scripts/drive.py search --user [e-mail] --query "name contains 'invoice'"
python3 scripts/drive.py recent --user [e-mail]
python3 scripts/drive.py file --user [e-mail] --id <fileId>
python3 scripts/drive.py shared --user [e-mail]
python3 scripts/drive.py type --user [e-mail] --type sheet

gcalendar.py — Read Calendars

bash

python3 scripts/gcalendar.py today --user [e-mail]
python3 scripts/gcalendar.py tomorrow --user [e-mail]
python3 scripts/gcalendar.py events --user [e-mail] --start ISO --end ISO [--query "meeting"]
python3 scripts/gcalendar.py calendars --user [e-mail]

sheets.py — Read Spreadsheets

bash

python3 scripts/sheets.py metadata --user [e-mail] --id <spreadsheetId>
python3 scripts/sheets.py get --user [e-mail] --id <spreadsheetId> --range "Sheet1!A1:D10"
python3 scripts/sheets.py batch --user [e-mail] --id <spreadsheetId> --ranges "Sheet1!A1:B5" "Sheet2!A1:C3"

docs.py — Read Documents

bash

python3 scripts/docs.py get --user [e-mail] --id <documentId>
python3 scripts/docs.py text --user [e-mail] --id <documentId>

people.py — Contacts & Org Directory

bash

python3 scripts/people.py contacts --user [e-mail]
python3 scripts/people.py search --user [e-mail] --query "John"
python3 scripts/people.py directory --user [e-mail] --query "manager"

Setup

See references/setup-checklist.md for one-time GCP + Google Admin configuration steps.