Microsoft Graph Security — Alert Ingestion Guide

This guide covers two approaches for ingesting Microsoft security alerts into Swimlane Turbine via the Microsoft Graph Security API, normalized to TEDS format:

Connector — Use the Microsoft Graph API connector actions directly in a playbook for full control over your workflow.

Component — Use the Microsoft Graph Alert Ingestion Component for a turnkey pipeline that retrieves alerts, extracts IOCs, and ingests enriched alerts via webhook.

Both approaches support the same authentication methods (OAuth 2.0 Client Credentials or Delegated Flow). The Component adds automated IOC extraction and webhook-based ingestion on top of the connector's alert retrieval capabilities.

Key Capabilities

Automatic IOC extraction — Indicators of Compromise (domains, IPs, emails, URLs, file hashes) are automatically parsed from alert descriptions and evidence using the Swimlane Utilities IOC Parser.

Unified TEDS format — Every Microsoft security alert is normalized to TEDS, enabling cross-vendor playbooks and dashboards alongside CrowdStrike, SentinelOne, and other sources.

Configurable ingestion window — Control exactly how far back to pull alerts using a timestamp input. Run continuously on a schedule, backfill historical alerts on demand, or use manual triggers for testing.

Dual authentication support — Works with both OAuth 2.0 Client Credentials (serComponente accounts) and Delegated Flow (user-based authentication), fitting any Azure AD deployment model.

Multi-provider coverage — Ingests alerts from any Microsoft security product surfaced through the Graph Security API, including Microsoft Defender for Endpoint, Azure AD Identity Protection, Microsoft Defender for Cloud, and others.

Using the Connector

The Microsoft Graph API Security connector provides dedicated alert ingestion actions: List Alerts, Get Alert, and Update Alert. Use this approach when you want full control over your playbook logic and custom processing.

How It Works

List Alerts — Use the List Alerts action to retrieve security alerts from the Microsoft Graph Security API, filtered by time range, severity, or status using OData filters.

Get Alert Details — Use the Get Alert action to fetch detailed information for specific alerts by alert ID.

Normalize — Use playbook logic or transform blocks to map alert fields to TEDS or your desired record format.

Create Records — Build CIM records, TI records, or custom record types based on your application's data model.

Connector Setup

Prerequisites

Azure AD application registration with Microsoft Graph Security API permissions

The Microsoft Graph API Security connector installed from the Turbine marketplace

Steps

Create an Asset — In Turbine, create a new Microsoft Graph API Security asset with your OAuth 2.0 credentials.

Create a Playbook — Create a new playbook with a scheduled trigger (e.g., every 5 minutes).

Add the List Alerts Action — Add the Microsoft Graph API Security connector's List Alerts action to retrieve alerts.

Configure Time Window — Add a transform block to calculate the ingestion window (e.g., current time minus 10 minutes) and pass it as an OData filter to the alert query.

Build Processing Logic — Add playbook steps to extract observables, create records, and handle any custom normalization.

Authentication

The connector supports two authentication methods:

OAuth 2.0 Client Credentials (SerComponente-to-SerComponente):

Field	Required	Description
url	Yes	Base URL of the Microsoft Graph API (default: https://graph.microsoft.com)
client_id	Yes	OAuth 2.0 client ID registered in Azure AD
client_secret	Yes	OAuth 2.0 client secret
token_url	Yes	Token endpoint: https://login.microsoftonline.com/{tenant_id}/oauth2/v2.0/token
scope	Yes	Permission scopes for the action

Delegated Flow (User-Based):

Field	Required	Description
url	Yes	Base URL of the Microsoft Graph API (default: https://graph.microsoft.com)
login_url	Yes	Login URL (default: https://login.microsoftonline.com)
tenant_id	Yes	Microsoft Tenant ID
oauth_un	Yes	Microsoft Graph username
oauth_pwd	Yes	Microsoft Graph password
oauth_cl_id	Yes	Microsoft Graph client ID
oauth_cl_secret	Yes	Microsoft Graph client secret
scope	Yes	Permission scopes for the action

Required API Permissions:

SecurityEvents.Read.All — Read all security alerts

SecurityEvents.ReadWrite.All — Read and write security events (if alert management is needed)

Using the Component

The Microsoft Graph Alert Ingestion Component retrieves security alerts from the Microsoft Graph Security API, extracts IOCs from each alert using the Swimlane Utilities IOC Parser, enriches alerts with the extracted observables, and ingests them into Swimlane via webhook. Use this approach when you want automated alert ingestion with built-in IOC extraction.

What the Component Adds

Automatic IOC extraction — Uses the Swimlane Utilities IOC Parser to identify domains, IP addresses, email addresses, URLs, and file hashes (MD5, SHA1, SHA256) from alert text and evidence.

Alert enrichment — Appends extracted observables to each alert before ingestion, so downstream playbooks have IOCs ready for correlation and response.

Webhook-based ingestion — Sends each enriched alert to a configured Swimlane webhook endpoint for flexible downstream processing.

How It Works

Query Alerts — Calls the Microsoft Graph Security API to retrieve alerts created or updated since the configured start_time.

Loop Through Alerts — For each alert:

Extract IOCs — Parses alert description, title, and evidence text through the IOC Parser to identify observables (domains, IPs, emails, URLs, hashes).

Enrich Alert — Appends the extracted observables array to the alert object.

Post to Webhook — Sends the enriched alert to the configured Swimlane webhook endpoint.

Compile Results — Aggregates all processed alerts with their observables into the output alerts array.

Component Setup

Prerequisites

Azure AD application registration with Microsoft Graph Security API permissions (SecurityEvents.Read.All)

The Microsoft Graph API connector installed from the Turbine marketplace

The Microsoft Graph Alert Ingestion Component imported from the marketplace

A Swimlane webhook endpoint configured to receive alert payloads

Steps

Create an Asset — In Turbine, create a new Microsoft Graph API asset with your OAuth 2.0 credentials (Client Credentials or Delegated Flow).

Install the Component — Import the Microsoft Graph Alert Ingestion Component from the marketplace.

Configure the Component — Add the Component component to your playbook and assign the Microsoft Graph API asset.

Set Inputs — Provide the start_time (ISO 8601 timestamp for the ingestion window) and organisation (organization identifier).

Configure Webhook — Ensure the webhook endpoint is configured to receive and process enriched alerts.

Schedule the Playbook — Set up a scheduled trigger (e.g., every 5 minutes) for continuous ingestion.

Component Inputs

Parameter	Required	Description
start_time	Yes	ISO 8601 timestamp to retrieve alerts from (e.g., 2025-09-15T00:00:00Z). Use a transform block to calculate dynamically.
organisation	Yes	Organization identifier or name for scoping alert retrieval.

Component Outputs

Field	Type	Description
alerts	array	Array of enriched alert objects, each containing TEDS-normalized alert data with extracted observables.

Error Handling

Scenario	Behavior
Alert retrieval fails	Error logged, processing stops
IOC extraction fails for an alert	Alert continues processing without observables
Webhook POST fails	Error logged, processing continues with next alert
Partial success	Returns successfully processed alerts even if some fail

Recommended Configuration

Scenario	Polling Interval	start_time (lookback)
Standard deployment	Every 5 minutes	10 minutes ago
High-volume environments	Every 2 minutes	5 minutes ago
Initial backfill	One-time run	24 hours ago
Testing	Manual trigger	1 hour ago

TEDS Output Schema

Both the connector and Component produce alerts in this standardized format:

TEDS Field	Type	Description
alert_uid	string	Unique alert identifier from Microsoft Graph
alert_title	string	Alert display name
alert_description	string	Description of what was detected
alert_severity	string	low, medium, high, critical
alert_provider	string	Source product (e.g., "AAD Identity Protection", "Microsoft Defender for Endpoint")
alert_organization	string	Organization identifier
alert_categories	array	Alert category classifications (e.g., ["InitialAccess"])
alert_created_timestamp	string	ISO 8601 creation time
alert_start_timestamp	string	When the activity was first observed
alert_end_timestamp	string	When the activity was last observed
alert_ingested_timestamp	string	When the alert was ingested by Turbine
alert_impacted_hostnames	array	Affected endpoint hostnames
alert_impacted_ip_addresses	array	Affected endpoint IPs
alert_impacted_usernames	array	Affected user accounts
alert_risk_score	number	Risk score (if available)
alert_permalink	string	Direct link to the alert in the Microsoft Security portal
alert_rules	array	Detection rules with rule_id, rule_name, rule_description, rule_type
alert_mitre_attack_tactic_technique	array	MITRE ATT&CK tactics and techniques
observables	array	Extracted IOCs — objects with observable_type and observable_value
alert_originating_files	array	File objects with name, hashes, and MIME type
raw_alert	object	Complete original alert from the Microsoft Graph API

Observable Types

The IOC Parser extracts the following observable types from alert content:

Type	Example
domain	malicious-site.com
ipv4_public	35.169.90.250
ipv6	2001:db8::1
email	[email protected]
url	https://phishing-site.com/login
md5	d41d8cd98f00b204e9800998ecf8427e
sha1	da39a3ee5e6b4b0d3255bfef95601890afd80709
sha256	e3b0c44298fc1c149afbf4c8996fb924...

Sample Output

{
  "alert_uid": "adba921ff0463beedb23c12bebb82225d013ca982c",
  "alert_title": "Unfamiliar sign-in properties",
  "alert_description": "The following properties of this sign-in are unfamiliar for the given user: ASN, Browser, DeComponente, IP",
  "alert_severity": "low",
  "alert_provider": "AAD Identity Protection",
  "alert_categories": ["InitialAccess"],
  "alert_created_timestamp": "2025-09-15T15:30:17.213Z",
  "alert_start_timestamp": "2025-09-15T15:26:41.123Z",
  "alert_end_timestamp": "2025-09-15T15:26:41.123Z",
  "alert_ingested_timestamp": "2026-03-10T13:22:00.332Z",
  "alert_impacted_usernames": ["pov"],
  "alert_permalink": "https://security.microsoft.com/alerts/...",
  "alert_rules": [
    {
      "rule_id": "UnfamiliarLocation",
      "rule_name": "Unfamiliar sign-in properties",
      "rule_description": "InitialAccess / azureAdIdentityProtection",
      "rule_type": "azureAdIdentityProtection"
    }
  ],
  "alert_mitre_attack_tactic_technique": [
    {
      "tactics": [],
      "technique": {"uid": "T1078", "name": "Unknown"}
    }
  ],
  "observables": [
    {"observable_type": "domain", "observable_value": "microsoft.graph.security"},
    {"observable_type": "ipv4_public", "observable_value": "35.169.90.250"},
    {"observable_type": "email", "observable_value": "[email protected]"}
  ],
  "alert_originating_files": [],
  "raw_alert": {}
}

Connector Reference

For the full list of actions, input/output schemas, and authentication setup, see the Microsoft Graph API Security connector documentation.