We now have a new PowerShell module for the Microsoft Graph Security API that makes it easier for IT Pros to connect with the API from a PowerShell console. This module is available on the PowerShell gallery, thanks to a community contribution from the Microsoft Cloud Security’s Customer Experience Engineering team.
The Microsoft Graph Security API connects multiple security solutions to enable easier correlation of alerts, provide access to rich contextual information, simplify automations and investigations. This empowers organizations to quickly gain insights and take actions across their security products, while reducing the cost and complexity of building and maintaining multiple integrations. For further details on integrating with the Microsoft Graph Security API, learn about the API and access the schema.
Getting Started
Use this module to get access to security alerts and Secure Score information in your Azure Active Directory (Azure AD) tenant across different security products. Refer to the documentation for further details.
- Ensure you have PowerShell v5 or above (standard on Windows 10).
- Register your application for this PowerShell Module in Azure AD in user-delegated mode. As part of this,
a. Select 'Add Platform' (under Platforms)
b. Select 'Native Application'
c. Retain redirect URI as 'urn:ietf:wg:oauth:2.0:oob' - this is needed for desktop application redirect to work.
- Configure permissions and be sure to add the SecurityEvents.ReadWrite.All permission to your application. Get your Azure AD tenant administrator to grant tenant administrator consent to your application. This is a one-time activity unless permissions change for the application.
- Open your PowerShell terminal as an administrator and install the module by running the Install-Module MicrosoftGraphSecurity command as shown in the diagram below:
*If this is your first time installing a module, you will be prompted to install the Nuget Package Provider.
Authentication
You’ll need to authenticate before you can start getting and updating data from Microsoft Graph Security API. Authentication will be triggered upon initial data access or when authentication expires.
- Enter Get-GraphSecurityAlert
- Enter your username and the application ID (from the application registration process in getting started section) when prompted, as illustrated below.
Authentication
- Enter your password when prompted. Upon successful authentication, the connection with Microsoft Graph Security API is established and you will get a list of alerts.
User Scenarios
This covers a representative set of scenarios. Refer to the documentation for the complete list of supported PowerShell command line switches associated with each command to tailor this for your scenario.
Get latest alerts for Security Management
You can get top alerts using this module by the command Get-GraphSecurityAlert -top 1. This returns the recent most alert received from each of the security products running in your Azure AD tenant supported by the Microsoft Graph Security API. This enables you to correlate recent suspicious patterns raised by different security products.
Get alerts for security management
Investigate alerts associated with a user
You can add multiple command line switches to get alerts across different security products filtered by user principal name, for example,
Get-GraphSecurityAlert -userPrincipalName <enter the value> -severity medium -Verbose | select title, status, description, assignedTo, severity, userStates
as illustrated below. This enables initial investigations where suspicious user activities reported by different security products can be plotted to understand where to plan the next level of investigations.
Investigate alerts
Customize get alerts to your scenario
Run the Get-GraphSecurityAlert -<ctrlkey><space> command to get a list of all properties that you can filter to get your alerts as illustrated in the following diagram. Navigate to know supported types for each of these switches using your arrow keys. For example, in the diagram below we can see -Version switch expects a string type value. You can build your commands using different property values available to get alerts based on your scenario for customized security management and investigations.
List of switches for Get-GraphSecurityAlert
Update alerts for better security management
You can update alerts by the Set-GraphSecurityAlert -id <enter the value> command. You can update the status of the alert to resolved as shown in this example below or even assign an alert for investigation or tag alerts to filter those as needed for better security management.
Run the Set-GraphSecurityAlert -<ctrlkey><space> command to get a list of all properties that you can use to build your update alert command.
Update alert
Get Secure Score for understanding security posture
You can also get secure score information by the Get-GraphSecuritySecureScore command as illustrated below to get details on the security posture of your organization and to determine what remediations are needed to improve the score over time.
Run the Get-GraphSecuritySecureScore -<ctrlkey><space> command to get a list of all switches that you can use to build your secure score command.
Get Secure Score
Closing
Try out the new Microsoft Graph Security API PowerShell module and provide your feedback by filing a GitHub issue in the PowerShell module repo.