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.ReadWrite.All - Application
  • User.Read.All - Application
  • User.Read - Delegated
  • User.ReadWrite.All - Application
  • Directory.Read.All - Delegated
  • Directory.ReadWrite.All - Application
  • 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 Demisto 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
    5. Get information for a user object: msg-get-user

    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 Demisto logs, and you can find more details under the Warning header. For more information, see the Microsoft Graph documentation .