gwsadm-mcp: Instructions file for Claude Code

CLAUDE.md

Overview

MCP (Model Context Protocol) server for Google Workspace security auditing. Exposes login_audit (Google-side account locks, suspicious logins), gmail_usage_report (daily Gmail send/receive counts per domain via Reports API customerUsageReports, one date at a time ending yesterday in the API's own UTC-8:00/PST anchor -- requires the separate admin.reports.usage.readonly DWD scope, a DIFFERENT grant from admin.reports.audit.readonly despite both being Reports API), suspended_accounts (current suspended-account snapshot), get_user (one named account's state — suspended/archived/2SV/last login — via users().get, on the same admin.directory.user.readonly scope suspended_accounts uses; a 404 answers found: false, never an error), user_oauth_tokens (one user's third-party OAuth app grants), admin_actions (Reports API applicationName=admin: what administrators did to one user or group via server-side USER_EMAIL / GROUP_EMAIL filters on the target's domain, or tenant-wide; same admin.reports.audit.readonly scope), workspace_status (Google's public Workspace status feed, no credential: open incidents and those ended within the window), user_activity (one account's activity merged across Reports API applications via userKey=<username>, newest first, with the posture-changing events — 2SV enrol/disable, recovery changes, password change, outbound forwarding, risky_sensitive_action_*, OAuth authorize — surfaced as flags and the distinct source addresses as ips; Google's own account_disabled_* / suspicious_* verdicts are NOT served under the account's userKey — verified live — so they are fetched per event name with userKey=all and matched on affected_email_address, reported under the synthetic application login_verdicts), ip_activity (every account one source address acted as, per domain, via actorIpAddress; both on the same admin.reports.audit.readonly scope and the same activities().list call as login_audit), drive_external_sharing (ACL grants to external targets, new link/public exposure), drive_doc_activity (one document's owner + ACL/lifecycle history via a server-side doc_id filter), shared_drive_membership_changes (shared-drive member add/remove/role history), gmail_message_trace (did a known Message-ID reach specific mailboxes, and where — Gmail API, requires the separate gmail.readonly DWD scope, see its docstring), dmarc_rua_summary (DMARC aggregate/RUA report pass/fail summary and top reject-candidate source IPs, per domain — Gmail API against the domain's configured dmarc_rua_mailbox, shares gmail_message_trace's gmail.readonly DWD scope but reads attachment content, not just metadata), group_delivery_policy (a Google Group's own posting/delivery policy — Groups Settings API, requires the separate apps.groups.settings DWD scope), list_group_members (a Google Group's metadata + member roster — Directory API, requires the separate admin.directory.group.readonly and admin.directory.group.member.readonly DWD scopes), compromise_sweep (the post-compromise follow-through for one account: user_activity + get_user + user_oauth_tokens + ip_activity for the attacker's addresses + the Gmail settings an attacker leaves behind — Gmail API users.settings.getAutoForwarding / forwardingAddresses.list / filters.list / delegates.list / sendAs.list, all served by the gmail.readonly DWD scope, verified live — and the sent-mail envelope, messages().list + messages().get(format="metadata") with To/Cc/Bcc/Date only; its gmail.kind distinguishes ok / partial / api_disabled (HTTP 403 accessNotConfigured: the Gmail API is off in the key's own Cloud project, GwsApiDisabledError) / no_grant / error), and a daily_brief combining the Reports-based tools, to AI assistants via STDIO transport, built on the official mcp Python SDK's MCPServer. Read-only (the one request without a credential is workspace_status's GET of https://www.google.com/appsstatus/dashboard/incidents.json): the only Admin SDK / Groups Settings / Gmail API methods called anywhere in this package are activities().list (Reports API), customerUsageReports().get() (Reports API, for gmail_usage_report -- same discovery document as activities().list but a DIFFERENT DWD scope), users().list (Directory API, for suspended_accounts), users().get (Directory API, for get_user), tokens().list (Directory API, for user_oauth_tokens), groups().get / members().list (Directory API, for list_group_members), groups().get (Groups Settings API, for group_delivery_policy), messages().list / messages().get (Gmail API, format="metadata" only, for gmail_message_trace), and messages().list / messages().get (format="full") / messages().attachments().get() (Gmail API, for dmarc_rua_summary -- this one DOES read message/attachment content, not just metadata, since a DMARC report's data lives in its attachment), the Gmail settings reads users().settings().getAutoForwarding() / .forwardingAddresses().list() / .filters().list() / .delegates().list() / .sendAs().list() plus messages().list / messages().get (format="metadata", To/Cc/Bcc/Date headers only) for compromise_sweep, and users().getProfile() for the health_check Gmail probe — all read-only. The one exception is users().signOut() (Directory API, admin.directory.user.security scope; the tool's preflight users().get additionally needs admin.directory.user.readonly), issued only by sign_out_user, a state-changing tool registered only when GWSADM_ENABLE_SIGN_OUT is exactly 1 (the flag is re-checked inside the tool). It is never on by default: a deployment that sets the flag owns the approval step in front of each call. Keep it the only mutating call. Its outcome is tri-state, carried by exception type from the client: success (signed_out: true), GwsWriteRefused / GwsAuthError (definite refusal, nothing changed: false) and GwsWriteUnknown (the POST was or may have been sent with no definite answer: null). The whole tool runs under one GWSADM_SIGN_OUT_DEADLINE_SECONDS budget (default 45): get_user and _execute accept a deadline, and no request starts with less than _MIN_REQUEST_SECONDS left. Address-to-client routing for the per-account tools goes through _resolve_user_client (strict=True for sign-out: the address's own domain must be configured and an explicit domain must match). The underlying googleapiclient.discovery.build() setup call also fetches Google's discovery document over HTTP, separately from this guarantee.