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

Applies to:

Use the new Microsoft 365 Defender API for all your alerts

Important

In February we announced the Deprecation of the Microsoft Defender for Endpoint (MDE) SIEM API would be postponed. After gathering customer feedback, we have learned there are challenges with the timeline originally communicated. As a result, we are making changes to our timeline to improve our customers' experience in migrating to the new API. The new Microsoft 365 Defender alerts API, released to public preview in MS Graph, is the official and recommended API for customers migrating from the SIEM API. This API will enable customers to work with alerts across all Microsoft 365 Defender products using a single integration. We expect the new API to reach general availability (GA) by Q1 CY 2023. To provide customers with more time to plan and prepare their migration to the new Microsoft 365 Defender APIs, we have pushed the SIEM API deprecation date to December 31, 2023. This will give customers one year from the expected GA release of Microsoft 365 Defender APIs to migrate from the SIEM API. At the time of deprecation, the SIEM API will be declared "deprecated" but not "retired." This means that until this date, the SIEM API will continue 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 31st, 2024, three years after the original deprecation announcement, we reserve the right to turn off the SIEM API, without additional notice.

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

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

If you are a customer using the SIEM API, we strongly recommend planning and executing the migration. Listed below is 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 365 Defender alerts API directly

Read about the new Microsoft 365 Defender alerts and incidents API

Pulling Defender for Endpoint alerts into an external system

If you are pulling Defender for Endpoint alerts into an external system, there are various 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 365 Defender connector allows customers to easily pull in all their incidents and alerts from all Microsoft 365 Defender products. To learn more about the integration, see Microsoft 365 Defender 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 365 Defender 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 365 Defender - IBM Documentation.
  3. Splunk SOAR helps customers orchestrate workflows and automate tasks in seconds to work smarter and respond faster. Spunk SOAR is integrated with the new Microsoft 365 Defender APIs, including the alerts API. For more information, see Microsoft 365 Defender | Splunkbase

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

Calling the Microsoft 365 Defender alerts API directly

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

SIEM API property Mapping Microsoft 365 Defender 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 (MDE 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 (MDE 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 Azure Active Directory (AAD) using the OAuth 2.0 authentication protocol for a registered AAD application representing the specific SIEM solution or connector installed in your environment.

For more information, see: