Microsoft Graph Get

Security

Synopsis

Retrieves detailed information about security alerts or incidents from Microsoft Graph Security API, enabling telemetry pipelines to enrich events with complete alert context, incident details, and investigation data from Microsoft Defender and Sentinel.

Schema

- msgraph_get:
    tenant_id: <string>
    client_id: <string>
    client_secret: <string>
    id: <string>
    type: <string>
    target_field: <string>
    description: <text>
    if: <script>
    disabled: <boolean>
    ignore_failure: <boolean>
    ignore_missing: <boolean>
    on_failure: <processor[]>
    on_success: <processor[]>
    tag: <string>

Configuration

Field	Required	Default	Description
tenant_id	N	${GRAPH_TENANT_ID}	Azure AD tenant ID for authentication
client_id	N	${GRAPH_CLIENT_ID}	Application (client) ID from Azure AD app registration
client_secret	N	${GRAPH_CLIENT_SECRET}	Client secret for OAuth 2.0 authentication
id	Y		Alert or incident identifier to retrieve from Microsoft Graph API
type	N	alert	Resource type to retrieve: alert or incident (case-insensitive)
target_field	N	Type value	Field name where retrieved resource data will be stored
description	N		Explanatory note
if	N		Condition to run
disabled	N	false	Disable this processor
ignore_failure	N	false	See Handling Failures
ignore_missing	N	false	Continue when resource does not exist
on_failure	N		See Handling Failures
on_success	N		See Handling Success
tag	N		Identifier

Details

The msgraph_get processor retrieves complete security alert or incident data from Microsoft Graph Security API, enabling telemetry pipelines to enrich events with detailed investigation context from Microsoft Defender and Sentinel platforms.

Authentication: Uses OAuth 2.0 client credentials flow with Azure AD. The processor automatically obtains and caches access tokens for the Microsoft Graph API scope (https://graph.microsoft.com/.default). Ensure your Azure AD application has appropriate API permissions (SecurityAlert.Read.All or SecurityIncident.Read.All).

Resource Types: Supports two resource types through the type parameter:

• alert: Retrieves alerts from /security/alerts_v2/{id} endpoint (Microsoft Defender alerts)
• incident: Retrieves incidents from /security/incidents/{id} endpoint (Microsoft Sentinel incidents)

Default Behavior: When type is not specified, defaults to alert. When target_field is not specified, the processor stores the retrieved resource in a field matching the type value (e.g., alert or incident).

Template Support: All string fields support Go template syntax with event field interpolation using {{{field_name}}} notation. This enables dynamic resource ID retrieval based on event data.

Token Caching: Access tokens are automatically cached and reused across multiple processor invocations, reducing authentication overhead and improving performance for high-volume processing.

Error Handling: The processor supports both ignore_failure (continue on API errors) and ignore_missing (continue when resource not found) flags for graceful degradation in production pipelines.

API Timeout: HTTP requests to Microsoft Graph API have a 15-second timeout to prevent pipeline stalls during network issues or service degradation.

For Azure AD app registration requirements, see the defender processor documentation for detailed setup instructions.

Examples

Basic Alert Retrieval

Retrieving alert details from Microsoft Defender...	{ "alert_id": "da637578995287051192_756343937", "event_type": "security_alert" } - msgraph_get: tenant_id: "${GRAPH_TENANT_ID}" client_id: "${GRAPH_CLIENT_ID}" client_secret: "${GRAPH_CLIENT_SECRET}" type: "alert" id: "{{{alert_id}}}" target_field: "alert_details"
Complete alert data stored in alert_details field...	{ "alert_id": "da637578995287051192_756343937", "event_type": "security_alert", "alert_details": { "id": "da637578995287051192_756343937", "severity": "high", "status": "new", "classification": "truePositive", "determination": "malware" } }

Incident Retrieval

Fetching incident data from Microsoft Sentinel...	{ "incident_id": "2972395", "source": "sentinel" } - msgraph_get: tenant_id: "${GRAPH_TENANT_ID}" client_id: "${GRAPH_CLIENT_ID}" client_secret: "${GRAPH_CLIENT_SECRET}" type: "incident" id: "{{{incident_id}}}" target_field: "incident_data"
Incident details with alerts and investigation status...	{ "incident_id": "2972395", "source": "sentinel", "incident_data": { "id": "2972395", "severity": "high", "status": "active", "alerts": [] } }

Default Type and Target Field

Using default type (alert) and target field...	{ "alert_id": "da637578995287051192_756343937" } - msgraph_get: tenant_id: "${GRAPH_TENANT_ID}" client_id: "${GRAPH_CLIENT_ID}" client_secret: "${GRAPH_CLIENT_SECRET}" id: "{{{alert_id}}}"
Alert data stored in default "alert" field...	{ "alert_id": "da637578995287051192_756343937", "alert": { "id": "da637578995287051192_756343937", "severity": "high" } }

Dynamic Type Selection

Using template variables for dynamic resource type...	{ "resource_type": "incident", "resource_id": "2972395", "target_name": "security_event" } - msgraph_get: tenant_id: "${GRAPH_TENANT_ID}" client_id: "${GRAPH_CLIENT_ID}" client_secret: "${GRAPH_CLIENT_SECRET}" type: "{{{resource_type}}}" id: "{{{resource_id}}}" target_field: "{{{target_name}}}"
Resource retrieved based on event data...	{ "resource_type": "incident", "resource_id": "2972395", "target_name": "security_event", "security_event": { "id": "2972395", "status": "active" } }

With Error Handling

Gracefully handling missing or invalid resources...	{ "alert_id": "nonexistent_alert_123" } - msgraph_get: tenant_id: "${GRAPH_TENANT_ID}" client_id: "${GRAPH_CLIENT_ID}" client_secret: "${GRAPH_CLIENT_SECRET}" type: "alert" id: "{{{alert_id}}}" target_field: "alert_data" ignore_missing: true ignore_failure: true
Processing continues despite missing resource...	{ "alert_id": "nonexistent_alert_123" }

Alert Enrichment Pipeline

Enriching security events with full alert context...	{ "event_id": "evt-001", "defender_alert_id": "da637578995287051192_756343937", "severity": "unknown" } processors: - msgraph_get: type: "alert" id: "{{{defender_alert_id}}}" target_field: "full_alert" - set: field: "severity" value: "{{{full_alert.severity}}}" - set: field: "classification" value: "{{{full_alert.classification}}}"
Event enriched with alert severity and classification...	{ "event_id": "evt-001", "defender_alert_id": "da637578995287051192_756343937", "severity": "high", "classification": "truePositive", "full_alert": { "id": "da637578995287051192_756343937", "severity": "high", "classification": "truePositive" } }

Case-Insensitive Type

Type parameter accepts case-insensitive values...	{ "alert_id": "da637578995287051192_756343937" } - msgraph_get: tenant_id: "${GRAPH_TENANT_ID}" client_id: "${GRAPH_CLIENT_ID}" client_secret: "${GRAPH_CLIENT_SECRET}" type: "ALERT" id: "{{{alert_id}}}"
Type normalized to lowercase internally...	{ "alert_id": "da637578995287051192_756343937", "alert": { "id": "da637578995287051192_756343937" } }

Azure AD App Registration

To use the msgraph_get processor, you must register an application in Azure AD with appropriate permissions:

1. Register Application:

   • Navigate to Azure Portal > Microsoft Entra ID > App registrations > New registration
   • Choose a name and select supported account types
   • Register the application

2. Create Client Secret:

   • Go to Certificates & secrets > New client secret
   • Add description and expiration
   • Copy the secret value (shown only once)

3. Assign API Permissions:

   • Go to API Permissions > Add permission
   • Select "Microsoft Graph" > Application permissions
   • For alerts: Add SecurityAlert.Read.All or SecurityAlert.ReadWrite.All
   • For incidents: Add SecurityIncident.Read.All or SecurityIncident.ReadWrite.All
   • Grant admin consent

4. Configure Environment Variables:

   export GRAPH_TENANT_ID="your-tenant-id"
   export GRAPH_CLIENT_ID="your-client-id"
   export GRAPH_CLIENT_SECRET="your-client-secret"

5. Obtain Resource IDs:

   • Alert IDs can be found in Microsoft Defender portal or via alerts API
   • Incident IDs can be found in Microsoft Sentinel portal or via incidents API

For detailed API documentation, see Microsoft Graph Security API Reference.