Skip to content

armgit / AiSOC

Public Imported from GitHub
0

Open-source AI Security Operations Center: alert fusion, LLM-agent triage, MITRE ATT&CK investigation, and a replayable decision ledger for every agent step. Self-hostable, runs with no API keys, MIT licensed. Ships an MCP server for Claude, Cursor and Continue.

13.6 KB
Raw Blame
"""Gmail client — reported-phish remediation across Workspace mailboxes.

Beside :mod:`app.clients.google_workspace_client` rather than inside it, and
the reason is structural rather than tidiness. That client holds **one**
delegated subject for its whole lifetime, because the Admin SDK acts on the
directory and one admin subject covers every user in it. Gmail does not work
that way: under domain-wide delegation the mailbox you may touch is the one
named in the JWT's ``sub`` claim, so acting on twenty-five recipients means
twenty-five tokens. Reusing the existing client would have meant constructing
twenty-five of it, or silently acting on the wrong mailbox.

Verbs, all documented by the Gmail API
--------------------------------------
* search    — ``GET users/{mailbox}/messages?q=rfc822msgid:<id>``
* read      — ``GET users/{mailbox}/messages/{id}?format=metadata``
* trash     — ``POST users/{mailbox}/messages/{id}/trash``
* untrash   — ``POST users/{mailbox}/messages/{id}/untrash``
* filters   — ``POST`` / ``DELETE users/{mailbox}/settings/filters``

Trash is the Workspace half of ``purge_email`` and untrash is its reverse,
exactly as the plan specifies. A trashed message is recoverable for 30 days;
``users.messages.delete`` is permanent, has no reverse, and is deliberately
absent.

As on Microsoft, the sender block is a **per-mailbox** filter. Workspace's
domain-level blocked-sender list lives in Admin console email settings, which
the Admin SDK does not expose, so the organisation-wide verb is not declared.

Scopes the service account needs, granted domain-wide:

* ``https://www.googleapis.com/auth/gmail.modify``         — trash, untrash
* ``https://www.googleapis.com/auth/gmail.settings.basic`` — filters
* ``https://www.googleapis.com/auth/gmail.readonly``       — search, read

Credentials expected in ``LiveActionRequest.params``:

* ``gws_service_account_key`` — the JSON key, as a string or an object
* ``gws_subject_email``       — fallback mailbox when the caller names none,
  normally the report mailbox the poller reads
"""

from __future__ import annotations

import base64
import json
import time
from typing import Any
from urllib.parse import quote

import httpx
import structlog

logger = structlog.get_logger()

_TOKEN_URI = "https://oauth2.googleapis.com/token"
_GMAIL = "https://gmail.googleapis.com/gmail/v1"

_SCOPES = " ".join(
    [
        "https://www.googleapis.com/auth/gmail.readonly",
        "https://www.googleapis.com/auth/gmail.modify",
        "https://www.googleapis.com/auth/gmail.settings.basic",
    ]
)

#: Headers the intake path needs. Gmail returns only what you ask for in
#: ``metadataHeaders``, so a header omitted here is a header the analysis
#: cannot recover later — the field is not merely unparsed, it was never
#: fetched.
METADATA_HEADERS = (
    "Message-ID",
    "From",
    "Sender",
    "Reply-To",
    "Return-Path",
    "To",
    "Cc",
    "Subject",
    "Date",
    "Received",
    "Received-SPF",
    "Authentication-Results",
    "ARC-Authentication-Results",
    "DKIM-Signature",
)


def quote_gmail_query_value(value: str) -> str:
    """Make an attacker-supplied value safe inside a Gmail ``q=`` expression.

    Gmail's search grammar is whitespace-separated operators, so a raw value
    containing a space, a quote or a colon can close one term and open
    another: ``rfc822msgid:x in:anywhere from:ceo@`` searches for something
    nobody asked for. Every value here comes off a message a stranger sent.

    The refusal is deliberate and follows the osquery lesson: a denylist of
    dangerous characters is the wrong control, and an escaped value that
    reaches the API and matches nothing reports a clean result from a query
    that never ran. So the dangerous shape is made unrepresentable — the value
    is restricted to the characters a message id or an address can contain,
    and anything else raises.
    """
    cleaned = str(value).strip().strip("<>")
    if not cleaned:
        raise ValueError("empty Gmail query value")
    allowed = set("abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789.@_-+=/")
    bad = sorted({ch for ch in cleaned if ch not in allowed})
    if bad:
        raise ValueError(f"value is not a message id or an address; refusing rather than escaping (disallowed: {bad!r})")
    return cleaned


class GmailClient:
    """Async Gmail wrapper that mints one delegated token per mailbox.

    Tokens are cached per mailbox for their lifetime less a safety margin, so
    a 25-recipient purge mints 25 tokens once rather than 50 times.
    """

    def __init__(self, service_account_key: str | dict, subject_email: str = "", *, timeout: float = 30.0) -> None:
        if isinstance(service_account_key, str):
            try:
                service_account_key = json.loads(service_account_key)
            except json.JSONDecodeError as exc:
                raise ValueError(f"gws_service_account_key is not valid JSON: {exc}") from exc
        if not isinstance(service_account_key, dict):
            raise ValueError(f"gws_service_account_key must be a JSON object, got {type(service_account_key).__name__}")
        self._key: dict[str, Any] = service_account_key
        self._default_subject = subject_email
        self._timeout = timeout
        #: mailbox -> (access token, expiry epoch seconds)
        self._tokens: dict[str, tuple[str, float]] = {}

    def _subject_for(self, mailbox: str) -> str:
        subject = (mailbox or self._default_subject or "").strip()
        if not subject:
            raise ValueError("Gmail calls need a mailbox: domain-wide delegation impersonates exactly one user per token")
        return subject

    async def _mint_token(self, client: httpx.AsyncClient, subject: str) -> str:
        """Sign a delegated JWT for ``subject`` and exchange it for a token.

        Signed inline for the same reason the Workspace client does it: the
        claim set is fixed and pulling in ``google-auth`` for one RSA-SHA256
        signature is not worth the dependency.
        """
        from cryptography.hazmat.primitives import hashes, serialization
        from cryptography.hazmat.primitives.asymmetric import padding

        now = int(time.time())
        header = {"alg": "RS256", "typ": "JWT"}
        claims = {
            "iss": self._key["client_email"],
            "sub": subject,
            "scope": _SCOPES,
            "aud": _TOKEN_URI,
            "iat": now,
            "exp": now + 3600,
        }

        def _b64(blob: dict) -> str:
            return base64.urlsafe_b64encode(json.dumps(blob, separators=(",", ":")).encode()).rstrip(b"=").decode()

        signing_input = f"{_b64(header)}.{_b64(claims)}".encode()
        private_key = serialization.load_pem_private_key(self._key["private_key"].encode(), password=None)
        signature = private_key.sign(signing_input, padding.PKCS1v15(), hashes.SHA256())
        jwt_str = f"{signing_input.decode()}.{base64.urlsafe_b64encode(signature).rstrip(b'=').decode()}"

        resp = await client.post(
            _TOKEN_URI,
            data={"grant_type": "urn:ietf:params:oauth:grant-type:jwt-bearer", "assertion": jwt_str},
        )
        resp.raise_for_status()
        body = resp.json()
        token = str(body["access_token"])
        self._tokens[subject] = (token, time.time() + int(body.get("expires_in", 3600)) - 60)
        return token

    async def _headers_for(self, client: httpx.AsyncClient, mailbox: str) -> dict[str, str]:
        subject = self._subject_for(mailbox)
        cached = self._tokens.get(subject)
        token = cached[0] if cached and time.time() < cached[1] else await self._mint_token(client, subject)
        return {"Authorization": f"Bearer {token}", "Content-Type": "application/json"}

    @staticmethod
    def _path(mailbox: str, suffix: str) -> str:
        return f"{_GMAIL}/users/{quote(mailbox, safe='')}/{suffix}"

    # ── Reads ────────────────────────────────────────────────────────────

    async def search_messages(
        self,
        mailbox: str,
        *,
        internet_message_id: str = "",
        sender: str = "",
        after_epoch_seconds: int = 0,
        limit: int = 25,
    ) -> list[dict[str, Any]]:
        """Return ``{id, threadId}`` for each match. Terms combine with AND.

        At least one of the message id or the sender is required. An unfiltered
        mailbox listing is a different operation from finding one reported
        message and is not what this is for.
        """
        terms: list[str] = []
        if internet_message_id:
            terms.append(f"rfc822msgid:{quote_gmail_query_value(internet_message_id)}")
        if sender:
            terms.append(f"from:{quote_gmail_query_value(sender)}")
        if not terms:
            raise ValueError("search_messages needs an internet_message_id or a sender")
        if after_epoch_seconds > 0:
            # `after:` takes a bare epoch; it is generated here and never
            # caller-supplied, so there is no value to sanitise.
            terms.append(f"after:{int(after_epoch_seconds)}")

        async with httpx.AsyncClient(timeout=self._timeout) as client:
            headers = await self._headers_for(client, mailbox)
            resp = await client.get(
                self._path(self._subject_for(mailbox), "messages"),
                headers=headers,
                params={
                    "q": " ".join(terms),
                    "maxResults": str(max(1, min(int(limit), 100))),
                    "includeSpamTrash": "true",
                },
            )
            resp.raise_for_status()
            return list(resp.json().get("messages") or [])

    async def get_message(self, mailbox: str, message_id: str) -> dict[str, Any]:
        """Metadata and headers only. The body is never fetched.

        ``format=metadata`` is a deliberate ceiling: the intake path runs
        unattended against every reported message, and pulling message bodies
        out of a customer's tenant into AiSOC's database is a disclosure
        nobody asked for. Headers are what the analysis needs.
        """
        async with httpx.AsyncClient(timeout=self._timeout) as client:
            headers = await self._headers_for(client, mailbox)
            resp = await client.get(
                self._path(self._subject_for(mailbox), f"messages/{quote(message_id, safe='')}"),
                headers=headers,
                params=[("format", "metadata"), *[("metadataHeaders", h) for h in METADATA_HEADERS]],
            )
            resp.raise_for_status()
            return dict(resp.json())

    async def list_messages_with_label(self, mailbox: str, label: str, *, limit: int = 50) -> list[dict[str, Any]]:
        """List message ids carrying ``label``. Used by the report-mailbox poller."""
        async with httpx.AsyncClient(timeout=self._timeout) as client:
            headers = await self._headers_for(client, mailbox)
            resp = await client.get(
                self._path(self._subject_for(mailbox), "messages"),
                headers=headers,
                params={"labelIds": label, "maxResults": str(max(1, min(int(limit), 100)))},
            )
            resp.raise_for_status()
            return list(resp.json().get("messages") or [])

    # ── State changes ────────────────────────────────────────────────────

    async def trash_message(self, mailbox: str, message_id: str) -> dict[str, Any]:
        """Move a message to Trash. Recoverable for 30 days; undone by untrash."""
        return await self._post(mailbox, f"messages/{quote(message_id, safe='')}/trash")

    async def untrash_message(self, mailbox: str, message_id: str) -> dict[str, Any]:
        """Take a message back out of Trash. The declared reverse of trash."""
        return await self._post(mailbox, f"messages/{quote(message_id, safe='')}/untrash")

    async def _post(self, mailbox: str, suffix: str, payload: dict[str, Any] | None = None) -> dict[str, Any]:
        async with httpx.AsyncClient(timeout=self._timeout) as client:
            headers = await self._headers_for(client, mailbox)
            resp = await client.post(self._path(self._subject_for(mailbox), suffix), headers=headers, json=payload or {})
            resp.raise_for_status()
            return dict(resp.json()) if resp.content else {}

    async def create_filter(self, mailbox: str, sender: str) -> dict[str, Any]:
        """Add a filter trashing future mail from ``sender``. Per-mailbox only."""
        return await self._post(
            mailbox,
            "settings/filters",
            {"criteria": {"from": sender}, "action": {"addLabelIds": ["TRASH"], "removeLabelIds": ["INBOX"]}},
        )

    async def list_filters(self, mailbox: str) -> list[dict[str, Any]]:
        async with httpx.AsyncClient(timeout=self._timeout) as client:
            headers = await self._headers_for(client, mailbox)
            resp = await client.get(self._path(self._subject_for(mailbox), "settings/filters"), headers=headers)
            resp.raise_for_status()
            return list(resp.json().get("filter") or [])

    async def delete_filter(self, mailbox: str, filter_id: str) -> dict[str, Any]:
        async with httpx.AsyncClient(timeout=self._timeout) as client:
            headers = await self._headers_for(client, mailbox)
            resp = await client.delete(
                self._path(self._subject_for(mailbox), f"settings/filters/{quote(filter_id, safe='')}"),
                headers=headers,
            )
            resp.raise_for_status()
            return {"deleted": True, "filter_id": filter_id}