Microsoft Graph security

Integration version: 16.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).

Note: You can make changes at a later stage if needed. Once configured, the Instances can be used in Playbooks. For detailed information on configuring and supporting multiple instances, please refer here.

Actions

Get Administrator Consent

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.

Note: Filtering is done on the Microsoft Graph API side. Filtering may not be supported by some products that publish alerts to Microsoft Graph. For example, filtering by Equality on Title may not be supported by Office 365 Security and Compliance. As a result, all alerts from these products would be added to the response as if they've passed the filter.

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": "[e-mail]"
                },
                {
                    "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": "[e-mail]"
                }
            ],
            "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 configuration parameters
• Microsoft Graph security Connector configuration parameters

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.

Note: Following Microsoft Limitations, running a connector with multiple values under 'Alert Statuses to fetch' or/and 'Alert Severities to fetch' while the 'Fetch Alerts only from' is set to 'Office 365 Security and Compliance' is not supported.

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.