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.
Connector Version: 2.0.1
Authored By: Community
Certified: No
Following enhancements have been made to the Cisco ESA connector in version 2.0.1:
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
For the procedure to configure a connector, click here.
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 . |
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 |
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. |
The JSON output details of Simple Report(s) retrieved from Cisco ESA based on the input parameters you have specified.
The output contains the following populated JSON schema:
{
"uri": "",
"data": {}
}
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. |
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": {}
}
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. |
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": {}
}
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. |
The JSON output contains the status and result of the operation.
The output contains the following populated JSON schema:
{
"status": "",
"result": ""
}
Parameter | Description |
---|---|
Email ID | One or more comma-separated email addresses that you want to unblock on Cisco ESA. |
The JSON output contains the status and result of the operation.
The output contains the following populated JSON schema:
{
"result": "",
"status": ""
}
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. |
The JSON output contains the status and result of the operation.
The output contains the following populated JSON schema:
{
"result": "",
"status": ""
}
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. |
The JSON output contains the status and result of the operation.
The output contains the following populated JSON schema:
{
"result": "",
"status": ""
}
None.
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": ""
}
]
}
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. |
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": ""
}
None.
The output contains the following populated JSON schema:
{
"result": {},
"message": ""
}
Parameter | Description |
---|---|
Name Of Dictionary | Name of the dictionary whose entries you want to retrieve from Cisco ESA. |
The output contains the following populated JSON schema:
{
"message": "",
"result": []
}
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 |
The output contains the following populated JSON schema:
{
"message": "",
"status": ""
}
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. |
The output contains the following populated JSON schema:
{
"message": "",
"status": ""
}
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. |
The output contains the following populated JSON schema:
{
"data": "",
"policy_data": ""
}
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:
|
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:
|
The output contains the following populated JSON schema:
{
"message": "",
"status": ""
}
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. |
The output contains the following populated JSON schema:
{
"message": "",
"status": ""
}
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:
|
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:
|
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:
|
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:
|
The output contains the following populated JSON schema:
{
"meta": {
"totalCount": ""
},
"data": [
{
"attributes": {
"envelopeRecipient": [],
"toAddress": [],
"subject": "",
"date": "",
"fromAddress": [],
"size": ""
},
"mid": ""
}
]
}
Parameter | Description |
---|---|
Message ID | ID of the message whose details you want to retrieve from Cisco ESA. For example, 1755 |
The output contains the following populated JSON schema:
{
"data": {
"attributes": {
"envelopeRecipient": [
""
],
"toAddress": [
""
],
"attachments": [],
"messageBody": "",
"date": "",
"fromAddress": [
""
],
"subject": ""
},
"mid": ""
}
}
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] |
The output contains the following populated JSON schema:
{
"data": {
"action": "",
"totalCount": ""
}
}
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] |
The output contains the following populated JSON schema:
{
"data": {
"action": "",
"totalCount": ""
}
}
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:
If you choose 'Matches Exactly', then you must specify the following parameter:
If you choose 'Does Not Contain', then you must specify the following parameter:
If you choose 'Does Not Start With', then you must specify the following parameter:
If you choose 'Does Not Match', then you must specify the following parameter:
|
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:
If you choose 'Attachment Size Filter By', then you must specify the following parameter:
|
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:
|
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:
|
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 'Matches Exactly', then you must specify the following parameter:
If you choose 'Does Not Start With', then you must specify the following parameter:
If you choose 'Does Not End With', then you must specify the following parameter:
If you choose 'Does Not Match', then you must specify the following parameter:
|
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 'Matches Exactly', then you must specify the following parameter:
If you choose 'Does Not Start With', then you must specify the following parameter:
If you choose 'Does Not End With', then you must specify the following parameter:
If you choose 'Does Not Match', then you must specify the following parameter:
|
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": ""
}
]
}
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 . |
The output contains a non-dictionary value.
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.
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.
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.
Connector Version: 2.0.1
Authored By: Community
Certified: No
Following enhancements have been made to the Cisco ESA connector in version 2.0.1:
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
For the procedure to configure a connector, click here.
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 . |
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 |
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. |
The JSON output details of Simple Report(s) retrieved from Cisco ESA based on the input parameters you have specified.
The output contains the following populated JSON schema:
{
"uri": "",
"data": {}
}
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. |
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": {}
}
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. |
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": {}
}
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. |
The JSON output contains the status and result of the operation.
The output contains the following populated JSON schema:
{
"status": "",
"result": ""
}
Parameter | Description |
---|---|
Email ID | One or more comma-separated email addresses that you want to unblock on Cisco ESA. |
The JSON output contains the status and result of the operation.
The output contains the following populated JSON schema:
{
"result": "",
"status": ""
}
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. |
The JSON output contains the status and result of the operation.
The output contains the following populated JSON schema:
{
"result": "",
"status": ""
}
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. |
The JSON output contains the status and result of the operation.
The output contains the following populated JSON schema:
{
"result": "",
"status": ""
}
None.
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": ""
}
]
}
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. |
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": ""
}
None.
The output contains the following populated JSON schema:
{
"result": {},
"message": ""
}
Parameter | Description |
---|---|
Name Of Dictionary | Name of the dictionary whose entries you want to retrieve from Cisco ESA. |
The output contains the following populated JSON schema:
{
"message": "",
"result": []
}
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 |
The output contains the following populated JSON schema:
{
"message": "",
"status": ""
}
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. |
The output contains the following populated JSON schema:
{
"message": "",
"status": ""
}
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. |
The output contains the following populated JSON schema:
{
"data": "",
"policy_data": ""
}
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:
|
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:
|
The output contains the following populated JSON schema:
{
"message": "",
"status": ""
}
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. |
The output contains the following populated JSON schema:
{
"message": "",
"status": ""
}
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:
|
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:
|
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:
|
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:
|
The output contains the following populated JSON schema:
{
"meta": {
"totalCount": ""
},
"data": [
{
"attributes": {
"envelopeRecipient": [],
"toAddress": [],
"subject": "",
"date": "",
"fromAddress": [],
"size": ""
},
"mid": ""
}
]
}
Parameter | Description |
---|---|
Message ID | ID of the message whose details you want to retrieve from Cisco ESA. For example, 1755 |
The output contains the following populated JSON schema:
{
"data": {
"attributes": {
"envelopeRecipient": [
""
],
"toAddress": [
""
],
"attachments": [],
"messageBody": "",
"date": "",
"fromAddress": [
""
],
"subject": ""
},
"mid": ""
}
}
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] |
The output contains the following populated JSON schema:
{
"data": {
"action": "",
"totalCount": ""
}
}
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] |
The output contains the following populated JSON schema:
{
"data": {
"action": "",
"totalCount": ""
}
}
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:
If you choose 'Matches Exactly', then you must specify the following parameter:
If you choose 'Does Not Contain', then you must specify the following parameter:
If you choose 'Does Not Start With', then you must specify the following parameter:
If you choose 'Does Not Match', then you must specify the following parameter:
|
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:
If you choose 'Attachment Size Filter By', then you must specify the following parameter:
|
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:
|
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:
|
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 'Matches Exactly', then you must specify the following parameter:
If you choose 'Does Not Start With', then you must specify the following parameter:
If you choose 'Does Not End With', then you must specify the following parameter:
If you choose 'Does Not Match', then you must specify the following parameter:
|
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 'Matches Exactly', then you must specify the following parameter:
If you choose 'Does Not Start With', then you must specify the following parameter:
If you choose 'Does Not End With', then you must specify the following parameter:
If you choose 'Does Not Match', then you must specify the following parameter:
|
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": ""
}
]
}
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 . |
The output contains a non-dictionary value.
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.
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.