Microsoft Graph security

Integration version: 18.0

‌Configure Microsoft Graph security to work with Google Security Operations SOAR

The basic steps required are:

  1. Register your app with Azure AD. Register your app at Azure App registrations settings in the Azure Portal. You can use either a Microsoft account or a work or school account to register your app.

    • Click on the + New registration button to create a new app.
    • Select a name for the app and the account types that should be accessible to this API.
    • Set http://localhost/ as the Redirect URI.
    • Click on the Register button.
    • On the main app page, copy the Application (client) ID and the Directory (tenant) ID.
    • Go to the API permissions settings and click on + Add a permission button.

    • Add the following permissions:

    • Microsoft Graph -> Application permissions -> User.ReadWrite.All

    • Microsoft Graph -> Application permissions -> Mail.Read

    • Microsoft Graph -> Application permissions -> Directory.ReadWrite.All

    • Microsoft Graph -> Delegated permissions -> Directory.AccessAsUser.All

    • Microsoft Graph -> Application permissions -> SecurityEvents.ReadWrite.All

    • Microsoft Graph -> Application permissions -> SecurityEvents.Read.All

    • Click on Grant admin consent to grant access for Google Security Operations SOAR to the API. i. Go to Certificates & secrets and create a new Client Secret for Google Security Operations SOAR to use. Set it to never expire. Copy the generated Client Secret value.

  2. Configure Microsoft Graph Integration with the following values from the previous step:

    • Client ID = Application (client) ID
    • Tenant: Directory (tenant) ID
    • Secret ID: Client Secret

Configure Microsoft Graph security integration in Google Security Operations SOAR

For detailed instructions on how to configure an integration in Google Security Operations SOAR, see Configure integrations.

Integration parameters

Use the following parameters to configure the integration:

Parameter Display Name Type Default Value Is Mandatory Description
Instance Name String N/A No Name of the Instance you intend to configure integration for.
Description String N/A No Description of the Instance.
Client ID String N/A Yes Client (Application) ID that was added for the app registration in Azure Active Directory for this integration.
Secret ID String N/A Yes A secret that was entered for Azure AD app registration.
Certificate Path String N/A No If authentication based on certificates is used instead of client secret, specify the path to the certificate on the Google Security Operations SOAR server.
Certificate Password Password N/A No Optional, if the certificate is password-protected, specify the password to open the certificate file.
Tenant String N/A Yes An instance of Microsoft Graph security.
Run Remotely Checkbox Unchecked No Check the field in order to run the configured integration remotely. Once checked, the option appears to select the remote user (agent).

Actions

Description

Run the action and browse to the received URL to grant the permissions your app needs at the Azure portal.

Parameters

Parameter Display Name Type Default Value Is Mandatory Description
Redirect URL String N/A Yes Use the redirect URL you registered to request an authorization.

Run On

This action runs on all entities.

Action Results

Script Result
Script Result Name Value Options Example
is_connected True/False is_connected:False
JSON Result
N/A

Get Alert

Description

Retrieve the properties and relationships of an alert by ID.

Parameters

Parameter Display Name Type Default Value Is Mandatory Description
Alert ID String N/A Yes N/A

Run On

This action runs on all entities.

Action Results

Script Result
Script Result Name Value Options Example
alert_details True/False alert_details:False
JSON Result
{
  "feedback": "@odata.type: microsoft.graph.alertFeedback",
  "recommendedActions": ["String"],
  "networkConnections":
    [{
      "applicationName": "String",
      "natDestinationPort": "String",
      "destinationAddress": "String",
      "localDnsName": "String",
      "natDestinationAddress": "String",
      "destinationUrl": "String",
      "natSourceAddress": "String",
      "sourceAddress": "String",
      "direction": "@odata.type: microsoft.graph.connectionDirection",
      "domainRegisteredDateTime": "String (timestamp)",
      "status": "@odata.type: microsoft.graph.connectionStatus",
      "destinationDomain": "String",
      "destinationPort": "String",
      "sourcePort": "String",
      "protocol": "@odata.type: microsoft.graph.securityNetworkProtocol",
      "natSourcePort": "String",
      "riskScore": "String",
      "urlParameters": "String"
     }],
  "cloudAppStates":
    [{
      "destinationServiceIp": "String",
      "riskScore": "String",
      "destinationServiceName": "String"
     }],
  "detectionIds": ["String"],
  "id": "String (identifier)",
  "category": "String",
  "fileStates":
    [{
      "path": "String",
      "riskScore": "String",
      "name": "String",
      "fileHash":
        {
          "hashType": "@odata.type: microsoft.graph.fileHashType",
          "hashValue": "String"
         }
     }],
  "severity": "@odata.type: microsoft.graph.alertSeverity",
  "title": "String",
  "sourceMaterials": ["String"],
  "comments": ["String"],
  "assignedTo": "String",
  "eventDateTime": "String (timestamp)",
  "activityGroupName": "String",
  "status": "@odata.type: microsoft.graph.alertStatus",
  "description": "String",
  "tags": ["String"],
  "confidence": 1024,
  "vendorInformation":
      {
        "providerVersion": "String",
        "vendor": "String",
        "subProvider": "String",
        "provider": "String"
      },
  "userStates":
      [{
        "emailRole": "@odata.type: microsoft.graph.emailRole",
        "logonId": "String",
        "domainName": "String",
        "onPremisesSecurityIdentifier": "String",
        "userPrincipalName": "String",
        "userAccountType": "@odata.type: microsoft.graph.userAccountSecurityType",
        "logonIp": "String",
        "logonDateTime": "String (timestamp)",
        "logonType": "@odata.type: microsoft.graph.logonType",
        "logonLocation": "String",
        "aadUserId": "String",
        "accountName": "String",
        "riskScore": "String",
        "isVpn": "true"
        }],
 "malwareStates":
      [{
        "category": "String",
        "wasRunning": "true",
        "name": "String",
        "family": "String",
        "severity": "String"
       }],
  "processes":
      [{
        "processId": 1024,
        "integrityLevel": "@odata.type: microsoft.graph.processIntegrityLevel",
        "name": "String",
        "fileHash":
            {
              "hashType": "@odata.type: microsoft.graph.fileHashType",
              "hashValue": "String"
            },
       "parentProcessId": 1024,
       "createdDateTime": "String (timestamp)",
       "commandLine": "String",
       "parentProcessName": "String",
       "accountName": "String",
       "isElevated": "true",
       "path": "String",
       "parentProcessCreatedDateTime": "String (timestamp)"
      }],
  "azureTenantId": "String",
  "triggers":
     [{
       "type": "String",
       "name": "String",
       "value": "String"
      }],
  "createdDateTime": "String (timestamp)",
  "vulnerabilityStates":
     [{
       "cve": "String",
       "severity": "String",
       "wasRunning": "true"
     }],
  "hostStates":
     [{
       "isAzureAadRegistered": "true",
       "riskScore": "String",
       "fqdn": "String",
       "isHybridAzureDomainJoined": "true",
       "netBiosName": "String",
       "publicIpAddress": "String",
        "isAzureAadJoined": "true",
        "os": "String",
        "privateIpAddress": "String"
      }],
  "lastModifiedDateTime": "String (timestamp)",
  "registryKeyStates":
      [{
        "processId": 1024,
        "oldKey": "String",
        "oldValueName": "String",
         "valueType": "@odata.type: microsoft.graph.registryValueType",
        "oldValueData": "String",
        "hive": "@odata.type: microsoft.graph.registryHive",
        "valueData": "String",
        "key": "String",
        "valueName": "String",
        "operation": "@odata.type: microsoft.graph.registryOperation"
       }],
  "closedDateTime": "String (timestamp)",
  "azureSubscriptionId": "String"
}

Kill User Session

Description

The action invalidates all the refresh tokens issued to applications for a user, by resetting the signInSessionsValidFromDateTime user property to the current date-time.

Parameters

Parameter Display Name Type Default Value Is Mandatory Description
userPrincipalName| ID String N/A Yes The user's username used during sign in or the user Unique ID provided by Azure AD.

Run On

This action runs on all entities.

Action Results

Script Result
Script Result Name Value Options Example
is_success True/False is_success:False
JSON Result
N/A

List Alerts

Description

List available alerts in Microsoft Graph.

Parameters

Parameter Display Name Type Default Value Is Mandatory Description
Filter Key DDL

Not Specified

Possible Values:

  • Not Specified
  • Category
  • Title
 No Specify the key that needs to be used to filter alerts.
Filter Logic DDL

Not Specified

Possible Values:

  • DDL
  • Not Specified
  • Equal
  • Contains
 No Specify what filter logic should be applied. Filtering logic is working based on the value provided in the "Filter Key" parameter.
Filter Value String N/A No

Specify the value that should be used in the filter.

If "Equal" is selected, the action tries to find the exact match among results.

If "Contains" is selected, the action tries to find results that contain the selected substring.

If nothing is provided in this parameter, the filter is not applied. Filtering logic is working based on the value provided in the "Filter Key" parameter.
Max Records To Return Integer 50 No

Specify the number of records to return.

If nothing is provided, the action returns 50 records.

Run On

This action runs on all entities.

Action Results

Script Result
Script Result Name Value Options Example
alerts_details N/A N/A
JSON Result
{
            "id": "106220499052e8b00215943d6814c0f8503530e48a06ba5410ca5c418ef1d342",
            "azureTenantId": "d48f52ca-5b1a-4708-8ed0-ebb98a26a46a",
            "azureSubscriptionId": null,
            "riskScore": null,
            "tags": [],
            "activityGroupName": null,
            "assignedTo": null,
            "category": "ImpossibleTravel",
            "closedDateTime": null,
            "comments": [],
            "confidence": null,
            "createdDateTime": "2022-04-29T13:10:59.705Z",
            "description": "Sign-in from an atypical location based on the user"s recent sign-ins",
            "detectionIds": [],
            "eventDateTime": "2022-04-29T11:36:59.1520667Z",
            "feedback": null,
            "incidentIds": [],
            "lastEventDateTime": null,
            "lastModifiedDateTime": "2022-04-30T14:44:43.4742002Z",
            "recommendedActions": [],
            "severity": "medium",
            "sourceMaterials": [],
            "status": "newAlert",
            "title": "Atypical travel",
            "vendorInformation": {
                "provider": "IPC",
                "providerVersion": null,
                "subProvider": null,
                "vendor": "Microsoft"
            },
            "alertDetections": [],
            "cloudAppStates": [],
            "fileStates": [],
            "hostStates": [],
            "historyStates": [],
            "investigationSecurityStates": [],
            "malwareStates": [],
            "messageSecurityStates": [],
            "networkConnections": [],
            "processes": [],
            "registryKeyStates": [],
            "securityResources": [],
            "triggers": [],
            "userStates": [
                {
                    "aadUserId": "b786d3cf-e97d-4511-b61c-0559e9f4da75",
                    "accountName": "james.bond",
                    "domainName": "siemplifycyarx.onmicrosoft.com",
                    "emailRole": "unknown",
                    "isVpn": null,
                    "logonDateTime": "2022-04-29T11:36:59.1520667Z",
                    "logonId": null,
                    "logonIp": "188.226.20.194",
                    "logonLocation": "Yekaterinburg, Sverdlovskaya Oblast', RU",
                    "logonType": null,
                    "onPremisesSecurityIdentifier": null,
                    "riskScore": null,
                    "userAccountType": null,
                    "userPrincipalName": "james.bond@siemplifycyarx.onmicrosoft.com"
                },
                {
                    "aadUserId": "b786d3cf-e97d-4511-b61c-0559e9f4da75",
                    "accountName": "james.bond",
                    "domainName": "siemplifycyarx.onmicrosoft.com",
                    "emailRole": "unknown",
                    "isVpn": null,
                    "logonDateTime": "2022-04-29T11:15:00Z",
                    "logonId": null,
                    "logonIp": "2.137.129.160",
                    "logonLocation": "ES",
                    "logonType": null,
                    "onPremisesSecurityIdentifier": null,
                    "riskScore": null,
                    "userAccountType": null,
                    "userPrincipalName": "james.bond@siemplifycyarx.onmicrosoft.com"
                }
            ],
            "uriClickSecurityStates": [],
            "vulnerabilityStates": []
}
Case Wall
Result Type Value / Description Type
Output message*

The action should not fail nor stop a playbook execution:

If data is available (is_success=true): "Successfully found alerts for the provided criteria in Microsoft Graph".

If data is not available (is_success=false): "No alerts were found for the provided criteria in Microsoft Graph"

If the "Filter Value" parameter is empty (is_success=true):

"The filter was not applied, because parameter "Filter Value" has an empty value."

The action should fail and stop a playbook execution:

If Filter Key == "Select One" and Filter Logic = "Equal" or "Contains":

"Error executing action "List Alerts". Reason: you need to select a field from the "Filter Key" parameter."

If invalid value is provided for the Max Records to Return parameter:

"Error executing action "List Alerts". Reason: "Invalid value was provided for "Max Records to Return": Positive number should be provided."

If fatal error, like wrong credentials, no connection to server, other is reported:

"Error executing action "List Alerts". Reason: {0}''.format(error.Stacktrace)

 General
Case Wall Table

Table Name: Available Alerts

Table Columns:

  • Alert ID
  • Title
  • Category
  • Description
  • Status
  • Severity
  • Assigned To
  • Risk Score
  • Comments
  • Azure Tenant ID
  • Azure Subscription ID
  • Created Time
  • Last Modified Time
 General

Ping

Description

Test Connectivity.

Parameters

N/A

Run On

This action runs on all entities.

Action Results

Script Result
Script Result Name Value Options Example
is_connected True/False is_connected:False
JSON Result
N/A

Update Alert

Description

Update an editable alert property.

Parameters

Parameter Display Name Type Default Value Is Mandatory Description
Alert ID String N/A Yes The ID of the alert to update.
Assigned To String N/A No Name of the analyst the alert is assigned to for triage, investigation, or remediation.
Closed Date Time String N/A No

Time at which the alert was closed. using ISO format, always in UTC time.

Example: 2014-01-01T00:00:00Z
Comments String N/A No Analyst comments on the alert. Separated by comma.
Feedback String N/A No

Analyst feedback on the alert.

Possible values:

  • unknown
  • truePositive
  • falsePositive
  • benignPositive
Status String N/A No

Alert lifecycle status (stage).

Possible values are:

  • unknown
  • newAlert
  • inProgress
  • resolved
Tags String N/A No User-definable labels that can be applied to an alert. Separated by comma.

Run On

This action runs on all entities.

Action Results

Script Result
Script Result Name Value Options Example
is_updated True/False is_updated:False
JSON Result
N/A

Connectors

Configure Microsoft Graph security connectors in Google Security Operations SOAR

For detailed instructions on how to configure a connector in Google Security Operations SOAR, see Configuring the connector.

To configure the selected connector use the connector-specific parameters listed in the following tables:

Microsoft Graph security Connector

Description

Microsoft Graph security Alerts Connector ingests alerts published in Microsoft Graph Security as Google Security Operations SOAR alerts. The connector periodically connects to the Microsoft Graph security endpoint and pulls a list of incidents generated for a specific time period.

Connector parameters

Use the following parameters to configure the connector:

td>N/A
Parameter Display Name Type Default Value Is Mandatory Description
Environment DDL Yes

Select the required environment. For example, "Customer One".

In case that the alert's Environment field is empty, this alert will be injected to this environment.
Run Every Integer 0:0:0:10 No Select the time to run the connection.
Product Field Name String ProductFieldName Yes NOT SUPPORTED | Describes the name of the field where the product name is stored.
Event Field Name String AlertName Yes NOT SUPPORTED | Describes the name of the field where the event name is stored.
Script Timeout (Seconds) String 30 No The timeout limit (in seconds) for the python process running the current script.
Environment Field Name String N/A No https://.cylance.com
Pattern String .* No A regex pattern to run on the value found in the Environment Field Name field.
Client ID String N/A Yes Client (Application) ID that was added for the app registration in Azure Active Directory for this integration.
Client Secret Password N/A Yes Secret that was entered for Azure AD app registration.
Certificate Path String N/A No If authentication based on certificates is used instead of client secret, specify the path to the certificate on the Google Security Operations SOAR server.
Certificate Password Password N/A No Optional, if the certificate is password-protected, specify the password to open the certificate file.
Azure Active Directory ID String N/A Yes Azure Active Directory Tenant ID.
Offset Time In Hours Integer 120 Yes Fetch alerts from X hours backwards.
Fetch Alerts only from String N/A No Specify for what providers Connector should pull alerts from Graph Security. Values should be comma separated.
Alert Statuses to fetch String unknown, newAlert, inProgress, resolved Yes Specify statuses of the alerts that should be fetched by the Google Security Operations SOAR server. Values should be comma separated.
Alert Severities to fetch String high, medium, low, informational, unknown Yes Specify severities of the alerts that should be fetched by the Google Security Operations SOAR server. Values should be comma separated.
Max Alerts Per Cycle Integer 50 Yes How many alerts should be processed during one connector run.
Proxy Server Address String N/A No The address of the proxy server to use.
Proxy Username String N/A No The proxy username to authenticate with.
Proxy Password Password N/A No The proxy password to authenticate with.

Connector rules

Blacklist/Whitelist

The connector doesn't support the Blacklist/Whitelist rule.

Proxy support

The connector supports proxy.

Microsoft Graph Office 365 Security and Compliance Connector

Description

Ingest Office 365 Security and Compliance alerts using Graph API

Connector parameters

Use the following parameters to configure the connector:

Parameter Display Name Type Default Value Is Mandatory Description
Environment DDL N/A Yes

Select the required environment. For example, "Customer One".

In case that the alert's Environment field is empty, this alert will be injected to this environment.
Run Every Integer 0:0:0:10 No Select the time to run the connection.
Product Field Name String ProductFieldName Yes NOT SUPPORTED | Describes the name of the field where the product name is stored.
Event Field Name String AlertName Yes NOT SUPPORTED | Describes the name of the field where the event name is stored.
Script Timeout (Seconds) String 30 No The timeout limit (in seconds) for the python process running the current script.
Environment Field Name String N/A No Describes the name of the field where the environment name is stored. If the environment field isn't found, the environment is the default environment.
Environment Regex Pattern String .* No A regex pattern to run on the value found in the "Environment Field Name" field. Default is .* to catch all and return the value unchanged. Used to allow the user to manipulate the environment field via regex logic. If the regex pattern is null or empty, or the environment value is null, the final environment result is the default environment.
Client ID String N/A Yes Client (Application) ID that was added for the app registration in Azure Active Directory for this integration.
Client Secret Password N/A Yes Secret that was entered for Azure AD app registration.
Certificate Path String N/A No If authentication based on certificates is used instead of client secret, specify the path to the certificate on the Google Security Operations SOAR server.
Certificate Password Password N/A No Optional, if the certificate is password-protected, specify the password to open the certificate file.
Azure Active Directory ID String N/A Yes Azure Active Directory Tenant ID.
Offset Time In Hours Integer 120 Yes Fetch alerts from X hours backwards.
Alert Statuses to fetch String unknown, Active, Investigating, resolved No Specify statuses of the alerts that should be fetched by the Google Security Operations SOAR server. Values should be comma separated.
Alert Severities to fetch String high, medium, low, informational, unknown No Specify severities of the alerts that should be fetched by the Google Security Operations SOAR server. Values should be comma separated.
Max Alerts Per Cycle Integer 50 Yes How many alerts should be processed during one connector run.
Proxy Server Address String N/A No The address of the proxy server to use.
Proxy Username String N/A No The proxy username to authenticate with.
Proxy Password Password N/A No The proxy password to authenticate with.
Verify SSL Checkbox Unchecked No If enabled, verify the SSL certificate for the connection to the Microsoft Graph server is valid.

Connector rules

Blacklist/Whitelist

The connector doesn't support the Blacklist/Whitelist rule.

Proxy support

The connector supports proxy.