Use the Microsoft Graph Security API

Important

APIs under the /beta version in Microsoft Graph are subject to change. Use of these APIs in production applications is not supported.

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 (updates are available via the Microsoft Graph Security API but might not be exposed in the provider’s management experience), and Subscribe (via webhooks) is indicated in the following table.

Security provider

GET alert

PATCH alert

Subscribe to alert

Azure Security Center

Azure Active Directory Identity Protection

Microsoft Cloud App Security

Microsoft Defender Advanced Threat Protection *

File issue

Azure Advanced Threat Protection **

Office 365

File issue

File issue

Azure Information Protection (preview)

Azure Sentinel (preview)

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.

* Microsoft Defender Advanced Threat Protection requires additional user roles to those required by the Microsoft Graph Security API. Only the users in both Microsoft Defender Advanced Threat Protection and Microsoft Graph Security API roles can have access to the Microsoft Defender Advanced Threat Protection data. Because application-only authentication is not limited by this, we recommend that you use an application-only authentication token.

** Azure Advanced Threat Protection alerts are available via the Microsoft Cloud App Security integration. This means you will get Azure Advanced Threat Protection alerts only if you have joined the Unified SecOps preview program and connected Azure Advanced Threat Protection into Microsoft Cloud App Security.

Threat indicators (preview)

Threat indicators, also referred to as indicators of compromise (IoCs), represent data about known threats, such as malicious files, URLs, domains, and IP addresses. Customers can generate indicators through internal threat intelligence gathering or acquire indicators from threat intelligence communities, licensed feeds, and other sources. These indicators are then used in various security tools to defend against related threats.

The Microsoft Graph Security tiIndicators entity allows customers to feed threat indicators to Microsoft security solutions to enable block and alert actions on malicious activity or allow, which suppresses actions for indicators determined not to be relevant to an organization. When sending indicators, both the Microsoft solution that will utilize the indicator and the action to be taken on that indicator are specified.

You can integrate the tiIndicator entity into your application or use one of the following integrated threat intelligence platforms (TIP):

Threat indicators sent via the Microsoft Graph Security API are available today in the following products:

Support in other Microsoft security services will be available soon.

Security Actions (preview)

Take immediate action to defend against threats using the Microsoft Graph Security securityAction entity. When a security analyst discovers a new indicator, such as a malicious file, URL, domain, or IP address, protection can be instantly enabled in your Microsoft security solutions. Invoke an action for a specific provider, see all actions taken, and cancel an action if needed. Try security actions with Microsoft Defender Advanced Threat Protection to block malicious activity on your Windows endpoints using properties seen in alerts or identified during investigations.

Note: Currently security actions only support application permissions.

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/beta/security/alerts
Update alerts Update alert
Update multiple alerts
https://graph.microsoft.com/beta/security/alerts/{alert-id}
https://graph.microsoft.com/beta/security/alerts/updateAlerts
Get security action Get security action (preview) https://graph.microsoft.com/beta/security/securityActions/{id}
List security actions List security actions (preview) https://graph.microsoft.com/beta/security/securityActions
Create security actions Create security actions (preview) https://graph.microsoft.com/beta/security/securityActions
Cancel security action Cancel security actions (preview) https://graph.microsoft.com/beta/security/securityActions/{id}/cancelSecurityAction
Get TI indicator Get tiIndicator (preview) https://graph.microsoft.com/beta/security/tiIndicators/{id}
List TI Indicators List tiIndicators (preview) https://graph.microsoft.com/beta/security/tiIndicators
Create TI Indicator Create tiIndicator (preview) https://graph.microsoft.com/beta/security/tiIndicators
Submit TI Indicators Submit tiIndicators (preview) https://graph.microsoft.com/beta/security/tiIndicators/submitTiIndicators
Update TI Indicators Update tiIndicator (preview)
Update multiple tiIndicators (preview)
https://graph.microsoft.com/beta/security/tiIndicators/{id}
https://graph.microsoft.com/beta/security/tiIndicators/updateTiIndicators
Delete TI Indicators Delete tiIndicator (preview)
Delete multiple tiIndicators (preview)
Delete tiIndicator by externalId (preview)
DELETE
https://graph.microsoft.com/beta/security/tiIndicators/{id}
POST
https://graph.microsoft.com/beta/security/tiIndicators/deleteTiIndicators
POST
https://graph.microsoft.com/beta/security/tiIndicators/deleteTiIndicatorsByExternalId
List secure scores List secureScores https://graph.microsoft.com/beta/security/secureScores
List secure score control profiles List secureScoreControlProfiles https://graph.microsoft.com/beta/security/secureScoreControlProfiles
Update secure score control profiles Update secureScoreControlProfiles https://graph.microsoft.com/beta/security/secureScoreControlProfiles/{id}

You can use Microsoft Graph webhooks to subscribe to and receive notifications about updates to Microsoft Graph Security API entities.

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:

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:

Explore other options to connect with the Microsoft Graph Security API:

Engage with the community: