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: 1.0.0
FortiSOAR™ Version Tested on: 4.11.0-1161
Cisco ESA Version Tested on: Cisco C100V 11.1.0-069
Authored By: Fortinet
Certified: Yes
Installing the connector
All connectors provided by FortiSOAR™ are delivered using a FortiSOAR™ repository. Therefore, you must set up your FortiSOAR™ repository and use the yum command to install connectors:
yum install cyops-connector-cisco-esa
For the detailed procedure to install a connector, click here.
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 the automated operations and credentials to access that server.
- You must enable AsyncOS API on the Management interface.
- 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 to configure the following parameters:
| 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 the automated operations. |
| Password |
Password to access the Cisco ESA server to which you will connect and perform the automated operations. |
| Protocol |
Protocol that will be used to communicate, 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. |
| 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 FortiSOAR™ release 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 an 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 message filters from Cisco ESA. It also displays details of email addresses that are associated with the message filters. |
get_msg_filters
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.
Following image displays a sample output of a Simple Report of type Authentication Summary:
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.
Following image displays a sample output of a Top-N Report of type Incoming HAT Connections:
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.
Following image displays a sample output of a Query Based Report of type Incoming IP Hostname Detail:
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.
Following image displays a sample output:
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.
Following image displays a sample output, where you have specified the following email IDs to be unblocked: demo@example.com, demo@example2.com. The image displays that the demo@example.com email ID that you have specified is unblocked and the demo@example2.com email ID that you have not specified is not found in message filters:
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.
Following image displays a sample output:
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.
Following image displays a sample output:
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.
Following image displays a sample output:
Included playbooks
The Sample - Cisco-ESA - 1.0.0 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.
- Block Email
- Block Sender
- Get Message Filters List
- Query Based Report
- Simple Report
- Top-N Report
- Unblock Email
- 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 connector upgrade and delete.
