Use the Microsoft Graph Security API
The Microsoft Graph Security API provides a unified interface and schema to integrate with security solutions from Microsoft and ecosystem partners. This empowers customers to streamline security operations and better defend against increasing cyber threats. The Microsoft Graph Security API federates queries to all onboarded security providers and aggregates responses. Use the Microsoft Graph Security API to build applications that:
- Consolidate and correlate security alerts from multiple sources
- Unlock contextual data to inform investigations
- Automate security tasks, business processes, workflows, and reporting
- Send threat indicators to Microsoft products for customized detections
- Invoke actions to in response to new threats
- Provide visibility into security data to enable proactive risk management
The Microsoft Graph Security API includes the following key entities.
Alerts
Alerts are potential security issues within a customer's tenant that Microsoft or partner security solutions have identified and flagged for action or notification. With the Microsoft Graph Security alerts entity, you can unify and streamline management of security issues across all integrated solutions. This also enables applications to correlate alerts and context to improve threat protection and response. With the alert update capability, you can sync the status of specific alerts across different security products and services that are integrated with the Microsoft Graph Security API by updating your alerts entity.
Alerts from the following providers are available via the Microsoft Graph Security API. Support for GET alerts, PATCH alerts, and Subscribe (via webhooks) is indicated in the following table.
Security provider | GET alert |
PATCH alert |
Subscribe to alert |
---|---|---|---|
Microsoft Defender for Cloud | ✓ |
✓ |
✓ |
Azure Active Directory Identity Protection | ✓ |
✓ |
|
Microsoft Defender for Cloud Apps | ✓ |
✓ |
|
Microsoft Defender for Endpoint ** | ✓ |
✓ |
|
Microsoft Defender for Identity *** | ✓ |
✓ |
|
Microsoft 365
|
✓ |
||
Azure Information Protection (preview) | ✓ |
✓ |
|
Azure Sentinel (preview) | ✓ |
Not supported in Azure Sentinel |
✓ |
Note: New providers are continuously onboarding to the Microsoft Graph Security ecosystem. To request new providers or for extended support from existing providers, file an issue in the Microsoft Graph Security GitHub repo.
* File issue: Alert status gets updated across Microsoft Graph Security API integrated applications but not reflected in the provider’s management experience.
** Microsoft Defender for Endpoint requires additional user roles to those required by the Microsoft Graph Security API. Only the users in both Microsoft Defender for Endpoint and Microsoft Graph Security API roles can have access to the Microsoft Defender for Endpoint data. Because application-only authentication is not limited by this, we recommend that you use an application-only authentication token.
*** Microsoft Defender for Identity alerts are available via the Microsoft Defender for Cloud Apps integration. This means you will get Microsoft Defender for Identity alerts only if you have joined Unified SecOps and connected Microsoft Defender for Identity into Microsoft Defender for Cloud Apps. Learn more about how to integrate Microsoft Defender for Identity and Microsoft Defender for Cloud Apps.
Information protection
The Microsoft Graph threat assessment API helps organizations to assess the threat received by any user in a tenant. This empowers customers to report spam emails, phishing URLs or malware attachments they receive to Microsoft. The policy check result and rescan result can help tenant administrators understand the threat scanning verdict and adjust their organizational policy.
Secure Score
Microsoft Secure Score is a security analytics solution that gives you visibility into your security portfolio and how to improve it. With a single score, you can better understand what you have done to reduce your risk in Microsoft solutions. You can also compare your score with other organizations and see how your score has been trending over time. The Microsoft Graph Security secureScore and secureScoreControlProfile entities help you balance your organization's security and productivity needs while enabling the appropriate mix of security features. You can also project what your score would be after you adopt security features.
Common use cases
The following are some of the most popular requests for working with the Microsoft Graph Security API:
Use cases | REST resources | Try it in Graph Explorer |
---|---|---|
List alerts | List alerts | https://graph.microsoft.com/v1.0/security/alerts |
Update alerts | Update alert | https://graph.microsoft.com/v1.0/security/alerts/{alert-id} |
List secure scores | List secureScores | https://graph.microsoft.com/v1.0/security/secureScores |
Get secure score | Get secureScore | https://graph.microsoft.com/v1.0/security/secureScores/{id} |
List secure score control profiles | List secureScoreControlProfiles | https://graph.microsoft.com/v1.0/security/secureScoreControlProfiles |
Get secure score control profile | Get secureScoreControlProfile | https://graph.microsoft.com/v1.0/security/secureScoreControlProfiles/{id} |
Update secure score control profiles | Update secureScoreControlProfile | https://graph.microsoft.com/v1.0/security/secureScoreControlProfiles/{id} |
You can use Microsoft Graph webhooks to subscribe to and receive notifications about updates to Microsoft Graph Security entities.
Resources
Code and contribute to these Microsoft Graph Security API samples:
Engage with the community:
What's new
Find out about the latest new features and updates for these API sets.
Next steps
The Microsoft Graph Security API can open up new ways for you to engage with different security solutions from Microsoft and partners. Follow these steps to get started:
- Drill down into alerts, secureScore, and secureScoreControlProfiles.
- Try the API in the Graph Explorer. Under Sample Queries, choose show more samples and set the Security category to on.
- Try subscribing to and receiving notifications on entity changes.
Need more ideas? See how some of our partners are using Microsoft Graph.
See also
Code and contribute to these Microsoft Graph Security API samples:
- ASP.NET (C#) sample
- Python sample
- Node.js (JavaScript) sample
- PowerShell sample
- Other samples or contribute a new sample
Explore other options to connect with the Microsoft Graph Security API:
Engage with the community:
Feedback
Submit and view feedback for