Learn to work with the Microsoft Graph Security API
The API assists organizations that want to connect their security systems with a programmatic way to produce quicker results when performing investigations.
As enterprises add more security layers to protect their environments, one underpinning technology helps IT to connect the dots if a security incident occurs.
Administrators have experienced management growing pains when the organization enlists more cloud services, but the Microsoft Graph is the company's recent initiative to provide a consistent way to gather information from multiple cloud platforms. Microsoft Graph is an API that streamlines administrative access to objects and resources in Azure, Office 365/Microsoft 365 and other cloud-based services from Microsoft. As part of this effort, the Microsoft Graph Security API offers a single programmatic interface to connect security products from Microsoft and its partners. By combining Microsoft Graph Security with PowerShell, admins can automate alerts to take action if a security incident occurs.
Why use the Microsoft Graph Security?
Cyber attacks continue to intensify and hit enterprises around the world. In many cases, organizational or infrastructure damage has already occurred before any identification of a data or security breach is completed. The Microsoft Graph Security extends existing security applications and products to correlate security alerts from multiple sources to help the organization uncover threats and unlock contextual data to provide insights and prevent further damage.
Microsoft also offers the Intelligent Security Graph, which gathers general security intelligence from Microsoft, global security operations centers and Microsoft security partners. This integration links security platforms and services that use machine learning and behavioral monitoring for additional assistance with protection, detection and response to security threats. The Microsoft Graph Security connects organizations directly to the Intelligent Security Graph.
The Microsoft Graph Security does not apply security policies but gives organizations easier access to security-related data from multiple sources. It helps organizations and partners to integrate or build applications to perform various security functions, including:
- aggregate and correlate security alerts from multiple sources;
- retrieve contextual data for investigations;
- automate security tasks, business processes, workflows and reporting;
- send threat indicators to Microsoft products for enhanced detections;
- invoke operations in response to new threats; and
- start proactive risk management.
What is available within the Microsoft Graph Security?
The Microsoft Graph Security has multiple core entities to query: alerts, information protection, threat indicators, security actions and Secure Score.
- Alerts. Alerts are potential security issues found within Microsoft 365 and Azure tenants by Microsoft or a partner product, then surfaced within the Graph. The default alert providers are the Azure Security Center, Azure Active Directory Identity Protection, Microsoft Cloud App Security, Microsoft Defender for Endpoint, Microsoft Defender for Identity, Microsoft 365, Azure Information Protection and Azure Sentinel.
- Information protection. Information protection, such as the sensitivity label applied to the content, gives the organization a way to evaluate potential threats. Information protection details combine with threat assessment information from spam, phishing or malware reports identified by Microsoft 365 services.
- Threat indicators. Threat indicators signify data about recognized threats, such as malicious URLs, domains, IP addresses and files, which is imported in a security tool to protect the environment. Microsoft also refers to these as threat intelligence indicators and indicators of compromise. Indicators sent into the Microsoft Graph Security are currently available within Azure Sentinel and Microsoft Defender Advanced Threat Protection.
- Security Actions. Security teams can invoke a specific action based on an identified threat returned within the Microsoft Graph Security. For example, confirmed malicious files, URLs, domains or IP addresses could automatically activate specific security controls or blocking.
- Secure Score. Microsoft's Secure Score security analytics tool grades the current tenant's security posture. Using the Microsoft Graph Security API, organizations can create reports to see where it can reduce risk within Microsoft applications, platforms and services.
How to work with Microsoft Graph Security
Each supported entity provides an endpoint within Microsoft Graph Security. The easiest way to test the Microsoft Graph Security is to use the Graph Explorer available at this link. Admins can use this online tool for different security-related jobs, such as testing Microsoft Graph endpoints, which include Graph Security.
To use the Graph Explorer, sign in as a global administrator or with an account with rights to retrieve security information. Accept the permissions request by either granting consent for just the logged-in account or for the entire organization. Next, set the version of the graph and the specific URL of the data to retrieve. For this example, set the HTTP method to GET, select beta for the Microsoft Graph version and enter https://graph.microsoft.com/beta/security/alerts for the URL.
Once completed, click Run query to retrieve the results. If a 401 error occurs, click the Modify permissions tab and check the missing permissions.
Grant consent, then reissue the same query. If there are alerts within the tenant, the query will return results in JavaScript Object Notation (JSON) format. The advantages of JSON are it loads fast, is easy to query and is simple to import to other applications.
The Graph Explorer offers several prebuilt queries, including several in the Security category, that show the capabilities of the Microsoft Graph Security API. Use of filters and values in queries sends customized calls to the Microsoft Graph Security to extract specific information, such as showing only new alerts or just the high-severity alerts.
The Graph Explorer is helpful to test the available endpoints, but it is not the best way to view the information. There are multiple connectors to use with Microsoft Graph Security, including Power Automate (formerly Microsoft Flow) and Power BI, but PowerShell is another excellent option to query Graph Security data. To get started, use the following configuration steps to perform app registration in Azure Active Directory:
- Set the implicit grant for access tokens
- Add the following delegated permissions:
- SecurityEvents.Read.All
- SecurityEvents.ReadWrite.All
- SecurityActions.Read.All
- SecurityActions.ReadWrite.All
- Set redirect URI to urn:ietf:wg:oauth:2.0:oob
- Create a secret for connecting
How to use PowerShell with the Graph Security
To start using PowerShell with the Microsoft Graph Security, import the PowerShell module and start the connection.
# Install the Microsoft Graph Security PowerShell Module
Install-Module MicrosoftGraphSecurity # Import the Microsoft Graph Security PowerShell Module
Import-Module MicrosoftGraphSecurity # Set the Login Account and App ID (details from the App Registration)
Get-GraphSecurityCredential
When prompted, use the account login and the application ID from the app registration.
Next, now query specific information such as alerts and the Secure Score details. To query all or specific alerts, try the following commands:
# Retrieve all security alerts
Get-GraphSecurityAlert # Retrieve security alert by ID
Get-GraphSecurityAlert ` -ID 19d165f2510e09cc4434d212d02ca2d2660c03edcf432eb9e43558a9i835a2we # Retrieve security alert by User
Get-GraphSecurityAlert –userPrincipalName [email protected]
PowerShell's integration capabilities let admins export alerts locally and inspect them within other platforms as needed. Different approaches provide integration with Azure Logic Apps, Power Automate, Power BI and programming languages, such as Python, C#, NodeJS and .NET.
Microsoft's Graph Security also supports common integration types, including Security Incident and Management, Security Response and Orchestration, and Incident Tracking and Service Management.
