Cisco Email Security Appliance (ESA)

App Vendor: Cisco

Connector Category: Network Security| Email Gateway

App Version in Orchestrate: 2.0.0

API Version: v2.0

About App

Cisco ESA email security gateway appliance detects and blocks a wide variety of email-based threats, such as malware, spam, and phishing attempts.

In addition to the basic security capabilities of antivirus, antimalware, antiphishing, and antispam, Cisco ESA offers several advanced capabilities such as sandboxing for suspicious files, file reputation services, and file retrospection services. Cisco ESA also offers threat intelligence that is updated continuously to help detect the latest threats.

The Cisco ESA app built for the Orchestrate application helps security teams to perform email gateway security-related actions on the Cisco ESA application and enable security orchestration workflows. You can execute the following actions using the app.

Action Name	Description
Search Messages	This action searches messages on Cisco ESA.
Release Quarantine Messages	This action releases quarantined messages on Cisco ESA.
Modify Quarantine List Entries	This action modifies the list of quarantined entries on Cisco ESA.
Get List of Quarantine Entries	This action retrieves a list of quarantined entries.
Get Message Details	This action retrieves message details on Cisco ESA.
Get List of Rules	This action retrieves a list of Rules on Cisco ESA.
Get List of Quarantined Messages	This action retrieves a list of quarantined messages on Cisco ESA.
Delete Quarantined Messages	This action deletes quarantined messages on Cisco ESA.
Delete Quarantine List Entries	This action deletes quarantined list entries on Cisco ESA.
Multiple Report Counter	This action shows a query to retrieve multiple values of a specific counter from a counter group with the device type.
Single Report Counter	This action shows a query to retrieve the value of a specific counter from a counter group with the device type.
List Reports	This action retrieves the list of all the reports on Cisco ESA.
Rejected Messages	This action searches for rejected messages on Cisco ESA.
Download Quarantine Messages	This action downloads quarantined messages from Cisco ESA.
Retrieve Quarantine Messages	This action retrieves quarantined messages from Cisco ESA.
Get Message AMP Details	This action retrieves message AMP details from Cisco ESA.
Get Message DLP Details	This action retrieves message DLP details from Cisco ESA.
Get Message URL Details	This action retrieves message URL details from Cisco ESA.
Search Rule	This action is used to search for a Rule from Cisco ESA.

Configuration Parameters

The following configuration parameters are required for the Cisco ESA App to communicate with the Cisco ESA application. The parameters can be configured by creating instances in the app.

Parameter	Description	Field Type	Required/Optional
Base URL	Enter the base URL to access the Cisco ESA application. Example: https://<managemenet server>:<port>/	Text	Required
Username	Enter the username for the Cisco ESA application.	Text	Required
Password	Enter the password for your Cisco ESA application.	Password	Required

Parameter

Description

Field Type

Required/Optional

Comments

Base URL

Enter the base URL to access the Cisco ESA application.

Example:

https://<managemenet server>:<port>/

Text

Required

Username

Enter the username for the Cisco ESA application.

Text

Required

Password

Enter the password for your Cisco ESA application.

Password

Required

Delete Quarantined Messages

This action deletes quarantined messages on Cisco ESA.

Input Parameters

Parameter	Description	Field Type	Required/Optional	Comments
Message ID	Enter the message ID to delete from quarantine. Example: "1225"	Integer	Required
Quarantine Type	Specify the quarantine type for the message. Example: "Spam"	Text	Optional	Default value: Spam Other

Parameter

Description

Field Type

Required/Optional

Comments

Message ID

Enter the message ID to delete from quarantine.

Example:

"1225"

Integer

Required

Quarantine Type

Specify the quarantine type for the message.

Example:

"Spam"

Text

Optional

Default value:

Spam
Other

Example Request

{
    "message_id": "167"
}

Delete Quarantine List Entries

This action deletes quarantined list entries on Cisco ESA.

Input Parameters

Parameter	Description	Field Type	Required/Optional	Comments
Action Type	Specify the action type to delete the quarantine entry. Example: "append"	Text	Required	Allowed values: add edit append
Addresses	Enter the list of addresses to delete quarantine list entries.	List	Required
View By	Specify the preference to delete the quarantine list. Example: "sender"	Text	Optional	Allowed values: sender recipient
Quarantine Type	Specify the quarantine type for the message. list. Example: "Spam"	Text	Optional	Allowed value: Spam
List Type	Specify the list type for the quarantine entries. Example: "safe"	Text	Optional	Allowed values: safe block Default value: block

Example Request

{
    "action_type": "append",
    "addresses": ['sampleuser@exampledomain.com']
}

Download Quarantine Messages

This action downloads quarantined messages from Cisco ESA.

Input Parameters

Parameter	Description	Field Type	Required/Optional	Comments
Message ID	Enter the unique message ID for the message. Example: "1245"	Integer	Required
Attachment ID	Specify the attachment ID to download the message. Example: "2"	Text	Required
Quarantine Type	Specify the quarantine type to download the message. Example: "pvo"	Text	Optional	Default value: pvo Accepted value: pvo

Parameter

Description

Field Type

Required/Optional

Comments

Message ID

Enter the unique message ID for the message.

Example:

"1245"

Integer

Required

Attachment ID

Specify the attachment ID to download the message.

Example:

"2"

Text

Required

Quarantine Type

Specify the quarantine type to download the message.

Example:

"pvo"

Text

Optional

Default value:

Accepted value:

Example Request

{
    "message_id": "1245",
    "attachment_id":  "2"
}

Get List of Quarantined Messages

This action retrieves a list of quarantined messages on Cisco ESA.

Input Parameters

Parameter	Description	Field Type	Required/Optional	Comments
Start Date	Specify the start date time to retrieve messages. Example: "2020-08-23 02:12:00"	Text	Required	Date Time Format: "YYYY-MM-DD hh:mm:ss" Note: Seconds must be 00 due to API limitation.
End Date	Specify the end date time to retrieve messages. Example: "2021-08-23 02:12:00"	Text	Required	Date Time Format: "YYYY-MM-DD hh:mm:ss" Note: Seconds must be 00 due to API limitation.
Order By	Specify the order for the quarantine messages. Example: "sender"	Text	Optional	Accepted values: sender recipient
Filter Operator	Specify the filter operator to get the list of messages. Example: "begins_with"	Text	Optional	Accepted values: contains is begins_with ends_with does_not_contain
Filter Value	Enter the filter value. Example: "abc.com"	Text	Optional
Quarantine Type	Specify the quarantine type for the quarantine messages. Example: "spam"	Text	Optional	Accepted value: spam
Order Dir	Specify the order direction for the quarantine messages. Example: "asc"	Text	Optional	Accepted values: asc desc
Offset	Specify the offset value to retrieve a subset of records starting with the quarantine messages. Example: "3"	Integer	Optional	Default value: 0 Note: Offest works with limit.
Limit	Specify the limit for the list of messages. Example: "8"	Integer	Optional	Default value: 25
Recipient Filter	Specify the recipient filter. Example: "contains"	Text	Optional	Accepted value: contains is begins_with ends_with does_not_contain
Recipient Value	Specify the recipient value.	Text	Optional
Extra Params	Enter any extra parameters to get the list of messages.	Key-Value	Optional

Example Request

{
    "start_date": "2020-08-23 02:12:00",
    "end_date":  "2021-08-23 02:12:00"
}

Get List of Quarantine Entries

This action retrieves a list of quarantined entries.

Input Parameters

Parameter	Description	Field Type	Required/Optional	Comments
List Type	Specify the list type for the quarantine entries. Example: "safe"	Text	Optional	Accepted values: safe block Default value: block
Action	Specify the action for the quarantine entries. Example: "view"	Text	Optional	Accepted value: view
Quarantine Type	Specify the quarantine type for the quarantine entries. Example: "spam"	Text	Optional	Accepted value: spam
View By	Specify the view preference for the quarantine entries. Example: "sender"	Text	Optional	Accepted values: sender recipient
Order Dir	Specify the order direction for the quarantine entries. Example: "asc"	Text	Optional	Accepted values: asc desc
Order By	Specify the order for the quarantine entries. Example: "sender"	Text	Optional	Accepted values: sender recipient
Offset	Specify the offset value to retrieve a subset of records starting with the quarantine entries. Example: "3"	Integer	Optional	Default value: 0 Note: Offset works with limit.
Limit	Specify the limit for the list of entries. Example: "8"	Integer	Optional	Default value: 25
Search	Enter the search value. Example: "recipient"	Text	Optional	Note: This value is accepted only for orderBy=recipient parameter and value.
Extra Params	Specify any extra parameters required to retrieve the list of quarantine entries.	Key-Value	Optional

Example Request

{
    "list_type": "safe",
    "action": "view",
    "quarantine_type": "spam"
}

Get List of Rules

This action retrieves a list of rules on Cisco ESA.

Input Parameters

Parameter	Description	Field Type	Required/Optional	Comments
Quarantine Type	Specify the quarantine type for the list of rules. Example: "spam"	Text	Optional	Accepted value: spam other

Parameter

Description

Field Type

Required/Optional

Comments

Quarantine Type

Specify the quarantine type for the list of rules.

Example:

"spam"

Text

Optional

Accepted value:

spam
other

Example Request

{
    "quarantine_type": "spam"
}

Get Message AMP Details

This action retrieves message Advanced Malware Protection (AMP) details from Cisco ESA.

Input Parameters

Parameter	Description	Field Type	Required/Optional
Message ID	Enter the unique ID for the message. Example: "22124"	Integer	Required
ICID	Enter the Injection Connection ID for the message. Example: "40"	Integer	Required
Serial Number	Specify the serial number for the message. Example: "641xxx362xxE-FCxxxxxxV1ST"	Text	Optional
Start Date	Specify the start date time to retrieve messages. Example: "2020-08-23 02:12:00"	Text	Required
End Date	Specify the start date time to retrieve messages. Example: "2021-08-23 02:12:00"	Text	Required
Extra Params	Enter any extra parameters required to get message AMP details.	Key-Value	Optional

Example Request

{
    "message_id": "1225",
    "icid": "40",
    "start_date": "2020-08-23 02:12:00",
    "end_date":  "2021-08-23 02:12:00"
}

Get Message Details

This action retrieves message details on Cisco ESA.

Input Parameters

Parameter	Description	Field Type	Required/Optional	Comments
Message ID	Enter the message ID to release from quarantine. Example: "1225"	Integer	Required
Serial Number	Specify the serial number for the message. Example: "64x22xxxxx6E-FCH18xxxST"	Text	Optional
Start Date	Specify the start date time to search for messages. Example: "2020-08-23 02:12:00"	Text	Optional	Date Time Format: "YYYY-MM-DD hh:mm:ss"
End Date	Specify the end date time to search for messages. Example: "2021-08-23 02:12:00"	Text	Optional	Date Time Format: "YYYY-MM-DD hh:mm:ss"
Extra Params	Specify any extra parameters that you want to include in the search.	Key-Value	Optional

Example Request

{
    "message_id": "1225",
    "start_date": "2020-08-23 02:12:00",
    "end_date":  "2021-08-23 02:12:00"
}

Get Message DLP Details

This action retrieves message Data Loss Prevention (DLP) details from Cisco ESA.

Input Parameters

Parameter	Description	Field Type	Required/Optional
Message ID	Enter the unique message ID to get message DLP details. Example: "22125"	Integer	Required
ICID	Enter the Injection Connection ID for the message. Example: "40"	Integer	Required
Serial Number	Specify the serial number for the message. Example: "641xxx362xxE-FCxxxxxxV1ST"	Text	Optional
Start Date	Specify the start date time to retrieve messages. Example: "2020-08-23 02:12:00"	Text	Required
End Date	Specify the start date time to retrieve messages. Example: "2021-08-23 02:12:00"	Text	Required
Extra Params	Enter the extra parameters to get message details.	Key-Value	Optional

Example Request

{
    "message_id": "1225",
    "icid": "40",
    "start_date": "2020-08-23 02:12:00",
    "end_date":  "2021-08-23 02:12:00"
}

Get Message URL Details

This action retrieves message URL details from Cisco ESA.

Input Parameters

Parameter	Description	Field Type	Required/Optional
Message ID	Enter the unique ID for the message. Example: "22124"	Integer	Required
ICID	Enter the Injection Connection ID for the message. Example: "40"	Integer	Required
Serial Number	Enter the serial number for the message. Example: "641xxx362xxE-FCxxxxxxV1ST"	Text	Optional
Start Date	Specify the start date time to retrieve messages. Example: "2020-08-23 02:12:00"	Text	Required
End Date	Specify the end date time to retrieve messages. Example: "2021-08-23 02:12:00"	Text	Required
Extra Parameters	Enter any extra parameters required to get message AMP details.	Key-Value	Optional

Example Request

{
    "message_id": "1225",
    "icid": "40",
    "start_date": "2020-08-23 02:12:00",
    "end_date":  "2021-08-23 02:12:00"
}

List Reports

This action retrieves the list of all the reports on Cisco ESA.

Input Parameters

Parameter	Description	Field Type	Required/Optional	Comments
Start Date	Specify the start date time to retrieve reports. Example: "2020-08-23 02:12:00"	Text	Required	Date Time Format: "YYYY-MM-DD hh:mm:ss" Note: Seconds must be 00 due to API limitation.
End Date	Specify the end date time to retrieve reports. Example: "2021-08-23 02:12:00"	Text	Required	Date Time Format: "YYYY-MM-DD hh:mm:ss" Note: Seconds must be 00 due to API limitation.
Order By	Specify the order for the reports. Example: "sender"	Text	Optional	Allowed values: sender recipient
Order Dir	Specify the order for the report. Example: "asc"	Text	Optional	Allowed values: asc desc
Filter Operator	Specify the filter operator to get the list of reports. Example: "begins_with"	Text	Optional	Allowed values: contains is begins_with ends_with does_not_contain
Filter Value	Enter the filter value. Example: "abc.com"	Text	Optional
Filter By	Enter the data to be retrieved according to the filter property and value. Example: "starts_with"	Text	Optional	Allowed values: starts_with ends_with matches_exactly does_not_contain does_not_start_with does_not_end_with does_not_match
Device Group Name	Specify the device group name to filter results. Example: "Business Critical Devices"	Text	Optional
Device Type	Specify the device type to filter results. Example: "esa"	Text	Optional	Allowed value: esa
Device Name	Specify the name of the device to filter results. Example: "Example Device Name"	Text	Optional
Limit	Enter the number of report entries to retrieve. Example: "8"	Integer	Optional	Default value: 10
Extra Params	Enter any extra parameters required to retrieve the reports.	Key-Value	Optional

Example Request

{
    "start_date": "2020-08-23 02:12:00",
    "end_date":  "2021-08-23 02:12:00"
}

Modify Quarantine List Entries

This action modifies the list of quarantined entries on Cisco ESA.

Input Parameters

Parameter	Description	Field Type	Required/Optional	Comments
Action Type	Specify the action type for the quarantine list entries. Example: "edit"	Text	Required	Supported values: add edit append
Sender Addresses	Specify the sender addresses for the quarantine list entries. Example: "sender@exampledomain.com"	Text	Required
Recipient Addresses	Specify the recipient addresses for the quarantine list entries. Example: "recipient@exampledomain.com"	Text	Required
View By	Specify the view by value to view quarantine list entries. Example: "sender"	Text	Optional	Supported values: sender recipient
Quarantine Type	Specify the quarantine type for the quarantine list entries. Example: "Spam"	Text	Optional	Allowed value: Spam
List Type	Specify the list type for the quarantine list entries. Example: "block"	Text	Optional	Allowed values: safe block Default value: block

Example Request

{
    "action_type": "add",
    "sender_addresses": "sender@exampledomain.com",
    "recipient_addresses": "recipient@exampledomain.com"
}

Multiple Report Counter

This action shows a query to retrieve multiple values of a specific counter from a counter group with the device type.

Input Parameters

Parameter	Description	Field Type	Required/Optional	Comments
Start Date	Specify the start date time to retrieve values. Example: "2020-08-23 02:12:00"	Text	Required	Date Time Format: "YYYY-MM-DD hh:mm:ss" Note: Seconds must be 00 due to API limitation.
End Date	Specify the end date time to retrieve values. Example: "2021-08-23 02:12:00"	Text	Required	Date Time Format: "YYYY-MM-DD hh:mm:ss" Note: Seconds must be 00 due to API limitation.
Device Type	Enter the device type to retrieve multiple values of a counter. Example: "esa"	Text	Required	Allowed value: esa
Extra Params	Enter any extra parameters that you want to include to retrieve values.	Key-Value	Optional

Example Request

{
    "start_date": "2020-08-23 02:12:00",
    "end_date":  "2021-08-23 02:12:00",
    "device_type": "esa"
}

Rejected Messages

This action searches for rejected messages on Cisco ESA.

Input Parameters

Parameter	Description	Field Type	Required/Optional	Comments
Sender IP	Enter the sender's IP address for the message. Example: "1.1.1.1"	Text	Optional
Start Date	Specify the start date time to retrieve messages. Example: "2020-08-23 02:12:00"	Text	Required
End Date	Specify the end date time to retrieve messages. Example: "2021-08-23 02:12:00"	Text	Required
Search Option	Enter the search option to retrieve messages. Example: "rejected_connections"	Text	Optional	Allowed value: rejected_connections
Offset	Specify the offset value to retrieve a subset of messages. Example: "3"	Integer	Optional	Default value: 0 Note: Offest works with limit.
Limit	Specify the limit for the list of messages. Example: "8"	Integer	Optional	Default value: 25
Extra Params	Enter any extra parameters to get the messages.	Key-Value	Optional

Example Request

{
    "start_date": "2020-08-23 02:12:00",
    "end_date":  "2021-08-23 02:12:00"
}

Release Quarantine Messages

This action releases quarantined messages on Cisco ESA.

Input Parameters

Parameter	Description	Field Type	Required/Optional	Comments
Message ID	Enter the list of message IDs to release from quarantine. Example: [167, 168, 169]	List	Required
Quarantine Type	Specify the quarantine type for the message. Example: "Spam"	Text	Optional	Allowed value: Spam
Quarantine Name	Specify the quarantine name for the message. Example: "Outbreak"	Text	Optional	Allowed values: Outbreak Virus File+Analysed Unclassified Policy Default value: Outbreak

Parameter

Description

Field Type

Required/Optional

Comments

Message ID

Enter the list of message IDs to release from quarantine.

Example:

[167, 168, 169]

List

Required

Quarantine Type

Specify the quarantine type for the message.

Example:

"Spam"

Text

Optional

Allowed value:

Spam

Quarantine Name

Specify the quarantine name for the message.

Example:

"Outbreak"

Text

Optional

Allowed values:

Outbreak
Virus
File+Analysed
Unclassified
Policy

Default value:

Outbreak

Example Request

{
    "message_id": [167, 168, 169]
}

Retrieve Quarantine Messages

This action retrieves quarantined messages from Cisco ESA.

Input Parameters

Parameter	Description	Field Type	Required/Optional	Comments
Message ID	Enter the unique message ID to retrieve the message. Example: "5634"	Integer	Required
Quarantine Type	Specify the quarantine type to retrieve the messages. Example: "Spam"	Text	Optional

Parameter

Description

Field Type

Required/Optional

Comments

Message ID

Enter the unique message ID to retrieve the message.

Example:

"5634"

Integer

Required

Quarantine Type

Specify the quarantine type to retrieve the messages.

Example:

"Spam"

Text

Optional

Example Request

{
    "message_id": "1225"
}

Search Messages

This action searches messages on Cisco ESA.

Input Parameters

Parameter	Desceription	Field Type	Required/Optional	Comments
Start Date	Specify the start date time to search for messages. Example: "2020-08-23 02:12:00"	Text	Required	Date Time Format: "YYYY-MM-DD hh:mm:ss" Note: Seconds must be 00 due to API limitation.
End Date	Specify the end date time to search for messages. Example: "2021-08-23 02:12:00"	Text	Required	Date Time Format: "YYYY-MM-DD hh:mm:ss" Note: Seconds must be 00 due to API limitation.
Cisco Host	Specify the hostname to search for messages. Example: "esa.cisco.com:6080"	Text	Optional	Default value: All Host
Search Option	Specify the search option value to search for rejected connections. Example: "rejected_connections"	Text	Optional	Default value: messages
Offset	Specify an offset value to retrieve a subset of records starting with the offset value. Example: 3	Integer	Optional	Default value: 0 Note: Offset works with limit.
Limit	Specify the number of records to retrieve. Example: 8	Integer	Optional	Default value: 20
Extra Params	Specify any extra parameters that you want to include in the search.	Key-value	Optional	Supported Extra Parameters: quarantineType orderBy orderDir envelopeRecipientFilterOperator envelopeRecipientFilterValue filterOperator filterValue

Example Request

{
    "start_date": "2020-08-23 02:12:00",
    "end_date":  "2021-08-23 02:12:00"
}

Search Rule

This action is used to search for a rule from Cisco ESA.

Input Parameters

Parameter	Description	Field Type	Required/Optional	Comments
Rule ID	Enter the unique ID for the Rule to search. Example: "Malware: Malware"	Text	Required
Quarantine Type	Specify the quarantine type for the rule. Example: "pvo"	Text	Optional	Allowed value: pvo Default value: pvo
Order By	Specify the order for search results. Example: "received"	Text	Optional	Allowed value: received
Order Dir	Specify the order direction for the search results. Example: "asc"	Text	Optional	Allowed value: asc desc Default value: asc
Offset	Specify an offset value to retrieve a subset of records starting with the offset value. Example: "3"	Integer	Optional	Default value: 0 Note: Offset works with limit.
Limit	Specify the number of records to retrieve. Example: "8"	Integer	Optional	Default value: 25
Extra Parameters	Enter the extra parameters required to search rules.	Key-Value	Optional

Example Request

{
    "rule_id": "Malware: Malware"
}

Single Report Counter

This action shows a query to retrieve the value of a specific counter from a counter group with the device type.

Input Parameters

Parameter

Description

Field Type

Required/Optional

Comments

Start Date

Specify the start date time to retrieve values.

Example:

"2020-08-23 02:12:00"

Text

Required

Date Time Format:

"YYYY-MM-DD hh:mm:ss"

Note: Seconds must be 00 due to API limitation.

End Date

Specify the end date time to retrieve values.

Example:

"2021-08-23 02:12:00"

Text

Required

Date Time Format:

"YYYY-MM-DD hh:mm:ss"

Note: Seconds must be 00 due to API limitation.

Extra Params

Enter any extra parameters to retrieve the values of a counter.

Key-Value

Optional

Example Request

{
    "start_date": "2020-08-23 02:12:00",
    "end_date":  "2021-08-23 02:12:00"
}

Cyware Orchestrate

Cisco Email Security Appliance (ESA)

About App

Configuration Parameters

Delete Quarantined Messages

Input Parameters

Example Request

Delete Quarantine List Entries

Input Parameters

Example Request

Download Quarantine Messages

Input Parameters

Example Request

Get List of Quarantined Messages

Input Parameters

Example Request

Get List of Quarantine Entries

Input Parameters

Example Request

Get List of Rules

Input Parameters

Example Request

Get Message AMP Details

Input Parameters

Example Request

Get Message Details

Input Parameters

Example Request

Get Message DLP Details

Input Parameters

Example Request

Get Message URL Details

Input Parameters

Example Request

List Reports

Input Parameters

Example Request

Modify Quarantine List Entries

Input Parameters

Example Request

Multiple Report Counter

Input Parameters

Example Request

Rejected Messages

Input Parameters

Example Request

Release Quarantine Messages

Input Parameters

Example Request

Retrieve Quarantine Messages

Input Parameters

Example Request

Search Messages

Input Parameters

Example Request

Search Rule

Input Parameters

Example Request

Single Report Counter

Input Parameters

Example Request

Search results