Migrate from the MDE SIEM API to the Microsoft Defender XDR alerts API

Applies to:

Use the new Microsoft Defender XDR API for all your alerts

The Microsoft Defender XDR alerts API, released to public preview in MS Graph, is the official and recommended API for customers migrating from the SIEM API. This API enables customers to work with alerts across all Microsoft Defender XDR products using a single integration. We expect the new API to reach general availability (GA) by Q1 CY 2023.

The SIEM API was deprecated on December 31, 2023. It's declared to be "deprecated," but not "retired." This means that until this date, the SIEM API continues to function for existing customers. After the deprecation date, the SIEM API will continue to be available, however it will only be supported for security-related fixes.

Effective December 31, 2024, three years after the original deprecation announcement, we reserve the right to turn off the SIEM API, without further notice.

For additional information about the new APIs, see the blog announcement: The new Microsoft Defender XDR APIs in Microsoft Graph are now available in public preview!

API documentation: Use the Microsoft Graph security API - Microsoft Graph

If you're a customer using the SIEM API, we strongly recommend planning and executing the migration. This article includes information about the options available to migrate to a supported capability:

  1. Pulling MDE alerts into an external system (SIEM/SOAR).

  2. Calling the Microsoft Defender XDR alerts API directly.

Read about the new Microsoft Defender XDR alerts and incidents API

Pulling Defender for Endpoint alerts into an external system

If you're pulling Defender for Endpoint alerts into an external system, there are several supported options to give organizations the flexibility to work with the solution of their choice:

  1. Microsoft Sentinel is a scalable, cloud-native, SIEM and Security orchestration, automation, and response (SOAR) solution. Delivers intelligent security analytics and threat intelligence across the enterprise, providing a single solution for attack detection, threat visibility, proactive hunting, and threat response. The Microsoft Defender XDR connector allows customers to easily pull in all their incidents and alerts from all Microsoft Defender XDR products. To learn more about the integration, see Microsoft Defender XDR integration with Microsoft Sentinel.

  2. IBM Security QRadar SIEM provides centralized visibility and intelligent security analytics to identify and prevent threats and vulnerabilities from disrupting business operations. QRadar SIEM team has just announced the release of a new DSM that is integrated with the new Microsoft Defender XDR alerts API to pull in Microsoft Defender for Endpoint alerts. New customers are welcome to take advantage of the new DSM upon release. Learn more about the new DSM and how to easily migrate to it at Microsoft Defender XDR - IBM Documentation.

  3. Splunk SOAR helps customers orchestrate workflows and automate tasks in seconds to work smarter and respond faster. Splunk SOAR is integrated with the new Microsoft Defender XDR APIs, including the alerts API. For more information, see Microsoft Defender XDR | Splunkbase

Other integrations are listed in Technological partners of Microsoft Defender XDR, or contact your SIEM / SOAR provider to learn about integrations they provide.

Calling the Microsoft Defender XDR alerts API directly

The below table provides a mapping between the SIEM API to the Microsoft Defender XDR alerts API:

SIEM API property Mapping Microsoft Defender XDR alert API property
AlertTime -> createdDateTime
ComputerDnsName -> evidence/deviceEvidence: deviceDnsName
AlertTitle -> title
Category -> category
Severity -> severity
AlertId -> id
Actor -> actorDisplayName
LinkToWDATP -> alertWebUrl
IocName X IoC fields not supported
IocValue X IoC fields not supported
CreatorIocName X IoC fields not supported
CreatorIocValue X IoC fields not supported
Sha1 -> evidence/fileEvidence/fileDetails: sha1 (or evidence/processEvidence/imageFile: sha1)
FileName -> evidence/fileEvidence/fileDetails: fileName (or evidence/processEvidence/image: fileName)
FilePath -> evidence/fileEvidence/fileDetails: filePath (or evidence/processEvidence/image: filePath)
IPAddress -> evidence/ipEvidence: ipAddress
URL -> evidence/urlEvidence: url
IoaDefinitionId -> detectorId
UserName -> evidence/userEvidence/userAccount: accountName
AlertPart X Obsolete (Defender for Endpoint alerts are atomic/complete that are updatable, while the SIEM API were immutable records of detections)
FullId X IoC fields not supported
LastProcessedTimeUtc -> lastActivityDateTime
ThreatCategory -> mitreTechniques []
ThreatFamilyName -> threatFamilyName
ThreatName -> threatDisplayName
RemediationAction -> evidence: remediationStatus
RemediationIsSuccess -> evidence: remediationStatus (implied)
Source -> detectionSource (use with serviceSource: microsoftDefenderForEndpoint)
Md5 X Not supported
Sha256 -> evidence/fileEvidence/fileDetails: sha256 (or evidence/processEvidence/imageFile: sha256)
WasExecutingWhileDetected -> evidence/processEvidence: detectionStatus
UserDomain -> evidence/userEvidence/userAccount: domainName
LogOnUsers -> evidence/deviceEvidence: loggedOnUsers []
MachineDomain -> Included in evidence/deviceEvidence: deviceDnsName
MachineName -> Included in evidence/deviceEvidence: deviceDnsName
InternalIPV4List X Not supported
InternalIPV6List X Not supported
FileHash -> Use sha1 or sha256
DeviceID -> evidence/deviceEvidence: mdeDeviceId
MachineGroup -> evidence/deviceEvidence: rbacGroupName
Description -> description
DeviceCreatedMachineTags -> evidence: tags [] (for deviceEvidence)
CloudCreatedMachineTags -> evidence: tags [] (for deviceEvidence)
CommandLine -> evidence/processEvidence: processCommandLine
IncidentLinkToWDATP -> incidentWebUrl
ReportId X Obsolete (Defender for Endpoint alerts are atomic/complete that are updatable, while the SIEM API were immutable records of detections)
LinkToMTP -> alertWebUrl
IncidentLinkToMTP -> incidentWebUrl
ExternalId X Obsolete
IocUniqueId X IoC fields not supported

Ingest alerts using security information and events management (SIEM) tools

Note

Microsoft Defender for Endpoint Alert is composed from one or more suspicious or malicious events that occurred on the device and their related details. The Microsoft Defender for Endpoint Alert API is the latest API for alert consumption and contains a detailed list of related evidence for each alert. For more information, see Alert methods and properties and List alerts.

Microsoft Defender for Endpoint supports security information and event management (SIEM) tools ingesting information from your enterprise tenant in Microsoft Entra ID using the OAuth 2.0 authentication protocol for a registered Microsoft Entra application representing the specific SIEM solution or connector installed in your environment.

For more information, see:

Tip

Do you want to learn more? Engage with the Microsoft Security community in our Tech Community: Microsoft Defender for Endpoint Tech Community.