Cortex XSOAR for Developers (Formerly Demisto)

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

Required Permissions in the MS Graph Security App:

  • SecurityEvents.ReadWrite.All - Application
  • User.Read.All - Application
  • User.Read - Delegated
  • User.ReadWrite.All - Application
  • Directory.Read.All - Delegated
  • Directory.ReadWrite.All - Application

    • Generate Authentication Parameters

    To use this integration, you have to grant access to Demisto from Microsoft Graph.

    1. Navigate to Settings > Integrations > Servers & Services .
    2. Search for Microsoft Graph Security.
    3. Click Add instance to create and configure a new integration instance.
    4. Click the question mark button in the upper-right corner and read the information, and click the link.
    5. Click the Start Authorization Process button.
    6. Log in with Microsoft admin user credentials.
    7. Authorize Demisto application to access data.
    8. When you are redirected, copy the parameter values, which you will need when configuring the integration instance in Demisto.
      • ID
      • Key
      • Token

    Configure Microsoft Graph on Demisto

    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.

    Use a Self-Deployed Azure Application

    To use a self-configured Azure application, a need to add a new Azure App Registration in the Azure Portal. To add the registration, refer to the following Microsoft article: https://docs.microsoft.com/en-us/azure/active-directory/develop/quickstart-register-app

    The Tenant ID, Client ID, and Client secret are required for the integration. To configure the integration in Demisto to use the application, place those parameters in the following manner (instead of how you received them from the admin consent in the current doc):

    ID - Client ID
    Token - Tenant ID
    Key - Client Secret

    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 .

    Edit this page
    Report an Issue