Mimecast Limited is a Jersey-domiciled, UK-headquartered company specializing in cloud-based email management for Microsoft Exchange and Microsoft Office 365, including security, archiving, and continuity services to protect business mail.
D3 SOAR is providing REST operations to function with Mimecast.
The Mimecast API enforces call rate limiting among other protective measures to ensure fair usage. These include max entry counts, historical date restrictions, and max request item counts per call, all detailed under respective endpoint descriptions.
If an API endpoint starts impacting the platform negatively, additional limits may be set.
Upon sending a request to the API, users are given a call quota to monitor subsequent requests. Once the quota is exceeded, requests fail until the quota drops below the max count. A reset mechanism replenishes the call quota at defined intervals. HTTP headers in each response indicate rate limiting status, showing the user's call quota, remaining calls, and the reset time in milliseconds.
Normally, the API returns a 200 response code, but a 429 code is returned if the rate limit is breached, suggesting a pause before sending further requests as indicated by the X-RateLimit-Reset header.
From the side menu, navigate to Services > API and Platform Integrations.
From the Available Integrations tab, locate the Mimecast API 1.0 tile. Click Generate Keys.
Complete the Application Details section. Select SOAR Integration for the category. It is also recommended to select the Enable Extended Session checkbox. This ensures the access key used to interface with D3 SOAR will not expire. When you are done, click Next.
Complete the Notification Settings section. When you are done, click Next.
Review the Summary page to ensure all details are correct. To fix any errors:
a. Click the Edit link next to the Details or Settings to return to the relevant page.
b. Make changes and click the Next button to proceed to the Summary page again.
Click Add. The application's details are displayed in a slide-in panel. Copy and save the Application ID and Key in a secure location. It will be required for creating the integration connection in D3 SOAR.
Input a Role Name and Description. Select the appropriate Security Permissions for the role. Under Application Permissions, check boxes for required roles. Refer to Permission Requirements for a list of required permissions for each command. Once you are done, click Save and Exit.
To add an account to the role, select the created role from the list of roles.
Click Add User to Role. You will see a list of current users. Select the user(s) you wish to assign the new role to and then click Add Selected Users. For more information on user management, refer to Email Security Cloud Gateway - Creating or Editing Users.
From the side menu, navigate to Services > API and Platform Integrations > Your API 1.0 Applications. Select your created API application. Click Create Keys.
Input an existing user account's email address. The access and secret keys will inherit the role permissions of the user account.
READER NOTE
Be prepared with the service account's domain or cloud password for upcoming steps.
In the Authentication dialog, provide the following details:
Email Address: This should display the email of the service account you entered earlier.
Type: Choose the password type of the service account (e.g., domain or cloud).
Password: Input the service account's password.
Click Next. This will bring you to the Verification stage. Copy and save the Access and Secret Keys in a secure location. It will be required for creating the integration connection in D3 SOAR.
READER NOTE
If you have configured a 2-step authentication method, an authentication code will be sent to you either via SMS or email. Ensure you enter this code within 15 minutes.
Click Close to complete the process.
Configuring D3 SOAR to Work with Mimecast
Log in to D3 SOAR.
Find the Mimecast integration.
a. Navigate to Configuration on the top header menu.
b. Click on the Integration icon on the left sidebar.
c. Type Mimecast in the search box to find the integration, then click it to select it.
d. 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 Mimecast.
a. Connection Name: The desired name for the connection.
b. 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.
c. 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.
d. 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.
e. Description (Optional): Add your desired description for the connection.
f. 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.
g. Configure User Permissions: Defines which users have access to the connection.
h. Active: Check the tick box to ensure the connection is available for use.
i. System: This section contains the parameters defined specifically for the integration. These parameters must be configured to create the integration connection.
1. Select the region of your Mimecast region. To identify your Mimecast region, log into your Mimecast account using your credentials. Upon successful login, look at the address bar of your web browser to view the URL. This URL will typically follow a pattern like https://login-xx.mimecast.com/..., where "xx" stands for the region code.
j. 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.
k. 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.
a. 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 markappear beside the Test Connection button. If the test connection fails, please check your connection parameters and try again.
b. Click OK to close the alert window.
c. Click +Add to create and add the configured connection.
Commands
Mimecast 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.
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 Group Member
Adds user email addresses to a profile group.
READER NOTE
Group ID is a required parameterto run this command.
Run the Get Groups command to obtain Group ID. Group IDs can be found in the returned raw data at the path $.data[*].folders[*].id.
The same user cannot be added to the same group.
Input
Input Parameter
Required/Optional
Description
Example
Email Address
Required
The email addresses of users to add to a group.
["***@*****.***"]
Group ID
Required
The Mimecast ID of the group to add to. Group IDs can be obtained using the Get Groups command.
The data extracted from Raw Data converted into JSON format. Context Data may be identical to Raw Data in some cases.
D3 customizes the Context Data by extracting the data from path the $.data in the API returned JSON.
It is recommended to refer to the Raw Data instead of Context Data, since it contains the complete API response data. D3 will deprecate Context Data in the future, and playbook tasks using Context Data will be replaced with Raw 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.
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
id
folderId
emailAddress
internal
*****-*****
*****
*****@*****.com
True
Error Handling
If the Return Data is Partially Successful or Failed, an Error tab will appear in the Test Result window.
The errortab 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 Group Member 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, a 404 means that the request URL does not exist. Refer to Response Codes | Mimecast 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: err_folder_group_member_already_exists.
Error Sample Data
Add Group Member failed.
Status Code: 400.
Message: err_folder_group_member_already_exists.
Create Group
Creates new profile groups at the root level, or as a child-group. Groups can be used to apply permissions and policies.
READER NOTE
Parent ID is an optional parameterto run this command.
Run the Get Groups command to obtain a Parent ID. Parent IDs can be found in the returned raw data at the path $.data[*].folders[*].id.
Input
Input Parameter
Required/Optional
Description
Example
Group Name
Required
The name of the new group.
*****
Parent ID
Optional
The Mimecast ID of the new group's parent group. If excluded, the new group will be created at the root level. Parent ID can be found from the Get Groups command.
The data extracted from Raw Data converted into JSON format. Context Data may be identical to Raw Data in some cases.
D3 customizes the Context Data by extracting the data from the path $.data in the API returned JSON.
It is recommended to refer to the Raw Data instead of Context Data, since it contains the complete API response data. D3 will deprecate Context Data in the future, and playbook tasks using Context Data will be replaced with Raw 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.
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
id
description
source
parentId
userCount
folderCount
*****
*****
cloud
*****
0
0
Error Handling
If the Return Data is Failed, an Error tab will appear in the Test Result window.
The errortab 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.
Create Group 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, a 404 means that the request URL does not exist. Refer to Response Codes | Mimecast 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: Error occurred during group creation.
Error Sample Data
Create Group failed.
Status Code: 400.
Message: Error occurred during group creation.
Create Managed URL
Adds new managed URL entries for URL protection. The common actions are to manually block or permit a URL, however additional options include the ability to disable URL rewriting and bypassing user awareness.
Input
Input Parameter
Required/Optional
Description
Example
URL
Required
The URL to block or permit.
http://www.*****.com
Action
Required
The requested action to be taken. The action can be set to either “block” or “permit”.
permit
Match Type
Required
The match type of the action. The match type can be set to “explicit” to block or permit the specific URL or “domain” to block or permit the entire domain.
The data extracted from Raw Data converted into JSON format. Context Data may be identical to Raw Data in some cases.
D3 customizes the Context Data by extracting the data from the path $.data in the API returned JSON.
It is recommended to refer to the Raw Data instead of Context Data, since it contains the complete API response data. D3 will deprecate Context Data in the future, and playbook tasks using Context Data will be replaced with Raw 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
id
scheme
domain
port
path
queryString
matchType
action
comment
disableUserAwareness
disableRewrite
disableLogClick
*****
http
www.*****.com
-1
domain
permit
False
False
False
Error Handling
If the Return Data is Failed, an Error tab will appear in the Test Result window.
The errortab 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.
Create Managed URL 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, a 404 means that the request URL does not exist. Refer to Response Codes | Mimecast 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 URL is invalid.
Error Sample Data
Create Managed URL failed.
Status Code: 400.
Message: The URL is invalid.
Create Policy
Creates new blocked sender policies, which can be used to manage a combination of sender and recipient restrictions.
Input
Input Parameter
Required/Optional
Description
Example
Option
Required
The policy action. The available options are no_action and blcok_sender.
no_action
Description
Required
The description for the new policy.
Test Policy 1404
From Type
Required
The from type for the new policy. The available options are internal_addresses, external_addresses, email_domain, profile_group, individual_email_address, address_attribute_value, free_mail_domains, and header_display_name.
individual_email_address
From Value
Optional
A value defining which senders the policy applies to corresponds to the selected From Type. When this type is set as "individual_email_address", the policy is applied to individual email addresses. If the type is "email_domain", the policy targets the email domain. For "profile_group", the policy is relevant to group users. When set to "header_display_name", the policy impacts the display names in email headers. Lastly, if the type is "address_attribute_value", the policy pertains to the address attribute.
*****@*****.***
To Type
Required
The to type of the new policy.
individual_email_address
To Value
Optional
The to value which the policy will be applied to. Policy is applied on email address when type is set to individual_email_address. Policy is applied on email domain when type is set to email_domain Policy is applied on group users when type is set to profile_group. Policy is applied on email headers display name when type is set to header_display_name. Policy is applied on address attribute when type is set to address_attribute_value.
The data extracted from Raw Data converted into JSON format. Context Data may be identical to Raw Data in some cases.
D3 customizes the Context Data by extracting the data from the path $.data in the API returned JSON.
It is recommended to refer to the Raw Data instead of Context Data, since it contains the complete API response data. D3 will deprecate Context Data in the future, and playbook tasks using Context Data will be replaced with Raw Data.
If the Return Data is Failed, an Error tab will appear in the Test Result window.
The errortab 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.
Create Policy 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, a 404 means that the request URL does not exist. Refer to Response Codes | Mimecast 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: Option and Description and FromType and ToType is required.
Error Sample Data
Create Policy failed.
Status Code: 400.
Message: Option and Description and FromType and ToType is required.
Create Remediation Incident
This endpoint can be used to create a remediation incident, by messageId or file hash.
READER NOTE
Message ID is a required parameterto run this command.
Run the Get Message List command to obtain Message ID. Message IDs can be found in the returned raw data at the path $.data[*].id.
At least one of the following parameters: Subject, Sender, Mime Message ID, File Hash, URL and Parent Incident Code, is required to run this command.
Run the Fetch Event command to obtain Mime Message ID. Mime Message ID can be found in the returned raw data at the path $.MessageDetail.mimeMessageId.
Run the Fetch Event or Search Messages command to obtain File Hash.
Input
Input Parameter
Required/Optional
Description
Example
Message ID
Required
The message ID for creating the remediation incident. Message IDs can be obtained using the Get Message List command.
["*****]
Reason
Required
The reason for creating the remediation incident.
tim1
Start Time
Required
The earliest date of the messages to remediate.
2021-04-07 00:00
End Time
Required
The latest end date of the messages to remediate.
2021-05-07 00:00
Subject
Optional
The case-insensitive string to filter incidents by subject. This string must be at least 3 characters in length. Additionally, at least one of the following parameters: Subject, Sender, Mime Message ID, File Hash, URL, and Parent Incident Code, cannot be empty at the same time.
Account
Sender
Optional
The case-insensitive string to filter incident by sender email address. This string must be at least 3 characters in length. Additionally, at least one of the following parameters: Subject, Sender, Mime Message ID, File Hash, and URL, cannot be empty at the same time.
mimecast.com
Mime Message ID
Optional
The Mime message ID to filter results. This string must be at least 3 characters in length. Additionally, at least one of the following parameters: Subject, Sender, Mime Message ID, File Hash, URL, and Parent Incident Code cannot be empty at the same time. Mime message IDs can be obtained using the Fetch Event command, where the MIME message includes a MessageDetail field.
<Mimecast.**.***@*****.mimecast.***>
File Hash
Optional
The file hash to filter results. This value should be at least 32 characters long. The parameter Subject, Sender, Mime Message ID, File Hash, URL, or Parent Incident Code cannot be empty at the same time. Mime message IDs can be obtained using the Fetch Event or Search Messages commands.
*****
URL
Optional
The URL to filter results. This value should be at least 3 characters long. The parameter Subject, Sender, Mime Message ID, File Hash, URL, or Parent Incident Code cannot be empty at the same time.
www.d3security.com
Parent Incident Code
Optional
The case-insensitive string to filter incidents by parent incident code This string must be at least 3 characters in length. Additionally, at least one of the following parameters: Subject, Sender, Mime Message ID, File Hash, URL, and Parent Incident Code, cannot be empty at the same time. The created incident will fail when the specified incident does not have at least one identified message.
The data extracted from Raw Data converted into JSON format. Context Data may be identical to Raw Data in some cases.
D3 customizes the Context Data by extracting the data from the path $.data in the API returned JSON.
It is recommended to refer to the Raw Data instead of Context Data, since it contains the complete API response data. D3 will deprecate Context Data in the future, and playbook tasks using Context Data will be replaced with Raw Data.
If the Return Data is Failed, an Error tab will appear in the Test Result window.
The errortab 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.
Create Remediation Incident 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, a 404 means that the request URL does not exist. Refer to Response Codes | Mimecast 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: At least one of [fileHash, messageId, messageIds, subject, parentIncidentCode, from, url] must be not null.
Error Sample Data
Create Remediation Incident failed.
Status Code: 400.
Message: At least one of [fileHash, messageId, messageIds, subject, parentIncidentCode, from, url] must be not null.
The data extracted from Raw Data converted into JSON format. Context Data may be identical to Raw Data in some cases.
D3 customizes the Context Data by extracting the data from the path $.data in the API returned JSON.
It is recommended to refer to the Raw Data instead of Context Data, since it contains the complete API response data. D3 will deprecate Context Data in the future, and playbook tasks using Context Data will be replaced with Raw 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
Result
Provides a brief summary of outputs in an HTML formatted table.
SAMPLE DATA
url
success
http://www.*****.com
True
Error Handling
If the Return Data is Partially Successful or Failed, an Error tab will appear in the Test Result window.
The errortab 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.
Decode URL 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, a 404 means that the request URL does not exist. Refer to Response Codes | Mimecast 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: App ID is invalid: xxx.
Error Sample Data
Decode URL failed.
Status Code: 400.
Message: App ID is invalid: xxx.
Fetch Event
Retrieve events from Mimecast.
Input
Input Parameter
Required/Optional
Description
Example
Start Time
Required
The start time of the time range to fetch events, in UTC time.
2021-04-27 00:00
End Time
Required
The end time of the time range to fetch events, in UTC time.
2021-04-30 00:00
Number of Event(s) Fetched
Required
The maximum number of events to retrieve.
1
Search Archive
Optional
The option to search either archive or message tracking. The selection in this parameter will impact the query syntax that is used in the Search Condition parameter.
True
Search Conditions
Required
The search condition for querying results varies based on the state of the "Search Archive" parameter. When set to True, it allows for querying within the archive using specific parameters: view (such as INBOX), mailbox (like test1@example.com), from (for instance, test2@example.com), to (mirroring the from value), subject (targeting a specific subject line), and filename (for attachments, e.g., test.pdf). An example query in this case would be view=INBOX, mailbox=test1@example.com, from=test2@example.com, filename=test.pdf.
If "Search Archive" is set to False, the query format changes to focus on the current mailbox, using parameters like to (e.g., test1@example.com), from (e.g., test2@example.com), subject (a specific subject line), and senderIP (such as ***.***.***.***). An example query here would be to=test1@example.com, from=test2@example.com, subject=test, senderip=***.***.***.***.
view=INBOX, mailbox=*****@*****.***
Tolerance Scope
Optional
The tolerance scope (in minutes) for the query to fetch events between the specified start and end time to avoid event loss or fetch failure. The events will be fetched between {Start Time - Tolerance Scope, End Time}. The default value is 0.
The data extracted from Raw Data converted into JSON format. Context Data may be identical to Raw Data in some cases.
It is recommended to refer to the Raw Data instead of Context Data, since it contains the complete API response data. D3 will deprecate Context Data in the future, and playbook tasks using Context Data will be replaced with Raw Data.
Please note that Fetch Event commands require event field mapping. Field mapping plays a key role in the data normalization process part of the event pipeline. Field mapping converts the original data fields from the different providers to the D3 fields which are standardized by the D3 Model. Please refer to Event and Incident Intake Field Mapping for details.
To customize field mapping, click + Add Field and add the custom field of your choice. You can also remove built-in field mappings by clicking x. Please note that two underscore characters will automatically prefix the defined Field Name as the System Name for a custom field mapping. Additionally, if an input Field Name contains any spaces, they will automatically be replaced with underscores for the corresponding System Name.
As a system integration, the Mimecast integration has some pre-configured field mappings for default field mapping.
Default Event Source The Default Event Source is the default set of field mappings that are applied when this fetch event command is executed. For out-of-the-box integrations, you will find a set of field mapping provided by the system. Default event source provides field mappings for common fields from fetched events. The default event source has a “Main Event JSON Path” (i.e., $) that is used to extract a batch of events from the response raw data. Click Edit Event Source to view the “Main Event JSON Path”.
Main Event JSON Path: $ The Main Event JSON Path determines the root path where the system starts parsing raw response data into D3 event data. The JSON path begins with $, representing the root element. The path is formed by appending a sequence of child elements to $, each separated by a dot (.). Square brackets with nested quotation marks ([‘...’]) should be used to separate child elements in JSON arrays.
For example, the root node of a JSON Path is value. The child node denoting the Unique Event Key field would be id. Putting it together, the JSON Path expression to extract the Unique Event Key is $.id.
The pre-configured field mappings are detailed below:
Field Name
Source Field
Email subject
.subject
Source IP address
.senderIP
Recipient
.to.emailAddress
Sender
.fromEnv.emailAddress
Receipt time
.received
Unique Event Key
.id
Start Time
.sent
Error Handling
If the Return Data is Failed, an Error tab will appear in the Test Result window.
The errortab 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.
Fetch Event 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, a 404 means that the request URL does not exist. Refer to Response Codes | Mimecast 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: App ID is invalid: xxx.
Error Sample Data
Fetch Event failed.
Status Code: 400.
Message: App ID is invalid: xxx.
Fetch Related Events
Retrieve related events from Mimecast.
Input
Input Parameter
Required/Optional
Description
Example
Last Hours
Optional
The number of hours before the current time to fetch related events.
240
Top Recent Event Number
Required
The maximum number of the most recent events to retrieve.
1
Search Archive
Optional
The option to search either archive or message tracking. The selection in this parameter will impact the query syntax that is used in the Search Condition parameter.
FALSE
Search Condition
Required
The search condition for querying results varies based on the state of the "Search Archive" parameter. When set to True, it allows for querying within the archive using specific parameters: view (such as INBOX), mailbox (like *****@*****.***), from (for instance, *****@*****.***), to (mirroring the from value), subject (targeting a specific subject line), and filename (for attachments, e.g., test.pdf). An example query in this case would be view=INBOX, mailbox=*****@*****.***, from=*****@*****.***, filename=test.pdf.
If "Search Archive" is set to False, the query format changes to focus on the current mailbox, using parameters like to (e.g., *****@*****.com), from (e.g., *****@*****.***), subject (a specific subject line), and senderIP (such as ***.***.***.***). An example query here would be to=*****@*****.com, from=*****@*****.***, subject=test, senderip=***.***.***.***.
The data extracted from Raw Data converted into JSON format. Context Data may be identical to Raw Data in some cases.
It is recommended to refer to the Raw Data instead of Context Data, since it contains the complete API response data. D3 will deprecate Context Data in the future, and playbook tasks using Context Data will be replaced with Raw Data.
If the Return Data is Failed, an Error tab will appear in the Test Result window.
The errortab 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.
Fetch Related Events 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, a 404 means that the request URL does not exist. Refer to Response Codes | Mimecast 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: App ID is invalid: xxx.
Error Sample Data
Fetch Related Events failed.
Status Code: 400.
Message: App ID is invalid: xxx.
Get Files
Retrieves attachments from the currently stored messages.
READER NOTE
Attachment IDs is a required parameterto run this command.
Run the Get Message Detail command to obtain Attachment IDs. Attachment IDs can be found in the returned raw data at the path $.data[*].attachments[*].id.
Input
Input Parameter
Required/Optional
Description
Example
Attachment IDs
Required
The ID of attachment to retrieve files. Attachment IDs can be obtained using the Get Message Detail command.
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
Result
Provides a brief summary of outputs in an HTML formatted table.
SAMPLE DATA
fileId
fileName
md5
sha1
sha256
*****
forgetpassword.jpg
*****
*****
*****
Error Handling
If the Return Data is Partially Successful or Failed, an Error tab will appear in the Test Result window.
The errortab 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 Files 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, a 404 means that the request URL does not exist. Refer to Response Codes | Mimecast 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: App ID is invalid: xxx.
Error Sample Data
Get Files failed.
Status Code: 400.
Message: App ID is invalid: xxx.
Get Group Members
Retrieves members from the specified group.
READER NOTE
Group ID are required parametersto run this command.
Run the Get Groups command to obtain Group ID. Group IDs can be found in the returned data at the path $.data[*].folder[*].id.
Input
Input Parameter
Required/Optional
Description
Example
Group ID
Required
The ID of the group to retrieve members. Group ID can be obtained using the Get Groups command.
*****
Page Size
Optional
The size of the page. This can be used for the pagination and it can specify the number of items to return in one page. The default value is 10, the maximum value 500.
10
Page Token
Optional
The page token serves as the index for pagination. This value can be sourced from the "NextPageToken" or "PreviousPageToken" fields in the response of a prior request.
The data extracted from Raw Data converted into JSON format. Context Data may be identical to Raw Data in some cases.
D3 customizes the Context Data by extracting the data from the path $.data[*].groupMembers in the API returned JSON.
It is recommended to refer to the Raw Data instead of Context Data, since it contains the complete API response data. D3 will deprecate Context Data in the future, and playbook tasks using Context Data will be replaced with Raw 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
emailAddress
name
internal
domain
type
*****@*****.***
***
True
*****.***
created_manually
*****@*****.***
****
True
*****.***
created_manually
*****@*****.***
***
True
*****.***
created_manually
Error Handling
If the Return Data is Failed, an Error tab will appear in the Test Result window.
The errortab 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 Group Members 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, a 404 means that the request URL does not exist. Refer to Response Codes | Mimecast 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 value for parameter (Page Size) is invalid.
Error Sample Data
Get Group Members failed.
Status Code: 400.
Message: The value for parameter (Page Size) is invalid.
Get Groups
Retrieves groups.
READER NOTE
If no groups are found, the command will successfully return without any result.
Input
Input Parameter
Required/Optional
Description
Example
Query
Optional
The query string to retrieve groups.
test
Source
Optional
The source (i.e., cloud or ldap) of the group to filter returned results.
The data extracted from Raw Data converted into JSON format. Context Data may be identical to Raw Data in some cases.
D3 customizes the Context Data by extracting the data from the path $.data[*].folders in the API returned JSON.
It is recommended to refer to the Raw Data instead of Context Data, since it contains the complete API response data. D3 will deprecate Context Data in the future, and playbook tasks using Context Data will be replaced with Raw Data.
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.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.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.
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
id
description
source
parentId
userCount
folderCount
*****
testGroup33
cloud
*****
0
0
*****
testGroup34
cloud
*****
3
0
*****
*****
cloud
*****
0
0
Error Handling
If the Return Data is Failed, an Error tab will appear in the Test Result window.
The errortab 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 Groups 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, a 404 means that the request URL does not exist. Refer to Response Codes | Mimecast 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: App ID is invalid: xxx.
Error Sample Data
Get Groups failed.
Status Code: 400.
Message: App ID is invalid: xxx.
Get Hold Message List
Retrieves information about the held messages based on the given search conditions.
Input
Input Parameter
Required/Optional
Description
Example
Start Time
Optional
The start time of the time range to retrieve the hold message list, in UTC time.
2021-06-01 00:00
End Time
Optional
The end time of the time range to retrieve the hold message list, in UTC time.
2021-06-15 00:00
Field Name
Optional
The field to filter results. The available options are: all, subject, sender, recipient, reasonCode.
subject
Field Value
Optional
The value of the field to filter results as selected in the Field Name parameter.
test
Admin
Optional
The level of results to return. If false, only results for the currently authenticated user will be returned. If true, held messages for all recipients will be returned.
The data extracted from Raw Data converted into JSON format. Context Data may be identical to Raw Data in some cases.
It is recommended to refer to the Raw Data instead of Context Data, since it contains the complete API response data. D3 will deprecate Context Data in the future, and playbook tasks using Context Data will be replaced with Raw Data.
"policyInfo": "Attachment Hold on Size"
}
fail
Error Handling
If the Return Data is Failed, an Error tab will appear in the Test Result window.
The errortab 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 Hold Message List 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, a 404 means that the request URL does not exist. Refer to Response Codes | Mimecast 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 payload.
Error Sample Data
Get Hold Message List failed.
Status Code: 400.
Message: Invalid payload.
Get Managed URL
Retrieves a managed URL which can be used to return all entries currently in an accounts Managed URL list.
Input
Input Parameter
Required/Optional
Description
Example
Url
Required
The domain or URL to filter results.
["www.*****.com"]
Action
Required
The action to take when the URL is clicked. The available options are block or permit.
The data extracted from Raw Data converted into JSON format. Context Data may be identical to Raw Data in some cases.
It is recommended to refer to the Raw Data instead of Context Data, since it contains the complete API response data. D3 will deprecate Context Data in the future, and playbook tasks using Context Data will be replaced with Raw Data.
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.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.
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
id
scheme
domain
port
path
queryString
matchType
action
comment
disableUserAwareness
disableRewrite
disableLogClick
*****
http
http://www.*****.***
-1
domain
permit
False
False
False
Error Handling
If the Return Data is Failed, an Error tab will appear in the Test Result window.
The errortab 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 Managed URL 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, a 404 means that the request URL does not exist. Refer to Response Codes | Mimecast 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: App ID is invalid: xxx.
Error Sample Data
Get Managed URL failed.
Status Code: 400.
Message: App ID is invalid: xxx.
Get Message Attachment
Retrieves the attachment of the specified message.
READER NOTE
Message ID is a required parameterto run this command.
Run the Get Message List command to obtain Message ID. Message IDs can be found in the returned raw data at the path $.data[*].id.
Input
Input Parameter
Required/Optional
Description
Example
Message ID
Optional
The ID of the message to retrieve its attachment. Message IDs can be obtained using the Get Message List command.
The data extracted from Raw Data converted into JSON format. Context Data may be identical to Raw Data in some cases.
It is recommended to refer to the Raw Data instead of Context Data, since it contains the complete API response data. D3 will deprecate Context Data in the future, and playbook tasks using Context Data will be replaced with Raw Data.
If the Return Data is Failed, an Error tab will appear in the Test Result window.
The errortab 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 Message Attachment 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, a 404 means that the request URL does not exist. Refer to the Response Codes | Mimecast 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 token.
Error Sample Data
Get Message Attachment failed.
Status Code: 400.
Message: Invalid token.
Get Message Detail
Retrieves details on the specified message.
READER NOTE
Message ID is a required parameterto run this command.
Run the Get Message List command to obtain Message ID. Message IDs can be found in the returned raw data at the path $.data[*].id.
Input
Input Parameter
Required/Optional
Description
Example
Message ID
Required
The ID of the message to retrieve details. Message IDs can be obtained using the Get Message List command.
The data extracted from Raw Data converted into JSON format. Context Data may be identical to Raw Data in some cases.
D3 customizes the Context Data by extracting the data from the path $.data in the API returned JSON.
It is recommended to refer to the Raw Data instead of Context Data, since it contains the complete API response data. D3 will deprecate Context Data in the future, and playbook tasks using Context Data will be replaced with Raw Data.
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.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.
If the Return Data is Failed, an Error tab will appear in the Test Result window.
The errortab 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 Message Detail 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, a 404 means that the request URL does not exist. Refer to Response Codes | Mimecast 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 token.
Error Sample Data
Get Message Detail failed.
Status Code: 400.
Message: Invalid token.
Get Message List
Request message lists for any user
Input
Input Parameter
Required/Optional
Description
Example
View
Required
The message list type. Must be one of: INBOX or SENT
INBOX
MailBox
Required
The mailbox of the message list
*****@*****.***
Start Time
Optional
The start date of messages to return in UTC time
2023-07-01 00:00
End Time
Optional
The end date of messages to return in UTC time.
2023-07-11 00:00
Limit
Optional
The number of messages to get. If the value is 0, a negative number, or not specified, the command will use the default value number to get the messages. The default value is 25
The data extracted from Raw Data converted into JSON format. Context Data may be identical to Raw Data in some cases.
D3 customizes the Context Data by extracting the data from the path $.data in the API returned JSON.
It is recommended to refer to the Raw Data instead of Context Data, since it contains the complete API response data. D3 will deprecate Context Data in the future, and playbook tasks using Context Data will be replaced with Raw 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.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.
If the Return Data is Failed, an Error tab will appear in the Test Result window.
The errortab 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 Message List 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, a 404 means that the request URL does not exist. Refer to Response Codes | Mimecast 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: App ID is invalid: xxx.
Error Sample Data
Get Message List failed.
Status Code: 400.
Message: App ID is invalid: xxx.
Get Policy
Retrieves a blocked sender policy.
Input
Input Parameter
Required/Optional
Description
Example
Policy ID
Optional
The ID of the blocked sender policy to return. If this parameter is not defined, all blocked sender policies will be returned.
The data extracted from Raw Data converted into JSON format. Context Data may be identical to Raw Data in some cases.
D3 customizes the Context Data by extracting the data from the path $.data in the API returned JSON.
It is recommended to refer to the Raw Data instead of Context Data, since it contains the complete API response data. D3 will deprecate Context Data in the future, and playbook tasks using Context Data will be replaced with Raw 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
Result
Provides a brief summary of outputs in an HTML formatted table.
If the Return Data is Partially Successful or Failed, an Error tab will appear in the Test Result window.
The errortab 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 Policy 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, a 404 means that the request URL does not exist. Refer to Response Codes | Mimecast 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 policy ID.
Error Sample Data
Get Policy failed.
Status Code: 400.
Message:Invalid policy ID.
Get Remediation Incident
Retrieves information about an existing incident.
Input
Input Parameter
Required/Optional
Description
Example
Incident ID
Required
The ID of the incident from the remediation incident list to retrieve information.
The data extracted from Raw Data converted into JSON format. Context Data may be identical to Raw Data in some cases.
D3 customizes the Context Data by extracting the data from the path $.data in the API returned JSON.
It is recommended to refer to the Raw Data instead of Context Data, since it contains the complete API response data. D3 will deprecate Context Data in the future, and playbook tasks using Context Data will be replaced with Raw Data.
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.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.
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
Result
Provides a brief summary of outputs in an HTML formatted table.
If the Return Data is Partially Successful or Failed, an Error tab will appear in the Test Result window.
The errortab 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 Remediation Incident 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, a 404 means that the request URL does not exist. Refer to Response Codes | Mimecast 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: App ID is invalid: xxx.
Error Sample Data
Get Remediation Incident failed.
Status Code: 400.
Message: App ID is invalid: xxx.
Get TTP Attachment Log
Retrieves TTP attachment logs.
Input
Input Parameter
Required/Optional
Description
Example
Start Time
Required
The start time of the time range to retrieve TTP attachment logs, in UTC time.
2021-03-01 00:00
End Time
Required
The end time of the time range to retrieve TTP attachment logs, in UTC time.
The data extracted from Raw Data converted into JSON format. Context Data may be identical to Raw Data in some cases.
D3 customizes the Context Data by extracting the data from the path $.data[*].attachmentLogs in the API returned JSON.
It is recommended to refer to the Raw Data instead of Context Data, since it contains the complete API response data. D3 will deprecate Context Data in the future, and playbook tasks using Context Data will be replaced with Raw Data.
If the Return Data is Failed, an Error tab will appear in the Test Result window.
The errortab 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 TTP Attachment Log 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, a 404 means that the request URL does not exist. Refer to Response Codes | Mimecast 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: App ID is invalid: xxx.
Error Sample Data
Get TTP Attachment Log failed.
Status Code: 400.
Message: App ID is invalid: xxx.
Get URL Logs
Retrieves URL logs.
Input
Input Parameter
Required/Optional
Description
Example
From Date
Optional
The start date of the date range to retrieve URL logs.
2021-05-01 00:00
To Date
Optional
The end date of the date range to retrieve URL logs.
The data extracted from Raw Data converted into JSON format. Context Data may be identical to Raw Data in some cases.
It is recommended to refer to the Raw Data instead of Context Data, since it contains the complete API response data. D3 will deprecate Context Data in the future, and playbook tasks using Context Data will be replaced with Raw Data.
SAMPLE DATA
CODE
[]
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.
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
SAMPLE DATA
CODE
No Sample Data
Error Handling
If the Return Data is Failed, an Error tab will appear in the Test Result window.
The errortab 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 URL Logs 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, a 404 means that the request URL does not exist. Refer to Response Codes | Mimecast 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: App ID is invalid: xxx.
Error Sample Data
Get URL Logs failed.
Status Code: 400.
Message: App ID is invalid: xxx.
Permit Or Block Sender
Permits or blocks a sender.
Input
Input Parameter
Required/Optional
Description
Example
Action
Required
The action to take against the specified sender. Select "permit" to bypass spam checks, or choose "block" to reject the email.
The data extracted from Raw Data converted into JSON format. Context Data may be identical to Raw Data in some cases.
It is recommended to refer to the Raw Data instead of Context Data, since it contains the complete API response data. D3 will deprecate Context Data in the future, and playbook tasks using Context Data will be replaced with Raw Data.
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
{
"ID": ["MTOKEN:*****@*****.***"]
}
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
Result
Provides a brief summary of outputs in an HTML formatted table.
If the Return Data is Partially Successful or Failed, an Error tab will appear in the Test Result window.
The errortab 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.
Permit Or Block Sender 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, a 404 means that the request URL does not exist. Refer to Response Codes | Mimecast 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: To address is not a valid internal address.
Error Sample Data
Permit Or Block Sender failed.
Status Code: 400.
Message: To address is not a valid internal address.
Release Message
Release a currently held message.
READER NOTE
Message ID is a required parameterto run this command.
Run the Get Message List command to obtain Message ID. Message IDs can be found in the returned raw data at the path $.data[*].id.
Input
Input Parameter
Required/Optional
Description
Example
Message ID
Optional
The ID of the message to release. Message IDs can be obtained using the Get Message List command.
*****
Output
Raw Data
SAMPLE DATA
JSON
No Sample Data
Context Data
The data extracted from Raw Data converted into JSON format. Context Data may be identical to Raw Data in some cases.
It is recommended to refer to the Raw Data instead of Context Data, since it contains the complete API response data. D3 will deprecate Context Data in the future, and playbook tasks using Context Data will be replaced with Raw Data.
SAMPLE DATA
CODE
No Sample Data
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
SAMPLE DATA
JSON
No Sample Data
Error Handling
If the Return Data is Failed, an Error tab will appear in the Test Result window.
The errortab 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 Message 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, a 404 means that the request URL does not exist. Refer to Response Codes | Mimecast 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: App ID is invalid: xxx.
Error Sample Data
Release Message failed.
Status Code: 400.
Message: App ID is invalid: xxx.
Remove Group Member
Removes the specified group member.
READER NOTE
Group ID are required parametersto run this command.
Run the Get Groups command to obtain Group ID. Group IDs can be found in the returned data at the path $.data[*].folder[*].id.
Ensure the input email address is already part of the group. If you are unsure, run the Get Group command to retrieve the relevant group ID. Once you have the group ID, you can then use the Get Group Members command to accurately identify and select the member you intend to remove.
Input
Input Parameter
Required/Optional
Description
Example
Email Address
Required
The email address of the group member to remove.
["*****@*****.***"]
Group ID
Required
The ID of the group to remove the group member from. Group ID can be obtained using the Get Groups command.
The data extracted from Raw Data converted into JSON format. Context Data may be identical to Raw Data in some cases.
D3 customizes the Context Data by extracting the data from the path $.data in the API returned JSON.
It is recommended to refer to the Raw Data instead of Context Data, since it contains the complete API response data. D3 will deprecate Context Data in the future, and playbook tasks using Context Data will be replaced with Raw 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
Result
Provides a brief summary of outputs in an HTML formatted table.
SAMPLE DATA
id
folderId
emailAddress
internal
*****
*****
*****@*****.***
True
Error Handling
If the Return Data is Partially Successful or Failed, an Error tab will appear in the Test Result window.
The errortab 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 Group Member 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, a 404 means that the request URL does not exist. Refer to Response Codes | Mimecast 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: Error email address not found.
Error Sample Data
Remove Group Member failed.
Status Code: 404.
Message: Error email address not found.
Search File Hash
Identifies if an account has seen a specific file hash within messages over the last year. A maximum of 100 hashes can be submitted in a single call. Note: The command does not currently support image file hashes.
The data extracted from Raw Data converted into JSON format. Context Data may be identical to Raw Data in some cases.
D3 customizes the Context Data by extracting the data from the path $.data[*].hashStatus in the API returned JSON.
It is recommended to refer to the Raw Data instead of Context Data, since it contains the complete API response data. D3 will deprecate Context Data in the future, and playbook tasks using Context Data will be replaced with Raw Data.
SAMPLE DATA
CODE
[
{
"hash": "*****",
"detected": false
}
]
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
{
"HashStatusDetected": [false]
}
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
hash
detected
*****
False
Error Handling
If the Return Data is Failed, an Error tab will appear in the Test Result window.
The errortab 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.
Search File Hash 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, a 404 means that the request URL does not exist. Refer to Response Codes | Mimecast 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: App ID is invalid: xxx.
Error Sample Data
Search File Hash failed.
Status Code: 400.
Message: App ID is invalid: xxx.
Update Group
Updates the specified group.
READER NOTE
Group ID are required parametersto run this command.
Run the Get Groups command to obtain Group ID. Group IDs can be found in the returned data at the path $.data[*].folder[*].id.
Parent ID is an optional parameterto run this command.
Run the Get Groups command to obtain a Parent ID. Parent IDs can be found in the returned raw data at the path $.data[*].folders[*].id.
Input
Input Parameter
Required/Optional
Description
Example
Group ID
Required
The ID of the group to update. Parent ID can be found from the Get Groups command.
*****
Group Name
Required
The name of the group to update.
testgroup34
Parent ID
Optional
The ID of the group's parent group. Parent ID can be found from the Get Groups command.
The data extracted from Raw Data converted into JSON format. Context Data may be identical to Raw Data in some cases.
D3 customizes the Context Data by extracting the data from the path $.data in the API returned JSON.
It is recommended to refer to the Raw Data instead of Context Data, since it contains the complete API response data. D3 will deprecate Context Data in the future, and playbook tasks using Context Data will be replaced with Raw Data.
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.
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
id
description
source
parentId
userCount
folderCount
*****
testgroup34
cloud
*****
0
0
Error Handling
If the Return Data is Failed, an Error tab will appear in the Test Result window.
The errortab 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.
Update Group 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, a 404 means that the request URL does not exist. Refer to Response Codes | Mimecast 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: App ID is invalid: xxx.
Error Sample Data
Update Group failed.
Status Code: 400.
Message: App ID is invalid: xxx.
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, a 404 means that the request URL does not exist. Refer to Response Codes | Mimecast 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: App ID is invalid: xxx.
Error Sample Data
Test Connection failed. Failed to check the connector.
Status Code: 400.
Message: App ID is invalid: xxx.
JavaScript errors detected
Please note, these errors can depend on your browser setup.
If this problem persists, please contact our support.
