Cisco ESA

The Cisco ESA connector facilitates the automation of email security operations by allowing Swimlane Turbine to interact with Cisco Email Security Appliance.

Cisco Email Security Appliance (ESA) is a robust email security platform that provides protection against email threats. The Swimlane Turbine integration with Cisco ESA enables users to automate the retrieval of detailed message tracking information, including Advanced Malware Protection (AMP) attributes, connection details, and Data Loss Prevention (DLP) incidents. This connector empowers security teams to efficiently investigate and respond to email-based threats, enhancing overall email security and incident response capabilities within the Swimlane ecosystem.

The AsyncOS API for Cisco Secure Email Gateway (or AsyncOS API) is a representational state transfer (REST) based set of operations that provide secure and authenticated access to the email gateway reports, report counters, and tracking. You can retrieve the email gateway reporting and tracking data using the API.

Prerequisites

To effectively utilize the Cisco ESA connector for Swimlane Turbine, ensure you have the following prerequisites:

Username and Passphrase authentication with the following parameters:

URL: Endpoint URL for the Cisco ESA API.

User Name: Your Cisco ESA account username.

Passphrase: Your Cisco ESA account passphrase.

Capabilities

This Connector provides the following capabilities:

AMP Details

Connection Details

DLP Details

Message Details

Rejected Connections

Remediation Details

Retrieving All Incoming Messages

Retrieving All Outgoing Messages

Searching for Messages

URL Details

Notes

API Documentation

Configurations

Cisco ESA Asset

Authenticates using Username and Passphrase

Configuration Parameters

Parameter	Description	Type	Required
url	A URL to the target host.	string	Required
username	Username.	string	Required
passphrase	Passphrase.	string	Required
verify_ssl	Verify SSL certificate.	boolean	Optional
http_proxy	A proxy to route requests through.	string	Optional

Actions

AMP Details

Retrieve message details with Advanced Malware Protection attributes from Cisco ESA, using filters like date range and identifiers including endDate, icid, mid, and startDate.

Endpoint

URL: /esa/api/v2.0/message-tracking/amp-details

Method: GET

Input

Argument Name	Type	Required	Description
parameters.endDate	string	Required	Parameters for the AMP Details action
parameters.icid	number	Required	Parameters for the AMP Details action
parameters.mid	number	Required	Parameters for the AMP Details action
parameters.serialNumber	string	Optional	Parameters for the AMP Details action
parameters.startDate	string	Required	Parameters for the AMP Details action

Input Example

{"parameters":{"endDate":"2018-11-16T11:25:00.000Z","icid":19213,"mid":22124,"serialNumber":"64122536256E-FCH1812V1ST","startDate":"2018-11-09T00:00:00.000Z"}}

Output

Parameter	Type	Description
status_code	number	HTTP status code of the response
reason	string	Response reason phrase
data	object	Response data
data.messages	object	Response data
data.messages.showAMPDetails	boolean	Response data
data.messages.direction	string	Response data
data.messages.smtpAuthId	string	Response data
data.messages.sender	string	Response data
data.messages.midHeader	string	Response data
data.messages.timestamp	string	Response data
data.messages.hostName	string	Response data
data.messages.mid	array	Response data
data.messages.sendingHostSummary	object	Response data
data.messages.attachments	array	Response data
data.messages.messageSize	string	Response data
data.messages.ampDetails	array	Response data
data.messages.ampDetails.timestamp	string	Response data
data.messages.ampDetails.description	string	Response data
data.messages.ampDetails.lastEvent	boolean	Response data
data.messages.senderGroup	string	Response data
data.messages.recipient	array	Response data
data.messages.subject	string	Response data

Output Example

{"status_code":200,"response_headers":{},"reason":"OK","json_body":{"data":{"messages":{}}}}

Connection Details

Retrieve detailed message connection information from Cisco ESA by specifying attributes such as endDate, icid, mid, and startDate.

Endpoint

URL: /esa/api/v2.0/message-tracking/connection-details

Method: GET

Input

Argument Name	Type	Required	Description
parameters.endDate	string	Required	Parameters for the Connection Details action
parameters.icid	number	Required	Parameters for the Connection Details action
parameters.mid	number	Required	Parameters for the Connection Details action
parameters.serialNumber	string	Optional	Parameters for the Connection Details action
parameters.startDate	string	Required	Parameters for the Connection Details action

Input Example

{"parameters":{"endDate":"2018-11-16T11:25:00.000Z","icid":19213,"mid":22124,"serialNumber":"64122536256E-FCH1812V1ST","startDate":"2018-11-09T00:00:00.000Z"}}

Output

Parameter	Type	Description
status_code	number	HTTP status code of the response
reason	string	Response reason phrase
senderGroup	string	Output field: senderGroup
messages	object	Response message
messages.summary	array	Response message
messages.summary.timestamp	string	Response message
messages.summary.description	string	Response message
messages.summary.lastEvent	boolean	Response message
sbrs	string	Output field: sbrs

Output Example

{"status_code":200,"response_headers":{},"reason":"OK","json_body":{"senderGroup":"RELAYLIST","messages":{"summary":[]},"sbrs":"not enabled"}}

DLP Details

Retrieve detailed Data Loss Prevention information for messages in Cisco ESA using attributes such as endDate, icid, mid, and startDate.

Endpoint

URL: /esa/api/v2.0/message-tracking/dlp-details

Method: GET

Input

Argument Name	Type	Required	Description
parameters.endDate	string	Required	Parameters for the DLP Details action
parameters.icid	number	Required	Parameters for the DLP Details action
parameters.mid	number	Required	Parameters for the DLP Details action
parameters.serialNumber	string	Optional	Parameters for the DLP Details action
parameters.startDate	string	Required	Parameters for the DLP Details action

Input Example

{"parameters":{"endDate":"2018-11-16T11:25:00.000Z","icid":19213,"mid":22124,"serialNumber":"64122536256E-FCH1812V1ST","startDate":"2018-11-09T00:00:00.000Z"}}

Output

Parameter	Type	Description
status_code	number	HTTP status code of the response
reason	string	Response reason phrase
data	object	Response data
data.messages	object	Response data
data.messages.direction	string	Response data
data.messages.smtpAuthId	string	Response data
data.messages.sender	string	Response data
data.messages.midHeader	string	Response data
data.messages.timestamp	string	Response data
data.messages.hostName	string	Response data
data.messages.mid	array	Response data
data.messages.sendingHostSummary	object	Response data
data.messages.attachments	array	Response data
data.messages.messageSize	string	Response data
data.messages.dlpDetails	object	Response data
data.messages.dlpDetails.violationSeverity	string	Response data
data.messages.dlpDetails.dlpMatchedContent	array	Response data
data.messages.dlpDetails.dlpMatchedContent.messagePartMatch	array	Response data
data.messages.dlpDetails.dlpMatchedContent.messagePart	string	Response data
data.messages.dlpDetails.mid	string	Response data
data.messages.dlpDetails.riskFactor	number	Response data
data.messages.dlpDetails.dlpPolicy	string	Response data
data.messages.showDLPDetails	boolean	Response data
data.messages.senderGroup	string	Response data
data.messages.recipient	array	Response data

Output Example

{"status_code":200,"response_headers":{},"reason":"OK","json_body":{"data":{"messages":{}}}}

Message Details

Retrieve detailed information on messages within Cisco ESA, using filters such as endDate, icid, mid, and startDate.

Endpoint

URL: /esa/api/v2.0/message-tracking/details

Method: GET

Input

Argument Name	Type	Required	Description
parameters.endDate	string	Required	Parameters for the Message Details action
parameters.icid	number	Required	Parameters for the Message Details action
parameters.mid	number	Required	Parameters for the Message Details action
parameters.serialNumber	string	Optional	Parameters for the Message Details action
parameters.startDate	string	Required	Parameters for the Message Details action

Input Example

{"parameters":{"endDate":"2018-11-16T12:09:00.000Z","icid":19214,"mid":22125,"serialNumber":"64122536256E-FCH1812V1ST","startDate":"2018-11-16T00:00:00.000Z"}}

Output

Parameter	Type	Description
status_code	number	HTTP status code of the response
reason	string	Response reason phrase
data	object	Response data
data.messages	object	Response data
data.messages.direction	string	Response data
data.messages.smtpAuthId	string	Response data
data.messages.sender	string	Response data
data.messages.midHeader	string	Response data
data.messages.timestamp	string	Response data
data.messages.showAMP	boolean	Response data
data.messages.hostName	string	Response data
data.messages.mid	array	Response data
data.messages.sendingHostSummary	object	Response data
data.messages.sendingHostSummary.reverseDnsHostname	string	Response data
data.messages.sendingHostSummary.ipAddress	string	Response data
data.messages.sendingHostSummary.sbrsScore	string	Response data
data.messages.summary	array	Response data
data.messages.summary.timestamp	string	Response data
data.messages.summary.description	string	Response data
data.messages.summary.lastEvent	boolean	Response data
data.messages.attachments	array	Response data
data.messages.messageSize	string	Response data
data.messages.isCompleteData	boolean	Response data
data.messages.showDLP	boolean	Response data
data.messages.messageStatus	string	Response data

Output Example

{"status_code":200,"response_headers":{},"reason":"OK","json_body":{"data":{"messages":{}}}}

Rejected Connections

Retrieve details of rejected connections from Cisco ESA within a specified date range, including pagination options using startDate, endDate, offset, and limit.

Endpoint

URL: /esa/api/v2.0/message-tracking/messages

Method: GET

Input

Argument Name	Type	Required	Description
parameters.startDate	string	Required	Parameters for the Rejected Connections action
parameters.endDate	string	Required	Parameters for the Rejected Connections action
parameters.senderIp	string	Optional	Parameters for the Rejected Connections action
parameters.searchOption	string	Optional	Parameters for the Rejected Connections action
parameters.offset	number	Required	Parameters for the Rejected Connections action
parameters.limit	number	Required	Parameters for the Rejected Connections action

Input Example

{"parameters":{"startDate":"2016-11-16T00:00:00.000Z","endDate":"2018-11-16T14:22:00.000Z","senderIp":"10.76.70.112","searchOption":"rejected_connections","offset":0,"limit":20}}

Output

Parameter	Type	Description
status_code	number	HTTP status code of the response
reason	string	Response reason phrase
meta	object	Output field: meta
meta.num_bad_records	number	Output field: meta.num_bad_records
meta.totalCount	number	Count value
data	array	Response data
data.attributes	object	Response data
data.attributes.icid	number	Response data
data.attributes.timestamp	string	Response data
data.attributes.hostName	string	Response data
data.attributes.rejected	string	Response data
data.attributes.messageStatus	string	Response data
data.attributes.senderIp	string	Response data
data.attributes.senderGroup	string	Response data
data.attributes.sbrs	string	Response data
data.attributes.serialNumber	string	Response data

Output Example

{"status_code":200,"response_headers":{},"reason":"OK","json_body":{"meta":{"num_bad_records":3,"totalCount":1},"data":[{}]}}

Remediation Details

Retrieve detailed message information from Cisco ESA's Mailbox Search and Remediate feature using batchID, endDate, and startDate.

Endpoint

URL: esa/api/v2.0/message-tracking/remediation-details

Method: GET

Input

Argument Name	Type	Required	Description
parameters.batchID	string	Required	Parameters for the Remediation Details action
parameters.endDate	string	Required	Parameters for the Remediation Details action
parameters.searchOption	string	Optional	Parameters for the Remediation Details action
parameters.startDate	string	Required	Parameters for the Remediation Details action

Input Example

{"parameters":{"batchID":"admin_1590646987","endDate":"2020-05-28T14:24:00.000Z","searchOption":"batch_details","startDate":"2020-05-26T00:00:00.000Z"}}

Output

Parameter	Type	Description
status_code	number	HTTP status code of the response
reason	string	Response reason phrase
batch_details	object	Output field: batch_details
batch_details.b_init_username	string	Name of the resource
batch_details.mor_action	string	Output field: batch_details.mor_action
batch_details.b_init_time	number	Time value
batch_details.batch_name	string	Name of the resource
batch_details.batch_desc	string	Output field: batch_details.batch_desc
batch_details.b_init_source	string	Output field: batch_details.b_init_source
message_details	array	Response message
message_details.delivered_at	number	Response message
message_details.mid	string	Unique identifier
message_details.from_email	string	Response message
message_details.recipient_email	string	Response message
message_details.mor_status	string	Status value
message_details.msg_read	string	Response message

Output Example

{"status_code":200,"response_headers":{},"reason":"OK","json_body":{"batch_details":{"b_init_username":"admin","mor_action":"Delete","b_init_time":1590646987,"batch_name":"Re7","batch_desc":"N/A","b_init_source":"ESA 117"},"message_details":[{"delivered_at":1584574165,"mid":"3","from_email":"[email protected]","recipient_email":"[email protected]","mor_status":"Success","msg_read":"0"},{"delivered_at":1584574165,"mid":"3","from_email":"[email protected]","recipient_email":"[email protected]","mor_st...

Retrieving All Incoming Messages

Retrieve all incoming messages matching a mail policy within a specified date range from Cisco ESA, with pagination support.

Endpoint

URL: esa/api/v2.0/message-tracking/messages

Method: GET

Input

Argument Name	Type	Required	Description
parameters.startDate	string	Required	Parameters for the Retrieving All Incoming Messages action
parameters.endDate	string	Required	Parameters for the Retrieving All Incoming Messages action
parameters.ciscoHost	string	Optional	Parameters for the Retrieving All Incoming Messages action
parameters.mailPolicyName	string	Optional	Parameters for the Retrieving All Incoming Messages action
parameters.mailPolicyDirection	string	Optional	Parameters for the Retrieving All Incoming Messages action
parameters.searchOption	string	Optional	Parameters for the Retrieving All Incoming Messages action
parameters.offset	number	Required	Parameters for the Retrieving All Incoming Messages action
parameters.limit	number	Required	Parameters for the Retrieving All Incoming Messages action

Input Example

{"parameters":{"startDate":"2021-03-01T18:30:00.000Z","endDate":"2021-03-02T12:11:00.000Z","ciscoHost":"All_Hosts","mailPolicyName":"Default","mailPolicyDirection":"inbound","searchOption":"messages","offset":0,"limit":100}}

Output

Parameter	Type	Description
status_code	number	HTTP status code of the response
reason	string	Response reason phrase
meta	object	Output field: meta
meta.num_bad_records	number	Output field: meta.num_bad_records
meta.totalCount	number	Count value
data	array	Response data
data.attributes	object	Response data
data.attributes.hostName	string	Response data
data.attributes.friendly_from	array	Response data
data.attributes.isCompleteData	string	Response data
data.attributes.messageStatus	object	Response data
data.attributes.messageStatus.2325234	string	Response data
data.attributes.recipientMap	object	Response data
data.attributes.recipientMap.2325232	array	Response data
data.attributes.recipientMap.2325234	array	Response data
data.attributes.senderIp	string	Response data
data.attributes.mailPolicy	array	Response data
data.attributes.senderGroup	string	Response data
data.attributes.subject	string	Response data
data.attributes.mid	array	Response data
data.attributes.senderDomain	string	Response data
data.attributes.finalSubject	object	Response data
data.attributes.finalSubject.2325234	string	Response data
data.attributes.direction	string	Response data
data.attributes.icid	number	Response data

Output Example

{"status_code":200,"response_headers":{},"reason":"OK","json_body":{"meta":{"num_bad_records":0,"totalCount":39},"data":[{}]}}

Retrieving All Outgoing Messages

Retrieve all outgoing messages matching a mail policy within a specified date range from Cisco ESA, with optional offset and limit for pagination.

Endpoint

URL: esa/api/v2.0/message-tracking/messages

Method: GET

Input

Argument Name	Type	Required	Description
parameters.startDate	string	Required	Parameters for the Retrieving All Outgoing Messages action
parameters.endDate	string	Required	Parameters for the Retrieving All Outgoing Messages action
parameters.ciscoHost	string	Optional	Parameters for the Retrieving All Outgoing Messages action
parameters.mailPolicyName	string	Optional	Parameters for the Retrieving All Outgoing Messages action
parameters.mailPolicyDirection	string	Optional	Parameters for the Retrieving All Outgoing Messages action
parameters.searchOption	string	Optional	Parameters for the Retrieving All Outgoing Messages action
parameters.offset	number	Required	Parameters for the Retrieving All Outgoing Messages action
parameters.limit	number	Required	Parameters for the Retrieving All Outgoing Messages action

Input Example

{"parameters":{"startDate":"2021-03-01T18:30:00.000Z","endDate":"2021-03-02T12:11:00.000Z","ciscoHost":"All_Hosts","mailPolicyName":"Default","mailPolicyDirection":"outbound","searchOption":"messages","offset":0,"limit":100}}

Output

Parameter	Type	Description
status_code	number	HTTP status code of the response
reason	string	Response reason phrase
meta	object	Output field: meta
meta.num_bad_records	number	Output field: meta.num_bad_records
meta.totalCount	number	Count value
data	array	Response data
data.attributes	object	Response data
data.attributes.hostName	string	Response data
data.attributes.friendly_from	array	Response data
data.attributes.isCompleteData	string	Response data
data.attributes.messageStatus	object	Response data
data.attributes.messageStatus.2325166	string	Response data
data.attributes.recipientMap	object	Response data
data.attributes.recipientMap.2325166	array	Response data
data.attributes.senderIp	string	Response data
data.attributes.mailPolicy	array	Response data
data.attributes.senderGroup	string	Response data
data.attributes.subject	string	Response data
data.attributes.mid	array	Response data
data.attributes.senderDomain	string	Response data
data.attributes.finalSubject	object	Response data
data.attributes.finalSubject.2325166	string	Response data
data.attributes.direction	string	Response data
data.attributes.icid	number	Response data
data.attributes.morDetails	object	Response data

Output Example

{"status_code":200,"response_headers":{},"reason":"OK","json_body":{"meta":{"num_bad_records":0,"totalCount":2},"data":[{}]}}

Searching for Messages

Locate messages by attributes in Cisco ESA within a specified date range and manage pagination using startDate, endDate, offset, and limit.

Endpoint

URL: /esa/api/v2.0/message-tracking/messages

Method: GET

Input

Argument Name	Type	Required	Description
parameters.startDate	string	Required	Parameters for the Searching for Messages action
parameters.endDate	string	Required	Parameters for the Searching for Messages action
parameters.ciscoHost	string	Optional	Parameters for the Searching for Messages action
parameters.searchOption	string	Optional	Parameters for the Searching for Messages action
parameters.offset	number	Required	Parameters for the Searching for Messages action
parameters.limit	number	Required	Parameters for the Searching for Messages action

Input Example

{"parameters":{"startDate":"2018-01-01T00:00:00.000Z","endDate":"2018-11-20T09:36:00.000Z","ciscoHost":"All_Hosts","searchOption":"messages","offset":0,"limit":20}}

Output

Parameter	Type	Description
status_code	number	HTTP status code of the response
reason	string	Response reason phrase
meta	object	Output field: meta
meta.num_bad_records	number	Output field: meta.num_bad_records
meta.totalCount	number	Count value
data	array	Response data
data.attributes	object	Response data
data.attributes.direction	string	Response data
data.attributes.icid	number	Response data
data.attributes.senderGroup	string	Response data
data.attributes.sender	string	Response data
data.attributes.replyTo	string	Response data
data.attributes.timestamp	string	Response data
data.attributes.hostName	string	Response data
data.attributes.subject	string	Response data
data.attributes.mid	array	Response data
data.attributes.isCompleteData	boolean	Response data
data.attributes.messageStatus	string	Response data
data.attributes.mailPolicy	array	Response data
data.attributes.senderIp	string	Response data
data.attributes.verdictChart	string	Response data
data.attributes.senderDomain	string	Response data
data.attributes.recipient	array	Response data
data.attributes.sbrs	string	Response data
data.attributes.serialNumber	string	Response data

Output Example

{"status_code":200,"response_headers":{},"reason":"OK","json_body":{"meta":{"num_bad_records":7,"totalCount":13},"data":[{}]}}

URL Details

Retrieve detailed URL information within Cisco ESA messages by specifying attributes such as endDate, icid, mid, and startDate.

Endpoint

URL: /esa/api/v2.0/message-tracking/url-details

Method: GET

Input

Argument Name	Type	Required	Description
parameters.endDate	string	Required	Parameters for the URL Details action
parameters.icid	number	Required	Parameters for the URL Details action
parameters.mid	number	Required	Parameters for the URL Details action
parameters.serialNumber	string	Optional	Parameters for the URL Details action
parameters.startDate	string	Required	Parameters for the URL Details action

Input Example

{"parameters":{"endDate":"2018-11-16T11:25:00.000Z","icid":19124,"mid":21981,"serialNumber":"64122536256E-FCH1812V1ST","startDate":"2018-11-09T00:00:00.000Z"}}

Output

Parameter	Type	Description
status_code	number	HTTP status code of the response
reason	string	Response reason phrase
data	object	Response data
data.messages	object	Response data
data.messages.direction	string	Response data
data.messages.smtpAuthId	string	Response data
data.messages.sdrAge	string	Response data
data.messages.sender	string	Response data
data.messages.midHeader	string	Response data
data.messages.urlDetails	array	Response data
data.messages.urlDetails.timestamp	string	Response data
data.messages.urlDetails.description	string	Response data
data.messages.sdrCategory	string	Response data
data.messages.hostName	string	Response data
data.messages.mid	array	Response data
data.messages.sendingHostSummary	object	Response data
data.messages.attachments	array	Response data
data.messages.attachments.file_name	string	Response data
data.messages.attachments.file	string	Response data
data.messages.sdrReputation	string	Response data
data.messages.showURLDetails	boolean	Response data
data.messages.senderGroup	string	Response data
data.messages.recipient	array	Response data
data.messages.subject	string	Response data

Output Example

{"status_code":200,"response_headers":{},"reason":"OK","json_body":{"data":{"messages":{}}}}

Response Headers

Header	Description	Example
Content-Type	The media type of the resource	application/json
Date	The date and time at which the message was originated	Thu, 01 Jan 2024 00:00:00 GMT