About the connector
The Cisco Email Security Virtual Appliance significantly lowers the cost of deploying email security, especially in highly distributed networks. Spam and malware are part of a complex email security picture that includes inbound threats and outbound risks. The all-in-one Cisco ESA (Email Security Appliance) offers simple, fast deployment with few maintenance requirements, low latency, and low operating costs.
This document provides information about the Cisco ESA (Email Security Appliance) connector, which facilitates automated interactions, with a Cisco ESA (Email Security Appliance) server using FortiSOAR™ playbooks. Add the Cisco ESA connector as a step in FortiSOAR™ playbooks and perform automated operations, such as retrieving various statistical reports from the Cisco ESA server.
Version information
Connector Version: 2.0.1
Authored By: Community
Certified: No
Release Notes for version 2.0.1
Following enhancements have been made to the Cisco ESA connector in version 2.0.1:
- Added the connector documentation. The connector documentation was not created for version 2.0.0.
- In version 2.0.0 following enhancements were made:
- Added "API version" as a configuration parameter to add compatibility for Cisco API versions 12.x and 13.x.
Important: The 13.x API works only on the "Premise" setup.
- Added the following new operations and playbooks:
- Search Emails From SPAM Quarantine
- Get Message Details
- Release Emails From Quarantine
- Delete Message
- Search Emails From Other Quarantine
- Download Attachment
Installing the connector
From FortiSOAR™ 5.0.0 onwards, use the Connector Store to install the connector. For the detailed procedure to install a connector, click here.
You can also use the yum command to install connectors. Connectors provided by FortiSOAR™ are delivered using a FortiSOAR™ repository. Therefore, you must set up your FortiSOAR™ repository and run the yum command as a root user to install connectors:
yum install cyops-connector-cisco-esa
Prerequisites to configuring the connector
- You must have the IP address or FQDN of the Cisco ESA server to which you will connect and perform automated operations and credentials (username-password pair) to access that server.
- You must enable AsyncOS API on the Management interface. The ASyncOS API is available from version 12.x.
- To access the FortiSOAR™ UI, ensure that port 443 is open through the firewall for the FortiSOAR™ instance.
Configuring the connector
For the procedure to configure a connector, click here.
Configuration parameters
In FortiSOAR™, on the Connectors page, click the Cisco ESA connector row (if you are in the Grid view on the Connectors page) and in the Configurations tab enter the required configuration details:
| Parameter |
Description |
| Server Address |
IP address or FQDN of the Cisco ESA endpoint server to which you will connect and perform the automated operations. |
| Username |
Username to access the Cisco ESA server to which you will connect and perform automated operations. |
| Password |
Password to access the Cisco ESA server to which you will connect and perform automated operations. |
| Protocol |
Protocol that will be used to communicate with the Cisco ESA server. You can choose either http and https.
By default, this is set to https. |
| Port |
AsyncOS API port of the Cisco ESA server.
Defaults to 6443 for the https protocol. For the http protocol port should be set as 6080. |
| API Version |
API Version that you want to use with the Cisco ESA connector. You can choose from the following options: 12.x or 13.x. |
| Verify SSL |
Specifies whether the SSL certificate for the server is to be verified or not.
By default, this option is set as True. |
Actions supported by the connector
The following automated operations can be included in playbooks and you can also use the annotations to access operations from version 4.10.0 onwards:
| Function |
Description |
Annotation and Category |
| Simple Report |
Retrieves details of a Simple Report from Cisco ESA based on the input parameters such as Report Type and Time Range you have specified.
Reports in the Simple Report category counts various events in your appliance such as how many authentication attempts failed and how many content filters were triggered for a specified time duration. Examples of Simple Reports are: mail_authentication_summary and mail_dlp_outgoing_traffic_summary reports. |
get_report
Investigation |
| Top-N Report |
Retrieves details of a Top-N report from Cisco ESA based on the input parameters such as Report Type and Time Range you have specified.
Reports in the Top-N category counts various events in your appliance against an entity such as IP addresses and domain, for a specified time duration and retrieves the Top-N events, where N is a user-specified value. Examples of Top-N Reports are: mail_content_filter_incoming and mail_dmarc_incoming_traffic_summary. |
get_report
Investigation |
| Query-based Report |
Retrieves details of a Query-based report from Cisco ESA based on the input parameters such as Report Type and Time Range you have specified.
Reports in the Query-based category counts various events in your appliance against a user-specified entity such as IP addresses and domain, for a specified time duration. Examples of Query-based Reports are: mail_authentication_incoming_domain and mail_content_filter_outgoing. |
get_report
Investigation |
| Block Email |
Blocks an email address by adding the email address to the specified message filter on Cisco ESA. |
block_email
Containment |
| Unblock Email |
Unblocks an email address by removing the email address from the message filter on Cisco ESA. |
unblock_email
Remediation |
| Block Sender |
Blocks a sender by adding the sender's IP address, or hostname, or geolocation in the HAT (Host Access Table) blacklist. HAT allows you to specify hosts that are allowed to connect to a listener. |
block_sender
Containment |
| Unblock Sender |
Unblocks a sender by removing the sender's IP address, or hostname, or geolocation from the HAT blacklist. |
unblock_sender
Remediation |
| Get Message Filter List |
Retrieves a list of message filters from Cisco ESA. It also displays details of email addresses that are associated with the message filters. |
get_msg_filters
Investigation |
| Message Tracking |
Searches for message logs in Cisco ESA based on the search type you have specified. |
message_tracking
Investigation |
| Get All Dictionaries |
Retrieves a list of all dictionaries from Cisco ESA. |
get_all_dictionaries
Investigation |
| Get Dictionary Entries |
Retrieves a list of dictionary entries for a specific dictionary from Cisco ESA based on the dictionary name you have specified. |
get_dictionary_entries
Investigation |
| Add Entries In Dictionary |
Adds new words or regular expressions into a specific dictionary in Cisco ESA based on the dictionary name and entries you have specified. |
add_to_dictionary
Investigation |
| Remove Entries From Dictionary |
Removes new words or regular expressions from a specific dictionary in Cisco ESA based on the dictionary name and entries you have specified. |
remove_from_dictionary
Investigation |
| Get All Policies |
Retrieves a list of all policies from Cisco ESA server. |
get_all_policies
Investigation |
| Add Entries In Policy |
Adds new sender and/or receiver entries into incoming or outgoing mail policies in Cisco ESA based on the policy name, policy type, and other input parameters you have specified. |
add_policy_entries
Investigation |
|
Remove Entries From Policy
|
Remove sender or receiver entries from the incoming and outgoing mail policies from Cisco ESA based on the policy name, policy type, and the row number of the entry in the policy table you have specified. |
remove_policy_entries
Investigation |
| Search Emails From SPAM Quarantine |
Fetches emails from the SPAM Quarantine in Cisco ESA based on the start time and end time of when the emails were quarantined and other input parameters you have specified. |
search_in_spam_quarantine
Investigation |
| Get Message Details |
Retrieves details for a specific message from Cisco ESA based on the message ID you have specified. |
get_message_details
Investigation |
| Release Emails From Quarantine |
Releases specific emails from quarantine in Cisco ESA based on the message IDs you have specified. |
release_emails_from_quarantine
Investigation |
| Delete Message |
Deletes specific emails from Cisco ESA based on the message IDs you have specified. |
delete_message
Investigation |
| Search Emails From Other Quarantine |
Fetches emails from a specific quarantine in Cisco ESA based quarantine name, quarantine type, the start time, and the end time of when the emails were quarantined and other input parameters you have specified. |
search_in_other_quarantine
Investigation |
| Download Attachment |
Downloads the attachment and details of the associated message from a quarantine in Cisco ESA based on the message ID and attachment ID you have specified. |
download_attachment
Investigation |
operation: Simple Report
Input parameters
| Parameter |
Description |
| Simple Report Type |
Type of the Simple Report whose details you want to retrieve from Cisco ESA.
You can choose from the following options: Authentication Summary, Outgoing DLP Traffic Summary, Incoming Malware Threat File Detail Summary, Incoming Traffic Summary, Mailbox Auto Remediation, Outgoing Traffic Summary, Security Summary, Sender Group Summary, or System Capacity.Type of the Top-N whose details you want to retrieve from Cisco ESA. |
| Time Range |
Time Range based on which retrieve Simple Report(s) from Cisco ESA.
You can choose from the following options:
One Hour: Aggregate report(s) for the last one hour.
One Day: Aggregate report(s) for the last one hour.
Custom Range: Aggregate report(s) for the duration that you specify. Supported value of Time Zone Designator (TZD) which is equal to Z , +hh:mm , or -hh:mm. Z stands for Zulu time also known as GMT or UTC.
If you do not specify the start time and end time, then Simple Reports for the last 250 days will be retrieved from Cisco ESA. |
| Start Time |
(Optional) If you select Custom Range option for the Time Range parameter then specify the DateTime from when you want to retrieve Simple Report(s) from Cisco ESA in this field. |
| End Time |
(Optional) If you select Custom Range option for the Time Range parameter then specify the DateTime till when you want to retrieve Simple Report(s) from Cisco ESA in this field. |
Output
The JSON output details of Simple Report(s) retrieved from Cisco ESA based on the input parameters you have specified.
Output
The output contains the following populated JSON schema:
{
"uri": "",
"data": {}
}
operation: Top-N Report
Input parameters
| Parameter |
Description |
| Simple Report Type |
Type of the Top-N Reports whose details you want to retrieve from Cisco ESA.
You can choose from the following options: Incoming Authentication Domain IP, Incoming Mail Content Filter, DMARC Incoming Traffic Summary, Sender Rate Limit, Sender Stats, Fed Content Filter Incoming, Hvm Msg Filter Stats, Incoming Hat Connections, Incoming Malware Threat File Detail, Incoming Web Interaction Track Malicious Users, Incoming Web Interaction Track Urls, Md Attachment Incoming File Type, Md Attachment Outgoing File Type, Outgoing Web Interaction Track Malicious Users, Outgoing Web Interaction Track Urls, Msg Filter Stats, Sender Group Detail, Subject Stats, URL Category Summary, URL Domain Summary, URL Reputation Summary, VOF Threat Summary, VOF Threats By Level, VOF Threats By Threat Type, VOF Threats By Time Threshold, VOF Threats By Type, or VOF Threats By Rewritten URL. |
| Time Range |
Time Range based on which retrieve Top-N Report(s) from Cisco ESA.
You can choose from the following options:
One Hour: Aggregate report(s) for the last one hour.
One Day: Aggregate report(s) for the last one hour.
Custom Range: Aggregate report(s) for the duration that you specify. Supported value of Time Zone Designator (TZD) which is equal to Z , +hh:mm , or -hh:mm.
If you do not specify the start time and end time, then Simple Reports for the last 250 days will be retrieved from Cisco ESA. |
| Start Time |
(Optional) If you select Custom Range option for the Time Range parameter then specify the DateTime from when you want to retrieve Top-N Report(s) from Cisco ESA in this field. |
| End Time |
(Optional) If you select Custom Range option for the Time Range parameter then specify the DateTime till when you want to retrieve Top-N Report(s) from Cisco ESA in this field. |
| Record Count |
(Optional) Maximum number of reports that this operation should return. You can add any number in this field from 1 to 1000.
By default, this is set to 10. |
Output
The JSON output details of Top-N Report(s) retrieved from Cisco ESA based on the input parameters you have specified.
The output contains the following populated JSON schema:
{
"uri": "",
"data": {}
}
operation: Query-based Report
Input parameters
| Parameter |
Description |
| Simple Report Type |
Type of the Query-based Reports whose details you want to retrieve from Cisco ESA.
You can choose from the following options: Incoming Authentication Domain, Outgoing Content Filters, Destination Domain Detail, DLP Outgoing Policy Detail, Incoming Domain Detail, Incoming IP Hostname Detail, Incoming Network Detail, Sender Domain Detail, Sender IP Hostname Detail, User Details, or Virus Type Detail. |
| Time Range |
Time Range based on which retrieve Query-based Report(s) from Cisco ESA.
You can choose from the following options:
One Hour: Aggregate report(s) for the last one hour.
One Day: Aggregate report(s) for the last one hour.
Custom Range: Aggregate report(s) for the duration that you specify. Supported value of Time Zone Designator (TZD) which is equal to Z , +hh:mm , or -hh:mm.
If you do not specify the start time and end time, then Query-based Reports for the last 250 days will be retrieved from Cisco ESA. |
| Start Time |
(Optional) If you select Custom Range option for the Time Range parameter then specify the DateTime from when you want to retrieve Query-based Report(s) from Cisco ESA in this field. |
| End Time |
(Optional) If you select Custom Range option for the Time Range parameter then specify the DateTime till when you want to retrieve Query-based Report(s) from Cisco ESA in this field. |
| Response Filter |
(Optional) Retrieve the Query-based Report(s) from Cisco ESA based on the filter value you specify such as email addresses or IP addresses.
Note: If you specify the Response Filter then you must specify the value of the Starts With parameter. |
| Starts With |
(Optional) Retrieve the Query-based Report(s) from Cisco ESA starting with the value you have specified in this parameter.
Note: This parameter must be used in conjunction with the Response Filter parameter. |
| Record Count |
(Optional) Maximum number of reports that this operation should return. You can add any number in this field from 1 to 1000.
By default, this is set to 10. |
Output
The JSON output details of Query-based Report(s) retrieved from Cisco ESA based on the input parameters you have specified.
The output contains the following populated JSON schema:
{
"uri": "",
"data": {}
}
operation: Block Email
Input parameters
| Parameter |
Description |
| Email ID |
One or more comma-separated email addresses that you want to block on Cisco ESA. |
| Message Filter Name |
Name of the message filter in which you want to add the specified email address on Cisco ESA. |
Output
The JSON output contains the status and result of the operation.
The output contains the following populated JSON schema:
{
"status": "",
"result": ""
}
operation: Unblock Email
Input parameters
| Parameter |
Description |
| Email ID |
One or more comma-separated email addresses that you want to unblock on Cisco ESA. |
Output
The JSON output contains the status and result of the operation.
The output contains the following populated JSON schema:
{
"result": "",
"status": ""
}
operation: Block Sender
Input parameters
| Parameter |
Description |
| Listener |
Name or number of the listener on which you want to block the specified sender. |
| Sender Type |
Type of sender you want to block. You can choose between Domain or Geolocation. |
| Domain Value |
If you choose the sender of type Domain, then specify one of the following values:
- an IP address
- a CIDR address such as 10.1.1.0/24 or 2001::0/64
- an IP range such as 10.1.1.10-20, 10.1.1-5 or 2001:db8::1-2001:db8::10
- an IP subnet such as 10.2.3
- a hostname such as crm.example.com
- a partial hostname such as .example.com
- a range of SenderBase Reputation Scores in the form SBRS[7.5:10.0]
- a SenderBase Network Owner ID in the form SBO:12345
- a remote blacklist query in the form dnslist[query.blacklist.example]
You can specify multiple domain values separated by commas. |
| Country |
If you choose the sender of type Geolocation, then specify the country using the Country drop-down list. You must select one value from the Country drop-down list, which includes a list of countries such as, 28. Bolivia [bo], 46. Chile [cl], 92. Guam [gu], 141. Marshall Islands [mh] etc. |
Output
The JSON output contains the status and result of the operation.
The output contains the following populated JSON schema:
{
"result": "",
"status": ""
}
operation: Unblock Sender
Input parameters
| Parameter |
Description |
| Listener |
Name or number of the listener from which you want to unblock the specified sender. |
| Sender Type |
Type of sender you want to unblock. You can choose between Domain or Geolocation. |
| Domain Value |
If you choose the sender of type Domain, then specify one of the following values:
- an IP address
- a CIDR address such as 10.1.1.0/24 or 2001::0/64
- an IP range such as 10.1.1.10-20, 10.1.1-5 or 2001:db8::1-2001:db8::10
- an IP subnet such as 10.2.3
- a hostname such as crm.example.com
- a partial hostname such as .example.com
- a range of SenderBase Reputation Scores in the form SBRS[7.5:10.0]
- a SenderBase Network Owner ID in the form SBO:12345
- a remote blacklist query in the form dnslist[query.blacklist.example]
You can specify multiple domain values separated by commas. |
| Country |
If you choose the sender of type Geolocation, then specify the country using the Country drop-down list. You must select one value from the Country drop-down list, which includes a list of countries such as, 28. Bolivia [bo], 46. Chile [cl], 92. Guam [gu], 141. Marshall Islands [mh] etc. |
Output
The JSON output contains the status and result of the operation.
The output contains the following populated JSON schema:
{
"result": "",
"status": ""
}
operation: Get Message Filters List
Input parameters
None.
Output
The JSON output contains the status and result of the operation. The results contain a list and details of message filters retrieved from Cisco ESA.
The output contains the following populated JSON schema:
{
"status": "",
"result": [
{
"Name": "",
"Num": "",
"Valid": "",
"Details": "",
"Active": ""
}
]
}
operation: Message Tracking
Input parameters
| Parameter |
Description |
| Search Type |
Search type based on which you want to track messages in Cisco ESA. You can choose from the following options: Search by envelope FROM, Search by Message ID, Search by Subject, or Search by envelope TO. |
| Search Value |
Value of search to be used for tracking messages in Cisco ESA. You must enter the search value based on the Search Type you have specified. For example, if you select the Search Type as Search by Subject, then enter the value of the subject using which you want to tracks messages in Cisco ESA. |
Output
The output contains the following populated JSON schema:
Output schema if 'Search Type' is 'Search by Subject'
{
"formatted_result": [
{
"subject": "",
"mid": "",
"received_time": ""
}
],
"result": [],
"status": ""
}
Output schema if 'Search Type' is 'Search by Message ID'
{
"formatted_result": {
"ip_address": [],
"message_id": "",
"to": [],
"subject": "",
"received_time": [],
"from": []
},
"result": [],
"status": ""
}
{
"result": [],
"status": ""
}
operation: Get All Dictionaries
Input parameters
None.
Output
The output contains the following populated JSON schema:
{
"result": {},
"message": ""
}
operation: Get Dictionary Entries
Input parameters
| Parameter |
Description |
| Name Of Dictionary |
Name of the dictionary whose entries you want to retrieve from Cisco ESA. |
Output
The output contains the following populated JSON schema:
{
"message": "",
"result": []
}
operation: Add Entries In Dictionary
Input parameters
| Parameter |
Description |
| Name Of Dictionary |
Name of the dictionary to which you want to add entries. |
| Entries |
Entries, i.e., new words or regular expressions that you want to add to the specified dictionary in Cisco ESA. You can separate multiple entries using "space". You can also optionally define weights (1 to 10) for entries by separating the word or expression with a comma and number. For example, v1,1 v2,5 |
Output
The output contains the following populated JSON schema:
{
"message": "",
"status": ""
}
operation: Remove Entries From Dictionary
Input parameters
| Parameter |
Description |
| Name Of Dictionary |
Name of the dictionary from which you want to remove entries. |
| Entries |
List of entries, separated by space, that you want to remove from the specified dictionary in Cisco ESA. |
Output
The output contains the following populated JSON schema:
{
"message": "",
"status": ""
}
operation: Get All Policies
Input parameters
| Parameter |
Description |
| Policy Type |
Type of policy whose policies you want to retrieve from Cisco ESA. You can choose from the following options: Incoming Mail Policies or Outgoing Mail Policies. |
Output
The output contains the following populated JSON schema:
{
"data": "",
"policy_data": ""
}
operation: Add Entries In Policy
Input parameters
| Parameter |
Description |
| Policy Name |
Name of the policy in which you want to add entries. |
| Policy Type |
Type of policy in which you want to add entries. You can choose from the following options: Incoming Mail Policies or Outgoing Mail Policies. |
| Policy Applicable For |
Select the option to whom the policy should apply. You can choose from the following options: All Senders, Any Of The Added Senders, or None Of The Added Senders.
If you choose the None Of The Added Senders option, then you must add the following parameters:
- Enter Policy Exceptions: Exceptions that you want to apply to the policy. Following types of entries are allowed:
Username entries such as joe@
Domain entries such as @example.com
Sub-domain entries such as @.example.com
- Enter LDAP Group Memberships?: Select this option if you want to add LDAP group membership for input receivers.
If you check the Enter LDAP Group Memberships? checkbox, then you must specify the following parameters:
- Query: Name of the query that you want to add to the policy for an input user.
- Group Name: Groupname for the LDAP query.
If you choose the Any Of The Added Sendersoption, then you must add the following parameters:
- Senders: Senders to whom the policy will apply. Following types of entries are allowed:
Username entries such as joe@
Domain entries such as @example.com
Sub-domain entries such as @.example.com
- Enter LDAP Group Memberships?: Select this option if you want to add LDAP group membership for input senders.
If you check the Enter LDAP Group Memberships? checkbox, then you must specify the following parameters:
- Query: Name of the query that you want to add to the policy for an input user.
- Group Name: Groupname for the LDAP query.
|
| Add Receiver |
Select this option if you want to add policy receivers.
If you check the Add Receivers checkbox, then you must specify the following parameters:
- Policy Applicable For: Select the option to whom the policy should apply. You can choose from the following options: All Receivers, Any Of The Added Receivers, or All Of The Added Receivers.
- If you choose the All Of The Added Receivers option, then you must add the following parameters:
- Receivers: Receivers to whom the policy will apply. Following types of entries are allowed:
Username entries such as joe@
Domain entries such as @example.com
Sub-domain entries such as @.example.com
- Enter LDAP Group Memberships?: Select this option if you want to add LDAP group membership for input receivers.
If you check the Enter LDAP Group Memberships? checkbox, then you must specify the following parameters:
- Query: Name of the query that you want to add to the policy for an input user.
- Group Name: Groupname for the LDAP query.
- Enter Exception?: Select this option if you want to add exceptions to the receivers of this policy.
If you check the Enter Exception? checkbox, then you must specify the following parameters:
- Policy Exceptions: Exceptions that you want to apply to the policy. Following types of entries are allowed:
Username entries such as joe@
Domain entries such as @example.com
Sub-domain entries such as @.example.com
- Enter LDAP Group Memberships?: Select this option if you want to add LDAP group membership for input receivers.
If you check the Enter LDAP Group Memberships? checkbox, then you must specify the following parameters:
- Query: Name of the query that you want to add to the policy for an input user.
- Group Name: Groupname for the LDAP query.
- If you choose the Any Of The Added Receivers option, then you must add the following parameters:
- Receivers: Receivers to whom the policy will apply. Following types of entries are allowed:
Username entries such as joe@
Domain entries such as @example.com
Sub-domain entries such as @.example.com
- Enter LDAP Group Memberships?: Select this option if you want to add LDAP group membership for input receivers.
If you check the Enter LDAP Group Memberships? checkbox, then you must specify the following parameters:
- Query: Name of the query that you want to add to the policy for an input user.
- Group Name: Groupname for the LDAP query.
|
Output
The output contains the following populated JSON schema:
{
"message": "",
"status": ""
}
operation: Remove Entries From Policy
Input parameters
| Parameter |
Description |
| Name Of Policy |
Name of the policy from which you want to remove entries. |
| Policy Type |
Type of policy from which you want to remove entries. You can choose from the following options: Incoming Mail Policies or Outgoing Mail Policies. |
| Row number |
Row number of the entry in the policy table that you want to delete. |
Output
The output contains the following populated JSON schema:
{
"message": "",
"status": ""
}
operation: Search Emails From SPAM Quarantine
Input parameters
| Parameter |
Description |
| Start Time |
Start time from when the emails were quarantined in the SPAM folder, in Cisco ESA, based on which you want to retrieve emails from Cisco ESA. |
| End Time |
End time till when the emails were quarantined in the SPAM folder, in Cisco ESA, based on which you want to retrieve emails from Cisco ESA. |
| Sorting |
(Optional) Value and/or direction using which you want to sort the results retrieved from Cisco ESA.
If you choose 'Order By', then you must specify the following parameter:
- Order By: Field using which you want to sort the results retrieved by this operation. You can choose from the following fields: From Address, To Address, or Subject.
If you choose 'Order Direction', then you must specify the following parameter:
- Order Direction: Sorts results retrieved by this operation in this direction. You can choose between Ascending or Descending.
|
| Lazy Loading |
Select this option if you want to limit the result data retrieved by this operation using lazy loading.
If you select this option then you must specify the following parameters:
- Offset: The offset value to retrieve a subset of records starting with the offset value. Offset works with the "limit" parameter, which determines how many records to retrieve starting from the offset.
- Limit: The maximum number of records that should be retrieved by this operation form Cisco ESA.
|
| Envelope Recipient |
(Optional) Filters emails to be retrieved from Cisco ESA by the "Envelope Recipient" value. You can choose from the following options: Contains, Is, Begins With, Ends With, or Does Not Contain.
If you choose 'Contains', then you must specify the following parameter:
- Contains: Filters messages whose envelope recipient value contains the text that you have specified in this field.
If you choose 'Is', then you must specify the following parameter:
- Is: Filter messages whose envelope recipient value matches the text that you have specified in this field.
If you choose 'Begins With', then you must specify the following parameter:
- Begins With: Filters messages whose envelope recipient value begins with the text that you have specified in this field.
If you choose 'Ends With', then you must specify the following parameter:
- Ends With: Filters messages whose envelope recipient value ends with the text that you have specified in this field.
If you choose 'Does Not Contain', then you must specify the following parameter:
- Does Not Contain: Filters messages whose envelope recipient value does not contain the text that you have specified in this field.
|
| Filtering |
(Optional) Filters emails to be retrieved from Cisco ESA by data or content. You can choose from the following options: Contains, Is, Begins With, Ends With, or Does Not Contain.
If you choose 'Contains', then you must specify the following parameter:
- Contains: Filters messages whose content contains the text that you have specified in this field.
If you choose 'Is', then you must specify the following parameter:
- Is: Filter messages whose content matches the text that you have specified in this field.
If you choose 'Begins With', then you must specify the following parameter:
- Begins With: Filters messages whose content begins with the text that you have specified in this field.
If you choose 'Ends With', then you must specify the following parameter:
- Ends With: Filters messages whose content ends with the text that you have specified in this field.
If you choose 'Does Not Contain', then you must specify the following parameter:
- Does Not Contain: Filters messages whose data does not contain the text that you have specified in this field.
|
Output
The output contains the following populated JSON schema:
{
"meta": {
"totalCount": ""
},
"data": [
{
"attributes": {
"envelopeRecipient": [],
"toAddress": [],
"subject": "",
"date": "",
"fromAddress": [],
"size": ""
},
"mid": ""
}
]
}
operation: Get Message Details
Input parameters
| Parameter |
Description |
| Message ID |
ID of the message whose details you want to retrieve from Cisco ESA. For example, 1755 |
Output
The output contains the following populated JSON schema:
{
"data": {
"attributes": {
"envelopeRecipient": [
""
],
"toAddress": [
""
],
"attachments": [],
"messageBody": "",
"date": "",
"fromAddress": [
""
],
"subject": ""
},
"mid": ""
}
}
operation: Release Emails From Quarantine
Input parameters
| Parameter |
Description |
| Message IDs |
Comma-separated list of message IDs that you want to release from quarantine in Cisco ESA. You can enter multiple message IDs in the CSV or List format. For example, 184,141,164 or [184,141,164] |
Output
The output contains the following populated JSON schema:
{
"data": {
"action": "",
"totalCount": ""
}
}
operation: Delete Message
Input parameters
| Parameter |
Description |
| Message IDs |
Comma-separated list of message IDs that you want to delete from Cisco ESA. You can enter multiple message IDs in the CSV or List format. For example, 184,141,164 or [184,141,164] |
Output
The output contains the following populated JSON schema:
{
"data": {
"action": "",
"totalCount": ""
}
}
operation: Search Emails From Other Quarantine
Input parameters
| Parameter |
Description |
| Start Time |
Start time from when the emails were quarantined in the "quarantined" folder you have specified, in Cisco ESA, based on which you want to retrieve emails from Cisco ESA. |
| End Time |
End time till when the emails were quarantined in the "quarantined" folder you have specified, in Cisco ESA, based on which you want to retrieve emails from Cisco ESA.
|
| Quarantine Name |
Name of the quarantine that you want to search in Cisco ESA and from which you want to retrieve emails. |
| Quarantine Type |
Type of the quarantine emails that you want to search for and retrieve from Cisco ESA. For example, pvo. |
| Subject |
(Optional) Filters emails to be retrieved from Cisco ESA by subject. You can choose from the following options: Contains, Begins With, Ends With, Matches Exactly, Does Not Contain, Does Not Begin With, Does Not End With, or Does Not Match.
If you choose 'Contains', then you must specify the following parameter:
- Contains: Filters messages whose subject contains the text that you have specified in this field.
If you choose 'Starts With', then you must specify the following parameter:
- Starts With: Filters messages whose subject starts with the text that you have specified in this field.
If you choose 'Ends With', then you must specify the following parameter:
- Ends With: Filters messages whose subject ends with the text that you have specified in this field.
If you choose 'Matches Exactly', then you must specify the following parameter:
- Matches Exactly: Filters messages whose subject exactly matches the text that you have specified in this field.
If you choose 'Does Not Contain', then you must specify the following parameter:
- Does Not Contain: Filters messages whose subject does not contain the text that you have specified in this field.
If you choose 'Does Not Start With', then you must specify the following parameter:
- Does Not Start With: Filters messages whose subject does not start with the text that you have specified in this field.
If you choose 'Does Not End With', then you must specify the following parameter:
- Does Not End With: Filters messages whose subject does not end with the text that you have specified in this field.
If you choose 'Does Not Match', then you must specify the following parameter:
- Does Not Match: Filters messages whose subject does not match with the text that you have specified in this field.
|
| Originating ESA |
(Optional) IP address of the ESA that processed the email message that you want to retrieve from Cisco ESA. |
| Attachment Details |
(Optional) Filters emails to be retrieved from Cisco ESA by name of the attachment or size of the email attachment, or both.
If you choose 'Attachment Name', then you must specify the following parameter:
- Attachment Name: Filter email message based on the attachment you have specified.
If you choose 'Attachment Size Filter By', then you must specify the following parameter:
- Size Filter: Filter attachments by the size you have specified. You can choose between Range, Less Than, or Greater Than.
- If you choose 'Range', then you must specify the following parameters:
- Attachment Size From Value: Filters emails whose attachment size, in KB, starts from the value that you have specified in this field.
- Attachment Size To Value: Filters emails whose attachment size, in KB, ends with the value that you have specified in this field.
- If you choose 'Less Than', then you must specify the following parameter:
- Attachment Size: Filters emails whose attachment size, in KB, is lesser than the value that you have specified in this field.
- If you choose 'More Than', then you must specify the following parameter:
- Attachment Size: Filters emails whose attachment size, in KB, is greater than the value that you have specified in this field.
|
| Sorting |
(Optional) Value and/or direction using which you want to sort the results retrieved from Cisco ESA.
If you choose 'Order By', then you must specify the following parameter:
- Order By: Field using which you want to sort the results retrieved by this operation. You can choose from the following fields: Sender, Subject, Received, Scheduled Exit, or Size.
If you choose 'Order Direction', then you must specify the following parameter:
- Order Direction: Sorts results retrieved by this operation in this direction. You can choose between Ascending or Descending.
|
| Lazy Loading |
Select this option if you want to limit the result data retrieved by this operation using lazy loading.
If you select this option then you must specify the following parameters:
- Offset: The offset value to retrieve a subset of records starting with the offset value. Offset works with the "limit" parameter, which determines how many records to retrieve starting from the offset.
- Limit: The maximum number of records that should be retrieved by this operation form Cisco ESA.
|
| Envelope Recipient |
(Optional) Filters emails to be retrieved from Cisco ESA by the "Envelope Recipient" value. You can choose from the following options: Contains, Begins With, Ends With, Matches Exactly, Does Not Contain, Does Not Begin With, Does Not End With, or Does Not Match.
If you choose 'Contains', then you must specify the following parameter:
- Contains: Filters messages whose envelope recipient value contains the text that you have specified in this field.
If you choose 'Starts With', then you must specify the following parameter:
- Starts With: Filters messages whose envelope recipient value begins with the text that you have specified in this field.
If you choose 'Ends With', then you must specify the following parameter:
- Ends With: Filters messages whose envelope recipient value ends with the text that you have specified in this field.
If you choose 'Matches Exactly', then you must specify the following parameter:
- Matches Exactly: Filters messages whose envelope recipient value exactly matches the text that you have specified in this field.
If you choose 'Does Not Contain', then you must specify the following parameter:
- Does Not Contain: Filters messages whose envelope recipient value does not contain the text that you have specified in this field.
If you choose 'Does Not Start With', then you must specify the following parameter:
- Does Not Start With: Filters messages whose envelope recipient value does not start with the text that you have specified in this field.
If you choose 'Does Not End With', then you must specify the following parameter:
- Does Not End With: Filters messages whose envelope recipient value does not end with the text that you have specified in this field.
If you choose 'Does Not Match', then you must specify the following parameter:
- Does Not Match: Filters messages whose envelope recipient value does not match with the text that you have specified in this field.
|
| Envelope Sender |
(Optional) Filters emails to be retrieved from Cisco ESA by the "Envelope Sender" value. You can choose from the following options: Contains, Begins With, Ends With, Matches Exactly, Does Not Contain, Does Not Begin With, Does Not End With, or Does Not Match.
If you choose 'Contains', then you must specify the following parameter:
- Contains: Filters messages whose envelope sender value contains the text that you have specified in this field.
If you choose 'Starts With', then you must specify the following parameter:
- Starts With: Filters messages whose envelope sender value begins with the text that you have specified in this field.
If you choose 'Ends With', then you must specify the following parameter:
- Ends With: Filters messages whose envelope sender value ends with the text that you have specified in this field.
If you choose 'Matches Exactly', then you must specify the following parameter:
- Matches Exactly: Filters messages whose envelope sender value exactly matches the text that you have specified in this field.
If you choose 'Does Not Contain', then you must specify the following parameter:
- Does Not Contain: Filters messages whose envelope sender value does not contain the text that you have specified in this field.
If you choose 'Does Not Start With', then you must specify the following parameter:
- Does Not Start With: Filters messages whose envelope sender value does not start with the text that you have specified in this field.
If you choose 'Does Not End With', then you must specify the following parameter:
- Does Not End With: Filters messages whose envelope sender value does not end with the text that you have specified in this field.
If you choose 'Does Not Match', then you must specify the following parameter:
- Does Not Match: Filters messages whose envelope sender value does not match with the text that you have specified in this field.
|
Output
The output contains the following populated JSON schema:
{
"meta": {
"totalCount": ""
},
"data": [
{
"attributes": {
"received": "",
nbsp; "sender": "",
"subject": "",
"esaHostName": "",
"inQuarantines": "",
"scheduledExit": "",
"originatingEsaIp": "",
"quarantineForReason": [],
"esaMid": "",
"recipient": [],
"quarantineForReasonDict": [
{
"reason": [],
"quarantineName": ""
}
],
"size": ""
},
"mid": ""
}
]
}
operation: Download Attachment
Input parameters
| Parameter |
Description |
| Message ID |
ID of the message whose details and associated attachment you want to retrieve from Cisco ESA. For example, 46. |
| Attachment ID |
ID of the attachment associated with the specified message that you want to download from Cisco ESA. For example, 2. |
Output
The output contains a non-dictionary value.
Included playbooks
The Sample - Cisco ESA - 2.0.1 playbook collection comes bundled with the Cisco ESA connector. This playbook contains steps using which you can perform all supported actions. You can see the bundled playbooks in the Automation > Playbooks section in FortiSOAR™ after importing the Cisco ESA connector.
- Delete Message
- Dictionary: Add Entries In Dictionary
- Dictionary: Get All Dictionaries
- Dictionary: Get Dictionary Entries
- Dictionary: Remove Entries From Dictionary
- Download Attachment
- Email: Block Email
- Email: Unblock Email
- Get Message Details
- Get Message Filters List
- Message Tracking
- Policy: Add Entries In Policy
- Policy: Get All Policies
- Policy: Remove Entries From Policy
- Release Emails From Quarantine
- Report: Query-based Report
- Report: Simple Report
- Report: Top-N Report
- Search Emails From Other Quarantine
- Search Emails From SPAM Quarantine
- Sender: Block Sender
- Sender: Unblock Sender
Note: If you are planning to use any of the sample playbooks in your environment, ensure that you clone those playbooks and move them to a different collection since the sample playbook collection gets deleted during the connector upgrade and delete.
