Description

Google Workspace admin and investigation tool via service account + domain-wide delegation. Covers Vault (eDiscovery email search), Gmail (read any inbox), D...

README (SKILL.md)

\r \r

GWS Skill\r

Name: Gws Skill
Author: jmac122

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

Security\r

\r

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

Auth\r

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

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

Scripts\r

\r

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

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

python3 scripts/vault.py --accounts [email protected] --terms "from:[email protected]" --start "2026-03-01T00:00:00Z" --end "2026-03-26T23:59:59Z"\r
python3 scripts/vault.py --org-unit \x3CorgUnitId> --terms "subject:confidential"\r
python3 scripts/vault.py --accounts [email protected] --terms "from:[email protected]" --export\r
```\r
\r
Search terms use Gmail operators: `from:`, `to:`, `subject:`, `has:attachment`, `filename:`, `newer_than:`, `older_than:`, etc.\r
\r
### gmail.py — Read Any User's Inbox\r
\r
```bash\r
# Metadata summary\r
python3 scripts/gmail.py --user [email protected] --query "from:acme.com newer_than:7d" --max 10 --mode summary\r
# Full email body\r
python3 scripts/gmail.py --user [email protected] --query "from:acme.com" --max 5 --mode full\r
# Single message by ID\r
python3 scripts/gmail.py --user [email protected] --query "" --mode read --message-id \x3Cid>\r
```\r
\r
**Investigation workflow:** Vault count → Gmail summary → Gmail full content.\r
\r
### directory.py — Users, Groups, OUs\r
\r
```bash\r
python3 scripts/directory.py users [--query "name:Jared"] [--max 100]\r
python3 scripts/directory.py user [email protected]\r
python3 scripts/directory.py groups\r
python3 scripts/directory.py members [email protected]\r
python3 scripts/directory.py orgunits\r
```\r
\r
### reports.py — Audit Logs & Activity\r
\r
```bash\r
python3 scripts/reports.py login [--user [email protected]] [--event login_failure] [--start ISO] [--end ISO]\r
python3 scripts/reports.py admin [--max 25]\r
python3 scripts/reports.py drive [--user [email protected]]\r
python3 scripts/reports.py token [--user [email protected]]\r
python3 scripts/reports.py gmail [--user [email protected]]\r
```\r
\r
### drive.py — Search & Read Files\r
\r
```bash\r
python3 scripts/drive.py search --user [email protected] --query "name contains 'invoice'"\r
python3 scripts/drive.py recent --user [email protected]\r
python3 scripts/drive.py file --user [email protected] --id \x3CfileId>\r
python3 scripts/drive.py shared --user [email protected]\r
python3 scripts/drive.py type --user [email protected] --type sheet\r
```\r
\r
### gcalendar.py — Read Calendars\r
\r
```bash\r
python3 scripts/gcalendar.py today --user [email protected]\r
python3 scripts/gcalendar.py tomorrow --user [email protected]\r
python3 scripts/gcalendar.py events --user [email protected] --start ISO --end ISO [--query "meeting"]\r
python3 scripts/gcalendar.py calendars --user [email protected]\r
```\r
\r
### sheets.py — Read Spreadsheets\r
\r
```bash\r
python3 scripts/sheets.py metadata --user [email protected] --id \x3CspreadsheetId>\r
python3 scripts/sheets.py get --user [email protected] --id \x3CspreadsheetId> --range "Sheet1!A1:D10"\r
python3 scripts/sheets.py batch --user [email protected] --id \x3CspreadsheetId> --ranges "Sheet1!A1:B5" "Sheet2!A1:C3"\r
```\r
\r
### docs.py — Read Documents\r
\r
```bash\r
python3 scripts/docs.py get --user [email protected] --id \x3CdocumentId>\r
python3 scripts/docs.py text --user [email protected] --id \x3CdocumentId>\r
```\r
\r
### people.py — Contacts & Org Directory\r
\r
```bash\r
python3 scripts/people.py contacts --user [email protected]\r
python3 scripts/people.py search --user [email protected] --query "John"\r
python3 scripts/people.py directory --user [email protected] --query "manager"\r
```\r
\r
## Setup\r
\r
See `references/setup-checklist.md` for one-time GCP + Google Admin configuration steps.\r

Usage Guidance

This skill legitimately needs a Google service account JSON key with domain‑wide delegation and an admin email — that key grants the ability to read any user's email, Drive, calendar, etc., so only install and run it in a trusted admin environment. Before installing: (1) Verify you trust the publisher and review the repository on the provided homepage; (2) Ensure the service account was created for this purpose, authorized in Admin Console with only the scopes you expect, and that you store the JSON key securely (chmod 600, limited access); (3) Limit who can invoke the skill and consider not allowing autonomous/unsupervised runs in environments where sensitive data may be exposed; (4) Audit access logs in Google Admin for impersonation activity and rotate/revoke the key if needed; (5) If you have compliance concerns, run the scripts in an isolated environment and review output handling to ensure raw message bodies or attachments are not forwarded outside approved channels.

Capability Analysis

Type: OpenClaw Skill Name: gws-dwd Version: 1.0.1 This bundle provides a comprehensive suite of tools for Google Workspace administration and eDiscovery, utilizing Domain-Wide Delegation (DWD) to impersonate any user in a domain. While the scripts (e.g., scripts/vault.py, scripts/gmail.py, scripts/auth.py) are well-documented, use standard Google API libraries, and align perfectly with the stated purpose of an investigation tool, the bundle is classified as suspicious due to the extremely broad permissions and high-risk capabilities inherent in its design. The tool grants the ability to read any user's email, search org-wide content via Vault, and access private Drive files. No evidence of malicious intent, such as hidden data exfiltration, backdoors, or prompt injection, was found in the code or SKILL.md instructions.

Capability Assessment

✓ Purpose & Capability

Name/description (GWS admin/investigation via service account + DWD) lines up with requested binaries (python3), env vars (service account path, admin email, domain), and the included scripts (vault, gmail, drive, directory, reports, calendar, sheets, docs, people). The requested items are appropriate for the declared purpose.

✓ Instruction Scope

SKILL.md and the scripts only instruct the agent/operator to use the provided Python scripts to call Google Workspace APIs and to impersonate users via domain‑wide delegation. The README explicitly warns about handling raw email content and credentials. There are no instructions to read unrelated system files or to send data to third‑party endpoints.

✓ Install Mechanism

No remote download/install spec is present; this is an instruction + script bundle that requires pip packages from PyPI (google-auth, google-api-python-client) — expected for Google API clients. Nothing is fetched from an untrusted URL or extracted to arbitrary locations.

ℹ Credentials

The skill requires a service account JSON key with domain‑wide delegation, an admin email, and domain — these are powerful credentials (they allow reading any user's data) but are exactly what a domain‑wide admin/investigation tool legitimately needs. Treat the key as highly sensitive and limit who can provide it. Declared scopes are read‑only, matching the stated intent.

✓ Persistence & Privilege

always is false and the skill does not request elevated platform privileges or modify other skills. It does suggest a default local key path (~/.config/gws/service-account.json) but does not persist or self‑enable itself beyond reading that file if present.

Version History

v1.0.1

Declare required env vars, credentials, and provenance in metadata

v1.0.0

Initial release of unified Google Workspace admin and investigation tool. - Provides read-only scripts for Vault, Gmail, Directory, Reports, Drive, Calendar, Sheets, Docs, and People APIs using service account and domain-wide delegation. - Allows searching and investigating any user's data across your Google Workspace domain. - Security-first: never outputs credentials, logs all impersonation, and limits access to read-only. - Scripts organized for email investigation, audit logs, file/content access, and organization directory queries. - Configuration and setup instructions included for secure deployment.

Metadata

Slug gws-dwd

Version 1.0.1

License MIT-0

All-time Installs 0

Active Installs 0

Total Versions 2

Frequently Asked Questions

What is Gws Skill?

Google Workspace admin and investigation tool via service account + domain-wide delegation. Covers Vault (eDiscovery email search), Gmail (read any inbox), D... It is an AI Agent Skill for Claude Code / OpenClaw, with 116 downloads so far.

How do I install Gws Skill?

Run "/install gws-dwd" in the OpenClaw or Claude Code chat to install it in one step — no extra setup required.

Is Gws Skill free?

Yes, Gws Skill is completely free, licensed under MIT-0. You can download, install and use it at no cost.

Which platforms does Gws Skill support?

Gws Skill is cross-platform and runs anywhere OpenClaw / Claude Code is available (cross-platform).

Who created Gws Skill?

It is built and maintained by jmac122 (@jmac122); the current version is v1.0.1.

More Skills

Gws Skill