Microsoft 365 Defender (Email & collaboration)

Overview

Microsoft 365 Defender, part of Microsoft's XDR solution, leverages the Microsoft 365 security portfolio to automatically analyze threat data across domains, building a complete picture of each attack in a single dashboard. This integration allows organizations to fetch security incidents, update security incidents and run advanced hunting queries to inspect unusual activity, detect possible threats, and even respond to attacks.

D3's integration for Microsoft 365 Defender (Email & collaboration) is using Exchange Online PowerShell to provide the operation on the Tenant Allow/Block list, which allows the user to Allow/Block email addresses, domains, URLs, and files.

D3 SOAR is providing REST operations to function with Microsoft 365 Defender (Email & collaboration).

Microsoft 365 Defender (Email & collaboration) is available for use in:

D3 SOAR	V16.0+
Category	Email Messaging
Deployment Options	Option II, Option IV

Connection

To connect to Microsoft 365 Defender (Email & collaboration) from D3 SOAR, please follow this part to collect the required information below:

Parameter	Description	Example
Username	The username to connect Microsoft Office 365	*@*.onmicrosoft.com
Password	The password to connect Microsoft Office 365	l8J*******************hr1

Permission Requirements

Each endpoint in the Microsoft 365 Defender (Email & collaboration) API requires a certain permission scope. The following are required scopes for the commands in this integration:

Command	Required Permission
Add Items To Blocklist	Security Administrator
Block File Hashes	Security Administrator
Block Senders	Security Administrator
List Items In Blocklist	Global Reader + Security Reader
Remove Items From Blocklist	Global Reader + Security Reader
Test Connection	Security Administrator

As Microsoft 365 Defender (Email & collaboration) is using role-based access control (RBAC), the D3 connector will be generated based on a specific user account and the application. Therefore, the command permissions are inherited from the user account’s role. Users need to configure their user profile from the Microsoft 365 Defender (Email & collaboration) console for each command in this integration.

Reader Note

https://learn.microsoft.com/en-us/microsoft-365/security/office-365-security/tenant-allow-block-list-email-spoof-configure?view=o365-worldwide

Configuring Microsoft 365 Defender (Email & collaboration) to Work with D3 SOAR

Reader Note

Before proceeding with the integration, ensure that the pwsh library is installed in your environment, be it on Windows or a Linux container.

Navigate to the Azure portal and log in with your credentials.
Click on Users or use the search bar at the top to search for "Users."
To use an existing user, locate the desired user from the list. To create a new user, click on + New User at the top of the page. In this example, we'll create and use a user named "D3 Support."
If you're creating a new user, complete the required fields and click on Review + create.
Once the user is selected or created, navigate to Assigned roles and click on + Add assignments.
Select the roles for this user, ensuring that Active is selected as the assignment type. The assigned role must be Security Administrator or another role with higher privileges than the Security Administrator role.
Upon creating the new user, ensure you log out of the current account, then log in using the newly created account credentials. You will be prompted to update your password; please follow the on-screen instructions to complete this step.
Store the updated username and password in a secure location, as they are required to build a connector in D3 SOAR. When configuring the connector parameters in D3 SOAR, remember that the username corresponds to the email address provided earlier.

Configuring D3 SOAR to Work with Microsoft 365 Defender (Email & collaboration)

Log in to D3 SOAR.
Find the Microsoft 365 Defender (Email & collaboration) integration.
1. Navigate to Configuration on the top header menu.
2. Click on the Integration icon on the left sidebar.
3. Type Microsoft 365 Defender (Email & collaboration) in the search box to find the integration, then click it to select it.
4. Click + Connection, on the right side of the Connections section. A new connection window will appear.
Configure the following fields to create a connection to Microsoft 365 Defender (Email & collaboration).
1. Connection Name: The desired name for the connection.
2. Site: Specifies the site to use the integration connection. Use the drop-down menu to select the site. The Share to Internal Sites option enables all sites defined as internal sites to use the connection. Selecting a specific site will only enable that site to use the connection.
3. Recipient site for events from connections Shared to Internal Sites: This field appears if you selected Share to Internal Sites for Site to let you select the internal site to deploy the integration connection.
4. Agent Name (Optional): Specifies the proxy agent required to build the connection. Use the dropdown menu to select the proxy agent from a list of previously configured proxy agents.
5. Description (Optional): Add your desired description for the connection.
6. Tenant (Optional): When configuring the connection from a master tenant site, you have the option to choose the specific tenant sites you want to share the connection with. Once you enable this setting, you can filter and select the desired tenant sites from the dropdowns to share the connection.
7. Configure User Permissions: Defines which users have access to the connection.
8. Active: Check the tick box to ensure the connection is available for use.
9. System: This section contains the parameters defined specifically for the integration. These parameters must be configured to create the integration connection.
  1. Input the Username. Please note this should be the email address of the user.
  2. Input the Password.
10. Enable Password Vault: An optional feature that allows users to take the stored credentials from their own password vault. Please refer to the password vault connection guide if needed.
11. Connection Health Check: Updates the connection status you have created. A connection health check is done by scheduling the Test Connection command of this integration. This can only be done when the connection is active.
  To set up a connection health check, check the Connection Health Check tickbox. You can customize the interval (minutes) for scheduling the health check. An email notification can be set up after a specified number of failed connection attempts.
Test the connection.
1. Click Test Connection to verify the account credentials and network connection. If the Test Connection Passed alert window appears, the test connection is successful. You will see Passed with a green checkmark appear beside the Test Connection button. If the test connection fails, please check your connection parameters and try again.
2. Click OK to close the alert window.
3. Click + Add to create and add the configured connection.

Commands

Microsoft 365 Defender (Email & collaboration) includes the following executable commands for users to set up schedules or create playbook workflows. With the Test Command, you can execute these commands independently for playbook troubleshooting.

Integration API Note

For more information about the Microsoft 365 Defender (Email & collaboration) API, please refer to the Microsoft 365 Defender (Email & collaboration) API reference.

Reader Note

Certain permissions are required for each command. Please refer to the Permission Requirements and Configuring Microsoft 365 Defender (Email & collaboration) to Work with D3 SOAR for details.

Note for Time-related parameters

The input format of time-related parameters may vary based on your account settings. As a result, the sample data provided in our commands is different from what you see. To set your preferred time format, follow these steps:

Navigate to Configuration > Application Settings. Select Date/Time Format.
Choose your desired date and time format.

After that, you will be able to view your preferred time format when configuring the DateTime input parameters for commands.

Add Items To Blocklist

Adds entries to the blocklist in the Microsoft 365 Defender portal.

Input

Input Parameter	Required /Optional	Description	Example
Entries	Required	The entries in the blocklist, with allowed value types being email addresses, domains, file hashes, or URLs. However, different types of entries cannot be set simultaneously. For URL entries, the maximum allowable length is 250 characters. Wildcard characters such as tilde (~) and asterisk (*) are supported for URL entries. For a comprehensive understanding of the URL syntax, refer to Allow or block URLs using the Tenant Allow/Block List \| Microsoft Learn from Microsoft's documentation.	[ "***@example.com","example.com" ]
List Type	Required	The blocklist type for the entries. The available types are Emails, Domains, File Hashes, and URLs.	Emails & Domains
Expiration Date	Optional	The expiration date in UTC time. If not defined, the expiration date remains unset by default.	2021-12-15 00:00
Note	Optional	A note providing additional information about the list.	The list was created by a tester.

Output

Raw Data

The primary response data from the API request.

SAMPLE DATA

JSON

{
    "Error": "",
    "Identity": "",
    "Value": [
        {
            "Error": null,
            "Identity": "***************************************",
            "Value": "***@example.com",
            "Action": "Block",
            "Notes": "Create a test list.",
            "SubmissionID": "Non-Submission",
            "ListSubType": "Tenant",
            "SysManaged": false,
            "LastModifiedDateTime": "2022-10-20T00:25:53.7813299Z",
            "ExpirationDate": "2023-05-06T07:30:00Z",
            "ObjectState": "New",
            "EntryValueHash": "***/***",
            "ModifiedBy": "***************************************"
        },
        {
            "Error": null,
            "Identity": "***************************************",
            "Value": "example.com",
            "Action": "Block",
            "Notes": "Create a test list.",
            "SubmissionID": "Non-Submission",
            "ListSubType": "Tenant",
            "SysManaged": false,
            "LastModifiedDateTime": "2022-10-20T00:25:53.8125775Z",
            "ExpirationDate": "2023-05-06T07:30:00Z",
            "ObjectState": "New",
            "EntryValueHash": "***************************************=",
            "ModifiedBy": "***@example.com"
        }
    ],
    "Action": 0,
    "Notes": "",
    "SubmissionID": "",
    "ListSubType": "",
    "SysManaged": "",
    "LastModifiedDateTime": "",
    "ExpirationDate": "",
    "ObjectState": "Unchanged",
    "EntryValueHash": "",
    "ModifiedBy": ""
}

Key Fields

Common cyber security indicators such as unique IDs, file hash values, CVE numbers, IP addresses, etc., will be extracted from Raw Data as Key Fields.
The system stores these key fields in the path $.[playbookTask].outputData. You can use these key-value pairs as data points for playbook task inputs.

SAMPLE DATA

CODE

{
    "Entries": "\"[ \\\"***@example.com\\\",\\\"example.com\\\" ]\"",
    "EntryIDs": "\"[ \\\"***************************************\\\" ]\"",
    "ListType": "\"Emails & Domains\""
}

Return Data

Indicates one of the possible command execution states: Successful or Failed.

The Failed state can be triggered by any of the following errors:

A connection issue with the integration
The API returned an error message
No response from the API

You can view more details about an error in the Error tab.

Return Data can be passed down directly to a subsequent command or used to create conditional tasks in playbooks.

SAMPLE DATA

CODE

Successful

Result

Provides a brief summary of outputs in an HTML formatted table.

SAMPLE DATA


Error
Identity
Value	{'Error': None, 'Identity': *' ', 'Value': '@example.com', 'Action': 'Block', 'Notes': 'Create a test list.', 'SubmissionID': '', 'ListSubType': 'Tenant', 'SysManaged': False, 'LastModifiedDateTime': '2022-10-20T00:25:53.7813299Z', 'ExpirationDate': '2023-05-06T07:30:00Z', 'ObjectState': 'New', 'EntryValueHash': '/', 'ModifiedBy': '@example.com'} {'Error': None, 'Identity': '', 'Value': 'example.com', 'Action': 'Block', 'Notes': 'Create a test list.', 'SubmissionID': '', 'ListSubType': 'Tenant', 'SysManaged': False, 'LastModifiedDateTime': '2022-10-20T00:25:53.8125775Z', 'ExpirationDate': '2023-05-06T07:30:00Z', 'ObjectState': 'New', 'EntryValueHash': '', 'ModifiedBy': '*@example.com'}
Action	0
Notes
SubmissionID
ListSubType
SysManaged
LastModifiedDateTime
ExpirationDate
ObjectState	Unchanged
EntryValueHash
ModifiedBy

Error Handling

If the Return Data is Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	Add Items To Blocklist failed.
Status Code	The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Microsoft 365 Defender (Email & collaboration) portal. Refer to the HTTP Status Code Registry for details.	Status Code: 400.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: Invalid user name and password.

Error Sample Data

Add Items To Blocklist failed.

Status Code: 400.

Message: Invalid user name and password.

Block File Hashes

Blocks email messages containing the specified file hashes.

Input

Input Parameter	Required /Optional	Description	Example
File Hashes	Required	The list of SHA256 hashes corresponding to files that are to be blocked when detected in email attachments.	["**********************"]
Expiration Date	Optional	The expiration date in UTC time. If not defined, the expiration date remains unset by default.	2021-12-15 00:00
Note	Optional	A note providing additional information about the list.	The list was created by a tester.

Output

Raw Data

The primary response data from the API request.

SAMPLE DATA

JSON

{
    "Error": "",
    "Identity": "",
    "Value": [
        {
            "Error": null,
            "Identity": "***************************************",
            "Value": "***************************************",
            "Notes": null,
            "SubmissionID": "Non-Submission",
            "ListSubType": "Tenant",
            "SysManaged": false,
            "LastModifiedDateTime": "2022-10-13T18:12:47.2469711Z",
            "ExpirationDate": null,
            "ObjectState": "New",
            "EntryValueHash": "***/***/***",
            "ModifiedBy": "***@example.com"
        },
        {
            "Error": null,
             "Identity": "***************************************",
            "Value": "***************************************",
            "Action": "Block",
            "Notes": null,
            "SubmissionID": "Non-Submission",
            "ListSubType": "Tenant",
            "SysManaged": false,
            "LastModifiedDateTime": "2022-10-13T18:12:47.2782149Z",
            "ExpirationDate": null,
            "ObjectState": "New",
            "EntryValueHash": "***************************************",
            "ModifiedBy": "***@example.com"
        }
    ],
    "Action": 0,
    "Notes": "",
    "SubmissionID": "***",
    "ListSubType": "",
    "SysManaged": "",
    "LastModifiedDateTime": "",
    "ExpirationDate": "",
    "ObjectState": "Unchanged",
    "EntryValueHash": "",
    "ModifiedBy": ""
}

Key Fields

Common cyber security indicators such as unique IDs, file hash values, CVE numbers, IP addresses, etc., will be extracted from Raw Data as Key Fields.
The system stores these key fields in the path $.[playbookTask].outputData. You can use these key-value pairs as data points for playbook task inputs.

SAMPLE DATA

CODE

{
    "Entries": "\"[\\\"*****\\\\", \\\"*****\\\" ]\"",
    "EntryIDs": "\"[ \\\"*****\\\" ]\"",
    "ListType": "\"File Hashes\""
}

Return Data

Indicates one of the possible command execution states: Successful or Failed.

The Failed state can be triggered by any of the following errors:

A connection issue with the integration
The API returned an error message
No response from the API

You can view more details about an error in the Error tab.

Return Data can be passed down directly to a subsequent command or used to create conditional tasks in playbooks.

SAMPLE DATA

CODE

Successful

Result

Provides a brief summary of outputs in an HTML formatted table.

SAMPLE DATA

Error
Identity
Value	{'Error': None, 'Identity': '***', 'Value': '*', 'Action': 'Block', 'Notes': None, 'SubmissionID': '*', 'ListSubType': 'Tenant', 'SysManaged': False, 'LastModifiedDateTime': '2022-10-13T18:12:47.2469711Z', 'ExpirationDate': None, 'ObjectState': 'New', 'EntryValueHash': '//=', 'ModifiedBy': '@example.com'} {'Error': None, 'Identity': '', 'Value': '', 'Action': 'Block', 'Notes': None, 'SubmissionID': '', 'ListSubType': 'Tenant', 'SysManaged': False, 'LastModifiedDateTime': '2022-10-13T18:12:47.2782149Z', 'ExpirationDate': None, 'ObjectState': 'New', 'EntryValueHash': '', 'ModifiedBy': '*@example.com'}
Action	0
Notes
SubmissionID
ListSubType
SysManaged
LastModifiedDateTime
ExpirationDate
ObjectState	Unchanged
EntryValueHash
ModifiedBy

Error Handling

If the Return Data is Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	Block File Hashes failed.
Status Code	The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Microsoft 365 Defender (Email & collaboration) portal. Refer to the HTTP Status Code Registry for details.	Status Code: 400.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: Invalid user name and password.

Error Sample Data

Block File Hashes failed.

Status Code: 400.

Message: Invalid user name and password.

Block Senders

Blocks email messages sent from the specified domains or email addresses.

Input

Input Parameter	Required /Optional	Description	Example
Senders	Required	The list of domains or email addresses from which email messages should be blocked.	[ "*@.com", "@*.com" ]
Expiration Date	Optional	The expiration date in UTC time. If not defined, the expiration date remains unset by default.	2021-12-15 00:00
Note	Optional	A note providing additional information about the list.	The list was created by a tester.

Output

Raw Data

The primary response data from the API request.

SAMPLE DATA

JSON

{
    "Error": "",
    "Identity": "",
    "Value": [
        {
            "Error": null,
            "Identity": "***************************************",
            "Value": "***@example.com",
            "Action": "Block",
            "Notes": "Create a test list.",
            "SubmissionID": "Non-Submission",
            "ListSubType": "Tenant",
            "SysManaged": false,
            "LastModifiedDateTime": "2022-10-13T00:13:56.2081668Z",
            "ExpirationDate": null,
            "ObjectState": "New",
            "EntryValueHash": "***/***",
            "ModifiedBy": "***@example.com"
        },
        {
            "Error": null,
            "Identity": "***************************************",
            "Value": "***@example.com",
            "Action": "Block",
            "Notes": "Create a test list.",
            "SubmissionID": "Non-Submission",
            "ListSubType": "Tenant",
            "SysManaged": false,
            "LastModifiedDateTime": "2022-10-13T00:13:56.2706543Z",
            "ExpirationDate": null,
            "ObjectState": "New",
            "EntryValueHash": "***************************************",
            "ModifiedBy": "***@example.com"
        }
    ],
    "Action": 0,
    "Notes": "",
    "SubmissionID": "***",
    "ListSubType": "",
    "SysManaged": "",
    "LastModifiedDateTime": "",
    "ExpirationDate": "",
    "ObjectState": "Unchanged",
    "EntryValueHash": "",
    "ModifiedBy": ""
}

Key Fields

Common cyber security indicators such as unique IDs, file hash values, CVE numbers, IP addresses, etc., will be extracted from Raw Data as Key Fields.
The system stores these key fields in the path $.[playbookTask].outputData. You can use these key-value pairs as data points for playbook task inputs.

SAMPLE DATA

CODE

{
    "Entries": "\"[ \\\"***@example.com\\\", \\\"***@example.com\\\" ]\"",
    "EntryIDs": "\"[ \\\"***************************************\\\" ]\"",
    "ListType": "\"Emails & Domains\""
}

Return Data

Indicates one of the possible command execution states: Successful or Failed.

The Failed state can be triggered by any of the following errors:

A connection issue with the integration
The API returned an error message
No response from the API

You can view more details about an error in the Error tab.

Return Data can be passed down directly to a subsequent command or used to create conditional tasks in playbooks.

SAMPLE DATA

CODE

Successful

Result

Provides a brief summary of outputs in an HTML formatted table.

SAMPLE DATA

Error
Identity
Value	{'Error': None, 'Identity': '*', 'Value': '@example.com', 'Action': 'Block', 'Notes': 'Create a test list.', 'SubmissionID': '', 'ListSubType': 'Tenant', 'SysManaged': False, 'LastModifiedDateTime': '2022-10-13T00:13:56.2081668Z', 'ExpirationDate': None, 'ObjectState': 'New', 'EntryValueHash': '/', 'ModifiedBy': '@example.com'} {'Error': None, 'Identity': '', 'Value': '@example.com', 'Action': 'Block', 'Notes': 'Create a test list.', 'SubmissionID': 'Non-Submission', 'ListSubType': 'Tenant', 'SysManaged': False, 'LastModifiedDateTime': '2022-10-13T00:13:56.2706543Z', 'ExpirationDate': None, 'ObjectState': 'New', 'EntryValueHash': '', 'ModifiedBy': '*@example.com'}
Action	0
Notes
SubmissionID
ListSubType
SysManaged
LastModifiedDateTime
ExpirationDate
ObjectState	Unchanged
EntryValueHash
ModifiedBy

Error Handling

If the Return Data is Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	Block Senders failed.
Status Code	The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Microsoft 365 Defender (Email & collaboration) portal. Refer to the HTTP Status Code Registry for details.	Status Code: 400.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: Invalid user name and password.

Error Sample Data

Block Senders failed.

Status Code: 400.

Message: Invalid user name and password.

List Items In Blocklist

Retrieves items from the specified blocklist type.

Input

Input Parameter	Required /Optional	Description	Example
Entry	Optional	The entry to retrieve item details. Entries can be specified as an email address, a domain, a file hash or a URL.	***@example.com
List Type	Required	The blocklist type for the entry. The available types are Emails, Domains, File Hashes, and URLs.	URLs

Output

Raw Data

The primary response data from the API request.

SAMPLE DATA

JSON

{
    "Error": "",
    "Identity": "***",
    "Value": [
        {
            "Error": null,
            "Identity": "***************************************",
            "Value": "***@example.com",
            "Action": "Block",
            "Notes": "Create a test list.",
            "SubmissionID": "Non-Submission",
            "ListSubType": "Tenant",
            "SysManaged": false,
            "LastModifiedDateTime": "2022-10-20T00:02:57.4032Z",
            "ExpirationDate": "2023-05-06T07:30:00Z",
            "ObjectState": "Unchanged",
            "EntryValueHash": "***/***",
            "ModifiedBy": "***@example.com"
        }
    ],
    "Action": 0,
    "Notes": "",
    "SubmissionID": "***",
    "ListSubType": "",
    "SysManaged": "",
    "LastModifiedDateTime": "",
    "ExpirationDate": "",
    "ObjectState": "Unchanged",
    "EntryValueHash": "",
    "ModifiedBy": ""
}

Key Fields

Common cyber security indicators such as unique IDs, file hash values, CVE numbers, IP addresses, etc., will be extracted from Raw Data as Key Fields.
The system stores these key fields in the path $.[playbookTask].outputData. You can use these key-value pairs as data points for playbook task inputs.

SAMPLE DATA

CODE

{
    "Entries": "\"[ \\\"***@example.com\\\" ]\"",
    "EntryIDs": "\"[ \\\"***************************************\\\" ]\"",
    "ListType": "\"URLs\""
}

Return Data

Indicates one of the possible command execution states: Successful or Failed.

The Failed state can be triggered by any of the following errors:

A connection issue with the integration
The API returned an error message
No response from the API

You can view more details about an error in the Error tab.

Return Data can be passed down directly to a subsequent command or used to create conditional tasks in playbooks.

SAMPLE DATA

CODE

Successful

Result

Provides a brief summary of outputs in an HTML formatted table.

SAMPLE DATA

Error
Identity
Value	{'Error': None, 'Identity': '*', 'Value': '@example.com', 'Action': 'Block', 'Notes': 'Create a test list.', 'SubmissionID': '', 'ListSubType': 'Tenant', 'SysManaged': False, 'LastModifiedDateTime': '2022-10-20T00:02:57.4032Z', 'ExpirationDate': '2023-05-06T07:30:00Z', 'ObjectState': 'Unchanged', 'EntryValueHash': '/**', 'ModifiedBy': ' '}
Action	0
Notes
SubmissionID
ListSubType
SysManaged
LastModifiedDateTime
ExpirationDate
ObjectState	Unchanged
EntryValueHash
ModifiedBy

Error Handling

If the Return Data is Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	List Items In Blocklist failed.
Status Code	The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Microsoft 365 Defender (Email & collaboration) portal. Refer to the HTTP Status Code Registry for details.	Status Code: 400.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: Invalid user name and password.

Error Sample Data

List Items In Blocklist failed.

Status Code: 400.

Message: Invalid user name and password.

Remove Items From Blocklist

Removes items from the specified blocklist type.

Reader Note

The parameter Entries is required to run this command.

Run the List Items In Blocklist command to obtain entry IDs. Entry IDs can be found in the returned raw data at the path $.value[*].Identity.

Input

Input Parameter	Required /Optional	Description	Example
Entries	Required	The entries or entry IDs to remove from the blocklist, with allowed value types being email addresses, domains, file hashes, or URLs. However, different types of entries cannot be set simultaneously. Entry IDs can be obtained using the List Items In Blocklist command.	["**********************"]
Entity Type	Optional	The entity type for the entries. The available types are Entries or Entry IDs. The default value is Entries.	Entry IDs
List Type	Required	The blocklist type for the entries. The available types are Emails, Domains, File Hashes, and URLs.	URLs

Output

Raw Data

The primary response data from the API request.

SAMPLE DATA

JSON

{
    "Error": "",
    "Identity": "***",
    "Value": [
        {
            "Error": null,
            "Identity": "***************************************",
            "Value": "***@example.com",
            "Action": "Block",
            "Notes": "Create a test list.",
            "SubmissionID": "Non-Submission",
            "ListSubType": "Tenant",
            "SysManaged": false,
            "LastModifiedDateTime": "2022-10-20T00:02:57.4032Z",
            "ExpirationDate": "2023-05-06T07:30:00Z",
            "ObjectState": "Unchanged",
            "EntryValueHash": "***/***",
            "ModifiedBy": "***@example.com"
        }
    ],
    "Action": 0,
    "Notes": "",
    "SubmissionID": "***",
    "ListSubType": "",
    "SysManaged": "",
    "LastModifiedDateTime": "",
    "ExpirationDate": "",
    "ObjectState": "Unchanged",
    "EntryValueHash": "",
    "ModifiedBy": ""
}

Key Fields

Common cyber security indicators such as unique IDs, file hash values, CVE numbers, IP addresses, etc., will be extracted from Raw Data as Key Fields.
The system stores these key fields in the path $.[playbookTask].outputData. You can use these key-value pairs as data points for playbook task inputs.

SAMPLE DATA

CODE

{
    "Entries": "\"[ \\\"***@example.com\\\" ]\"",
    "EntryIDs": "\"[ \\\"***************************************\\\" ]\"",
    "ListType": "\"URLs\""
}

Return Data

Indicates one of the possible command execution states: Successful or Failed.

The Failed state can be triggered by any of the following errors:

A connection issue with the integration
The API returned an error message
No response from the API

You can view more details about an error in the Error tab.

Return Data can be passed down directly to a subsequent command or used to create conditional tasks in playbooks.

SAMPLE DATA

CODE

Successful

Result

Provides a brief summary of outputs in an HTML formatted table.

SAMPLE DATA

Error
Identity
Value	{'Error': None, 'Identity': '*', 'Value': '@example.com', 'Action': 'Block', 'Notes': 'Create a test list.', 'SubmissionID': '', 'ListSubType': 'Tenant', 'SysManaged': False, 'LastModifiedDateTime': '2022-10-20T00:02:57.4032Z', 'ExpirationDate': '2023-05-06T07:30:00Z', 'ObjectState': 'Unchanged', 'EntryValueHash': '/', 'ModifiedBy': '*@example.com'}
Action	0
Notes
SubmissionID
ListSubType
SysManaged
LastModifiedDateTime
ExpirationDate
ObjectState	Unchanged
EntryValueHash
ModifiedBy

Error Handling

If the Return Data is Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	Remove Items From Blocklist failed.
Status Code	The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Microsoft 365 Defender (Email & collaboration) portal. Refer to the HTTP Status Code Registry for details.	Status Code: 400.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: Invalid user name and password.

Error Sample Data

Remove Items From Blocklist failed.

Status Code: 400.

Message: Invalid user name and password.

Test Connection

Allows you to perform a health check on an integration connection. You can schedule a periodic health check by selecting Connection Health Check when editing an integration connection.

Input

N/A

Output

Return Data

Indicates one of the possible command execution states: Successful or Failed.

The Failed state can be triggered by any of the following errors:

A connection issue with the integration
The API returned an error message
No response from the API

You can view more details about an error in the Error tab.

SAMPLE DATA

CODE

Successful

Error Handling

If the Return Data is Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	Test Connection failed. Failed to check the connector.
Status Code	The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Microsoft 365 Defender (Email & collaboration) portal. Refer to the HTTP Status Code Registry for details.	Status Code: 400.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: Invalid user name and password.

Error Sample Data

Test Connection failed. Failed to check the connector.

Status Code: 400.

Message: Invalid user name and password.