Understanding Microsoft Graph Security API: The Gateway to Microsoft's Security Universe

Understanding Microsoft Graph Security API: The Gateway to Microsoft’s Security Universe

Posted in

What Is the Microsoft Intelligent Security Graph?

The Microsoft Intelligent Security Graph is a component of the central control plane Microsoft Graph, providing a data plane that centralizes telemetry from across Microsoft applications. It uses machine learning to provide actionable security alerts and recommendations. The Intelligent Security Graph lets you access data collected from all Microsoft products, which other applications can utilize.

The Intelligent Security Graph works as a policy engine to control and store data from highly distributed sources. It makes it easier to access, process, and analyze Microsoft data. You can access this data from any console with highly customizable views.

Microsoft has possibly the largest digital ecosystem worldwide, with visibility over all Windows machines and Office data, as well as over 200 other Microsoft products. It thus has the biggest data lake for performance and security analytics.

Two Microsoft competitors offer similar data offerings: Citrix Analytics and VMware Workspace ONE. While both companies have smaller data lakes, they still provide a formidable amount of security data. Citrix and VMware solutions are both policy engines that store data and allow users to access it, analyze it, and enforce policy decisions based on it.

A key difference is that both Citrix and VMware provide pre-built dashboards where admins can view and manage alerts. In contrast, Microsoft does not provide a UI for its Security Graph, only enabling access via API.

What Is Microsoft Graph Security API?

The Microsoft Graph Security API is a broker providing a programmatic interface that connects several Microsoft Graph Security providers. Microsoft Graph provides unified access to data and intelligence collected across Microsoft 365, Enterprise Mobility + Security, and Microsoft Windows. You can use this information to build more secure applications.

The Microsoft Graph Security API is an intermediary service that lets you establish connections between various Microsoft security services, products, and partners. Microsoft federates requests made to the API to all relevant security providers and aggregates and returns the results to the requesting application in a shared schema.

You can leverage the Microsoft Graph Security API to streamline your security operations and enhance your threat detection and response processes.

Security Solutions Integrated With the Microsoft Graph Security API

The Microsoft Graph Security API allows you to integrate various security services and products offered by Microsoft and its partners. It provides a single integration that establishes a unified format for working with data across the Microsoft and partners ecosystem. The integration supports various Microsoft security offerings, including:

  • Microsoft 365 Defender: This eXtended detection and response (XDR) offering can automatically collect, correlate, and analyze threats, alerts, and signal data across the Microsoft 365 ecosystem, including emails, applications, identities, and endpoint. The solution employs artificial intelligence (AI) and automation to stop attacks and restore affected assets to a known safe state.
  • Microsoft Defender for Cloud: This solution includes a cloud workload protection platform (CWPP) coupled with cloud security posture management (CSPM) capabilities. It supports resources hosted on Azure, multi-cloud architectures using Azure with other cloud vendors like Google Cloud and Amazon Web Services (AWS), and on-premises resources.
  • Microsoft Defender for Cloud Apps: This cloud access security broker (CASB) supports several deployment types, such as API connectors and reverse proxy. It offers extended visibility, data flow controls, and analytics functionality to identify and protect against cyberthreats across Microsoft and third-party cloud services.
  • Microsoft Defender for Endpoint: This enterprise endpoint security platform provides threat prevention, detection, investigation, and response. It helps protect enterprise networks against endpoint threats by extending visibility and establishing automated responses.
  • Microsoft Defender for Identity: This cloud-based solution uses on-premises Azure Active Directory (AD) signals to detect and investigate various malicious activities, including advanced threats, malicious insider actions, and compromised identities.

Graph Security API Use Cases

You can use various methods to connect applications using the Microsoft Graph Security API, including writing code and using scripts or Jupyter notebooks. Here are the primary use cases for the Microsoft Graph Security API:

Standardize Alert Tracking

The Microsoft Graph Security API lets you integrate security alerts from supported solutions and ensure alert assignments and status remain in sync across the entire ecosystem. It enables you to use API connectors to stream alerts to a security information and event management (SIEM) solution like Splunk or Exabeam.

Aggregate Security Alerts

The Microsoft Graph Security API provides a common alert schema for correlating alerts across distributed security solutions. It enables you to access actionable information from alerts, pivot alerts, and enrich them with user and asset information. As a result, teams and solutions can respond faster to threats and quickly protect assets.

Update Alert Information

The API lets you tag alerts to add more context or threat intelligence. This information helps guide response and remediation. You can ensure visibility into all workshops by capturing all feedback and comments on alerts. You can also keep alert assignments and status in sync to ensure each integrated solution reflects the current state and uses webhooks to set up notifications.

Add Security Context

The API lets you add security context to your investigations to dive deep into relevant security inventory such as users, apps, and hosts. To improve threat response, you can add organization-specific context from additional Microsoft Graph providers, including Azure AD, Microsoft 365, and Microsoft Intune.

Automate Workflows

Integrating Microsoft Graph Security into your dashboards and reports provides deeper insight into your security posture. It can help you automate security monitoring, investigations, and management to improve operations and response times.

Train Security Solutions

Groups could leverage this product to visualize data across multiple security products. The data can help you discover opportunities to learn and train security solutions. Additionally, the schema offers several properties to help you pivot and build rich exploratory datasets with your security data.

Manage Security Risks

Microsoft Secure Score provides visibility into security needs and offers improvement suggestions. It also provides a score that assesses the situation after suggestions are incorporated. You can use it to measure progress over time and gain insights into specific changes that helped improve your score.

Using the Microsoft Graph Security API

The Microsoft Graph Security API is comprised of several entities, including:


A securityAction entity enables immediate action to protect against threats in your Microsoft security solutions. When you discover a new indicator of attacks (IoA) like a URL, a malicious file, IP address, or domain, the securityAction entity can respond.

The Microsoft Graph Security API lets you invoke a securityAction for a certain provider, view all past actions, and cancel actions when needed. You can also use security actions with Microsoft Defender for Endpoint to prevent malicious activity on Windows endpoints.

You can read the properties and relationships of a certain securityAction object or post it to the securityActions collection to create a new securityAction. You can also list security actions to get a securityAction object collection.

Here’s how you can create a securityAction object:

POST https://graph.microsoft.com/beta/security/securityActions
Content-type: application/json
  "name": "BlockIp",
  "actionReason": "Test",
  "parameters": [
      "name": "IP",
      "value": ""
  "vendorInformation": {
    "provider": "Windows Defender ATP",
    "vendor": "Microsoft"

Attack Simulation and Training

Attack simulation and training is a service that simulates a realistic benign phishing attack. Users can experience this simulation and derive insights for better security conduct. The service is offered through Microsoft Defender for Office 365.

Tenant administrators can create simulations and assign training. Once the simulation is complete, administrators can read insights into user behaviors during phishing simulations. The API lets administrators get a list of simulation objects and their properties.

The service also provides attack simulation reports to help identify security knowledge gaps, helping further train users to make them less susceptible to phishing attacks. Administrators can use the simulationReportOverview command to get an overview of an attack simulation.

Here is how to get an overview of the simulations:

GET [https://graph.microsoft.com/beta/security/attackSimulation/simulations/{id}/report/overview](https://graph.microsoft.com/beta/security/attackSimulation/simulations/%7Bid%7D/report/overview)


An alert represents a possible security issue within your tenant environment. It is identified and created by either Microsoft or a partner security solution. The alert may require action, or it may be pushed only to notify the relevant stakeholders.

The Microsoft Graph Security alerts feature lets you unify and streamline security management across all your integrated security solutions. It enables applications to correlate alerts and context to improve threat protection and response.

It also provides an alert update capability to let you synchronize the status of certain alerts across the security solutions integrated with the Microsoft Graph Security API. You can read your alert object’s properties and relationships, update the alert object, or list alerts to get a collection of alert objects.

Here is how you can get an alert:

GET https://graph.microsoft.com/v1.0/security/alerts/{alert_id}

Information Protection

You can set up information protection using the Microsoft Graph threat assessment API. It can help assess the threat received by users in a tenant. Tenant administrators can use it to understand the results of the threat scanning and adjust the organizational policy accordingly.

The Microsoft Graph threat assessment API lets you create, get, and list threat assessment requests and retrieve the assessment results. A threat assessment request can include mail, file, URL, or email file.

Here is how to create a mail assessment request:

POST https://graph.microsoft.com/v1.0/informationProtection/threatAssessmentRequests
Content-type: application/json
  "@odata.type": "#microsoft.graph.mailAssessmentRequest",
  "recipientEmail": "tifc@a830edad9050849EQTPWBJZXODQ.onmicrosoft.com",
  "expectedAssessment": "block",
  "category": "spam",
  "messageUri": "https://graph.microsoft.com/v1.0/users/c52ce8db-3e4b-4181-93c4-7d6b6bffaf60/messages/AAMkADU3MWUxOTU0LWNlOTEt="

Secure Score

Secure Score is an analytics solution that provides visibility and insights into your security portfolio and helps you reduce security risk across Microsoft solutions. It indicates the current security posture and lets you compare your organization’s score with other organizations’ scores.

You can use the Microsoft Graph Security secureScoreControlProfile and secureScore entities to balance security and productivity needs. The API lets you list scores to get a secureScore object collection and obtain a secureScore object’s read information like properties and metadata.

Here’s how to get a secureScore:

GET https://graph.microsoft.com/v1.0/security/secureScores/{id}


In this article, I explained the basics of the Microsoft Intelligent Security Graph and the Graph Security API. I showed how to use the API to perform the following security activities:

  1. Actions: Creating a ‘securityAction’ entity lets you take immediate action to protect against threats in Microsoft security solutions.
  2. Attack simulation and training: Launching a realistic attack simulation that does not cause actual damage can help you test your security readiness.
  3. Alerts: A possible security issue in your environment identified by a Microsoft security solution or any integrated partner solution.
  4. Information protection: Helps assess the risk level of a threat based on Microsoft’s extensive threat intelligence database.
  5. Secure Score: An easy-to-read score that quantifies the security posture of a computing resource and lets you quickly identify unsecured resources.

I hope this will be useful as you make use of Microsoft’s troves of security information to secure your organization’s environment.