Google Workspace Admin Security-Audit MCP

One-call security summary across all configured domains. Aggregates login_audit (account locks, suspicious logins) and drive_external_sharing (external grants, new link exposure, and ``untargeted_external_transitions`` — see that tool's docstring). ``max_pages`` / ``samples`` are passed through to the drive scan; ``max_pages`` defaults to the same page budget as the standalone tool, so both report the same counters for the same window (``samples`` defaults lower here and only trims the example lists). Per-domain ``capped`` in the summary means at least one underlying scan was partial — treat that domain's counts as lower bounds (see ``capped_events`` in the drive section for which probes were cut short). Synchronous: on a large tenant this can exceed a client's ~60s tool-call timeout. If it does, use ``daily_brief_start`` + ``daily_brief_result`` (same result, run in the background) or lower ``max_pages``.

Fetch a ``daily_brief_start`` job by id. ``status`` is ``running`` (keep polling), ``done`` (``result`` holds the full daily_brief payload), ``error`` (``error`` holds the exception type name — the message is omitted to avoid leaking internal detail), or ``unknown`` (bad/expired id).

Start a daily_brief in the background; returns immediately with a ``job_id``. Use this instead of ``daily_brief`` when the synchronous call risks the client's ~60s tool-call timeout (large tenants). Args mirror ``daily_brief``. You MUST then poll ``daily_brief_result(job_id)`` every few seconds until ``status`` is ``done`` (the full daily_brief payload is under ``result``) or ``error``. On a config error returns ``{"error": ...}``; if too many jobs are already active returns ``{"status": "rejected", ...}``.

Summarize DMARC aggregate (RUA) reports: pass/fail per domain, top reject-candidate IPs. Impersonates the domain's configured ``dmarc_rua_mailbox`` (a real user -- domain-wide delegation cannot act as a group or alias; config default ``postmaster@<domain>``), searches it for mail addressed to ``dmarc_rua_recipient`` (the ``rua=mailto:`` address published in DNS, e.g. the ``postmaster+rua@`` plus-subaddress; default: same as the mailbox), reads the aggregate reports those messages carry, and answers "how much of this domain's mail volume is passing DMARC, and if we moved the policy to ``p=reject``, what would actually get blocked?" A record counts as PASS when either its aligned DKIM or SPF check reads "pass" (DMARC's own OR semantics) — NOT when both do. A record counts as a reject candidate when it is already quarantined or rejected (a tenant already running `p=quarantine`/`p=reject` enforces this today), or when BOTH checks fail with `disposition="none"` (what a stricter policy would newly start blocking); everything else is a pass. This distinction matters a lot in practice: a large share of legitimate mail (mailing-list forwards, some relays) passes DMARC via SPF alignment alone with DKIM unaligned, so counting on DKIM alone overstates the failure rate severalfold. ``reject_candidate_ips`` (the top ``top`` per domain by volume) is where to actually look before flipping a policy to ``p=reject``: a header_from that names a SUBDOMAIN of the audited domain is governed by that subdomain's own ``sp=`` policy, not the parent's ``p=``, so it is not necessarily what a `p=reject` change on the parent would affect. Requires the ``gmail.readonly`` DWD scope — the same one ``gmail_message_trace`` needs, granted PER SERVICE ACCOUNT CLIENT ID in the Admin console (Security > API controls > Domain-wide delegation), separately from the ``admin.directory.*`` / ``admin.reports.*`` scopes the rest of this server uses. Read-only: only ``messages().list``/``messages().get``/ ``attachments().get`` against the one configured mailbox are issued — see ``DomainClient.fetch_dmarc_rua_records``. Args: hours: Lookback window. Default 72 (3 days): RUA reports typically arrive roughly daily per sending source, so a single day's window risks missing infrequent senders entirely. domain: Configured ``[domain.*]`` section to report on. Default: all configured domains. mailbox: Override the configured ``dmarc_rua_mailbox`` (the user to impersonate) for every selected domain. Set this only for an ad-hoc check against a different inbox than the one in config; unless ``recipient`` is also given, that inbox's own address is searched. Also re-enables a domain configured with ``dmarc_rua_mailbox = none`` for the duration of the call. Validated as an email-shaped address (rejected otherwise). recipient: Override the address searched for (``to:``) for every selected domain -- the ``rua=mailto:`` value in DNS when it is not the mailbox itself. Validated as an email-shaped address (rejected otherwise) before use, since it is interpolated into a Gmail search query. max_pages: Gmail ``messages().list`` pages (100 messages each) to walk per domain. ``capped=true`` in the result means more pages existed — a capped fetch UNDER-counts real report volume, not just a lower bound on some other total, since every matching message must be walked (there is no server-side aggregate to fall back on). top: How many reject-candidate source IPs to return per domain (highest volume first). The per-domain pass/quarantined/ rejected/undisposed_fail totals themselves are never truncated.

Full audit history of one Drive document: owner, ACL changes, lifecycle. The triage companion to ``drive_external_sharing``: a sharing finding names a ``doc_id``, and judging it requires who OWNS the document (an individual user vs. a shared drive completely changes the risk read) and its grant history over time. Uses a server-side ``doc_id`` filter, so the page budget is spent on this one document only. ``owner`` / ``doc_title`` are taken from the document's own events (a shared-drive-owned file reports the drive's name — not a user address — as owner). ``events`` lists ACL and lifecycle events newest-first (view/edit/download noise is counted in ``event_counts`` but not listed); ``events_truncated`` is set when more matched than ``max_events``. The ``doc_id`` filter matches at the ACTIVITY level and one activity can carry sibling events for OTHER documents (a multi-file share is one activity with one event per file) — events whose own ``doc_id`` parameter does not match (or is absent) are excluded from every output field and tallied in ``sibling_events_skipped`` instead, so a bulk action cannot contaminate this document's history or misattribute its owner. An empty result means no events in the window for the queried tenant — NOT proof the document does not exist (history older than the Reports API retention, or a document living in a different tenant, looks the same). Args: doc_id: Drive document id (from a sharing finding's ``doc_id`` field). days: How far back to scan (Reports API retains roughly 6 months). domain: Restrict to one configured domain/tenant (default: all). max_pages: Reports page cap per domain; ``capped=true`` means more existed. max_events: Cap on listed events (counts are unaffected).

Report Drive ACL grants to external targets and new link/public exposure. Counts grants whose target (``target_user`` address, or ``target_domain`` for domain-scoped grants) is outside the configured internal domains (revocations are reported separately, not as exposure) and visibility transitions into link/public access (``people_with_link`` / ``public_on_the_web``, excluding a narrowing from public down to link-only; Google's ``shared_externally`` is owner-domain relative, so external-ness is judged by the target instead). ``untargeted_external_transitions`` counts transitions into ``shared_externally`` with no target address or domain (e.g. scope became "anyone with the link" — ``target_domain: "all"`` — or an unresolved target); it is a residual bucket, not a cross-check for missed named grants, since domain-scoped grants are already classified above. ``external_samples`` / ``exposure_samples`` / ``untargeted_samples`` hold examples of each. A self-grant of ``owner`` on ``change_user_access`` /``change_acl_editors`` (a user creating their own new file — every Form/Sheet/Doc submission does this) is excluded from ``risky_visibility_events``: it always reports a visibility transition from a missing prior state, which is indistinguishable from a genuine narrow-to-wide exposure event by visibility fields alone, but is not exposure of anything pre-existing. When no ``target_user`` is named (the ``change_acl_editors`` shape), a missing target alone is not proof of creation — an admin bulk-transferring ownership of a pre-existing, already-shared file (e.g. offboarding) looks the same — so this case is corroborated against the event's own ``owner`` parameter (self-action only if ``owner`` matches the actor); if ``owner`` itself is absent the conservative default is to count it rather than risk dropping a real ownership change. This exclusion is deliberately never applied to ``change_document_access_scope``/``change_document_visibility`` (see ``SELF_CREATION_GRANT_EVENTS``) — those carry no ``target_user`` and can legitimately report ``new_value: "owner"`` for a real transition, so excluding them there would blind this tool's primary signal instead of just removing creation noise. Each audit-relevant event name is queried separately so the page budget is not consumed by view/edit noise (``change_document_visibility`` is fetched for its ``acl_events`` count only — it duplicates ``change_document_access_scope`` on this API and does not drive classification, so it cannot compensate if that probe's own fetch fails). ``capped_events`` lists event names that exceeded max_pages*1000 events; ``capped`` is also set when any probe's fetch errored outright (see ``event_errors``) — either way, treat that domain's counts as lower bounds. Narrow ``hours`` or raise ``max_pages`` for full coverage (term-time weekdays see >10k change_user_access events/day). Shared-drive caveat: a file created INSIDE a shared drive emits ``change_user_access`` events for each existing drive member (ACL propagation), so an external member merely uploading files looks like bulk external sharing here. When a finding's documents share one owner that is a drive NAME rather than a user address, triage with ``drive_doc_activity`` (per-document history: the "grants" coincide with ``create``/``upload`` by the same actor) and ``shared_drive_membership_changes`` (who added the members, and when).

Look up ONE named account's current state — the "why can't this person sign in" tool. Answers a helpdesk ticket that already names the exact address: is the account suspended (and for what reason, since when), archived, enrolled in or enforced into 2-step verification, when did it last log in, which org unit is it in, is a password change pending. One Directory API request, no pagination. Use this — not ``suspended_accounts`` — whenever the address is known. That tool lists only accounts that ARE suspended, so it can never confirm that a given address is *not* suspended, and once that list exceeds its page cap absence stops being evidence either way — after spending far more API calls than this. ``suspended_accounts`` is for the domain-wide sweep it is actually named for. This directory is downstream of the identity provider, not the master. Read the answer as "what Google Workspace currently believes about this account" and compare it against the IdP's own record, which is authoritative for who the account is. A disagreement is usually drift on this side rather than a mistyped address — an account the IdP still authenticates can be suspended or archived here, and an address the IdP does not assert at all will simply come back ``found: false``. An address that names no account returns ``found: false`` with no state fields. That is a normal, expected answer — a typo'd or long-deleted address — and is itself the diagnostic result, NOT a failure. A missing DWD scope, a rejected credential or a transient API failure is reported as ``{"error": ...}`` instead. The two are deliberately distinct: never read ``found: false`` as "the lookup did not work", and never read an ``error`` as evidence about whether the account exists. Read-only (Directory API ``users().get``; no mutating method exists in this package). Requires the ``admin.directory.user.readonly`` DWD scope — the same one ``suspended_accounts`` uses, so a tenant already running that tool needs no additional grant. Args: username: Exact user email, passed through as the Directory API ``userKey`` (primary or alias address both work on Google's side; the returned ``email`` is the account's canonical primary one). domain: Configured ``[domain.*]`` section to route the lookup through. Default: resolved from the username's suffix. Set it explicitly when the address uses an alias/secondary domain that has no config section of its own (common when copying addresses from mail headers or IdP logs).

Check whether a message (by RFC 822 Message-ID) reached specific users' mailboxes. Answers "who got this email and who didn't" for a KNOWN Message-ID and a KNOWN candidate recipient list — there is no Workspace API to search across every user for one message, so the caller supplies who to check (a mailing-list roster, or simply the people who reported a problem). For each recipient this impersonates that exact user via domain-wide delegation and searches their own mailbox (including Spam and Trash) for the Message-ID. Requires the ``gmail.readonly`` DWD scope — granted PER SERVICE ACCOUNT CLIENT ID in the Admin console (Security > API controls > Domain-wide delegation), separately from the ``admin.directory.*`` / ``admin.reports.*`` scopes the rest of this server uses, and NOT on by default. A domain missing that grant reports a per-recipient ``error`` rather than a silent "not found" — the two must never be confused, since "not found" here can also legitimately mean the message was delivered and later deleted by the user, or never delivered at all; this tool cannot tell those apart, only "a match currently exists in this mailbox" from "it doesn't". Read-only: only ``messages().list`` and ``messages().get`` (metadata only, never the message body) are issued against each impersonated mailbox — see ``DomainClient.find_message_by_id``. A per-recipient result sets ``ambiguous: true`` (with ``match_count``) when more than one message in that mailbox shares the Message-ID (e.g. a mailing-list copy plus a direct CC) — the other fields describe only the first match in that case, not a combined answer. ``match_count_capped`` is set alongside it when the mailbox has enough matches that ``match_count`` itself is a lower bound, not exact. Args: message_id: The RFC 822 Message-ID to search for, with or without angle brackets. Must be shaped like an address (``local@domain``, no whitespace) — this is validated before use, since it is interpolated into a Gmail search query. recipients: Comma- and/or whitespace-separated exact recipient email addresses to check (max 50 per call — split a larger list across multiple calls rather than expecting a partial result). domain: Configured ``[domain.*]`` section to route EVERY recipient through. Default: resolved per-recipient from their own address suffix, so one call can cover a mixed staff/student list. Set this only when recipients use an alias/secondary domain with no config section of its own.

Daily Gmail send/receive counts per domain (Admin SDK customerUsageReports). Answers "how much Gmail traffic did this domain send/receive on day X" -- a customer-level daily counter, NOT a per-user or per-message breakdown (the Reports API has no such thing; ``login_audit``'s activity stream is the per-event alternative for that, at the cost of no volume total). Each day's fetch is independent: a domain missing the DWD scope reports one whole-domain ``error`` (there is no point retrying `days` times for an identical scope failure), but a single date's fetch failing for some other reason (Google's processing for that day not finished yet is a known lag on this API family; a transient error) only skips that one date, recorded in ``date_errors`` -- the rest of the window still comes back. The per-domain result also carries ``capped`` -- true if ANY date's fetch hit the (rare, since a single day's customer report is normally one record) pagination limit -- so a truncated day's counters are never mistaken for the complete picture. Requires the ``admin.reports.usage.readonly`` DWD scope, granted PER SERVICE ACCOUNT CLIENT ID in the Admin console (Security > API controls > Domain-wide delegation) -- a DIFFERENT scope from ``admin.reports.audit.readonly`` (the one ``login_audit``, ``drive_external_sharing``, ``drive_doc_activity``, ``shared_drive_membership_changes`` and ``daily_brief`` use), even though both live under the same Admin SDK Reports API. Having one does not imply the other; grant this one separately. Read-only: only ``customerUsageReports().get()`` is issued, restricted to the two Gmail counters this tool reports via the API's own ``parameters`` filter (:data:`GMAIL_USAGE_PARAMETERS`) rather than pulling every application's counters. Args: days: How many days back to report, ending YESTERDAY (not today -- the current day's data is not final until it ends) in the Reports API's own UTC-8:00/Pacific-Standard-Time date anchor. Must be ``1..``:data:`MAX_USAGE_REPORT_DAYS` -- ``0``/negative would otherwise silently return a well-formed, error-free empty result indistinguishable from "queried correctly, zero Gmail traffic that window", and an unbounded value drives an unbounded (domain x date) fan-out (one blocking API call per task, even though they run concurrently). domain: Configured ``[domain.*]`` section to report on. Default: all configured domains.

Check a Google Group's own posting/delivery policy — why an external sender's mail never arrived. A Group's access-control layer sits IN FRONT of Gmail delivery: when ``who_can_post`` is restricted (e.g. domain-members-only), an external sender's message is rejected there and never generates a per-recipient Gmail delivery event at all — ``gmail_message_trace`` (a real mailbox) and any Reports-API-based delivery trace both see nothing for that address, indistinguishable from a genuine delivery failure without this. Use this FIRST when a group address "isn't receiving" mail from an external sender, before chasing it as a transport/spam problem. Read-only: only ``groups().get()`` is issued (Groups Settings API). Requires the ``apps.groups.settings`` DWD scope — granted PER SERVICE ACCOUNT CLIENT ID in the Admin console (Security > API controls > Domain-wide delegation), separately from every other scope this server uses, and NOT on by default. Returns ``who_can_post`` (e.g. ``ALL_IN_DOMAIN_CAN_POST`` blocks external senders entirely; ``ANYONE_CAN_POST`` allows them), ``allow_external_members``, ``is_archived``, ``message_moderation_level``, ``spam_moderation_level``, ``allow_web_posting``. Sets ``found: false`` (no policy fields) when ``group_email`` does not name any group in this domain — that is a normal, expected answer for a bad/typo'd address, not an ``error``. Args: group_email: The group's address (e.g. "[email protected]"). domain: Configured ``[domain.*]`` section to route the lookup through. Default: resolved from the address's suffix.

Report service status, version, and per-domain auth/API reachability. Always returns the same keys: status (healthy / degraded / error), service, version, config, and domains (per-domain auth result). Lightweight: one 1-item login query per domain.

List a Google Group's basic metadata and member roster (Directory API). Resolves a group's actual membership directly, independent of any specific message ever having been sent to it — unlike inferring membership from Reports API delivery-event fanout (``applicationName=gmail``), which only shows members who received one PARTICULAR message and requires one to already exist to trace. Pair with ``gmail_message_trace`` to deep-dive a specific member's mailbox once the roster is known, or with ``group_delivery_policy`` to see why the group as a whole may not be receiving mail at all. Read-only: only ``groups().get()`` and ``members().list()`` are issued (Directory API), never a mutating call. Requires the ``admin.directory.group.readonly`` and ``admin.directory.group.member.readonly`` DWD scopes — granted PER SERVICE ACCOUNT CLIENT ID in the Admin console, separately from every other scope this server uses, and NOT on by default. The two calls are independent: a tenant with only one of the two scopes granted still gets that one section, with the other reported as ``{"error": ...}`` in its place rather than failing the whole call — only when BOTH fail does the tool return a single top-level ``error``. Sets ``found: false`` (no ``group``/``members`` sections) when ``group_email`` does not name any group in this domain — a normal, expected answer for a bad/typo'd address, not an ``error``. This triggers both when BOTH calls agree with no error on either side, AND when one call CONFIRMS not-found while the other independently failed (its own error is then attached as ``group_lookup_error`` / ``members_lookup_error``) — a confirmed non-existence from one independently-scoped call is stronger evidence than an unrelated failure on the other, and must not be buried under it. Args: group_email: The group's address. domain: Configured ``[domain.*]`` section to route the lookup through. Default: resolved from the address's suffix. max_pages: Pagination cap for the member roster (Directory API hard limit 200 members per page). Default 20 (≤4,000 members) — raise for an unusually large group. ``capped: true`` means the roster is NOT the complete one — either more pages existed beyond this, or the member lookup failed outright (see ``members_error``); either way it must never be read as the full membership, and an empty ``members`` list must not be mistaken for a confirmed-empty group when ``capped`` is true.

Audit the login log: Google-auto-disabled accounts, suspicious logins, failure top-N. Answers "did Google itself decide something was wrong with an account here, and with which account?" — the question a "my mail suddenly stopped working" ticket usually turns out to be. ``account_disabled_*`` is Google reporting that it locked an account (leaked password, hijacking, spamming); ``suspicious_login`` and ``gov_attack_warning`` are warnings without a lock. In both sections ``user`` is the account the event is ABOUT, not an actor who did something: Google raised these itself, so the actor is Google and the account is read from the event's ``affected_email_address``. Treat a hit as evidence about that account, and reach for ``get_user`` next for its current state. An ``account_disabled_spamming`` entry means Google observed outbound spam, which is a compromise finding, not a delivery problem — the account was almost certainly being used by someone else. The IdP upstream is a separate system and is NOT disabled by this: an account locked here can still authenticate there until it is disabled there too. Combine with a Directory suspended-users snapshot (Phase 2) for current state. Each section carries ``capped`` (window not fully scanned) — treat counts as lower bounds then.

Membership add/remove/role-change history across shared drives. Answers "who added this (external) member, and when" — the other half of triaging a shared-drive sharing finding (see ``drive_doc_activity``). Membership changes are low-volume, so a plain window scan of the single ``shared_drive_membership_change`` event works even over months. Each entry's ``drive`` is the shared drive's NAME as the audit log reports it (the event's ``owner`` parameter — not an id, not a user address); ``target_is_external`` classifies the affected member against the configured internal domains. The Reports API cannot filter by drive server-side, so ``drive_name`` is a client-side case-insensitive substring match on that name — it narrows the listing, not the scan. An event whose drive name is absent can neither match nor be ruled out; with ``drive_name`` set such events are excluded from ``total``/``entries`` but tallied in ``missing_drive_name`` so the drop is never silent (without ``drive_name`` they are listed normally with ``drive: null``). Args: days: How far back to scan (Reports API retains roughly 6 months). domain: Restrict to one configured domain/tenant (default: all). drive_name: Only list entries whose drive name contains this substring. max_pages: Reports page cap per domain; ``capped=true`` means more existed. max_events: Cap on listed entries (``total`` counts all matches).

Snapshot of currently suspended Google Workspace accounts, per domain. A suspended-but-still-provisioned account is a common attack surface: an account disabled in Google may remain enabled in a downstream IdP (e.g. KeyCloak), where a password-spray attacker can still authenticate through it. Cross-reference this list against the IdP to find and disable such gaps. Unlike ``login_audit`` (which reports the *event* of Google disabling an account within a time window), this is current *state* — every account suspended right now, regardless of when. Read-only (Directory API ``users().list`` with ``query=isSuspended=true``). Requires the ``admin.directory.user.readonly`` DWD scope; a domain missing that grant degrades to ``{"error": ...}`` for that domain only. ``capped`` is set when ``max_pages`` was hit before the listing was exhausted. Coverage is per configured domain (Directory ``domain=`` filter), unlike the customer-wide Reports tools — every domain you want covered (e.g. a separate student domain) must have its own ``[domain.*]`` config section, or its suspended accounts are not listed. Args: domain: Restrict to one configured domain (default: all). max_pages: Page cap (500 accounts/page); ``capped=true`` means more exist.

List third-party OAuth apps one user has granted account access to. Account-compromise triage tool for the case ``login_audit`` and ``suspended_accounts`` are both blind to: a malicious app used a previously-granted OAuth token to read/delete mail or Drive files without ever generating a fresh login event. Check each entry's ``scopes`` for Gmail/Drive access on an unrecognized ``client_id``/``display_text`` — Google's own apps (e.g. iOS/Android account sync) show up too and are normal noise. Read-only (Directory API ``tokens().list``; never ``tokens().delete()``). Requires the ``admin.directory.user.security`` DWD scope — distinct from ``admin.directory.user.readonly`` used by ``suspended_accounts``; a domain missing that grant returns ``{"error": ...}``. No pagination: the API returns a user's full grant list in one response. Args: username: Exact user email, passed through as the Directory API ``userKey`` (primary or alias address both work on Google's side). domain: Configured ``[domain.*]`` section to route the lookup through. Default: resolved from the username's suffix. Set it explicitly when the address uses an alias/secondary domain that has no config section of its own (common when copying addresses from mail headers or IdP logs).