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

  1. Manage alerts
  2. 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 and msg-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 and msg-get-users )

Configure Microsoft Graph on Cortex XSOAR

  1. Navigate to Settings > Integrations > Servers & Services .
  2. Search for Microsoft Graph.
  3. 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
  4. 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.

  1. Search alerts: msg-search-alerts
  2. Get details for an alert: msg-get-alert-details
  3. Update an alert: msg-update-alert
  4. Get a list of user objects: msg-get-users - Deprecated - Use the Microsoft Graph User integration instead.
  5. 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

screen shot 2018-09-26 at 12 29 33

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

screen shot 2018-09-26 at 12 33 24

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

screen shot 2018-09-26 at 15 36 31

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

screen shot 2018-09-26 at 15 43 39

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.

Edit this page
Report an Issue