Microsoft Defender ATP

Integration version: 23.0

Important: Microsoft Defender ATP became Microsoft Defender for Endpoint.

Use cases

1. Use the data gathered in Microsoft Defender for Endpoint for enrichments while investigating a particular case.

   Analysts can use the data gathered and stored in Microsoft Defender for Endpoint in investigations—for example, to get information on alerts detected in Microsoft Defender for Endpoint or list machines registered in Microsoft Defender for Endpoint.

2. Perform active response actions in potential security incidents like isolating a specific host from a network or running an antivirus scan.

3. Monitor and inspect the Microsoft Defender for Endpoint alerts as Google Security Operations SOAR alerts fetched by the respective connector.

Prerequisites

Before configuring the integration in the Google Security Operations SOAR platform, make sure to complete the following prerequisite steps:

1. Create the Microsoft Entra app.

2. Configure the API permissions for your app.

3. Create a client secret.

We recommend using Application Context instead of User Context when accessing the Microsoft Defender for Endpoint API.

Create Microsoft Entra app

1. Sign in to the Azure portal as a user administrator or a password administrator.

2. Select Microsoft Entra ID.

3. Go to App registrations > New registration.

4. Enter the name of the app.

5. Click Register.

   Note: This document uses a single tenant setup as an example. Redirect URL is not needed for the OAuth flow (client credentials) supported by the integration.

6. Save the Application (client) ID and Directory (tenant) ID values to use them later when configuring the integration parameters.

Configure API permissions

1. Go to API Permissions > Add a permission > APIs my organization uses. The Request API permissions dialog opens.

2. In the Search field, enter WindowsDefenderATP.

3. Select the WindowsDefenderATP > Application permissions.

4. Under the Alert permission type, select the following permission:

   • Alert.Read.All

5. Click Add permissions.

6. On the API Permissions page, click Add a permission.

7. Select Microsoft Graph > Delegated permissions.

8. In the Select Permissions section, select the following required permission:

   • User.Read

9. Click Add permissions.

10. On the API Permissions page, click Add a permission.

11. Select WidnowsDefenderATP > Application permissions.

12. In the Select Permissions section, select the following required permissions:

    • AdvancedQuery.Read.All
    • Alert.Read.All
    • Alert.ReadWrite.All
    • Event.Write
    • File.Read.All
    • Ip.Read.All
    • Machine.Isolate
    • Machine.Read.All
    • Machine.ReadWrite.All
    • Machine.Scan
    • Machine.StopAndQuarantine
    • Ti.ReadWrite
    • Url.Read.All
    • User.Read.All

13. Click Grant admin consent for ORGANIZATION_NAME.

    When the Grant admin consent confirmation dialog appears, click Yes.

The example of an API request to get the Defender ATP alerts is as follows (note the $expand parameter that is used to fetch data about IP addresses, domains, and files):

GET /api/alerts?$expand=files,ips,domains HTTP/1.1
Host: api.securitycenter.windows.com
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJ...
User-Agent: PostmanRuntime/7.19.0
Accept: */ *
Cache-Control: no-cache
Postman-Token: 2dc0f885-068a-45d4-81a6-2da0d23a58ad,d3dd0e6e-83ab-4d27-94d2-0f3889dff324
Host: api.securitycenter.windows.com
Accept-Encoding: gzip, deflate
Connection: keep-alive
cache-control: no-cache

To learn more about the request parameters and request options like filter or expand, see Supported Microsoft Defender for Endpoint APIs in the Microsoft documentation.

Create client secret

1. Navigate to Certificates and secrets > New client secret.

2. Provide a description for a client secret and set its expiration deadline.

3. Click Add.

4. Save the value of the client secret (not the secret ID) to use it as the Client Secret parameter value when configuring the integration. The client secret value is only displayed once.

Enable SIEM integration - Deprecated

Deprecated: Microsoft has deprecated the SIEM integration with Microsoft Defender ATP.

1. In the navigation pane, select Settings > SIEM.

   Note: If you encounter an error when trying to enable the SIEM connector application, check the blocking settings of your browser. It might be blocking the new window being opened when you enable the capability.

2. Select Enable SIEM integration.

This activates the SIEM connector access details section with pre-populated values and an application is created under your Azure AD tenant.

Warning: The client secret is only displayed once. Make sure you keep a copy of it in a safe place.

• Choose SIEM type as Generic API.
• Copy the individual values or select Save details to file to download a file that contains all the values.
• You will need the values presented on this page to generate a token to access the detections data: Client ID, Client Secret, Resource.

Integrate Microsoft Defender ATP with Google Security Operations SOAR

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

Integration parameters

To configure the integration, use the following parameters:

Parameters
Client ID	Required Client (Application) ID of the Microsoft Entra app to use for the integration.
Client Secret	Required Client secret value of the Microsoft Entra app to use for the integration.
Azure Active Directory ID	Required Microsoft Entra ID (Tenant ID) value.
Verify SSL	Optional If selected, verifies that the SSL certificate for the connection to the Microsoft 365 Defender server is valid. Selected by default.
API Root	Required API root URL to use with integration. For better performance, you can use a server closest to your location: api-us.securitycenter.windows.com api-eu.securitycenter.windows.com api-uk.securitycenter.windows.com Default value is https://api.securitycenter.windows.com.

Actions

Ping

Test connectivity to Microsoft Defender for Endpoint instance with parameters provided at the integration configuration page.

Parameters

N/A

Use cases

The action is used to test the connectivity and can be executed as manual action, which is not a part of playbooks.

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

Enrich Entities

Enrich Google Security Operations SOAR Host, IP Address, or File hash entities based on the information from the Microsoft Defender for Endpoint.

Parameters

N/A

Use cases

The action can be used in the playbooks that investigate activity on devices. If the device has the Microsoft Defender for Endpoint agent installed, then the action pulls information from Defender ATP on a device to enrich Google Security Operations SOAR entities. The action also can be used to enrich the alert file hashes with the information from the Defender ATP.

Run on

This action runs on the following entities:

• Host
• IP Address
• Filehash

Action results

Script result

Script Result Name	Value Options	Example
is_success	True/False	is_success:False

JSON result

If enrichment works on IP Address or Host:

[
    {
        "EntityResult": {
            "@odata.context": "https://api.securitycenter.windows.com/api/$metadata#Machines/$entity",
            "id": "example_id",
            "computerDnsName": "example-name",
            "firstSeen": "2019-11-18T11:13:04.0588699Z",
            "lastSeen": "2019-11-24T18:31:50.581058Z",
            "osPlatform": "Windows10",
            "osVersion": null,
            "osProcessor": "x64",
            "version": "1803",
            "lastIpAddress": "192.0.2.138",
            "lastExternalIpAddress": "203.0.113.28",
            "agentVersion": "10.4860.17134.982",
            "osBuild": 17134,
            "healthStatus": "Active",
            "rbacGroupId": 0,
            "rbacGroupName": null,
            "riskScore": "High",
            "exposureLevel": "Medium",
            "aadDeviceId": null,
            "machineTags": []
        }
    }
]

If enrichment works on Filehash:

[
    {
        "EntityResult": {
            "@odata.context": "https://api.securitycenter.windows.com/api/$metadata#Files/$entity",
            "sha1": "bdd0d38e113a0c7dd6213cf2e89e6cc6d66b5cdb",
            "sha256": "328954033456d5c13e58fb5bcc6c0232f9f62cb6d9185afa51c7913338992491",
            "md5": "9512e1cc66a1d36feb0a290cab09087b",
            "globalPrevalence": 5205000,
            "globalFirstObserved": "2018-06-22T12:59:21.6460311Z",
            "globalLastObserved": "2019-11-21T00:24:01.921338Z",
            "size": 245760,
            "fileType": "APP",
            "isPeFile": true,
            "filePublisher": "Microsoft Corporation",
            "fileProductName": "Microsoft Windows Operating System",
            "signer": "Microsoft Windows",
            "issuer": "Microsoft Windows Production PCA 2011",
            "signerHash": "419e77aed546a1a6cf4dc23c1f977542fe289cf7",
            "isValidCertificate": true
            },
        "EntityResult": {
            "@odata.context": "https://api.securitycenter.windows.com/api/$metadata#microsoft.windowsDefenderATP.api.InOrgFileStats",
            "sha1": "bdd0d38e113a0c7dd6213cf2e89e6cc6d66b5cdb",
            "orgPrevalence": "1",
            "orgFirstSeen": "2019-11-19T03:54:15Z",
            "orgLastSeen": "2019-11-19T04:21:18Z",
            "globalPrevalence": "5205000",
            "globalFirstObserved": "2018-06-22T12:59:21.6460311Z",
            "globalLastObserved": "2019-11-21T00:24:01.921338Z",
            "topFileNames": ["notepad.exe"]
        }
    }
]

Entity enrichment

IP and Host

Enrichment Field Name	Logic - When to apply
Defender_ATP.sha1	Returns if it exists in JSON result
Defender_ATP.sha256	Returns if it exists in JSON result
Defender_ATP.md5	Returns if it exists in JSON result
Defender_ATP.globalPrevalence	Returns if it exists in JSON result
Defender_ATP.globalFirstObserved	Returns if it exists in JSON result
Defender_ATP.globalLastObserved	Returns if it exists in JSON result
Defender_ATP.size	Returns if it exists in JSON result
Defender_ATP.fileType	Returns if it exists in JSON result
Defender_ATP.isPeFile	Returns if it exists in JSON result
Defender_ATP.filePublisher	Returns if it exists in JSON result
Defender_ATP.fileProductName	Returns if it exists in JSON result
Defender_ATP.signer	Returns if it exists in JSON result
Defender_ATP.issuer	Returns if it exists in JSON result
Defender_ATP.signerHash	Returns if it exists in JSON result
Defender_ATP.isValidCertificate	Returns if it exists in JSON result
Defender_ATP.orgPrevalence	Returns if it exists in JSON result
Defender_ATP.orgFirstSeen	Returns if it exists in JSON result
Defender_ATP.orgLastSeen	Returns if it exists in JSON result
Defender_ATP.topFileNames	Returns if it exists in JSON result

File Hash

Enrichment Field Name	Logic - When to apply
Defender_ATP.sha1	Returns if it exists in JSON result
Defender_ATP.sha256	Returns if it exists in JSON result
Defender_ATP.md5	Returns if it exists in JSON result
Defender_ATP.globalPrevalence	Returns if it exists in JSON result
Defender_ATP.globalFirstObserved	Returns if it exists in JSON result
Defender_ATP.globalLastObserved	Returns if it exists in JSON result
Defender_ATP.size	Returns if it exists in JSON result
Defender_ATP.fileType	Returns if it exists in JSON result
Defender_ATP.isPeFile	Returns if it exists in JSON result
Defender_ATP.filePublisher	Returns if it exists in JSON result
Defender_ATP.fileProductName	Returns if it exists in JSON result
Defender_ATP.signer	Returns if it exists in JSON result
Defender_ATP.issuer	Returns if it exists in JSON result
Defender_ATP.signerHash	Returns if it exists in JSON result
Defender_ATP.isValidCertificate	Returns if it exists in JSON result
Defender_ATP.orgPrevalence	Returns if it exists in JSON result
Defender_ATP.orgFirstSeen	Returns if it exists in JSON result
Defender_ATP.orgLastSeen	Returns if it exists in JSON result
Defender_ATP.topFileNames	Returns if it exists in JSON result

List Alerts

List Microsoft Defender for Endpoint alerts based on provided search criteria. The action returns information on found alerts in a table and JSON view form as an action output, along with raw alert data that is stored in and attached to the action output JSON file.

Parameters

Parameter Display Name	Type	Default Value	Is Mandatory	Description
Time Frame	Integer	3	No	Specify a timeframe in hours for which to fetch alerts.
Status	String	Unknown, New, InProgress, Resolved	No	Specify the statuses of alerts to look for. Parameter accepts multiple values as a comma-separated string.
Severity	String	N/A	No	Specify the severity of the incidents to look for. If not provided, the action looks for all severities. Parameter accepts multiple values as a comma-separated string. Possible Values: UnSpecified, Informational, Low, Medium, and High
Category	String	N/A	No	Specify the alert category to look for. If not provided, the actions looks for all categories. Parameter accepts multiple values as a comma-separated string. Possible Values: 'Collection', 'CommandAndControl', 'CredentialAccess', 'DefenseEvasion', 'Discovery', 'Execution', 'Exfiltration', 'Exploit', 'InitialAccess', 'LateralMovement', 'Malware', 'Persistence', 'PrivilegeEscalation', 'Ransomware', 'SuspiciousActivity', 'UnwantedSoftware'.
Incident ID	Integer	N/A	No	Specify the Microsoft Defender Incident ID for which you want to find related alerts.

Use cases

The action may be used to review Defender ATP warnings to Google Security Operations SOAR server for an end-user. For example, when dealing with the warning that came from the Defender ATP connector, the user configures the "List Warnings" action to accept processed alert IncidentId as the input parameter to pull details from the Defender ATP server-there are any other warnings that are part of a single Defender ATP Incident.

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

{
    "@odata.context": "https://api.securitycenter.windows.com/api/$metadata#Alerts",
    "value": [
        {
            "id": "example_id",
            "incidentId": 2,
            "investigationId": null,
            "assignedTo": null,
            "severity": "Medium",
            "status": "New",
            "classification": null,
            "determination": null,
            "investigationState": "UnsupportedAlertType",
            "detectionSource": "WindowsDefenderAtp",
            "category": "Execution",
            "threatFamilyName": null,
            "title": "Unexpected behavior observed by a process run with no command line arguments",
            "description": "The legitimate process by this name does not normally exhibit this behavior when run with no command line arguments. \nSuch unexpected behavior may be a result of extraneous code injected into a legitimate process, or a malicious executable masquerading as the legitimate one by name.",
            "alertCreationTime": "2019-11-19T03:56:35.3007009Z",
            "firstEventTime": "2019-11-19T03:54:16.0441057Z",
            "lastEventTime": "2019-11-19T03:54:16.0441057Z",
            "lastUpdateTime": "2019-11-19T03:56:38.45Z",
            "resolvedTime": null,
            "machineId": "machine-id",
            "alertUser": null,
            "comments": [],
            "alertFiles": [],
            "alertDomains": [],
            "alertIps": [],
            "alertProcesses": []
            }
    ]
}

Update Alert

Update a specific Microsoft Defender for Endpoint Alert. The action can be used to close an alert in Microsoft Defender for Endpoint.

Parameters

Parameter	Type	Default Value	Is Mandatory	Description
Alert ID	String	N/A	Yes	Specify the Microsoft Defender for Endpoint Alert ID to update.
Status	DDL	New Possible Values: New InProgress Resolved	No	Specify the status of the alert to update to.
Assigned To	String	N/A	No	Specify the user info if you want to update this field.
Classification	DDL	Unknown Possible Values: Unknown FalsePositive TruePositive	No	Specify the classification to update the alert with.
Determination	DDL	NotAvailable Possible Values: NotAvailable Apt Malware SecurityPersonnel SecurityTesting UnwantedSoftware Other	No	Specify the determination to update the alert with.

Use cases

• Use the action to update a Defender ATP warning.

• Use the action to intervene in a workflow involving Defender ATP warning analysis.

  After the alert has been processed in Google Security Operations SOAR, you can ignore the Defender ATP alert to keep the Defender ATP and Google Security Operations SOAR alert lists aligned. Also, you can change the alert to show the progress of the alert analysis (for example, set the assignedTo attribute or set the alert status to inProgress).

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

{
    "@odata.context": "https://api.securitycenter.windows.com/api/$metadata#Alerts/$entity",
    "id": "example-id",
    "incidentId": 1,
    "investigationId": null,
    "assignedTo": null,
    "severity": "Informational",
    "status": "Resolved",
    "classification": null,
    "determination": null,
    "investigationState": "UnsupportedAlertType",
    "detectionSource": "WindowsDefenderAtp",
    "category": "Execution",
    "threatFamilyName": null,
    "title": "[Test Alert] Suspicious Powershell commandline",
    "description": "*** This is a test alert ***\nA suspicious Powershell commandline was found on the machine. This commandline might be used during installation, exploration, or in some cases with lateral movement activities which are used by attackers to invoke modules, download external payloads, and get more information about the system. Attackers usually use Powershell to bypass security protection mechanisms by executing their payload in memory without touching the disk and leaving any trace.",
    "alertCreationTime": "2019-11-18T11:17:48.287421Z",
    "firstEventTime": "2019-11-18T11:15:06.5226815Z",
    "lastEventTime": "2019-11-18T11:15:06.5226815Z",
    "lastUpdateTime": "2019-11-20T04:12:03.6066667Z",
    "resolvedTime": "2019-11-20T04:12:03.4976288Z",
    "machineId": "machine-id",
    "alertUser": {
        "accountName": "Administrator",
        "domainName": "example-domain"
    },
    "comments": [],
    "alertFiles": [
        {
            "sha1": "3ce71813199abae99348f61f0caa34e2574f831c",
            "sha256": "9a7c58bd98d70631aa1473f7b57b426db367d72429a5455b433a05ee251f3236",
            "filePath": "C:\\Windows\\System32\\cmd.exe",
            "fileName": "cmd.exe"
        },
        {
            "sha1": "1b3b40fbc889fd4c645cc12c85d0805ac36ba254",
            "sha256": "d3f8fade829d2b7bd596c4504a6dae5c034e789b6a3defbe013bda7d14466677",
            "filePath": "C:\\Windows\\System32\\WindowsPowerShell\\v1.0\\powershell.exe",
            "fileName": "powershell.exe"
        }
    ],
    "alertDomains": [],
    "alertIps": [],
    "alertProcesses": []
}

List Machines

Get information about machines registered with the Microsoft Defender for Endpoint server based on the parameters given for the search.

Note: This action returns data from a period of 30 days, and data up to 3 MB. Exceeding data is truncated. The action output is displayed in a table view and a JSON viewer. The output is also attached in the JSON format as a file to the Case wall.

Parameters

Parameter	Type	Default Value	Is Mandatory	Description
Last Seen Time Frame	Integer	N/A	No	Specify the last seen timeframe to look for in hours.
Machine Name	String	N/A	No	Specify the full machine name to look for.
Machine IP Address	String	N/A	No	Specify the machine IP address to look for.
Machine Risk Score	String	None, Low, Medium, High	No	Specify the machine risk score to look for. Parameter accepts multiple values as a comma-separated string.
Machine Health Status	String	Active, Inactive, ImpairedCommunication, NoSensorData, NoSensorDataImpairedCommunication	No	Specify the machine health status to look for. Parameter accepts multiple values as a comma-separated string.
Machine OS Platform	String	N/A	No	Specify the machine OS platform to look for.
RBAC Group ID	String	N/A	No	Specify the RBAC Group ID to look for.

Use cases

The action can be used for investigation purposes to get information on devices registered on the Defender ATP server. This action is mostly used as manual action, for the user to not have to switch back to Defender ATP console and look for which machines Defender ATP agent is working on.

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

{
    "@odata.context": "https://api.securitycenter.windows.com/api/$metadata#Machines",
    "value": [
        {
            "id": "example-id",
            "computerDnsName": "example-name",
            "firstSeen": "2019-11-18T11:13:04.0588699Z",
            "lastSeen": "2019-11-20T09:59:28.0646303Z",
            "osPlatform": "Windows10",
            "osVersion": null,
            "osProcessor": "x64",
            "version": "1803",
            "lastIpAddress": "192.0.2.138",
            "lastExternalIpAddress": "203.0.113.35",
            "agentVersion": "10.4860.17134.982",
            "osBuild": 17134,
            "healthStatus": "Active",
            "rbacGroupId": 0,
            "rbacGroupName": null,
            "riskScore": "High",
            "exposureLevel": "Medium",
            "aadDeviceId": null,
            "machineTags": []
        },{
            "id": "example-id",
            "computerDnsName": "example-name",
            "firstSeen": "2019-11-20T08:36:16.2721384Z",
            "lastSeen": "2019-11-20T08:36:52.7182837Z",
            "osPlatform": "Windows10",
            "osVersion": null,
            "osProcessor": "x64",
            "version": "1803",
            "lastIpAddress": "192.0.2.141",
            "lastExternalIpAddress": "203.0.113.35",
            "agentVersion": "10.4850.17134.191",
            "osBuild": 17134,
            "healthStatus": "Active",
            "rbacGroupId": 0,
            "rbacGroupName": null,
            "riskScore": "None",
            "exposureLevel": "Medium",
            "aadDeviceId": null,
            "machineTags": []
        }
    ]
}

Get Machine Log on Users

Get information on a users logon on a specific machine.

Parameters

N/A

Use cases

The action can be used for investigation purposes to get specific details on what users logon on a machine in question from the Defender ATP server.

Run on

This action runs on the following entities:

• Host
• IP Address

Action results

Script result

Script Result Name	Value Options	Example
is_success	True/False	is_success:False

JSON result

{
    "@odata.context": "https://api.securitycenter.windows.com/api/$metadata#Users",
    "value": [
        {
            "id": "example\\example.user",
            "accountName": "example.user",
            "accountDomain": "example",
            "accountSid": null,
            "firstSeen": "2019-11-19T03:50:36Z",
            "lastSeen": "2019-11-19T03:50:36Z",
            "mostPrevalentMachineId": null,
            "leastPrevalentMachineId": null,
            "logonTypes": "Interactive",
            "logOnMachinesCount": 1,
            "isDomainAdmin": false,
            "isOnlyNetworkUser": null
        }
    ]
}

Get Machine Related Alerts

Get alerts related to specific machine registered in Defender ATP.

Parameters

Parameter	Type	Default Value	Is Mandatory	Description
Status	String	Unknown, New, InProgress, Resolved	No	Specify the statuses of alerts to look for. Parameter accepts multiple values as a comma-separated string.
Severity	String	UnSpecified, Informational, Low, Medium, High	No	Specify the severities of the incidents to look for. Parameter accepts multiple values as a comma-separated string.
Category	String	N/A	No	Specify the alert category to look for. If not provided, the action looks for all categories. Parameter accepts multiple values as a comma-separated string. Possible Values: 'Collection', 'CommandAndControl', 'CredentialAccess', 'DefenseEvasion', 'Discovery', 'Execution', 'Exfiltration', 'Exploit', 'InitialAccess', 'LateralMovement', 'Malware', 'Persistence', 'PrivilegeEscalation', 'Ransomware', 'SuspiciousActivity', 'UnwantedSoftware'.
Incident ID	Integer	N/A	No	Specify the Microsoft Defender Incident ID for which you want to find related alerts.

Use cases

The action can be used for investigation purposes to get alerts related to a specific machine in question from the Defender ATP server.

Run on

This action runs on the following entities:

• Host
• IP Address

Action results

Script result

Script Result Name	Value Options	Example
is_success	True/False	is_success:False

JSON result

{
    "@odata.context": "https://api.securitycenter.windows.com/api/$metadata#Alerts",
    "value": [
        {
            "id": "example-id",
            "incidentId": 1,
            "investigationId": null,
            "assignedTo": "[e-mail]",
            "severity": "Informational",
            "status": "Resolved",
            "classification": "FalsePositive",
            "determination": "SecurityTesting",
            "investigationState": "UnsupportedAlertType",
            "detectionSource": "WindowsDefenderAtp",
            "category": "Execution",
            "threatFamilyName": null,
            "title": "[Test Alert] Suspicious Powershell commandline",
            "description": "*** This is a test alert ***\nA suspicious Powershell commandline was found on the machine. This commandline might be used during installation, exploration, or in some cases with lateral movement activities which are used by attackers to invoke modules, download external payloads, and get more information about the system. Attackers usually use Powershell to bypass security protection mechanisms by executing their payload in memory without touching the disk and leaving any trace.",
            "alertCreationTime": "2019-11-18T11:17:48.287421Z",
            "firstEventTime": "2019-11-18T11:15:06.5226815Z",
            "lastEventTime": "2019-11-18T11:15:06.5226815Z",
            "lastUpdateTime": "2019-11-20T04:12:03.91Z",
            "resolvedTime": "2019-11-20T04:12:03.4976288Z",
            "machineId": "machine-id",
            "alertUser": {
                "accountName": "Administrator",
                "domainName": "US-LT-V13007"
            },
            "comments": [],
            "alertFiles": [
                {
                    "sha1": "3ce71813199abae99348f61f0caa34e2574f831c",
                    "sha256": "9a7c58bd98d70631aa1473f7b57b426db367d72429a5455b433a05ee251f3236",
                    "filePath": "C:\\Windows\\System32\\cmd.exe",
                    "fileName": "cmd.exe"
                },
                {
                    "sha1": "1b3b40fbc889fd4c645cc12c85d0805ac36ba254",
                    "sha256": "d3f8fade829d2b7bd596c4504a6dae5c034e789b6a3defbe013bda7d14466677",
                    "filePath": "C:\\Windows\\System32\\WindowsPowerShell\\v1.0\\powershell.exe",
                    "fileName": "powershell.exe"
                }
            ],
            "alertDomains": [],
            "alertIps": [],
            "alertProcesses": []
        }
    ]
}

Isolate Machine

Isolate a machine using Microsoft Defender for Endpoint. The Machine can be set under full isolation, or selective isolation. Outlook, Skype for Business, and Teams applications continue to work on a machine under isolation.

Parameters

Parameter Display Name	Type	Default Value	Is Mandatory	Description
Isolation Type	DDL	Full Possible Values: Full Selective	Yes	Specify the isolation type.
Comment	String	N/A	Yes	Specify a comment as to why the machine needs to be isolated.
Create an Insight?	Checkbox	Checked		If enabled, the action creates a Google Security Operations SOAR Insight with related information if executed successfully.

Use cases

Isolate a machine that is considered to be infected. For example, Defender ATP connector alert was ingested to the Google Security Operations SOAR server, and during an alert analysis it was discovered that related to the alert machine (Case entity), it can be infected and needs to be isolated.

Run on

This action runs on the following actions:

• Host
• IP Address

Action results

Script result

True if the API Endpoint returned for every provided entity it ran on, status 201, in JSON Response "status": "Pending", which indicates that the API request executed successfully. If at least for one of the entities the action fails, the final result should be fail (False).

Script Result Name	Value Options	Example
is_success	True/False	is_success:False

JSON result

{
    "@odata.context": "https://api.securitycenter.windows.com/api/$metadata#MachineActions/$entity",
    "id": "example-id",
    "type": "Isolate",
    "requestor": "requestor-id",
    "requestorComment": "Machine Isolation due to alert ...",
    "status": "Pending",
    "machineId": "machine-id",
    "creationDateTimeUtc": "2019-11-21T03:55:59.5419077Z",
    "lastUpdateDateTimeUtc": "2019-11-21T03:55:59.5419077Z",
    "cancellationRequestor": null,
    "cancellationComment": null,
    "cancellationDateTimeUtc": null,
    "errorHResult": 0,
    "scope": null,
    "relatedFileInfo": null
}

Insights

• Insight Logic: If machine was isolated using Defender ATP agent, create an insight to indicate this.
• Type: Entity.
• Title (String): entity.
• IdentifierMessage: "Host was isolated using Microsoft Defender for Endpoint."

Unisolate Machine

Unisolate a machine that was previously isolated using Microsoft Defender for Endpoint.

Parameters

Parameter Display Name	Type	Default Value	Is Mandatory	Description
Comment	String	N/A	Yes	Specify a comment for why the machine needs to be unisolated.
Create an Insight?	Checkbox	Checked		If enabled, the action creates a Google Security Operations SOAR Insight with related information if executed successfully.

Use cases

The action can be used for situations where the machine was already isolated, but with the new data gathered during playbook processing (for example, first machine was isolated, next we created a threat indicator for a suspicious file, and ran the "Stop and Quarantine" action to remove this file from the affected machine) we can consider it safe to remove the affected machine from isolation.

Run on

This action runs on the following entities:

• Host
• IP Address

Action results

Script result

True if the API Endpoint returned for every provided entity it ran on, status 201, in JSON Response "status": "Pending", which indicates that the API request executed successfully. If at least for one of the entities the action fails, the final result should be fail (False).

Script Result Name	Value Options	Example
is_success	True/False	is_success:False

JSON result

{
    "@odata.context": "https://api.securitycenter.windows.com/api/$metadata#MachineActions/$entity",
    "id": "example-id",
    "type": "Unisolate",
    "requestor": "requestor-id",
    "requestorComment": "Unisolate machine due to the following remediation measures taken...",
    "status": "Pending",
    "machineId": "machine-id",
    "creationDateTimeUtc": "2019-11-21T03:59:34.7389352Z",
    "lastUpdateDateTimeUtc": "2019-11-21T03:59:34.7389352Z",
    "cancellationRequestor": null,
    "cancellationComment": null,
    "cancellationDateTimeUtc": null,
    "errorHResult": 0,
    "scope": null,
    "relatedFileInfo": null
}

Insights

• Type: Entity
• Title: entity.
• IdentifierMessage: Microsoft Defender for Endpoint isolation was removed.

Run Antivirus Scan

Start an antivirus scan on a host using Microsoft Defender for Endpoint. Two types of Defender ATP scans are available: Full or Quick.

Parameters

Parameter Display Name	Type	Default Value	Is Mandatory	Description
Antivirus Scan Type	DDL	Full Possible Values: Full Quick	Yes	Specify whether to start Full or Quick antivirus scan on machine.
Comment	String	N/A	Yes	Specify a comment as to why an antivirus scan needs to be executed on the machine.

Use cases

An alert came from the Defender ATP connector, during the alert processing indicators of malware compromises were found on the machine related to the Google Security Operations SOAR case entity, and because of that the user decided to run an antivirus scan on the machine to try to find malware on the host.

Run on

This action runs on the following entities:

• Host
• IP Address

Action results

Script result

True if the API Endpoint returned for every provided entity it ran on, status 201, in JSON Response "status": "Pending", which indicates that the API request executed successfully. If at least for one of the entities the action fails, the final result should be fail (False).

Script Result Name	Value Options	Example
is_success	True/False	is_success:False

JSON result

{
    "@odata.context": "https://api.securitycenter.windows.com/api/$metadata#MachineActions/$entity",
    "id": "example-id",
    "type": "RunAntiVirusScan",
    "requestor": "requestor_id",
    "requestorComment": "Run antivirus scan on suspect",
    "status": "Pending",
    "machineId": "machine-id",
    "creationDateTimeUtc": "2019-11-21T11:07:06.611628Z",
    "lastUpdateDateTimeUtc": "2019-11-21T11:07:06.611628Z",
    "cancellationRequestor": null,
    "cancellationComment": null,
    "cancellationDateTimeUtc": null,
    "errorHResult": 0,
    "scope": null,
    "relatedFileInfo": null
}

Stop and Quarantine a File on Specific Machine

Stop execution of a file on a specific machine and quarantine it using Microsoft Defender ATP agent. Action works with either Host or IP Google Security Operations SOAR entities.

Parameters

Parameter Display Name	Type	Default Value	Is Mandatory	Description
SHA1 File Hash to Quarantine	String	N/A	Yes	Specify SHA-1 file hash of the file to stop and quarantine. Note: The SHA-1 hash needs to be in the lower register for the action to find matching file.
Comment	String	N/A	Yes	Specify a comment as to why an antivirus scan needs to be executed on the machine.
Create an Insight?	Checkbox	Checked		If enabled, action will create a Google Security Operations SOAR Insight with related information if executed successfully.

Use cases

During processing of the alert that came from the Defender ATP connector, the "Stop and Quarantine File" action can be used to block the specific file from execution to prevent compromise of the machine. The need for this action might come from the advanced hunting, and the user might discover some potentially malicious files that at the moment the user wants to block on a single machine.

Run on

This action runs on the following entities:

• Host
• IP Address

Action results

Script result

Can be True or False. True if the API Endpoint returned for every provided entity it ran on, status 201, in JSON Response "status": "Pending", which indicates that API request executed successfully. If at least for one of the entities action fail - final result should be fail (False).

Script Result Name	Value Options	Example
is_success	True/False	is_success:False

JSON result

{
    "@odata.context": "https://api.securitycenter.windows.com/api/$metadata#MachineActions/$entity",
    "id": "example-id",
    "type": "StopAndQuarantineFile",
    "requestor": "requestor-id",
    "requestorComment": "Stopping and quarantining putty",
    "status": "Pending",
    "machineId": "machine-id",
    "creationDateTimeUtc": "2019-11-25T10:05:21.3641296Z",
    "lastUpdateDateTimeUtc": "2019-11-25T10:05:21.3641296Z",
    "cancellationRequestor": null,
    "cancellationComment": null,
    "cancellationDateTimeUtc": null,
    "errorHResult": 0,
    "scope": null,
    "relatedFileInfo": {
        "fileIdentifier": "d932604ab8e9debe475415851fd26929a0c0dcd1",
        "fileIdentifierType": "Sha1"
    }
}

Insights

• Type: Entity.
• Title (String): entity.
• IdentifierMessage (String): "File with SHA-1 Filehash {0} was stopped and quarantined on {1}". format (filehash,entity.Identifier).

Get File Related Alerts

Get alerts related to a file from Microsoft Defender for Endpoint based on the file hash.

Parameters

Parameter Display Value	Type	Default Value	Is Mandatory	Description
Status	String	Unknown, New, InProgress, Resolved	No	Specify the statuses of alerts to look for. Parameter accepts multiple values as a comma-separated string.
Severity	String	UnSpecified, Informational, Low, Medium, High	NO	Specify the severities of the incidents to look for. Parameter accepts multiple values as a comma-separated string.
Category	String	N/A	No	Specify the alert category to look for. If not provided, the action looks for all categories. Parameter accepts multiple values as a comma-separated string. Possible Values: 'Collection', 'CommandAndControl', 'CredentialAccess', 'DefenseEvasion', 'Discovery', 'Execution', 'Exfiltration', 'Exploit', 'InitialAccess', 'LateralMovement', 'Malware', 'Persistence', 'PrivilegeEscalation', 'Ransomware', 'SuspiciousActivity', 'UnwantedSoftware'.
Incident ID	Integer	N/A	No	Specify the Microsoft Defender Incident ID for which you want to find related alerts.

‌Use cases

While investigating an alert that came from the Defender ATP connector, this action can be used to gather information if this file is associated with any alerts to get insight on if the file is malicious or not.

Run On

This action runs on the Filehash entity.

Action results

Script result

Script Result Name	Value Options	Example
is_success	True/False	is_success:False

JSON result

{
    "@odata.context": "https://api.securitycenter.windows.com/api/$metadata#Alerts",
    "value": [
        {
            "id": "example_id",
            "incidentId": 2,
            "investigationId": 1,
            "assignedTo": null,
            "severity": "Medium",
            "status": "New",
            "classification": null,
            "determination": null,
            "investigationState": "TerminatedBySystem",
            "detectionSource": "WindowsDefenderAtp",
            "category": "DefenseEvasion",
            "threatFamilyName": null,
            "title": "Suspicious process injection observed",
            "description": "A process abnormally injected code into another process, As a result, unexpected code may be running in the target process memory. Injection is often used to hide malicious code execution within a trusted process. \nAs a result, the target process may exhibit abnormal behaviors such as opening a listening port or connecting to a command and control server.",
            "alertCreationTime": "2019-11-19T03:56:37.7335862Z",
            "firstEventTime": "2019-11-19T03:54:15.7698362Z",
            "lastEventTime": "2019-11-19T03:54:15.7698362Z",
            "lastUpdateTime": "2019-11-20T10:13:31.7266667Z",
            "resolvedTime": null,
            "machineId": "machine-id",
            "alertUser": {
                "accountName": "example.user",
                "domainName": "EXAMPLELAB"
            },
            "comments": [],
            "alertFiles": [
                {
                    "sha1": "1b3b40fbc889fd4c645cc12c85d0805ac36ba254",
                    "sha256": "d3f8fade829d2b7bd596c4504a6dae5c034e789b6a3defbe013bda7d14466677",
                    "filePath": "C:\\Windows\\System32\\WindowsPowerShell\\v1.0\\powershell.exe",
                    "fileName": "powershell.exe"
                },{
                    "sha1": "bdd0d38e113a0c7dd6213cf2e89e6cc6d66b5cdb",
                    "sha256": "328954033456d5c13e58fb5bcc6c0232f9f62cb6d9185afa51c7913338992491",
                    "filePath": "C:\\Windows\\System32\\notepad.exe",
                    "fileName": "notepad.exe"
                }
            ],
            "alertDomains": [],
            "alertIps": [],
            "alertProcesses": []
        }
    ]
}

Get File Related Machines

Get machines related to a file from Microsoft Defender for Endpoint based on the file hash.

Parameters

Parameter Display Name	Type	Default Value	Is Mandatory	Description
Machine Name	String	N/A	No	Specify the full machine name to look for.
Machine IP Address	String	N/A	No	Specify the machine IP address to look for.
Machine Risk Score	String	N/A	No	Specify the machine risk score to look for. Parameter accepts multiple values as a comma-separated string.
Machine Health Status	String	Active, Inactive, ImpairedCommunication, NoSensorData, NoSensorDataImpairedCommunication	No	Specify the machine health status to look for. Parameter accepts multiple values as a comma-separated string.
Machine OS Platform	String	N/A	No	Specify the machine OS platform to look for.
RBAC Group ID	String	N/A	No	Specify the RBAC Group ID to look for.

Use cases

While investigating an alert that came from the Defender ATP connector, this action can be used to gather information on which machines this file was registered to in Defender ATP.

Run on

This action runs on the Filehash entity.

Action results

Script result

Script Result Name	Value Options	Example
is_success	True/False	is_success:False

JSON result

{
    "@odata.context": "https://api.securitycenter.windows.com/api/$metadata#Machines",
    "value": [
        {
            "id": "example_id",
            "computerDnsName": "example-name",
            "firstSeen": "2019-11-18T11:13:04.0588699Z",
            "lastSeen": "2019-11-20T19:35:36.4619266Z",
            "osPlatform": "Windows10",
            "osVersion": null,
            "osProcessor": "x64",
            "version": "1803",
            "lastIpAddress": "192.0.2.1",
            "lastExternalIpAddress": "203.0.113.121",
            "agentVersion": "10.4860.17134.982",
            "osBuild": 17134,
            "healthStatus": "Active",
            "rbacGroupId": 0,
            "rbacGroupName": null,
            "riskScore": "High",
            "exposureLevel": "Medium",
            "aadDeviceId": null,
            "machineTags": []
        }
    ]
}

Run Advanced Hunting Query

Run Microsoft Defender for Endpoint advanced hunting query. Note that quotes, new lines, or other special symbols need to be escaped, for example, use the backslash for escaping quotes.

Parameters

Parameter Display Name	Type	Default Value	Is Mandatory	Description
Parameter Display Name	Type	Default Value	Is Mandatory	Description
Query	String	N/A	Yes	Advanced hunting query to execute.

Use cases

The user can have hunting queries that they want to use to query data gathered in Defender ATP during the processing of a specific Defender Alert, with this action the user can run those advanced hunting queries.

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

{
    "Stats": {
        "ExecutionTime": 0.0156652,
        "resource_usage": {
            "cache": {
                "memory": {
                    "hits": 13,
                    "misses": 0,
                    "total": 13
                },
                "disk": {
                    "hits": 0,
                    "misses": 0,
                    "total": 0
                }
            },
            "cpu": {
                "user": "00:00:00.0156250",
                "kernel": "00:00:00",
                "total cpu": "00:00:00.0156250"
            },
            "memory": {
                "peak_per_node": 33554624
            }
        },
        "dataset_statistics": [
            {
                "table_row_count": 2,
                "table_size": 60
            }
        ]
    },
    "Schema": [
        {
            "Name": "EventTime",
            "Type": "DateTime"
        },
        {
            "Name": "FileName",
            "Type": "String"
        },
        {
            "Name": "InitiatingProcessFileName",
            "Type": "String"
        }
    ],
    "Results": [
        {
            "EventTime": "2019-11-18T11:13:07.043128Z",
            "FileName": "csc.exe",
            "InitiatingProcessFileName": "powershell.exe"
        },
        {
            "EventTime": "2019-11-19T03:54:14.4256361Z",
            "FileName": "csc.exe",
            "InitiatingProcessFileName": "powershell.exe"
        }
    ]
}

Warning: The JSON Results depend on Query. Different queries yield different results, therefore example that matches all cannot be provided. Also, as the JSON example can't match the actual results, you need to manually write the placeholders according to the query.

Wait for Task Status

Wait for the status of a task.

Parameters

Parameter Display Name	Type	Default Value	Is Mandatory	Description
Task IDs	String	N/A	Yes	Task IDs list as a comma-separated string.

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

[
    {
        "status": "Succeeded",
        "creation_date_time_utc": "2020-02-08T03:24:52.8526634Z",
        "cancellation_requestor": null,
        "cancellation_date_time_utc": null,
        "id": "2e39d22e-60a7-4267-899c-a1471e800000",
        "last_update_date_time_utc": "2020-02-08T03:25:35.8345081Z",
        "related_file_info": null,
        "cancellation_comment": null,
        "requestor": "e4fc6454-754d-47f7-bbdb-045fad600000",
        "error_h_result": 0,
        "scope": "Selective",
        "machine_id": "fbc85cf3fbcc8bb14d1a84fcf7bbae4531f00000",
        "type": "Isolate",
        "requestor_comment": "test"
    }
]

Get Current Task Status

Get the current status of a task.

Parameters

Parameter Display Name	Type	Default Value	Is Mandatory	Description
Task IDs	String	N/A	Yes	Task IDs list as a comma-separated string.

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

[
    {
        "status": "Succeeded",
        "creation_date_time_utc": "2020-02-08T03:24:52.8526634Z",
        "cancellation_requestor": null,
        "cancellation_date_time_utc": null,
        "id": "2e39d22e-60a7-4267-899c-a1471e800000",
        "last_update_date_time_utc": "2020-02-08T03:25:35.8345081Z",
        "related_file_info": null,
        "cancellation_comment": null,
        "requestor": "e4fc6454-754d-47f7-bbdb-045fad600000",
        "error_h_result": 0,
        "scope": "Selective",
        "machine_id": "fbc85cf3fbcc8bb14d1a84fcf7bbae4531f00000",
        "type": "Isolate",
        "requestor_comment": "test"
    }
]

Submit Entity Indicators

Submit entities as indicators in Microsoft Defender for Endpoint.

Note: Only the MD5, SHA-1 and SHA256 hashes are supported.

Parameters

Parameter Display Name	Type	Default Value	Is Mandatory	Description
Action	DDL	Block Possible Values: Block Audit Block And Remediate Allow	Yes	Specify the action that needs to be applied to the entities. Note: The "Block And Remediate" value is supported only for the filehash entities.
Severity	DDL	High Possible Values: High Medium Low Informational	Yes	Specify the severity for the found entities.
Application	String	N/A	No	Specify an application that is related to the entities.
Indicator Alert Title	String	N/A	Yes	Specify the title for the alert, if they are identified in the environment.
Description	String	Google Security Operations SOAR Remediation	Yes	Specify the description for the entities.
Recommended Action	String	N/A	No	Specify the recommended actions for the handling of the entities.

Run on

This action runs on the following entities:

• IP Address
• URL
• Filehash

Action results

Script result

Script Result Name	Value Options	Example
is_success	True/False	is_success:False

Case wall

Result Type	Value / Description	Type
Output message*	The action should not fail nor stop a playbook execution: If data is available for one entity (is_success = true): "Successfully submitted the following entities as indicators to Microsoft Defender for Endpoint: {entity.identifier}". If data is not available for one entity (is_success=true): "Action wasn't able to submit the following entities as indicators to Microsoft Defender for Endpoint: {entity.identifier}". If the 403 status code is reported for one entity: "Instance doesn't have enough permissions to submit for the following entities: {entity.identifier} If data is not available for all entities (is_success=false): "None of the provided entities were submitted as indicators to Microsoft Defender for Endpoint." If an entity is already an indicator: "The following entities are already indicators in Microsoft Defender for Endpoint: {entity.identifier}" The action should fail and stop a playbook execution: If a fatal error, like wrong credentials, no connection to the server, other: "Error executing action "Submit Entity Indicators". Reason: {0}''.format(error.Stacktrace) If the 403 status code is reported for all entities: "Error executing action "Submit Entity Indicators". Reason: none of the indicators were created due to instance permissions, please check the configuration.''.	General

Delete Entity Indicators

Delete entity indicators in Microsoft Defender for Endpoint.

Note: Only the MD5, SHA-1 and SHA256 hashes are supported.

Parameters

N/A

Run on

This action runs on the following entities:

• IP Address
• URL
• Filehash

Action results

Script result

Script Result Name	Value Options	Example
is_success	True/False	is_success:False

Case wall

Result Type	Value / Description	Type
Output message*	The action should not fail nor stop a playbook execution: If the 204 status code is reported (is_success=true): "Successfully deleted the following entities as indicators in Microsoft Defender for Endpoint: {entity.identifier}. If the incident is not found (is_success=true): "The following entities don't exist as indicators in Microsoft Defender for Endpoint: {entity.identifier}. The action should fail and stop a playbook execution: If a fatal error, like wrong credentials, no connection to the server, other is reported: "Error executing action "Delete Entity Indicators". Reason: {0}''.format(error.Stacktrace)	General

List Indicators

List indicators in Microsoft Defender for Endpoint.

Parameters

Parameter Display Name	Type	Default Value	Is Mandatory	Description
Indicators	CSV	N/A	No	Specify a comma-separated list of indicators that you would like to retrieve.
Indicator Types	CSV	FileSha1,FileSha256,FileMd5,CertificateThumbprint,IpAddress,DomainName, Url	No	Specify a comma-separated list of indicator types that you want to retrieve. Possible values: FileSha1, FileSha256, FileMd5, CertificateThumbprint, IpAddress,DomainName, Url.
Actions	CSV	Warn,Block,Audit,Alert,AlertAndBlock,BlockAndRemediate,Allowed	No	Specify a comma-separated list of indicator actions that you want to use for filtering. Possible values: Warn,Block,Audit,Alert, AlertAndBlock,BlockAndRemediate,Allowed
Severity	CSV	Informational,Low,Medium,High	No	Specify a comma-separated list of severities that you want to use for filtering. Possible values: Informational,Low,Medium,High
Max Results To Return	Integer	50	No	Specify the number of indicators to return.

Run on

This action doesn't run on entities.

Action results

Script result

Script Result Name	Value Options	Example
is_success	True/False	is_success:False

JSON result

{
    "id": "18",
    "indicatorValue": "110e7d15b011d7fac48f2bd61114db1022197f7a",
    "indicatorType": "FileSha1",
    "action": "Audit",
    "createdBy": "45e9773c-100e-4a9f-ad37-d8e182e9ed26",
    "severity": "Informational",
    "category": 1,
    "application": "demo-test",
    "educateUrl": null,
    "bypassDurationHours": null,
    "title": "test",
    "description": "test",
    "recommendedActions": "nothing",
    "creationTimeDateTimeUtc": "2022-02-08T14:20:34.9071582Z",
    "expirationTime": null,
    "lastUpdateTime": "2022-02-08T14:20:34.9151307Z",
    "lastUpdatedBy": null,
    "rbacGroupNames": [],
    "rbacGroupIds": [],
    "notificationId": null,
    "notificationBody": null,
    "version": null,
    "mitreTechniques": [],
    "historicalDetection": false,
    "lookBackPeriod": null,
    "generateAlert": true,
    "additionalInfo": null,
    "createdByDisplayName": "Example Defender ATP",
    "externalId": null,
    "createdBySource": "PublicApi",
    "certificateInfo": null
}

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 indicators for the provided criteria in Microsoft Defender for Endpoint.". If data is not available (is_success=false): "No indicators were found for the provided criteria in Microsoft Defender for Endpoint." The action should fail and stop a playbook execution: If a fatal error, like wrong credentials, no connection to the server, other is reported: "Error executing action "List Indicators". Reason: {0}''.format(error.Stacktrace) If an invalid "Indicator types" parameter is provided: "Error executing action "List Indicators". Reason: invalid value for the parameter "Indicator Types". Possible values: FileSha1, FileSha256, FileMd5, CertificateThumbprint, IpAddress, DomainName, Url. If an invalid "Actions" parameter is provided: "Error executing action "List Indicators". Reason: invalid value for the parameter "Actions". Possible values: Warn, Block, Audit, Alert, AlertAndBlock, BlockAndRemediate, Allowed. If an invalid "Severity" parameter is provided: "Error executing action "List Indicators". Reason: invalid value for the parameter "Actions". Possible values: Informational, Low, Medium, High.	General
Case Wall Table	Found Indicators Type: indicatorType Action: action Severity: severity Description: description Title: title Recommendation: recommendedActions	Entity

Connectors

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 Defender ATP Connector configuration parameters
• Microsoft Defender ATP Connector v2 configuration parameters

Microsoft Defender ATP Connector

The Defender ATP SIEM API used in the Microsoft Defender ATP Connector for events is deprecated as of March 1, 2022.

The connector periodically connects to the Defender ATP API endpoint and pulls a list of alerts generated for a specific time period. For the alerts processed, the connector in a separate request pulls the information on the detections from the Defender ATP. Detections have an AlertId field that can be used to associate the detections with specific alerts.

Connector parameters

Use the following parameters to configure the connector:

Parameter Display Name	Type	Default Value	Is Mandatory	Description
Product Field Name	String	ProductName	Yes	Describes the name of the field where the product name is stored.
Event Field Name	String	AlertName	Yes	Describes the name of the field where the event name is stored.
Environment Field Name	String	""	No	Describes the name of the field where the environment name is stored. If environment field isn't found, environment is "".
Environment Regex Pattern	String	.*	No	A regular expression pattern to run on the value found in the Environment Field Name field. Default is .* to catch all and return value unchanged. Used to allow the user to manipulate the environment field using the regular expression logic. If the regular expression pattern is null or empty, or the environment value is null, the final environment result is "".
API Root	String	https://api.securitycenter.windows.com	Yes	API root URL to use with integration. For better performance, you can use a server closest to your location: api-us.securitycenter.windows.com api-eu.securitycenter.windows.com api-uk.securitycenter.windows.com
Azure Active Directory ID	String	N/A	Yes	Microsoft Entra Tenant ID, can be viewed in Active Directory > App Registration > Your application > Directory (tenant) ID.
Integration Client ID	String	N/A	Yes	Client (Application) ID that is added for app registration in Microsoft Entra for the integration.
Integration Client Secret	Password	N/A	Yes	Secret that is entered for Azure AD app registration for the integration.
SIEM Client ID	String	N/A	Yes	Client (Application) ID for the enabled SIEM integration in Microsoft Defender for Endpoint.
SIEM Client Secret	Password	N/A	Yes	Secret for the enabled SIEM integration in Microsoft Defender for Endpoint.
Offset Time In Hours	Integer	24	Yes	Fetch alerts from X hours backwards.
Max Alerts Per Cycle	Integer	100	Yes	Number of alerts that are processed during one connector run.
Alert Statuses to fetch	String	Unknown, New, InProgress, Resolved	Yes	Specify the statuses of the Defender ATP alerts that should be fetched by the Google Security Operations SOAR server. Parameter can take multiple values as a comma-separated string.
Alert Severities to fetch	String	UnSpecified, Informational, Low, Medium, High	Yes	Specify the severities of the Defender ATP alerts that should be fetched by the Google Security Operations SOAR server. Parameter can take multiple values as a comma-separated string.
Proxy Server Address	IP_OR_HOST	N/A	No	Proxy server to use for connection.
Proxy Server Username	String	N/A	No	Proxy server username.
Proxy Server Password	Password	N/A	No	Proxy server password.

Connector rules

• The connector doesn't support blocklist or dynamic list rules.

• The connector supports proxies.

Microsoft Defender ATP Connector V2

Fetch the Defender ATP alerts using the 365 Defender incident API to get the event data. Use the connector dynamic list to ingest only specific types of alerts based on the alert detectionSource attribute value.

The connector SourceGroupIdentifier attribute can be used to group alerts based on the Defender ATP incident ID.

Prerequisites

Before configuring the connector, make sure to grant additional permissions to your Microsoft Entra application:

1. Sign in to the Azure portal as a user administrator or a password administrator.

2. Select Microsoft Entra ID.

3. Go to API Permissions > Add a permission > APIs my organization uses.

4. Select Microsoft Threat Protection > Application permissions.

5. In the Select Permissions section, select the following required permissions:

   • Incident.Read.All
   • Incident.ReadWrite.All

6. Click Add permissions.

7. Click Grant admin consent for YOUR_ORGANIZATION_NAME.

Connector parameters

Use the following parameters to configure the connector:

Parameter Display Name	Type	Default Value	Is Mandatory	Description
Product Field Name	String	::	Yes	Describes the name of the field where the product name is stored.
Event Field Name	String	EventName	Yes	Describes the name of the field where the event name is stored.
Environment Field Name	String	""	No	Describes the name of the field where the environment name is stored. If environment field isn't found, environment is "".
Environment Regex Pattern	String	.*	No	A regular expression pattern to run on the value found in the Environment Field Name field. Default is .* to catch all and return value unchanged. Used to allow the user to manipulate the environment field using the regular expression logic. If the regular expression pattern is null or empty, or the environment value is null, the final environment result is "".
Defender ATP API Root	String	https://api.securitycenter.windows.com	Yes	API root URL to use with integration For better performance, you can use a server closest to your location: api-us.securitycenter.windows.com api-eu.securitycenter.windows.com api-uk.securitycenter.windows.com
365 Defender API Root	String	https://api.security.microsoft.com	Yes	API root of the Microsoft 365 Defender instance used to get the Google Security Operations SOAR events data.
Azure Active Directory ID	String	N/A	Yes	Microsoft Entra Tenant ID that can be found in Microsoft Entra > App Registration > Your application > Directory (tenant) ID.
Integration Client ID	String	N/A	Yes	Client (Application) ID that is added for app registration in Microsoft Entra for the integration.
Integration Client Secret	Password	N/A	Yes	Secret that is entered for Azure AD app registration for the integration.
Verify SSL	Checkbox	Checked	Yes	If enabled, verifies that the SSL certificate for the connection to the Microsoft 365 Defender server is valid.
Offset Time In Hours	Integer	24	Yes	Fetch alerts from X hours backwards.
Max Alerts Per Cycle	Integer	10	Yes	Number of alerts that are processed during one connector run.
Alert Statuses to fetch	String	Unknown, New, InProgress, Resolved	Yes	Specify the statuses of the Defender ATP alerts that should be fetched by the Google Security Operations SOAR server. Parameter can take multiple values as a comma-separated string.
Alert Severities to fetch	String	UnSpecified, Informational, Low, Medium, High	Yes	Specify the severities of the Defender ATP alerts that should be fetched by the Google Security Operations SOAR server. Parameter can take multiple values as a comma-separated string.
Disable Overflow	Checkbox	Unchecked	No	If enabled, the connector ignores the overflow mechanism.
Script Timeout	Integer	300	Yes	Specify the timeout for connector to run.
Use whitelist as a blacklist	Checkbox	Unchecked	No	If enabled, dynamic list is used as a blocklist.
Proxy Server Address	IP_OR_HOST	N/A	No	Proxy server to use for connection.
Proxy Server Username	String	N/A	No	Proxy server username.
Proxy Server Password	Password	N/A	No	Proxy server password.

Connector rules

The connector supports a dynamic list logic based on the detectionSource Defender ATP alert field value.