Microsoft 365 Defender (Email & collaboration)

LAST UPDATED: 09/05/2024

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
Default
Authentication Type	The type of authentication used for the integration connection. Available types are OAuth2 and Basic Authentication without MFA. If not specified, the default authentication type is Basic Authentication. It is recommended to use OAuth2 authentication. If you use OAuth2, please add the application permission "Office 365 Exchange Online - Exchange.ManageAsApp" to the application. Note that compliance search-related commands only support Basic Authentication.	OAuth2
Authentication Type: Basic Authentication
Username	The username to connect Microsoft Office 365	***@***.onmicrosoft.com
Password	The password to connect Microsoft Office 365	*****
Authentication Type: OAuth2
Tenant ID	The Microsoft tenant ID for OAuth2.0 authentication.	*****
Client ID	The client ID of Microsoft Entra ID application for OAuth2.0 authentication.	*****
Client Secret	The client Secret of Microsoft Entra ID application for OAuth2.0 authentication.	*****

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 Roles (Basic Authentication)	Required Application Permissions (OAuth2 Authentication)
Add Items To Blocklist	Microsoft Entra ID role: Security Administrator – or – Exchange Admin Center Role: Tenant AllowBlockList Manager	(Application permission) Office 365 Exchange Online: Exchange.ManageAsApp
Block File Hashes	Security Operator
Block Senders	Security Operator
Convert Type Of Mailboxes	Security Administrator
Delete Search Result Emails	Compliance Data Administrator role in Microsoft Entra Assigned the Search and Purge role directly or in Organization Management role group in the Microsoft Purview compliance portal. See Find the permissions required to run any Exchange cmdlet \| Microsoft Learn for more details.
Get Compliance Content Search Status	Compliance Data Administrator role in Microsoft Entra Assigned the Preview role in the Microsoft Purview compliance portal See Find the permissions required to run any Exchange cmdlet \| Microsoft Learn for more details.
List Items In Blocklist	Security Reader
List Quarantine Messages	Security Reader
Modify Permission To Mailbox	Security Administrator, Exchange Administrator role
Preview Compliance Search Result	Compliance Data Administrator role in Microsoft Entra Assigned the Preview role directly or in eDiscovery Manager role group in the Microsoft Purview compliance portal See Find the permissions required to run any Exchange cmdlet \| Microsoft Learn for more details.
Release Quarantine Messages	Security Administrator
Remove Items From Blocklist	Security Operator
Start Compliance Content Search	Compliance Data Administrator role in Microsoft Entra Assigned the Preview role in the Microsoft Purview compliance portal See Find the permissions required to run any Exchange cmdlet \| Microsoft Learn for more details.
Test Connection	Security Reader

As Microsoft 365 Defender (Email & collaboration) uses two types of authentication: Basic (using username and password) and OAuth2.

Basic authentication uses 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. Please refer to Allow or block email using the Tenant Allow/Block List - Microsoft Defender for Office 365 | Microsoft Learn for more details.

For OAuth2 authentication, the application permission "Office 365 Exchange Online - Exchange.ManageAsApp" must be added to the application.

Procedure for Adding a Custom Role Group in the Exchange Admin Center

Login to https://admin.exchange.microsoft.com/#/.
Click on Admin roles, on the left side menu, under the Roles section.
Click Add role group to add a custom role group.
Enter a name for the role group, then click on the Next button.
Select the Tenant AllowBlockList Manager role, then click on the Next button.
Select the users to assign to this role group, then click on the Next button.
Click on the Add role group button.

READER NOTE

The group owner or the user creating this role group must be an active user in the Microsoft 365 Admin Center and have a Microsoft 365-related license.

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

Configuring for Basic Authentication

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 for OAuth2 Authentication

Log into the Azure Portal (https://portal.azure.com/ ).
Navigate to the top search bar and search "App registrations", then click App Registrations.
If you already have created Apps, you can use one of them. Skip to step 6 to obtain the Client ID & Tenant ID.
If you do not have an App, click + New registration found near the top left corner to create one.
Register an application:
1. Enter an application Name. U
2. nder Support account types to Accounts select Accounts in this organizational directory only (<home organization name> only - Single tenant).
3. Click Register.
In the App Overview tab, copy and save the Application(client) ID and Directory(tenant) ID for building the D3 SOAR connection. Navigate to Client credentials, then click Add a certificate or secret.
Click + New client secret. Enter a Description for the client secret, and select a client secret expiry period using the Expires dropdown menu. Please note, the client ID cannot access API resources when the client secret expires. You must renew the client secret to keep the client ID active. Click Add to add the client secret.
Copy and save Secret Value for building the D3 SOAR connection. Please note that your Client Secret can only be viewed once. Store it securely before leaving the page.
Configure the API permissions. Click API permissions on the left navigation menu, then + Add a permission. Navigate to APIs my organization uses. The search for Office 365 Exchange Online.
Select the app, and choose Application permissions.
Search and select Exchange.ManageAsApp, then click Add permissions. This permission allows you to use all current commands for this integration.
It needs to be granted admin consent for d3uat to use. Ensure Grant admin consent for d3uat is checked.

You may see Not granted for d3uat in the status column. Those are the ungranted permissions you want to use. After you successfully grant permissions, a green checkmark will appear under the permission status column for the corresponding permissions. If your login account does not have admin privileges, ask your admin to grant consent.

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.
  Authentication Type: Basic Authentication
  1. Select the Authentication Type. Basic Authentication is the default type.
  2. Input the Username. Please note this should be the email address of the user.
  3. Input the Password.
  Authentication Type: OAuth2
  1. Select the OAuth2 authentication type.
  2. Input the Tenant ID. Please refer to step 6 of the Configuring for OAuth2 Authentication section.
  3. Input the Client ID. Please refer to step 6 of the Configuring for OAuth2 Authentication section.
  4. Input the Client Secret. Please refer to step 8 of the Configuring for OAuth2 Authentication section.
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 tick box. 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 check mark 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 username and password.

Error Sample Data

Add Items To Blocklist failed.

Status Code: 400.

Message: Invalid username 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 username and password.

Error Sample Data

Block File Hashes failed.

Status Code: 400.

Message: Invalid username 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

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

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"
}

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 username and password.

Error Sample Data

Block Senders failed.

Status Code: 400.

Message: Invalid username and password.

Convert Type Of Mailboxes

Converts the type of user mailboxes to Shared, Regular, Equipment and Room.

Input

Input Parameter

Required/Optional

Description

Example

Personal Mail Boxes

Required

The list of email addresses to be converted to shared mailboxes.

[

"*****@d3soar.com",

"*****@d3security.com"

]

Mailbox Type

Optional

The type of the mailboxes to be converted to. Available values are Equipment, Regular, Room, or Shared. The default value is Shared. Please refer to Convert a mailbox in Exchange Online for conversion limitations.

Shared

Output

Return Data

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

The Partially Successful state only occurs when a command’s input accepts an array of items (e.g. an array of IP addresses) and one or more items within the array return an error from the API request.

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

Raw Data

The primary response data from the API request.

SAMPLE DATA

JSON

{
    "results": [
        {
            "mailboxes": [
                "*****@d3soar.com"
            ],
            "message": "Converted to Shared Mailbox successful."
        }
    ],
    "D3Errors": []
}

Result

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

SAMPLE DATA

SharedCount	2
FailedCount	0

Error Handling

If the Return Data is Partially Successful or 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.	Convert Type Of Mailboxes 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: A parameter cannot be found that matches parameter name 'Type'.

Error Sample Data

Convert Type Of Mailboxes failed.

Status Code: 400.

Message: A parameter cannot be found that matches parameter name 'Type'.

Delete Search Result Emails

Deletes the email message(s) in the compliance search result.

READER NOTE

This command only supports Basic Authentication.

It is recommended to preview compliance search results before you delete the emails in the search result. Up to 10 items per mailbox can be removed at once. You can remove items from a maximum of 50,000 mailboxes with a single content search. To remove items from more than 50,000 mailboxes, create separate content searches. For more information, refer to Search for and delete email messages in your organization | Microsoft Learn. In addition, each search result can only be used once in this command. Subsequent command executions with the same search result will only return the previous deletion result.

The parameter Search Names is required to run this command.

Run the Start Compliance Content Search command to obtain the Search Names. Search Names can be found in the raw data at the path $.Name.

Input

Input Parameter

Required /Optional

Description

Example

Search Names

Required

The name of the compliance search used to delete message(s) from the search results. The Search Name can be obtained using the Start Compliance Content Search command. Ensure that the Search status is Completed with Get Compliance Content Search Status command before you delete the search result.

VSOC-0607e

Delete Type

Optional

Specifies how to delete emails in the search results. The options are Soft Delete and Hard Delete.

Soft Delete: Purged items are recoverable until the deleted item retention period expires.
Hard Delete (cloud only): Purged items are marked for permanent removal from the mailbox and will be permanently deleted the next time the mailbox is processed by the Managed Folder Assistant.

If single item recovery is enabled on the mailbox, purged items will be permanently removed after the deleted item retention period expires.

If not specified, the default type is Soft Delete.

Hard Delete(Cloud Only)

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.

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

SAMPLE DATA

CODE

Successful

Raw Data

The primary response data from the API request.

SAMPLE DATA

JSON

{
    "Result": {
        "PurgeType": "HardDelete",
        "ItemCount": 1,
        "TotalSize": 352813,
        "Details": [
            {
                "Location": "*****@d3devcyber.onmicrosoft.com",
                "ItemCount": 1,
                "TotalSize": 352813,
                "FailedCount": 0
            }
        ]
    },
    "D3Errors": []
}

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

{
  "PurgeType": HardDelete,
  "ItemCount": 1,
  "TotalSize": 352813
}

Result

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

SAMPLE DATA

Result	{'PurgeType': 'HardDelete', 'ItemCount': 1, 'TotalSize': 352813, 'Details': [{'Location': '*****@d3devcyber.onmicrosoft.com', 'ItemCount': 1, 'TotalSize': 352813, 'FailedCount': 0}]}
D3Errors	[]

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.	Delete Search Result Emails 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: 404.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: The compliance search object 'invalidName' cannot be found.

Error Sample Data

Delete Search Result Emails failed.

Status Code: 404.

Message: The compliance search object 'invalidName' cannot be found.

Get Compliance Content Search Status

Retrieves compliance search status and result summaries.

READER NOTE

This command only supports Basic Authentication.

The parameter Search Names is required to run this command.

Run the Start Compliance Content Search command to obtain the Search Names. Search Names can be found in the raw data at the path $.Name.

Input

Input Parameter

Required /Optional

Description

Example

Search Names

Required

The name(s) of the compliance search(s) for retrieving status(es). The Search Name can be obtained using the Start Compliance Content Search command.

[

"*****@d3soar.com",

"*****@d3security.com"

]

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.

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

SAMPLE DATA

CODE

Successful

Raw Data

The primary response data from the API request.

SAMPLE DATA

JSON

{
    "Results": [
        {
            "Name": "VSOC-0607ll",
            "Items": 201,
            "Size": 77405135,
            "JobProgress": 100,
            "Status": "Completed",
            "SuccessResults": [
                {
                    "Location": "*****@d3soar.com",
                    "Item count": 124,
                    "Total size": 17609568
                },
                {
                    "Location": "*****@d3devcyber.onmicrosoft.com",
                    "Item count": 77,
                    "Total size": 59795567
                }
            ]
        }
    ]
}

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

{
  "SearchNames": ["VSOC-0607ll"],
  "Statuses": ["Completed"],
  "JobProgresses": [100],
  "Items": [201] 
}

Result

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

SAMPLE DATA

Results

{'Name': 'VSOC-0607ll', 'Items': 201, 'Size': 77405135, 'JobProgress': 100, 'Status': 'Completed', 'SuccessResults': [{'Location': '*****@d3soar.com', 'Item count': 124, 'Total size': 17609568}, {'Location': '*****@d3devcyber.onmicrosoft.com', 'Item count': 77, 'Total size': 59795567}]}

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.	Get Compliance Content Search Status 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: 404.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: The operation couldn't be performed because 'invalidName' couldn't be found.

Error Sample Data

Get Compliance Content Search Status failed.

Status Code: 404.

Message: The operation couldn't be performed because 'invalidName' couldn't be found.

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

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

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": ["*****@d3soar.com"],
    "EntryIDs": ["*****"],
    "ListType": "URLs"
}

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 username and password.

Error Sample Data

List Items In Blocklist failed.

Status Code: 400.

Message: Invalid username and password.

List Quarantine Messages

Retrieves quarantined messages in your cloud-based organization. Please note that this command is available only in the cloud-based service.

Input

Input Parameter	Required/Optional	Description	Example
Sender Addresses	Optional	The sender's email address(es) used to filter quarantined messages.	[ "***@d3soar.com", "***@d3security.com" ]
Recipient Addresses	Optional	The recipient email address(es) used to filter quarantined messages.	[ "***@d3soar.com", "***@d3security.com" ]
Subject	Optional	The message subject used to filter quarantined messages.	TestEmail0624
Start Received Time	Optional	The quarantined message results are filtered to include only messages received after this specified time (UTC time). By default, if neither the Start Received Time nor End Received Time parameters are used, the command returns data for the past 16 days. The maximum value for this parameter is 30 days prior to the current time. If a date and time beyond 30 days is specified, the parameter is ignored, and only data from the last 30 days will be returned.	2024-06-24 00:00
End Received Time	Optional	The quarantined message results are filtered to include only messages received before this specified time (UTC). By default, if neither the Start Received Time nor End Received Time parameters are used, the command returns data for the past 16 days. If End Received Time is not specified, the default time is the current time. Please note that End Received Time cannot be beyond 30 days prior to the current time.	2024-06-25 00:00
Internet Message ID	Optional	The quarantined message results are filtered by Internet Message ID. Ensure to include the full Message ID string, which may include angle brackets and quotation marks (eg. "***@***.Eop-nam06.prod.protection.outlook.com").	<***=***=CU=X9qM7JQ@mail.gmail.com>
Direction	Optional	The quarantined message results are filtered by inbound or outbound messages. If not specified, both inbound and outbound messages will be returned.	Inbound

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.

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

SAMPLE DATA

CODE

Successful

Raw Data

The primary response data from the API request.

SAMPLE DATA

JSON

{
    "Results": [
        {
            "Identity": "*****\\*****",
            "ReceivedTime": "2024-06-24 4:48:50 PM",
            "Organization": "*****",
            "MessageId": "<*****@mail.gmail.com>",
            "SenderAddress": "*****@d3security.com",
            "RecipientAddress": [
                "*****@d3devcyber.onmicrosoft.com"
            ],
            "Subject": "TestEmail0624",
            "Size": 70041,
            "Type": "High Confidence Phish",
            "PolicyType": "HostedContentFilterPolicy",
            "PolicyName": "Default",
            "TagName": "AdminOnlyAccessPolicy",
            "PermissionToBlockSender": false,
            "PermissionToDelete": false,
            "PermissionToPreview": false,
            "PermissionToRelease": false,
            "PermissionToRequestRelease": false,
            "PermissionToViewHeader": false,
            "PermissionToDownload": false,
            "PermissionToAllowSender": false,
            "Released": false,
            "ReleaseStatus": "NOTRELEASED",
            "SystemReleased": false,
            "RecipientCount": 1,
            "QuarantineTypes": "HighConfPhish",
            "Expires": "2024-07-09 4:07:28 PM",
            "RecipientTag": [
                ""
            ],
            "DeletedForRecipients": [],
            "QuarantinedUser": [],
            "ReleasedUser": [],
            "Reported": false,
            "Direction": "Inbound",
            "CustomData": null,
            "EntityType": "Email",
            "SourceId": "",
            "TeamsConversationType": "",
            "ApprovalUPN": "",
            "ApprovalId": "",
            "MoveToQuarantineAdminActionTakenBy": "",
            "MoveToQuarantineApprovalId": "",
            "OverrideReasonIntValue": 0,
            "OverrideReason": "None",
            "ReleasedCount": 0,
            "ReleasedBy": []
        }
    ]
}

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

{
  "InternetMessageIDs": ["<*****@mail.gmail.com>"],
  "MessageIdentities": ["*****\\*****"],
  "Subjects": ["TestEmail0624"],
  "Senders": ["*****@d3security.com"],
  "Recipients": [["*****@d3devcyber.onmicrosoft.com"]],
  "ReceivedTime": [ "2024-06-24 4:48:50 PM" ],
  "QuarantineReasons": [ "High Confidence Phish" ],
  "ReleaseStatuses": ["NOTRELEASED"]
}

Result

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

SAMPLE DATA

Quarantined Messages Count

1

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 Quarantine Messages 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 username and password.

Error Sample Data

List Quarantine Messages failed.

Status Code: 400.

Message: Invalid username and password.

Modify Permission To Mailbox

Assigns or removes the access permission for the given user to the mailbox.

Input

Input Parameter	Required /Optional	Description	Example
User Identities	Required	The name, alias, or email address of the mailbox user who is getting or losing the permissions on the given mailbox.	[ "Helpdesk", "*****@d3security.onmicrosoft.com" ]
Mailbox	Required	The name, alias, or email address of the mailbox to which the permissions are being added from which they are being removed.	*****@d3security.onmicrosoft.com
Permission	Optional	The access permission of the mailbox assigned to the user. Please refer to Manage permissions for recipients in Exchange Online \| Microsoft Learn for details.	Shared
Auto Mapping	Optional	Enables the AutoMap feature for Full Access permission. By default, AutoMap is set to True when the Permission is set to Full Access. With AutoMap enabled, when a user is assigned Full Access permission to the mailbox, the mailbox is automatically added to the user's Outlook mail profile.	True
Action	Optional	The option to add or remove permission for the Mailbox. The default option is Add.	Add

Output

Return Data

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

The Partially Successful state only occurs when a command’s input accepts an array of items (e.g. an array of IP addresses) and one or more items within the array return an error from the API request.

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

Raw Data

The primary response data from the API request.

SAMPLE DATA

JSON

{
    "results": [],
    "D3Errors": []
}

Result

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

SAMPLE DATA

PermissionChangedCount

3

Error Handling

If the Return Data is Partially Successful or 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.	Modify Permission To Mailbox 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: The user is not recognized as a managed user, or a federated user.

Error Sample Data

Modify Permission To Mailbox failed.

Status Code: 400.

Message: The user is not recognized as a managed user, or a federated user.

Preview Compliance Search Result

Retrieves compliance content search results, including details such as mailbox, sender, subject, size, and received time, among others.

READER NOTE

This command only supports Basic Authentication.

It is recommended to preview compliance search results before you delete the emails in the search result. Only a randomly selected subset of the search result items will be returned. The result returned is consistent with the preview available from the Microsoft Purview portal.

The parameter Search Names is required to run this command.

Run the Start Compliance Content Search command to obtain the Search Names. Search Names can be found in the raw data at the path $.Name.

Input

Input Parameter	Required /Optional	Description	Example
Search Name	Required	The name of the compliance search to retrieve the compliance content results. The Search Name can be obtained using the Start Compliance Content Search command. Ensure Search status is Completed with Get Compliance Content Search Status command before you preview the search result.	VSOC-0607e

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.

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

SAMPLE DATA

CODE

Successful

Raw Data

The primary response data from the API request.

SAMPLE DATA

JSON

{
    "Results": [
        {
            "Location": "*****@example.com",
            "Sender": "*****@example.com",
            "Subject": "Fw: File and Item Attachments",
            "Type": "Email",
            "Size": 352791,
            "ReceivedTime": "11/15/2022 9:54:00 PM",
            "DataLink": "PreviewResults/Exchange/*****-*****==/item.eml"
        }
    ]
}

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

{
  "Mailboxes": ["*****@example.com"],
  "Senders": ["*****@example.com"],
  "Subjects": [ "Fw: File and Item Attachments" ],
  "ReceivedTime": [ "11/15/2022 9:54:00 PM" ]
}

Result

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

SAMPLE DATA

Results

{'Location': '*****@example.com', 'Sender': '*****@example.com', 'Subject': 'Fw: File and Item Attachments', 'Type': 'Email', 'Size': 352791, 'ReceivedTime': '11/15/2022 9:54:00 PM', 'DataLink': 'PreviewResults/Exchange/*****-*****==/item.eml'}

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.	Preview Compliance Search Result 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: 502.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: Connection failed. Please run the test command and view the details in the RawData section.

Error Sample Data

Preview Compliance Search Result failed.

Status Code: 502.

Message: Connection failed. Please run the test command and view the details in the RawData section.

Release Quarantine Messages

Releases quarantined message(s) in your cloud-based organization. Please note, this command is available only in the cloud-based service.

READER NOTE

The parameter Message Identities is required to run this command.

Run the List Quarantine Messages command to obtain the Message Identities. Message Identities can be found in the raw data at the path $.Results[*].Identity.

The parameter Recipients To Release is optional to run this command.

Run the List Quarantine Messages command to obtain the Recipients To Release. Recipients To Release can be found in the raw data at the path $.Results[*].RecipientAddress.

Input

Input Parameter	Required/Optional	Description	Example
Message Identities	Required	The identities of the messages to be released. Message Identities can be obtained using the List Quarantine Messages command. If any Message Identities in the list are invalid, none of the Message Identities will be released.	[ "107*****a7c" ]
Recipients To Release	Optional	The email address(es) of the recipient(s) to whom you wish to release the quarantined message(s). Recipients To Release can be obtained using the List Quarantine Messages command. These email addresses apply to all Message Identities. If a recipient email address is not on the original recipients list, the message(s) will not be released to that email address. If not specified, the message(s) will be released to all original recipients.	[ "*****@d3soar.com" ]
Allow Sender	Optional	The choice of whether all future messages from the sender(s) of the released message(s) will not be quarantined. If set to true, future messages from the sender(s) will not be quarantined. If not specified, the default value is False.	False
Report False Positive	Optional	The choice of whether to report the message(s) as false positive (good message incorrectly marked as bad) to Microsoft. If not specified, the default value is False.	False

Output

Return Data

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

The Partially Successful state only occurs when a command’s input accepts an array of items (e.g. an array of IP addresses) and one or more items within the array return an error from the API request.

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

Raw Data

The primary response data from the API request.

SAMPLE DATA

JSON

{
    "Results": [
        {
            "Identity": "*****\\*****",
            "ReceivedTime": "2024-06-24 4:07:28 PM",
            "Organization": "*****",
            "MessageId": "<*****@mail.gmail.com>",
            "SenderAddress": "*****@d3security.com",
            "RecipientAddress": [
                "*****@d3soar.com"
            ],
            "Subject": "TestEmail0624",
            "Size": 69009,
            "Type": "High Confidence Phish",
            "PolicyType": "HostedContentFilterPolicy",
            "PolicyName": "Default",
            "TagName": "AdminOnlyAccessPolicy",
            "PermissionToBlockSender": false,
            "PermissionToDelete": true,
            "PermissionToPreview": true,
            "PermissionToRelease": true,
            "PermissionToRequestRelease": false,
            "PermissionToViewHeader": false,
            "PermissionToDownload": true,
            "PermissionToAllowSender": true,
            "Released": true,
            "ReleaseStatus": "RELEASED",
            "SystemReleased": false,
            "RecipientCount": 1,
            "QuarantineTypes": "HighConfPhish",
            "Expires": "2024-07-09 4:07:28 PM",
            "RecipientTag": [
                ""
            ],
            "DeletedForRecipients": [],
            "QuarantinedUser": [],
            "ReleasedUser": [
                "*****@d3soar.com"
            ],
            "Reported": false,
            "Direction": "Inbound",
            "CustomData": null,
            "EntityType": "Email",
            "SourceId": "",
            "TeamsConversationType": "",
            "ApprovalUPN": "",
            "ApprovalId": "",
            "MoveToQuarantineAdminActionTakenBy": "",
            "MoveToQuarantineApprovalId": "",
            "OverrideReasonIntValue": 0,
            "OverrideReason": "None",
            "ReleasedCount": 0,
            "ReleasedBy": [
                "jon@d3soar.com released for *****@d3soar.com"
            ]
        }
    ]
}

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

{
  "InternetMessageIDs": ["<*****@mail.gmail.com>"],
  "MessageIdentities": ["*****\\*****"],
  "Subjects": ["TestEmail0624"],
  "Senders": ["*****@d3security.com"],
  "ReleaseStatuses": ["RELEASED"],
  "ReleasedUsers": [["*****@d3soar.com"]]
}

Result

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

SAMPLE DATA

Released Messages Count	1
Unreleased Messages Count	1

Error Handling

If the Return Data is Partially Successful orFailed, 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.	Release Quarantine Messages 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 username and password.

Error Sample Data

Release Quarantine Messages failed.

Status Code: 400.

Message: Invalid username 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 be removed from the blocklist. The allowed value types are email addresses, domains, file hashes, or URLs. 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

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

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"
}

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: Connection failed. Please run the test command and view the details in the RawData section.

Error Sample Data

Remove Items From Blocklist failed.

Status Code: 400.

Message: Connection failed. Please run the test command and view the details in the RawData section.

Start Compliance Content Search

Creates a compliance content search and starts the content search in the Exchange Server (2016 or later) and Microsoft Purview compliance portal.

READER NOTE

This command only supports Basic Authentication.

The parameter Search Names is required to run this command.

Run the Start Compliance Content Search command to obtain the Search Names. Search Names can be found in the raw data at the path $.Name.

Input

Input Parameter	Required /Optional	Description	Example
Search Names	Optional	The name(s) of the compliance search(s) for retrieving status(es). If not specified, the system will generate a search name automatically.	[ "***@d3soar.com", "***@d3security.com" ]
Description	Optional	A description for the compliance search.	search for internet message ID on 0607
Mailboxes	Optional	The mailbox(es) where the content search will be conducted. If not specified, the search will include all mailboxes within your organization.	[ "*****@d3soar.com", "user1@d3soar.com" ]
ContentSearchFilter	Required	Uses a text search string or a Keyword Query Language (KQL) query to filter the search results. For more information, please refer to Keyword Query Language (KQL) syntax reference \| Microsoft Learn and Keyword queries and search conditions for eDiscovery \| Microsoft Learn.	internetMessageId:<***@***.CANPRD01.PROD.OUTLOOK.COM>

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.

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

SAMPLE DATA

CODE

Successful

Raw Data

The primary response data from the API request.

SAMPLE DATA

JSON

{
    "Name": "VSOC-0607ll",
    "Items": 0,
    "Size": 0,
    "JobProgress": 0,
    "Status": "Starting",
    "SuccessResults": []
}

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

{
  "SearchName": VSOC-0607ll,
  "Status": Starting
}

Result

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

SAMPLE DATA

Name	VSOC-0607ll
Items	0
Size	0
JobProgress	0
Status	Starting
SuccessResults	[]

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.	Start Compliance Content Search 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: 502.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: Connection failed. Please run the test command and view the details in the RawData section.

Error Sample Data

Start Compliance Content Search failed.

Status Code: 502.

Message: Connection failed. Please run the test command and view the details in the RawData section.

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 username and password.

Error Sample Data

Test Connection failed. Failed to check the connector.

Status Code: 400.

Message: Invalid username and password.