Use the Microsoft Graph security API

Article
03/16/2023

Important

APIs under the /beta version in Microsoft Graph are subject to change. Use of these APIs in production applications is not supported. To determine whether an API is available in v1.0, use the Version selector.

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.
Pull and investigate all incidents and alerts from services that are part of or integrated with Microsoft 365 Defender.
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 provides key features as described in the following sections.

Actions (preview)

Take immediate action to defend against threats using the 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 for Endpoint (formerly Microsoft Defender ATP) 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.

Advanced hunting

Advanced hunting is a query-based threat hunting tool that lets you explore up to 30 days of raw data. You can proactively inspect events in your network to locate threat indicators and entities. The flexible access to data enables unconstrained hunting for both known and potential threats.

Use runHuntingQuery to run a Kusto Query Language (KQL) query on data stored in Microsoft 365 Defender. Leverage the returned result set to enrich an existing investigation or to uncover undetected threats in your network.

Quotas and resource allocation

You can run a query on data from only the last 30 days.
The results include a maximum of 100,000 rows.
The number of executions is limited per tenant:
- API calls: Up to 45 requests per minute, and up to 1500 requests per hour.
- Execution time: 10 minutes of running time every hour and 3 hours of running time a day.
The maximal execution time of a single request is 200 seconds.
A response code of HTTP 429 means you have reached the quota for either the number of API calls or execution time. Refer to the response body to confirm the limit you have reached.
The maximum query result size of a single request cannot exceed 124 MB. Exceeding the size limit results in HTTP 400 Bad Request with the message "Query execution has exceeded the allowed result size. Optimize your query by limiting the number of results and try again."

Alerts

Alerts are detailed warnings about suspicious activities in a customer's tenant that Microsoft or partner security providers have identified and flagged for action. Attacks typically employ various techniques against different types of entities, such as devices, users, and mailboxes. The result is alerts from multiple security providers for multiple entities in the tenant. Piecing the individual alerts together to gain insight into an attack can be challenging and time-consuming.

The beta version of the security API offers two types of alerts that aggregate other alerts from security providers and make analyzing attacks and determining response easier:

Alerts and incidents - these are the latest generation of alerts in the Microsoft Graph security API. They are represented by the alert resource and its collection, incident resource, defined in the microsoft.graph.security namespace.
Legacy alerts - these are the first generation of alerts in the Microsoft Graph security API. They are represented by the alert resource defined in the microsoft.graph namespace.

Alerts and incidents

These alert resources first pull alert data from security provider services, that are either part of or integrated with Microsoft 365 Defender. Then they consume the data to return rich, valuable clues about a completed or ongoing attack, the impacted assets, and associated evidence. In addition, they automatically correlate other alerts with the same attack techniques or the same attacker into an incident to provide a broader context of an attack. They recommend response and remediation actions, offering consistent actionability across all the different providers. The rich content makes it easier for analysts to collectively investigate and respond to threats.

Alerts from the following security providers are available via these rich alerts and incidents:

Legacy alerts

These alert resources federate calling of supported Azure and Microsoft 365 Defender security providers. They aggregate common alert data among the different domains to allow applications to unify and streamline management of security issues across all integrated solutions. They enable 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 alert entity.

Alerts from the following security providers are available via this legacy alert resource. 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
Azure Active Directory Identity Protection	✓	File issue *	✓
Azure Security Center	✓	✓	✓
Microsoft 365 Default Cloud App Security Custom Alert	✓	File issue	File issue
Microsoft Defender for Cloud Apps (formerly Microsoft Cloud App Security)	✓	File issue *	✓
Microsoft Defender for Endpoint (formerly Microsoft Defender ATP) **	✓	✓	File issue
Microsoft Defender for Identity (formerly Azure Advanced Threat Protection) ***	✓	File issue *	✓
Microsoft Sentinel (formerly Azure Sentinel)	✓	Not supported in Microsoft 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.

Attack simulation and training

Attack simulation and training is part of Microsoft Defender for Office 365. This service lets users in a tenant experience a realistic benign phishing attack and learn from it. Social engineering simulation and training experiences for end users help reduce the risk of users being breached via those attack techniques. The attack simulation and training API enables tenant administrators to view launched simulation exercises and trainings, and get reports on derived insights into online behaviors of users in the phishing simulations.

eDiscovery (preview)

Microsoft Purview eDiscovery (Premium) provides an end-to-end workflow to preserve, collect, analyze, review, and export content that's responsive to your organization's internal and external investigations.

Incidents

An incident is a collection of correlated  alerts and associated data that make up the story of an attack. Incident management is part of Microsoft 365 Defender, and is available in the Microsoft 365 Defender portal (https://security.microsoft.com/).

Microsoft 365 services and apps create  alerts  when they detect a suspicious or malicious event or activity. Individual alerts provide valuable clues about a completed or ongoing attack. However, attacks typically employ various techniques against different types of entities, such as devices, users, and mailboxes. The result is multiple  alerts for multiple entities in your tenant.

Because piecing the individual alerts together to gain insight into an attack can be challenging and time-consuming, Microsoft 365 Defender automatically aggregates the alerts and their associated information into an incident.

Grouping related alerts into an incident gives you a comprehensive view of an attack. For example, you can see:

Where the attack started.
What tactics were used.
How far the attack has gone into your tenant.
The scope of the attack, such as how many devices, users, and mailboxes were impacted.
All of the data associated with the attack.

The  incident resource and its APIs allow you to sort through incidents to create an informed cyber security response. It exposes a collection of incidents, with their related  alerts, that were flagged in your network, within the time range you specified in your environment retention policy.

Information protection

Labels - Information protection labels provide details about how to properly apply a sensitivity label to information. The information protection label API describes the configuration of sensitivity labels that apply to a user or tenant.

Threat assessment - 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 or suspicious emails, phishing URLs, or malware attachments they receive to Microsoft. Microsoft check the sample in question and the organizational policies in play before generating a result so that tenant administrators can understand the threat scanning verdict and adjust their organizational policy. They can also use it to report legitimate emails to prevent them from getting blocked.

Note: We recommend that you use the threat submission API instead.

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 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.

Threat intelligence (preview)

Microsoft Defender Threat Intelligence delivers world-class threat intelligence to help protect your organization from modern cyber threats. You can use Threat Intelligence to identify adversaries and their operations, accelerate detection and remediation, and enhance your security investments and workflows.

The threat intelligence APIs (preview) allow you to operationalize intelligence found within the user interface. This includes finished intelligence in the forms of articles and intel profiles, machine intelligence including IoCs and reputation verdicts, and finally, enrichment data including passive DNS, cookies, components, and trackers.

Threat intelligence 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 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):

Palo Alto Networks MineMeld Threat Intelligence Sharing
MISP Open Source Threat Intelligence Platform available through the TI sample

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

Azure Sentinel – Enables you to correlate threat indicators with log data to get alerts on malicious activity.
Microsoft Defender for Endpoint – Enables you to alert and/or block on threat indicators associated with malicious activity. You can also allow an indicator for ignoring the indicator from automated investigations. For details about the types of indicators supported and limits on indicator counts per tenant, see Manage indicators.

Support in other Microsoft security services will be available soon.

Threat submission

The Microsoft Graph threat submission API helps organizations to submit a threat received by any user in a tenant. This empowers customers to report spam or suspicious emails, phishing URLs, or malware attachments they receive to Microsoft. Microsoft checks the submission against the organizational policies in effect and sends it to human graders for analysis. The result then helps tenant administrators understand the threat scanning verdict and adjust their organizational policy. Admins can also use the results to report legitimate emails to prevent them from getting blocked.

Note: We recommend that you use this API instead of the deprecated Information Protection threat assessment API. The threat submission API provides unified security threat submission functionality and adds unified result support, user submission query support, tenant allow block list support, admin review support and app-only mode support.

Common use cases

The following are some of the most popular requests for working with the Microsoft Graph security API.

Use cases	REST operations	Try it in Graph Explorer
Actions (preview)
Get security action	Get security action	https://graph.microsoft.com/beta/security/securityActions/{id}
List security actions	List security actions	https://graph.microsoft.com/beta/security/securityActions
Create security actions	Create security actions	https://graph.microsoft.com/beta/security/securityActions
Cancel security action	Cancel security actions	https://graph.microsoft.com/beta/security/securityActions/{id}/cancelSecurityAction
Alerts and incidents
List alerts	List alerts	https://graph.microsoft.com/beta/security/alerts_v2
Update alert	Update alert	https://graph.microsoft.com/beta/security/alerts/{id}
List incidents	List incidents	https://graph.microsoft.com/beta/security/incidents
List incidents with alerts	List incidents	https://graph.microsoft.com/beta/security/incidents?$expand=alerts
Update incident	Update incident	https://graph.microsoft.com/beta/security/incidents/{id}
Attack simulation and training
List simulations	List simulations	https://graph.microsoft.com/beta/security/attackSimulation/simulations
Get simulation overview report	Get simulation overview report	https://graph.microsoft.com/beta/security/attackSimulation/simulations/{id}/report/overview
List simulation users report	List simulation users report	https://graph.microsoft.com/beta/security/attackSimulation/simulations/{id}/report/simulationUsers
eDiscovery
List eDiscovery cases	List eDiscoveryCases	https://graph.microsoft.com/beta/security/cases/eDiscoveryCases
List eDiscovery case operations	List caseOperations	https://graph.microsoft.com/beta/security/cases/ediscoveryCases/{id}/operations
Legacy alerts
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
Secure scores
List secure scores	List secureScores	https://graph.microsoft.com/beta/security/secureScores
Secure score control profiles
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}
Threat intelligence indications (preview)
Get TI indicator	Get tiIndicator	https://graph.microsoft.com/beta/security/tiIndicators/{id}
List TI Indicators	List tiIndicators	https://graph.microsoft.com/beta/security/tiIndicators
Create TI Indicator	Create tiIndicator	https://graph.microsoft.com/beta/security/tiIndicators
Submit TI Indicators	Submit tiIndicators	https://graph.microsoft.com/beta/security/tiIndicators/submitTiIndicators
Update TI Indicators	Update tiIndicator Update multiple tiIndicators	https://graph.microsoft.com/beta/security/tiIndicators/{id} https://graph.microsoft.com/beta/security/tiIndicators/updateTiIndicators
Delete TI Indicators	Delete tiIndicator Delete multiple tiIndicators Delete tiIndicator by externalId	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
Threat submission
Get email threat submission	Get emailThreat	https://graph.microsoft.com/beta/security/threatSubmission/emailThreats/{id}
List email threat submissions	List emailThreats	https://graph.microsoft.com/beta/threatSubmission/emailThreats
Create email threat submission	Create emailThreat	https://graph.microsoft.com/beta/security/threatSubmission/emailThreats
Review email threat submission	Review emailThreat	https://graph.microsoft.com/beta/security/threatSubmission/emailThreats/{id}/review
Get file threat submission	Get fileThreat	https://graph.microsoft.com/beta/security/threatSubmission/fileThreats/{id}
List file threat submissions	List fileThreats	https://graph.microsoft.com/beta/threatSubmission/urlThreats
Create file threat submission	Create fileThreat	https://graph.microsoft.com/beta/security/threatSubmission/fileThreats
Get url threat submission	Get urlThreat	https://graph.microsoft.com/beta/security/threatSubmission/urlThreats/{id}
List url threat submissions	List urlThreats	https://graph.microsoft.com/beta/security/threatSubmission/urlThreats
Create url threat submission	Create urlThreat	https://graph.microsoft.com/beta/security/threatSubmission/urlThreats
Get email threat submission policy	Get emailThreatSubmissionPolicy	https://graph.microsoft.com/beta/security/threatSubmission/emailThreatSubmissionPolicies/{id}
List email threat submission policies	List emailThreatSubmissionPolicies	https://graph.microsoft.com/beta/security/threatSubmission/emailThreatSubmissionPolicies
Create email threat submission policy	Create emailThreatSubmissionPolicy	https://graph.microsoft.com/beta/security/threatSubmission/emailThreatSubmissionPolicies
Update email threat submission policy	Update emailThreatSubmissionPolicy	https://graph.microsoft.com/beta/security/threatSubmission/emailThreatSubmissionPolicies/{id}
Delete email threat submission policy	Delete emailThreatSubmissionPolicy	https://graph.microsoft.com/beta/security/threatSubmission/emailThreatSubmissionPolicies/{id}

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

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, tiIndicator (preview), securityAction (preview), 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.