[New Integration] Material Security

## 1. Summary
An Elastic integration to collect **threat detections and audit logs** from **Material Security**, the email and cloud-workspace (Google Workspace / Microsoft 365) security platform. This brings Material's phishing, account-takeover, and data-loss detections — plus a trail of admin and analyst activity — into Elastic Security for threat monitoring, investigation, and correlation with the rest of a customer's security data.

## 2. Vendor & Product Context
- **Vendor:** Material Security — email security, account-takeover protection, data-loss prevention, and posture management for Google Workspace and Microsoft 365.
- **What it does:** monitors mailboxes and workspace accounts, detects phishing/malware and suspicious activity, protects sensitive data in email, and remediates threats (quarantine, message override, account lockdown).
- **Data source & collection:** Material offers two egress paths, and the integration should support whichever delivers the most value (see §6):
- **API pull (preferred starting point):** poll Material's REST API (API v1 / Issues API) using an API token + tenant URL. No inbound endpoint needed on the customer side.
- **Webhook push:** Material posts events to an Elastic Agent HTTP endpoint in near-real-time, secured with a bearer token. This path is documented to cover both detections *and* audit logs.

## 3. Data to Collect
- **Issues (detections)** — Material's core detection resource: phishing, account takeover, malware, suspicious activity, and data-loss findings, with severity, status, the affected account, and related message context. This is the primary threat/alert data.
- **Audit logs** — admin and analyst activity within Material: logins, remediation actions, sensitivity changes, configuration/integration changes, role changes, and API access. Confirmed available via the webhook path; availability via the pull API needs confirmation against a live tenant (see §6).

## 4. Expected Outcomes
- Material detections and admin activity searchable and alertable in Elastic Security, normalized to ECS so they sit alongside the customer's other security data.
- Correlation of Material's email-security signals with endpoint, identity, and network data already in Elastic (e.g. tying a phishing detection to downstream endpoint activity).
- A prebuilt dashboard and saved searches out of the box (see §5), and a foundation for detection rules on high-signal events (e.g. account-takeover detections, VIP-targeted phishing, sensitive-data exposure).

## 5. Proposed Dashboards
An out-of-the-box **Material Security Overview** dashboard:

- **Detections overview** — detections over time, broken down by type (phishing, account takeover, malware, data loss) and severity.
- **Detection status & response** — open vs. resolved detections, and remediation actions taken.
- **Affected accounts & VIPs** — which users and VIPs are most targeted or impacted.
- **Audit activity** — admin/analyst actions over time, top actors, and action breakdown.
- **Recent detections feed** — a chronological table of the latest detections for quick triage.

## 6. Open Questions & Risks
- **Collection approach to be validated against a live instance.** API-pull is the preferred starting point (simpler deployment, no inbound endpoint), but the **webhook/HTTP-endpoint path may deliver more value** — it's documented to cover both detections and audit logs and delivers in near-real-time. Which path to build (or whether to support both) needs research against a real Material tenant.
- **API documentation is gated** behind a Material console login — exact endpoints, pagination, and rate limits need tenant or vendor access to confirm.
- **Audit-log availability via the pull API** is unconfirmed (documented via webhook). If pull can't deliver audit logs, the webhook path becomes more attractive for full coverage.
- Access to a **Material Security test tenant** (or vendor contact) is needed for development, schema confirmation, and testing.

## 7. References
- [Material Security — API v1 announcement](https://material.security/resources/the-open-engine-smarter-detection-explanations-and-api-v1) · [API reference (login required)](https://docs.material.security/reference/api-v1) · [Deployment & security](https://material.security/products/deployment-and-security)
- [Event schemas — Panther reference](https://docs.panther.com/data-onboarding/supported-logs/material-security)

Start with the Material Security API v1 reference and the documented webhook/HTTP endpoint path, then validate both against a live tenant or vendor contact. Confirm endpoints, pagination, rate limits, audit-log availability, event schemas, and test access before choosing a collection approach. Done means detections and audit activity are collected, normalized to ECS, and covered by the proposed dashboard views.

Written by the indexing model from the issue text.