Microsoft Graph Security
Use the Microsoft Graph integration to connect to and interact with data on Microsoft Platforms. This integration was integrated and tested with Microsoft Graph v1.0.
Use Cases
- Manage alerts
- Manage users
Authentication
For more details about the authentication used in this integration, see Microsoft Integrations - Authentication .Required Permissions
-
SecurityEvents.Read.All - Application (required for the commands:
msg-search-alerts
andmsg-get-alert-details
) -
SecurityEvents.ReadWrite.All - Application (required for updating alerts with the command:
msg-update-alert
) -
User.Read.All - Application (Only required if using the deprecated commands:
msg-get-user
andmsg-get-users
)
Configure Microsoft Graph on Cortex XSOAR
- Navigate to Settings > Integrations > Servers & Services .
- Search for Microsoft Graph.
-
Click
Add instance
to create and configure a new integration instance.
- Name : a textual name for the integration instance.
- Host URL (e.g., https://graph.microsoft.com )
- ID you received from the admin consent
- Key you received from the admin consent
- Token you received from the admin consent
- Trust any certificate (not secure)
- Use system proxy settings
- Click Test to validate the URLs, token, and connection.
Commands
You can execute these commands from the Cortex XSOAR CLI, as part of an automation, or in a playbook.
After you successfully execute a command, a DBot message appears in the War Room with the command details.
- Search alerts: msg-search-alerts
- Get details for an alert: msg-get-alert-details
- Update an alert: msg-update-alert
- Get a list of user objects: msg-get-users - Deprecated - Use the Microsoft Graph User integration instead.
- Get information for a user object: msg-get-user - Deprecated - Use the Microsoft Graph User integration instead.
1. Search alerts
List alerts (security issues) within a customer's tenant that Microsoft or partner security solutions have identified.
Required Permissions
For more information about required permissions, see the Microsoft Graph documentation.
- SecurityEvents.Read.All
- SecurityEvents.ReadWrite.All
Base Command
msg-search-alerts
Input
Argument Name | Description | Required |
---|---|---|
last_modified | When the alert was last modified (string format - YYYY-MM-DD) | Optional |
severity | Alert severity - set by vendor/provider | Optional |
category |
Category of the alert, e.g. credentialTheft, ransomware.
Categories can be added or removed by vendors. |
Optional |
time_from |
The start time (creation time of alert) for the search
(string format - YYYY-MM-DD) |
Optional |
time_to |
The end time (creation time of alert) for the search
(string format - YYYY-MM-DD) |
Optional |
filter |
Use this field to filter on any of the alert properties in the format "{property} eq '{property-value}'", e.g. "category eq 'ransomware'". For Microsoft filter syntax, see the Microsoft Graph Documentation . |
Optional |
Context Output
Path | Type | Description |
---|---|---|
MsGraph.Alert.ID | string | Alert ID |
MsGraph.Alert.Title | string | Alert title |
MsGraph.Alert.Category | string | Alert category |
MsGraph.Alert.Severity | string | Alert severity |
MsGraph.Alert.CreatedDate | date | Alert created date |
MsGraph.Alert.EventDate | date | Alert event time |
MsGraph.Alert.Status | string | Alert status |
MsGraph.Alert.Vendor | string | Alert vendor/provider |
MsGraph.Alert.MalwareStates | string | Alert malware states |
MsGraph.Alert.Vendor | string | Alert vendor |
MsGraph.Alert.Provider | string | Alert provider |
Command Example
!msg-search-alerts category=repeatedShareActivity time_from=2018-09-19
Context Example
{ "MsGraph": { "Alert": [ { "Category": "repeatedShareActivity", "CreatedDate": "2018-09-21T14:33:00Z", "EventDate": "2018-09-21T13:34:00Z", "ID": "E21C584F-EA0B-34D9-8DD6-4DABF442A232", "Provider": "Cloud Application Security", "Severity": "medium", "Status": "newAlert", "Title": "Mass share", "Vendor": "Microsoft" }, { "Category": "repeatedShareActivity", "CreatedDate": "2018-09-18T18:10:00Z", "EventDate": "2018-09-18T16:09:00Z", "ID": "F5295FF7-C6DF-49B7-B6BF-4C298D5A7510", "Provider": "Cloud Application Security", "Severity": "medium", "Status": "newAlert", "Title": "Mass share", "Vendor": "Microsoft" } ] } }
Human Readable Output
2. Get details for an alert
Get details for a specific alert.
Required Permissions
For more information about required permissions, see the Microsoft Graph documentation.
- SecurityEvents.Read.All
- SecurityEvents.ReadWrite.All
Base Command
msg-get-alert-details
Input
Argument Name | Description | Required |
---|---|---|
alert_id | The Alert ID - Provider-generated GUID/unique identifier. | Required |
fields_to_include |
Fields to fetch for specified Alert apart from the basic properties, given as comma separated values. For example: NetworkConnections,Processes.
Optional values: All, NetworkConnections, Processes, RegistryKeys, UserStates, HostStates, FileStates, CloudAppStates, MalwareStates, CustomerComment, Triggers, VendorInformation, VulnerabilityStates |
Optional |
Context Output
Path | Type | Description |
---|---|---|
MsGraph.Alert.ID | string | Alert ID |
MsGraph.Alert.Title | string | Alert title |
MsGraph.Alert.Category | string | Alert category |
MsGraph.Alert.Severity | string | Alert severity |
MsGraph.Alert.CreatedDate | date | Alert created date |
MsGraph.Alert.EventDate | date | Alert event date |
MsGraph.Alert.Status | string | Alert status |
MsGraph.Alert.VendorProvider | string | Alert vendor/provider |
MsGraph.Alert.MalwareStates | string | Alert malware states |
Command Example
!msg-get-alert-details alert_id=E21C584F-EA0B-34D9-8DD6-4DABF442A232 fields_to_include=VendorInformation
Context Example
{ "MsGraph": { "Alert": { "Category": "repeatedShareActivity", "CreatedDate": "2018-09-21T14:33:00Z", "EventDate": "2018-09-21T13:34:00Z", "ID": "E21C584F-EA0B-34D9-8DD6-4DABF442A232", "MalwareStates": [], "Severity": "medium", "Status": "newAlert", "Title": "Mass share" } } }
Human Readable Output
3. Update an alert: msg-update-alert
Update an editable alert property within any integrated solution to keep alert status and assignments in sync across solutions using its reference ID.
Required Permissions
For more information about required permissions, see the Microsoft Graph documentation.
- SecurityEvents.Read.All
- SecurityEvents.ReadWrite.All
Base Command
msg-update-alert
Input
Argument Name | Description | Required |
---|---|---|
alert_id | Alert ID. Provider-generated GUID/unique identifier. | Required |
assigned_to | Name of the analyst the alert is assigned to for triage, investigation, or remediation. | Optional |
closed_date_time | Time that the alert was closed (string format - MM/DD/YYYY) | Optional |
comments | Analyst comments on the alert (for customer alert management) | Optional |
feedback | Analyst feedback on the alert. | Optional |
status | Alert lifecycle status (stage). | Optional |
tags | User-definable labels that can be applied to an alert and can serve as filter conditions, e.g. "HVA", "SAW"). | Optional |
vendor_information | Details about the security service vendor, e.g. Microsoft | Optional |
provider_information | Details about the security service vendor, e.g. Windows Defender ATP | Optional |
Context Output
Path | Type | Description |
---|---|---|
MsGraph.Alert.ID | string | Alert ID |
MsGraph.Alert.Status | string | Alert status |
Command Example
!msg-update-alert alert_id=E21C584F-EA0B-34D9-8DD6-4DABF442A232 provider_information="Cloud Application Security" vendor_information=Microsoft status=inProgress
Human Readable Output
Alert E21C584F-EA0B-34D9-8DD6-4DABF442A232 has ben successfully updated.
4. Get a list of user objects: msg-get-users
Retrieve a list of user objects.
Required Permissions
For more information about required permissions, see the Microsoft Graph documentation.
- User.Read.All
- User.ReadWrite.All
- Directory.Read.All
- Directory.ReadWrite.All
Base Command
msg-get-users
Context Output
Path | Type | Description |
---|---|---|
MsGraph.User.ID | string | User ID |
MsGraph.User.Name | string | User name |
MsGraph.User.Email | string | User email address |
MsGraph.User.Title | string | User job title |
Command Example
!msg-get-users
Context Example
{ "MsGraph": { "User": { "Email": "steve@demisto.com", "ID": "17174111-8edf-4613-97d4-74c605c5c181", "Name": "Steve Jobs", "Title": "Manager" } } }
Human Readable Output
5. Get information for a user object
Retrieve the properties and relationships of user object.
Base Command
msg-get-user
Input
Argument Name | Description | Required |
---|---|---|
user_id | User ID of user to retreive | Required |
Context Output
Path | Type | Description |
---|---|---|
MsGraph.User.ID | string | User ID |
MsGraph.User.Name | string | User name |
MsGraph.User.Email | string | User email address |
MsGraph.User.Title | string | User job title |
Command Example
!msg-get-user user_id=17174111-8edf-4613-97d4-74c605c5c181
Context Example
{ "MsGraph": { "User": { "Email": "steve@demisto.com", "ID": "17174111-8edf-4613-97d4-74c605c5c181", "Name": "Steve Jobs", "Title": "Manager" } } }
Human Readable Output
Troubleshooting
If not all expected alerts were returned, it is possible that partial content was returned from Microsoft Graph. If so, the response headers will be printed to Cortex XSOAR logs, and you can find more details under the **Warning** header. For more information, see the Microsoft Graph documentation .
Known Limitations
Microsoft does not support updating alerts with Office 365 Security and Compliance set as provider.