We are excited to announce the release of new Microsoft Defender for Office 365 API’s which enable security teams to leverage threat information and response capabilities of Microsoft Defender for Office 365 inside automation and security orchestration tools of their choice.
These new API’s enable your security teams to achieve more within their existing toolsets by leveraging the power of Microsoft Defender for Office 365!
Our new API methods extend our existing Microsoft Graph API functionality with additional key benefits, such as:
- Integration with a range of security tools and services such as SOAR platforms, enabling you to build custom automation and playbooks for security scenarios that can natively integrate with Microsoft Defender for Office 365.
- Retrieval of detailed threat information, such as filter verdicts, related underlying entities (such as attachments, linked URLs), Safe Attachments and Safe Links detonation details. This ensures that all email threat information can be leveraged for more complete and comprehensive automation capabilities.
- Ability to perform response actions on emails (such as soft delete, hard delete, move to junk, move to inbox) natively within your security tools and automation platforms, enabling you to create end to end playbooks with response capabilities.
We believe that these new API’s will enable us to meet the SOC where they are, enable your teams and third-party security vendors to natively interact with Microsoft Defender for Office 365.
Our new API’s are built around least-privilege with its own permission scopes, complete with auditing capabilities, allowing you to perform automation and integration securely in your organization.
It does not matter if you are using Sentinel, a third-party SOAR platform, logic apps, PowerShell automation, python scripts, or any other tool – these API’s are about meeting you where you are so you can leverage the power of Microsoft Defender for Office 365 to help secure your organization.
Scenario Examples
Whilst the opportunities are endless, here are just a few great ideas that we have heard from our customers. Because these new APIs are open, you could achieve these (and more) within Sentinel, or your platform of choice:
Automated Detection & Response: What about triggering a playbook off some threat condition within your environment? Maybe you received a new threat indicator? Leveraging Microsoft Defender XDR Advanced hunting API to find emails based on your IOCs (Indicators of Compromise), view detonation details about the IOCs and then remediating them using these new API methods? All now possible with our new Microsoft Defender for Office 365 APIs!
Reported message triage: Triage reported phish messages inside your orchestration tool of choice, pull in Microsoft Defender for Office 365 threat detection information (such as Safe Links detonation results), mix that with your automation logic and threat indicators, and then perform response actions, all within your orchestration platform of choice powered by these new APIs.
Showing it in action through the unified SOC experience.
Here’s an example of this all together. In this scenario, we will use a Microsoft Defender XDR incident as a trigger, that will start a Sentinel logic app playbook that uses our new response API’s for fetching email indicators, compare those indicators against our own threat intelligence, and then act on the message if meets our threat conditions:
Starting at the incident, using the Unified Security Operations Platform experience with Microsoft Sentinel and Defender XDR, we can trigger the playbook. In reality, you might choose to have this playbook triggered automatically based on the creation of a new incident rather than manually run it. For the purpose of the demonstration, we will run it manually:
The playbook leverages Defender Advanced Hunting API’s for discovering additional emails, and mixes with our internal threat intelligence sources. If we detect our known indicators within the message from the advanced hunting query, our playbook knows that this message should be removed and triggers the removal with our new API:
Our new MDO Response API’s are called against these suspect emails, which creates a trackable alert for response in the Microsoft Defender portal:
After the action has been completed, we can see the email associated with the playbook was deleted by our Response APIs by looking at the timeline view of the email:
Showing it in action through Splunk SOAR
Our new API’s are open, standard REST calls provided by Microsoft Graph, and as such they can be leveraged by any automation or security tool supporting standard API calls.
We are releasing actions to act on messages, but also to pull detailed verdict & indicator information from them.
In this example we will bring additional threat indicators from Microsoft Defender for Office 365 (using our new API's) into our third-party SOAR system as native artifacts!
Microsoft Defender for Office 365 has advanced detonation capabilities that use machine learning and behavioural patterns to detect threats within emails. Historically, the information extracted from our detonation chambers has been visible only via our Defender Portal as shown below:
With our new API’s, we are able to pull our detonation deep analysis in to third-party systems, such as Splunk SOAR:
Our above playbook can be triggered on an email artifact in Splunk SOAR. When the API playbook is triggered, we pull the URL artifacts and respective detonations on that email using our new API’s, exposing them as artifacts in Splunk SOAR!
Screenshot from Splunk SOAR showing our detonation information.
API Documentation References
As with all Graph API’s, we have detailed documentation, and example code available in the Graph Reference Guide to get you started:
List emails in a certain timeframe
– similar to what is available within the Threat Explorer API
You can also use filters like network message ids and recipient ids to search for specific emails.
Get detailed threat information on an individual email message. This contains verdict information, detailed Safe Links/Safe Attachments detonation IOCs, and verdict results – similar to what is available within the Email entity API.
Perform remediation activities on an email, such as soft delete, hard delete, move to inbox, quarantine release, delete sender's copy and move to deleted items.
Let us know what your ideas are! How will you leverage these new API’s within your platform and processes?
Learn More:
- For additional information visit: analyzed Email: remediate - Microsoft Graph beta | Microsoft Learn
- Engage with the community and Microsoft experts in the Defender for Office 365 forum questions or feedback
Microsoft
