Cisco Email Security

Overview

Cisco Email Security is an email security gateway. It detects and blocks a wide variety of email-borne threats, such as malware, spam and phishing.

D3 SOAR is providing REST operations to function with Cisco Email Security.

Cisco Email Security is available for use in:

D3 SOAR	V14.0.20.0+
Category	Email Security
Deployment Options	Option I, Option III

Connection

To connect to Cisco Email Security from D3 SOAR, please follow this part to collect the required information below:

Parameter	Description	Example
Server URL	The server URL of your Cisco Email Security environment.	https://1.1.1.1/
User Name	The username for authentication.	Admin
Password	The password for authentication.	Password
API Version	The API version for authentication.	v2.0

Permission Requirements

Each endpoint in the Cisco Email Security API requires a certain permission scope. Please configure your desired privileges based on your specific needs.

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

Reader Note

Cisco Email Security’s default user profiles (sorted from the least permissions to the most) are as follows:

Administrator: Administrator user accounts have full access to all configuration settings of the system.
Operator: Operator user accounts are restricted from creating or editing new user accounts, issuing the resetconfig command, checking for or installing available upgrades, running the System Setup Wizard, and certain quarantine functions (including creating and deleting quarantines). Otherwise, they have the same privileges as Administrators.
Guest user: Guest user accounts may only view status information.
Read-Only Operator: Read-Only Operator user accounts can view configuration but cannot commit changes.
Technician: Technicians can only manage upgrades and feature keys.
Help Desk user: Help Desk user accounts can only access message tracking features. Help Desk User accounts can be invited to the IronPort Spam Quarantine or system quarantines.
Custom user: Custom user role accounts can only access email security features assigned to the role. These features can be any combination of DLP policies, email policies, reports, quarantines, local message tracking, encryption profiles, and the Trace debugging tool.

Configuring Cisco Email Security to Work with D3 SOAR

Login to cisco email security with your credentials.

Creating a Role

Navigate to System Administration > User Roles to create roles.
Click Add User Role.
Name your role and configure the required Access Privileges. Click Submit to save your changes.

Creating a User

Navigate to System Administration > Users. Click Add User.
Enter the following information.
1. Name the user.
2. Define the user role. You can select from the Predefined Roles, or choose from your Custom Roles such as the role you created in Creating a Role.
3. Confirm your passphrase (the password of the account you are logged into).
4. Enter a passphrase for the user. You can click Generate to create one or choose your own passphrase.
Note: If you are creating your own password, the following criteria for passphrases need to met: at least 8 characters; at least one upper (A-Z) and one lower (a-z) case letter; at least one special character; the passphrase must not contain three or more repetitive or sequential characters (for example: AAA, DEF, FED).
5. Click Submit to create the user.

Configuring D3 SOAR to Work with Cisco Email Security

Log in to D3 SOAR.
Find the Cisco Email Security integration.
1. Navigate to Configuration on the top header menu.
2. Click on the Integration icon on the left sidebar.
3. Type Cisco Email Security 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 Cisco Email Security.
1. Connection Name: The desired name for the connection.
2. Site: Specifies the site to use the integration connection. Use the drop-down menu to select the site. The Share to Internal Sites option enables all sites defined as internal sites to use the connection. Selecting a specific site will only enable that site to use the connection.
3. Recipient site for events from connections Shared to Internal Sites: This field appears if you selected Share to Internal Sites for Site to let you select the internal site to deploy the integration connection.
4. Agent Name (Optional): Specifies the proxy agent required to build the connection. Use the dropdown menu to select the proxy agent from a list of previously configured proxy agents.
5. Description (Optional): Add your desired description for the connection.
6. Tenant (Optional): When configuring the connection from a master tenant site, you have the option to choose the specific tenant sites you want to share the connection with. Once you enable this setting, you can filter and select the desired tenant sites from the dropdowns to share the connection.
7. Configure User Permissions: Defines which users have access to the connection.
8. Active: Check the tick box to ensure the connection is available for use.
9. System: This section contains the parameters defined specifically for the integration. These parameters must be configured to create the integration connection.
  1. Input the Server URL.
  2. Input the User Name from the Cisco Email Security platform. Refer to Configuring Cisco Email Security to Work with D3 SOAR.
  3. Input the Password from the Cisco Email Security platform. Refer to Configuring Cisco Email Security to Work with D3 SOAR.
  4. Input the API Version. The default value is v2.0.
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.
Test the connection.
1. Click Test Connection to verify the account credentials and network connection. If the Test Connection Passed alert window appears, the test connection is successful. You will see Passed with a green checkmark appear beside the Test Connection button. If the test connection fails, please check your connection parameters and try again.
2. Click OK to close the alert window.
3. Click + Add to create and add the configured connection.

Commands

Cisco Email Security 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.

Reader Note

Certain permissions are required for each command. Please refer to the Permission Requirements and Configuring Cisco Email Security 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 Entries

Adds entries.

Input

Input Parameter	Required/Optional	Description	Example
List Type	Required	The list type of the entry.	N/A
Action	Required	The action of the entry.	append
View By	Required	The reviewer of the entry.	sender
Recipient Addresses	Required	The recipient address(es) of the entry.	[ "test1@example.com", "test2@example.com" ]
Recipient List	Required	The recipient list of the entry.	[ "test1@example.com", "test2@example.com" ]
Sender Addresses	Required	The sender address(es) of the entry.	[ "example.com", "testsender.com" ]
Sender List	Required	The sender list of the entry.	[ "example.com", "testsender.com" ]

Output

Raw Data

The primary response data from the API request.

SAMPLE DATA

JSON

No Sample Data

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.

SAMPLE DATA

CODE

No Sample Data

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.

Error Sample Data

Add Entries failed.

Status Code: 500.

Message: Server got itself in trouble: The application raised an exception.

Block Domain

Add, append, or edit sender domains list to recipient blocklist entries viewed by sender or recipient.

Input

Input Parameter	Required/Optional	Description	Example
Action	Required	The action to perform on the blocklist in Cisco ESA.	append
View By	Required	View by sender or recipient.	sender
Sender Addresses	Optional	The sender domains to perform the action on. This parameter is required when the View By option is the sender.	[ "example.com", "testsender.com" ]
Recipients List	Optional	The recipient email addresses list to perform the action on. This parameter is required when the View By option is the sender.	[ "test1@example.com", "test2@example.com" ]
Recipients Addresses	Optional	The recipient email addresses to perform the action on. This parameter is required when the View By option is the recipient.	[ "test1@example.com", "test2@example.com" ]
Sender List	Optional	The sender domains list to perform the action on. It is only required when the View By option is the recipient.	[ "example.com", "testsender.com" ]

Output

Raw Data

The primary response data from the API request.

SAMPLE DATA

JSON

No Sample Data

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

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

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

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 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 Domain 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 Cisco Email Security 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: Please use the test command and check Raw Data for the details.

Error Sample Data

Block Domain failed.

Status Code: 400.

Message: Please use the test command and check Raw Data for the details.

Block Email Addresses

Add, append or edit sender email addresses list to recipient blocklist entries viewed by sender or recipient.

Input

Input Parameter	Required/Optional	Description	Example
Action	Required	The action to perform on the blocklist in Cisco ESA.	append
View By	Required	View by sender or recipient.	sender
Sender Addresses	Optional	The sender email addresses to perform the action on. This parameter is required when the View By option is the sender.	[ "test@example.com", "test@testsender.com" ]
Recipients List	Optional	The recipient email addresses list to perform the action on. This parameter is required when the View By option is the sender.	[ "test@example.com", "test@testsender.com" ]
Recipients Addresses	Optional	The recipient email addresses to perform the action on. This parameter is required when the View By option is the recipient.	[ "test@example.com", "test@testsender.com" ]
Sender List	Optional	The sender email addresses list to perform the action on. This parameter is required when the View By option is the recipient.	[ "test@example.com", "test@testsender.com" ]

Output

Raw Data

The primary response data from the API request.

SAMPLE DATA

JSON

No Sample Data

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

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

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

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 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 Email Addresses 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 Cisco Email Security portal. Refer to the HTTP Status Code Registry for details.	Status Code: 500.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: The application raised an exception

Error Sample Data

Block Email Addresses failed.

Status Code: 500.

Message: The application raised an exception

Delete Entries

Deletes entries.

Input

Input Parameter	Required/Optional	Description	Example
List Type	Required	The list type of the entry.	NOT AVAILABLE
View By	Required	The reviewer of the entry.	sender
Recipient List	Required	The recipient list of the entry.	[ "test1@example.com", "test2@example.com" ]
Sender List	Required	The sender list of the entry.	[ "test@example.com", "test@testsender.com" ]

Output

Raw Data

The primary response data from the API request.

SAMPLE DATA

JSON

No Sample Data

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.

SAMPLE DATA

CODE

No Sample Data

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.	Delete Entries 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 Cisco Email Security portal. Refer to the HTTP Status Code Registry for details.	Status Code: 500.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: Server got itself in trouble: The application raised an exception.

Error Sample Data

Delete Entries failed.

Status Code: 500.

Message: Server got itself in trouble: The application raised an exception.

Delete Quarantine Messages

Deletes a quarantine message by message ID(s).

Input

Input Parameter	Required/Optional	Description	Example
Message IDs	Required	The message ID(s) to delete quarantine messages.	NOT AVAILABLE

Output

Raw Data

The primary response data from the API request.

SAMPLE DATA

JSON

No Sample Data

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.

SAMPLE DATA

CODE

No Sample Data

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.	Delete 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 Cisco Email Security 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: Message ID Not Found.

Error Sample Data

Delete Quarantine Messages failed.

Status Code: 404.

Message: Message ID Not Found.

Fetch Event

Retrieves email messages from Cisco ESA.

Input

Input Parameter	Required/Optional	Description	Example
Messages Source	Required	The source in Cisco ESA to retrieve messages. The available message sources are Message Tracking and Spam Quarantine.	Spam Quarantine
Start Time	Required	The start time of the time range to filter retrieved messages, in UTC time.	2023-04-24 00:00
End Time	Required	The end time of the time range to filter retrieved messages, in UTC time.	2023-04-26 00:00
Offset	Optional	The value indicating the position within the subset of records to begin fetching data. If an offset is used, a retrieval limit must be defined. If no offset value is provided, the default value is 0.	0
Limit	Optional	The maximum number of records to retrieve. If you set a limit value, the offset value must also be defined. For the Message Tracking source, the limit value should be between 1 and 100. For the Spam Quarantine source, the limit value should be between 1 and 250.	10

Output

Raw Data

The primary response data from the API request.

SAMPLE DATA

JSON

No Sample Data

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

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

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

SAMPLE DATA

CODE

No Sample Data

Fetch Event Field Mapping

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.

If you require a custom field mapping, click + Add Field to add a custom field mapping. 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.

The Cisco Email Security integration in D3 SOAR has some pre-configured field mappings for the Message Tracking related events and Spam Quarantine related events, which correspond to the Default Event Source and Event Mapping for Spam Quarantine mappings:

Default Event Source
Configures the field mapping which are specific to the Message Tracking related events. If a source field in the field mapping is not found, the corresponding field mapping will be ignored. 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.
Event Source for Spam Quarantine
Configures the field mapping which are specific to the Spam Quarantine related events. If a source field in the field mapping is not found, the corresponding field mapping will be ignored. As the data of the Spam Quarantine related events have a character that the value of the sourceType field is spamQuarantine, the Spam Quarantine related events can be defined by the Search String: {$.sourceType}=spamQuarantine. Click Edit Event Source to view the Search String.

The pre-configured field mappings are detailed below:

Field Name	Source Field
Default Event Source (Main Event JSON Path: $)
Event Source for Spam Quarantine (Search String: {$.sourceType}=spamQuarantine) The search string format is {jsonpath}=value. If the value of the sourceType key is spamQuarantine in the event object under raw data, then the Spam Quarantine related events will use the field mapping below.
Date	.attributes.date
Envelope Recipient	.attributes.envelopeRecipient
From Address	.attributes.fromAddress[*]
Mail Policy	.attributes.mailPolicy[*]
Message Status	.attributes.messageStatus
Sender IPSender IP	.attributes.senderIp
Serial Number	.attributes.serialNumber
TimeStamp	.attributes.timestamp
To Address	.attributes.toAddress[*]
Document ID	.mid
Recipient	.attributes.recipient[*]
Sender	.attributes.sender

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 AMP Details 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 Cisco Email Security 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: Message ID Not Found.

Error Sample Data

Get AMP Details failed.

Status Code: 404.

Message: Message ID Not Found.

Get AMP Details

Retrieves AMP details by Cisco ID and appliance serial number.

Input

Input Parameter	Required/Optional	Description	Example
Message ID	Required	The message ID to get AMP details.	N/A
Start Date	Required	The start date to get AMP details.	2023-01-01 00:00
End Date	Required	The end date to get AMP details.	2023-01-02 00:00
Cisco ID	Required	The Cisco ID to get AMP details.	N/A
Appliance Serial Number	Required	The appliance serial number to get AMP details.	N/A

Output

Raw Data

The primary response data from the API request.

SAMPLE DATA

JSON

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

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

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 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 AMP Details 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 Cisco Email Security 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: Message ID Not Found.

Error Sample Data

Get AMP Details failed.

Status Code: 404.

Message: Message ID Not Found.

Get DLP Details

Retrieves DLP details by Cisco ID and appliance serial number.

Input

Input Parameter	Required/Optional	Description	Example
Message ID	Required	The message ID to get DLP details.	N/A
Start Date	Required	The start date to get DLP details.	2023-01-01 00:00
End Date	Required	The end date to get DLP details.	2023-01-02 00:00
Cisco ID	Required	The Cisco ID to get DLP details.	N/A
Appliance Serial Number	Required	The appliance serial number to get DLP details.	N/A

Output

Raw Data

The primary response data from the API request.

SAMPLE DATA

JSON

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

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

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 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 DLP Details 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 Cisco Email Security 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: Message ID Not Found.

Error Sample Data

Get DLP Details failed.

Status Code: 404.

Message: Message ID Not Found.

Get Entries List

Retrieves the Entries List.

Input

Input Parameter	Required/Optional	Description	Example
List Type	Required	The list type of the entry.	NOT AVAILABLE
Limit	Required	The maximum number of the entry.	10
Offset	Required	The offset of the entry.	0
View By	Required	The reviewer of the entry.	sender
Order By	Required	The recipient list of the entry.	NOT AVAILABLE

Output

Raw Data

The primary response data from the API request.

SAMPLE DATA

JSON

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

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

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 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 Entries 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, 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 Cisco Email Security portal. Refer to the HTTP Status Code Registry for details.	Status Code: 500.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: Server got itself in trouble: The application raised an exception.

Error Sample Data

Get Entries List failed.

Status Code: 500.

Message: Server got itself in trouble: The application raised an exception.

Get Message Details

Retrieves message details by Cisco ID and appliance serial number

Input

Input Parameter	Required/Optional	Description	Example
Message ID	Required	The message ID to get message details.	NOT AVAILABLE
Start Date	Required	The start date to get message details.	2023-01-01 00:00
End Date	Required	The end date to get message details.	2023-01-02 00:00
Cisco ID	Required	The Cisco ID to get message details.	NOT AVAILABLE
Appliance Serial Number	Required	The appliance serial number to get message details.	NOT AVAILABLE

Output

Raw Data

The primary response data from the API request.

SAMPLE DATA

JSON

{
    "data": {
        "messages": {
            "direction": "outgoing",
            "smtpAuthId": "",
            "sender": "test@example.com",
            "midHeader": "<***@&&&.ibqa>",
            "timestamp": "16 Nov 2018 11:19:48 (GMT)",
            "showAMP": true,
            "hostName": "*** (1.1.1.1)",
            "mid": [
                ***
            ],
            "sendingHostSummary": {
                "reverseDnsHostname": "*** (verified)",
                "ipAddress": "1.1.1.1",
                "sbrsScore": "not enabled"
            },
            "summary": [
                {
                    "timestamp": "16 Nov 2018 11:19:48 (GMT)",
                    "description": "ICID 19214 sender_group: RELAYLIST sender_ip: 1.1.1.1, sbrs: not enabled",
                    "lastEvent": false
                },
                {
                    "timestamp": "16 Nov 2018 11:19:48 (GMT)",
                    "description": "Protocol SMTP interface Management  (IP 1.1.1.1) on incoming connection 
                     (ICID 19214) from sender IP 1.1.1.1. Reverse DNS  host ***.ibqa verified yes.",
                    "lastEvent": false
                },
...

...
                {
                    "timestamp": "16 Nov 2018 11:20:12 (GMT)",
                    "description": "Message *** scanned by Advanced Malware Protection engine. Final verdict
                     : UNKNOWN","lastEvent": false
                },
                {
                    "timestamp": "16 Nov 2018 11:20:12 (GMT)",
                    "description": "Message *** contains attachment 'driver_license_germany.txt' (SHA256 ***).",
                    "lastEvent": false
                },
                {
                    "timestamp": "16 Nov 2018 11:20:12 (GMT)",
                    "description": "Message ***attachment  'driver_license_germany.txt' scanned by Advanced Malware
                     Protection engine. File Disposition: Unknown",
                    "lastEvent": false
                },
                {
                    "timestamp": "16 Nov 2018 11:20:12 (GMT)",
                    "description": "Message *** Delivery Status: DROPPED",
                    "lastEvent": false
                },
                {
                    "timestamp": "16 Nov 2018 11:20:12 (GMT)",
                    "description": "Message *** Verdict chart: ***",
                    "lastEvent": true
                }
            ],
            "attachments": [
                "driver_license_germany.txt"
            ],
            "messageSize": "765 (Bytes)",
            "isCompleteData": true,
            "showDLP": true,
            "messageStatus": "Dropped by DLP",
            "showURL": false,
            "mailPolicy": [
                "DEFAULT"
            ],
            "senderGroup": "RELAYLIST",
            "recipient": [
                "test@example.ibqa"
            ],
            "showSummaryTimeBox": true,
            "subject": "Testing"
        }
    }
}

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

CODE

No Sample Data

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 Message Details 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 Cisco Email Security portal. Refer to the HTTP Status Code Registry for details.	Status Code: 500.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: Server got itself in trouble: The application raised an exception.

Error Sample Data

Get Message Details failed.

Status Code: 500.

Message: Server got itself in trouble: The application raised an exception.

Get Quarantine Message Details

Retrieves quarantine message details by message ID(s).

Input

Input Parameter	Required/Optional	Description	Example
Message ID	Required	The message ID to get quarantine message.	NOT AVAILABLE

Output

Raw Data

The primary response data from the API request.

SAMPLE DATA

JSON

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

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

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 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 Quarantine Message Details 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 Cisco Email Security portal. Refer to the HTTP Status Code Registry for details.	Status Code: 500.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: Server got itself in trouble: The application raised an exception.

Error Sample Data

Get Quarantine Message Details failed.

Status Code: 500.

Message: Server got itself in trouble: The application raised an exception.

Get Report List

Retrieves the Report List.

Input

Input Parameter	Required/Optional	Description	Example
Report Counter	Required	The report counter to get the report list.	NOT AVAILABLE
Start Date	Required	The start date to get the report list.	2023-01-01 00:00
End Date	Required	The end date to get the report list.	2023-01-02 00:00

Output

Raw Data

The primary response data from the API request.

SAMPLE DATA

JSON

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

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

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 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.

Error Sample Data

Get Report List failed.

Status Code: 500.

Message: Server got itself in trouble: The application raised an exception.

Get URL Details

Retrieves URL details by Cisco ID and appliance serial number.

Input

Input Parameter	Required/Optional	Description	Example
Message ID	Required	The message ID to get URL details.	NOT AVAILABLE
Start Date	Required	The start date to get URL details.	2023-01-01 00:00
End Date	Required	The end date to get URL details.	2023-01-02 00:00
Cisco ID	Required	The Cisco ID to get URL details.	NOT AVAILABLE
Appliance Serial Number	Required	The appliance serial number to get URL details.	NOT AVAILABLE

Output

Raw Data

The primary response data from the API request.

SAMPLE DATA

JSON

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

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

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 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 URL Details 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 Cisco Email Security portal. Refer to the HTTP Status Code Registry for details.	Status Code: 500.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: Server got itself in trouble: The application raised an exception.

Error Sample Data

Get URL Details failed.

Status Code: 500.

Message: Server got itself in trouble: The application raised an exception.

List Search Messages

Lists Search Messages.

Input

Input Parameter	Required/Optional	Description	Example
Query	Required	The query string to search message(s).	NOT AVAILABLE
Start Date	Required	The start date to search message(s).	2023-01-01 00:00
End Date	Required	The end date to search message(s).	2023-01-02 00:00
Offset	Required	The offset to search message(s).	0
Limit	Required	The limit to search message(s).	10

Output

Raw Data

The primary response data from the API request.

SAMPLE DATA

JSON

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

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

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 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 Search 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 Cisco Email Security portal. Refer to the HTTP Status Code Registry for details.	Status Code: 500.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: Server got itself in trouble: The application raised an exception.

Error Sample Data

List Search Messages failed.

Status Code: 500.

Message: Server got itself in trouble: The application raised an exception.

List Search Spam Quarantine

Lists spam message(s) by a query string.

Input

Input Parameter	Required/Optional	Description	Example
Query	Required	The query string to search spam message(s).	NOT AVAILABLE
Start Date	Required	The start date to search spam message(s).	2023-01-01 00:00
End Date	Required	The end date to search spam message(s).	2023-01-02 00:00
Offset	Required	The offset to search spam message(s).	0
Limit	Required	The limit to search spam message(s).	10

Output

Raw Data

The primary response data from the API request.

SAMPLE DATA

JSON

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

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

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 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 Search Spam Quarantine 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 Cisco Email Security portal. Refer to the HTTP Status Code Registry for details.	Status Code: 500.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: Server got itself in trouble: The application raised an exception.

Error Sample Data

List Search Spam Quarantine failed.

Status Code: 500.

Message: Server got itself in trouble: The application raised an exception.

Release Quarantine Messages

Releases a quarantine message by message ID(s).

Input

Input Parameter	Required/Optional	Description	Example
Message IDs	Optional	The message ID(s) to release quarantine message(s).	NOT AVAILABLE

Output

Raw Data

The primary response data from the API request.

SAMPLE DATA

JSON

No Sample Data

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.

SAMPLE DATA

CODE

No Sample Data

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.	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 Cisco Email Security 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: Message ID not found.

Error Sample Data

Release Quarantine Messages failed.

Status Code: 404.

Message: Message ID not found.

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 Cisco Email Security portal. Refer to the HTTP Status Code Registry for details.	Status Code: 500.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: Server got itself in trouble: The application raised an exception.

Error Sample Data

Test Connection failed. Failed to check the connector.

Status Code: 500.

Message: Server got itself in trouble: The application raised an exception.