How to Collect Microsoft Defender Security Alerts | Graph API Guide

Step-by-step guide to ingesting Microsoft Defender security alerts using Microsoft Graph API. Monitor threats, malware detections, and security incidents from Microsoft 365 Defender.

  4 minute read  

Overview

Microsoft Graph Security API provides access to security alerts from Microsoft Defender products including Defender for Endpoint, Defender for Office 365, Defender for Identity, and Defender for Cloud Apps. Use this guide to ingest security alerts for SIEM integration, threat monitoring, and incident response.

Common Use Cases:

  • Centralize security alerts from all Microsoft Defender products
  • Integrate with SIEM for unified threat monitoring
  • Automate incident response workflows
  • Track malware detections and suspicious activities
  • Monitor security alert trends and patterns

Prerequisites

Before configuring Edge Delta, complete the Azure AD application setup:

  1. Register an Azure AD application with Application permissions (not Delegated)
  2. Grant the SecurityEvents.Read.All permission and obtain admin consent
  3. Create a client secret and note your Tenant ID, Client ID, and Client Secret

For detailed setup instructions, see Microsoft Graph API Integration.

Configuration

Basic Security Alert Collection

nodes:
- name: microsoft_security_alerts
  type: http_pull_input
  endpoint: https://graph.microsoft.com/v1.0/security/alerts
  method: GET
  pull_interval: 5m

  authorization:
    strategy: oauth_client_credentials
    client_credentials:
      token_url: https://login.microsoftonline.com/YOUR_TENANT_ID/oauth2/v2.0/token
      client_id: YOUR_CLIENT_ID
      client_secret: YOUR_CLIENT_SECRET
      scopes:
        - https://graph.microsoft.com/.default
      header_templates:
        - header: Authorization
          value: Bearer $ACCESS_TOKEN

  parameters:
    - name: "$orderby"
      value: "createdDateTime asc"
    - name: "$top"
      value: "50"

  parameter_expressions:
    - name: "$filter"
      value_expression: Concat(["createdDateTime ge ", FormatTime(Now() - Duration("5m10s"), "%Y-%m-%dT%H:%M:%SZ")], "")

Monitor High-Severity Alerts Only

Focus on critical and high-severity security events:

nodes:
- name: high_severity_alerts
  type: http_pull_input
  endpoint: https://graph.microsoft.com/v1.0/security/alerts
  method: GET
  pull_interval: 2m

  authorization:
    strategy: oauth_client_credentials
    client_credentials:
      token_url: https://login.microsoftonline.com/YOUR_TENANT_ID/oauth2/v2.0/token
      client_id: YOUR_CLIENT_ID
      client_secret: YOUR_CLIENT_SECRET
      scopes:
        - https://graph.microsoft.com/.default
      header_templates:
        - header: Authorization
          value: Bearer $ACCESS_TOKEN

  parameters:
    - name: "$orderby"
      value: "createdDateTime asc"
    - name: "$top"
      value: "100"
    - name: "$filter"
      value: "severity eq 'high' or severity eq 'critical'"

Monitor Active Alerts

Track alerts that require attention (not resolved):

nodes:
- name: active_security_alerts
  type: http_pull_input
  endpoint: https://graph.microsoft.com/v1.0/security/alerts
  method: GET
  pull_interval: 5m

  authorization:
    strategy: oauth_client_credentials
    client_credentials:
      token_url: https://login.microsoftonline.com/YOUR_TENANT_ID/oauth2/v2.0/token
      client_id: YOUR_CLIENT_ID
      client_secret: YOUR_CLIENT_SECRET
      scopes:
        - https://graph.microsoft.com/.default
      header_templates:
        - header: Authorization
          value: Bearer $ACCESS_TOKEN

  parameters:
    - name: "$orderby"
      value: "createdDateTime asc"
    - name: "$top"
      value: "50"
    - name: "$filter"
      value: "status eq 'newAlert' or status eq 'inProgress'"

Alert Severity Levels

SeverityDescriptionRecommended Pull Interval
criticalImmediate threat, active attack1-2 minutes
highHigh-impact threat, quick action needed2-5 minutes
mediumModerate risk, investigation needed5 minutes
lowMinor issues, routine review5-10 minutes
informationalFYI, no action required10-15 minutes

OData Filter Examples

FilterDescription
severity eq 'high'High-severity alerts only
status eq 'newAlert'Unreviewed alerts
vendorInformation/provider eq 'Microsoft Defender ATP'Specific Defender product
category eq 'Malware'Malware-related alerts
assignedTo eq 'security-team@company.com'Assigned to specific team

Combine multiple conditions:

$filter: "severity eq 'high' and status ne 'resolved' and createdDateTime ge 2024-01-01T00:00:00Z"

Alert Categories

CategoryDescriptionSource Products
MalwareMalicious software detectedDefender for Endpoint
SuspiciousActivityAnomalous behavior patternsAll Defender products
UnwantedSoftwarePotentially unwanted programsDefender for Endpoint
PhishingPhishing attemptsDefender for Office 365
CompromisedCredentialsLeaked or stolen credentialsDefender for Identity
RansomwareRansomware activityDefender for Endpoint

Sample Security Alert

{
  "id": "alert-guid-here",
  "azureTenantId": "tenant-guid",
  "createdDateTime": "2024-01-01T10:00:00Z",
  "title": "Suspicious PowerShell command detected",
  "description": "A potentially malicious PowerShell command was executed on device WORKSTATION-001",
  "severity": "high",
  "status": "newAlert",
  "category": "SuspiciousActivity",
  "vendorInformation": {
    "provider": "Microsoft Defender ATP",
    "vendor": "Microsoft",
    "subProvider": "MicrosoftDefenderATP"
  },
  "userStates": [
    {
      "userPrincipalName": "user@company.com",
      "accountName": "user",
      "domainName": "COMPANY"
    }
  ],
  "hostStates": [
    {
      "netBiosName": "WORKSTATION-001",
      "fqdn": "workstation-001.company.com",
      "os": "Windows 10"
    }
  ],
  "fileStates": [
    {
      "name": "powershell.exe",
      "path": "C:\\Windows\\System32\\WindowsPowerShell\\v1.0\\powershell.exe"
    }
  ],
  "recommendedActions": [
    "Isolate the affected device",
    "Review user activity logs",
    "Scan for additional threats"
  ]
}

Key Fields for Analysis

FieldDescriptionUse Case
severityAlert priority levelTriage and routing
statusnewAlert, inProgress, resolvedTrack investigation state
categoryType of threatClassify incidents
vendorInformation.providerSource Defender productIdentify detection source
userStatesAffected usersImpact assessment
hostStatesAffected devicesContainment decisions
recommendedActionsSuggested remediationResponse guidance

Troubleshooting

IssueSolution
401 UnauthorizedVerify tenant ID, client ID, and secret are correct
403 ForbiddenEnsure SecurityEvents.Read.All permission has admin consent
Empty resultsVerify Microsoft Defender licenses are active
Missing alertsCheck alert age; very old alerts may be archived