PowerShell and the Microsoft Graph Security API
A brief introduction to the power of PowerShell in Security
As the nature of security operations continues to evolve, so must the tools and the practitioners. With a wide array of new shiny tools on the market, and the continual addition of new programming and query languages hitting the metaphorical shelves at the speed of light, it’s easy to become disenchanted with the environments we know and trust. This is especially true for those of us who have been embedded in the Microsoft ecosystem for a long time and have migrated into more security-focused roles. Let this serve as a reminder that sometimes the tools we know, and love, can be just as effective as the newer and “more modern” solutions.
What is Microsoft Graph Security API?
The Microsoft Graph Security API is a pivotal element in Microsoft’s security architecture. It provides a unified interface and schema to integrate with security solutions from Microsoft and ecosystem partners. This empowers organizations to streamline security operations and better defend against increasing cyber threats. The API consolidates and correlates security alerts from multiple sources, automates security tasks, and provides visibility into security data to enable proactive risk management.
How do you access the Microsoft Graph Security API?
Connecting to the Microsoft Graph Security API requires a few steps:
Register Your Application: Begin by registering your application with the Microsoft identity platform to obtain an Application ID
Configure Permissions: Assign the necessary permissions to your application in the Azure portal. This typically involves selecting the appropriate API permissions for Microsoft Graph
Grant Admin Consent: An administrator must grant consent for the permissions requested by your application. This step is crucial for the application to access the Microsoft Graph Security API
Obtain an Access Token: Use OAuth 2.0 to acquire an access token from the Microsoft identity platform. This token will be used to authenticate API calls
Make API Calls: With the access token, your application can make authenticated calls to the Microsoft Graph Security API and access the required security data
For more specific details on how to connect, check out this document from Microsoft.
How can we leverage PowerShell with the Microsoft Graph Security API?
PowerShell, as a first-class citizen of the Microsoft ecosystem, is a fantastic tool to leverage the Microsoft Graph Security API. PowerShell is usually pre-installed on all Windows workstations without the need for additional configuration, and has the capability to make HTTP requests against REST endpoints like the Graph API without needing any additional modules!
Check out this example of connecting to the Graph Security API and querying the endpoint to get a list of alerts:
# Authenticate and connect to the Microsoft Graph Security API
$tenantId = "<Your-Tenant-ID>"
$appId = "<Your-App-ID>"
$appSecret = "<Your-App-Secret>"
$resource = "https://graph.microsoft.com"
$tokenEndpoint = "https://login.microsoftonline.com/$tenantId/oauth2/token"
$body = "resource=$resource&client_id=$appId&client_secret=$appSecret&grant_type=client_credentials"
$oauth = Invoke-RestMethod -Method Post -Uri $tokenEndpoint -Body $body -ContentType "application/x-www-form-urlencoded"
# Set the header with the access token
$headers = @{'Authorization' = "Bearer $($oauth.access_token)"}
# Query the Microsoft Graph Security API for alerts
$alertsUrl = "https://graph.microsoft.com/v1.0/security/alerts"
$alerts = Invoke-RestMethod -Uri $alertsUrl -Headers $headers -Method Get
# Output the list of alerts
$alerts.valueNote: Be sure to customize the above script template with your tenant’s specific information.
The Point
PowerShell, having been around for nearly 2 decades, can look like an outdated tool at first glance. But don’t be fooled! With the updates that have been brought to PowerShell in recent years, the introduction of Graph API, and its tight integration with Azure and M365, PowerShell for Security in a Microsoft environment is still an excellent choice for automation, data enrichment, and administration across the board. If you want to learn more, check out some of the links in the resources section to get started with PowerShell, Microsoft Graph API, and Microsoft Graph Security API.