Microsoft Defender Get

Security

Synopsis

Retrieves detailed alert information from Microsoft Defender for Endpoint using the Alerts API, enabling telemetry pipelines to enrich security events with threat intelligence, investigation status, and remediation details from Microsoft's unified endpoint security platform.

Schema

- msdefender_get:
    tenant_id: <string>
    client_id: <string>
    client_secret: <string>
    alert_id: <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
alert_id	Y		Microsoft Defender alert identifier to retrieve
target_field	N	defender_alert	Field name where retrieved alert 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 if alert does not exist
on_failure	N		See Handling Failures
on_success	N		See Handling Success
tag	N		Identifier

Details

The msdefender_get processor retrieves comprehensive alert details from Microsoft Defender for Endpoint, enabling pipelines to enrich security events with threat intelligence, machine information, investigation status, severity classification, and recommended remediation actions.

Authentication: Uses OAuth 2.0 client credentials flow with Azure AD. The processor automatically obtains and manages access tokens, caching them for performance. Ensure your Azure AD application has the required API permissions (Alert.Read.All or Alert.Read) for Defender for Endpoint.

Alert ID Format: Microsoft Defender alert IDs follow the format {machine_id}_{unique_id} (e.g., 121688558380765161_2136280442). Alert IDs can be obtained from Defender portal URLs, webhook notifications, or the Alerts API listing endpoint.

Retrieved Alert Data: The processor stores a complete alert object containing:

• Alert metadata: ID, title, description, category, severity, status
• Machine information: Device ID, hostname, OS platform, IP addresses
• Detection details: Detection source, techniques (MITRE ATT&CK), evidence
• Investigation data: Assigned analyst, investigation state, classification
• Timestamps: First/last activity, creation time, resolution time
• Remediation: Recommended actions, automated investigation results

Token Caching: Access tokens are cached automatically to optimize performance when processing multiple alerts. Token refresh is handled transparently when tokens expire.

Error Handling: The processor supports both ignore_failure for API errors and ignore_missing for non-existent alerts. Use ignore_missing: true when processing alert references that may have been deleted or are not yet available in the Defender system.

Template Support: Both alert_id and target_field support Go template syntax with event field interpolation using {{{ .field_name }}} notation.

For creating alerts in Defender, see Microsoft Defender Create processor.

Examples

Basic Alert Retrieval

Retrieving alert details from Defender for correlation with security events...	{ "defender_alert_id": "121688558380765161_2136280442", "event_type": "security_alert" } - msdefender_get: tenant_id: "${GRAPH_TENANT_ID}" client_id: "${GRAPH_CLIENT_ID}" client_secret: "${GRAPH_CLIENT_SECRET}" alert_id: "{{{ defender_alert_id }}}" target_field: "defender_details"
Alert details stored in defender_details field for downstream processing...	{ "defender_alert_id": "121688558380765161_2136280442", "event_type": "security_alert", "defender_details": { "id": "121688558380765161_2136280442", "title": "Suspicious PowerShell Activity", "severity": "High", "category": "SuspiciousActivity", "status": "InProgress", "machineId": "121688558380765161", "investigationState": "Running" } }

Enriching SIEM Events

Enriching SIEM events with Defender investigation details...	{ "alert_reference": "121688558380765162_2136280443", "source_ip": "10.0.1.50", "user": "admin@contoso.com" } - msdefender_get: tenant_id: "${GRAPH_TENANT_ID}" client_id: "${GRAPH_CLIENT_ID}" client_secret: "${GRAPH_CLIENT_SECRET}" alert_id: "{{{ alert_reference }}}" target_field: "threat_intel"
Event enriched with Defender threat intelligence and investigation status...	{ "alert_reference": "121688558380765162_2136280443", "source_ip": "10.0.1.50", "user": "admin@contoso.com", "threat_intel": { "id": "121688558380765162_2136280443", "title": "Credential Dumping Detected", "category": "CredentialAccess", "severity": "High", "assignedTo": "soc-analyst@contoso.com", "classification": "TruePositive", "determination": "Malware" } }

Multiple Alert Processing

Processing multiple related alerts in a correlation pipeline...

{ "related_alerts": [ "121688558380765161_2136280442", "121688558380765162_2136280443", "121688558380765163_2136280444" ], "incident_id": "INC-2024-001" } - msdefender_get: tenant_id: "${GRAPH_TENANT_ID}" client_id: "${GRAPH_CLIENT_ID}" client_secret: "${GRAPH_CLIENT_SECRET}" alert_id: "{{{ related_alerts.0 }}}" target_field: "primary_alert" - msdefender_get: tenant_id: "${GRAPH_TENANT_ID}" client_id: "${GRAPH_CLIENT_ID}" client_secret: "${GRAPH_CLIENT_SECRET}" alert_id: "{{{ related_alerts.1 }}}" target_field: "secondary_alert"

Multiple alerts retrieved for incident correlation analysis...

{ "related_alerts": ["..."], "incident_id": "INC-2024-001", "primary_alert": { "id": "121688558380765161_2136280442", "severity": "High" }, "secondary_alert": { "id": "121688558380765162_2136280443", "severity": "Medium" } }

With Error Handling

Handling missing alerts gracefully in automated workflows...	{ "alert_id": "nonexistent_alert", "workflow": "automated_response" } - msdefender_get: tenant_id: "${GRAPH_TENANT_ID}" client_id: "${GRAPH_CLIENT_ID}" client_secret: "${GRAPH_CLIENT_SECRET}" alert_id: "{{{ alert_id }}}" target_field: "defender_data" ignore_missing: true tag: "defender_lookup"
Pipeline continues processing even when alert does not exist...	{ "alert_id": "nonexistent_alert", "workflow": "automated_response" }

Custom Target Field

Storing alert details in dynamically named fields...	{ "alert_id": "121688558380765161_2136280442", "target_name": "security_alert", "severity": "High" } - msdefender_get: tenant_id: "${GRAPH_TENANT_ID}" client_id: "${GRAPH_CLIENT_ID}" client_secret: "${GRAPH_CLIENT_SECRET}" alert_id: "{{{ alert_id }}}" target_field: "{{{ target_name }}}"
Alert details stored in dynamically specified field name...	{ "alert_id": "121688558380765161_2136280442", "target_name": "security_alert", "severity": "High", "security_alert": { "id": "121688558380765161_2136280442", "title": "Suspicious PowerShell Activity" } }

Investigation Status Monitoring

Monitoring Defender investigation progress for incident tracking...	{ "alert_id": "121688558380765161_2136280442", "check_type": "investigation_status" } - msdefender_get: tenant_id: "${GRAPH_TENANT_ID}" client_id: "${GRAPH_CLIENT_ID}" client_secret: "${GRAPH_CLIENT_SECRET}" alert_id: "{{{ alert_id }}}" target_field: "investigation"
Investigation status retrieved for automated incident management...	{ "alert_id": "121688558380765161_2136280442", "check_type": "investigation_status", "investigation": { "investigationState": "Running", "assignedTo": "soc-analyst@contoso.com", "status": "InProgress", "classification": null, "determination": null } }

Threat Intelligence Enrichment

Enriching firewall logs with Defender threat intelligence...	{ "source_ip": "192.168.1.100", "defender_alert": "121688558380765163_2136280444", "event_type": "firewall_block" } - msdefender_get: tenant_id: "${GRAPH_TENANT_ID}" client_id: "${GRAPH_CLIENT_ID}" client_secret: "${GRAPH_CLIENT_SECRET}" alert_id: "{{{ defender_alert }}}" target_field: "threat_context"
Firewall event enriched with Defender threat classification and MITRE techniques...	{ "source_ip": "192.168.1.100", "defender_alert": "121688558380765163_2136280444", "event_type": "firewall_block", "threat_context": { "category": "Malware", "severity": "High", "mitreTechniques": ["T1071", "T1105"], "threatName": "Trojan:Win32/Emotet" } }

Azure AD App Registration

To use the msdefender_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 "APIs my organization uses" > Search for "WindowsDefenderATP"
   • Choose Application permissions > Alert.Read.All (or Alert.Read for read-only access)
   • 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 Alert IDs:

   • Alert IDs can be found in Defender portal URLs when viewing alerts
   • Retrieved from webhook notifications
   • Listed via the Alerts API endpoint

For detailed setup instructions, see Microsoft Defender for Endpoint API Documentation.