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 https //www cisco com/c/en/us/td/docs/security/esa/esa14 0/api/b esa api guide 14 0/b esa api guide chapter 010 html#id 66316 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" "kr\@mar esa com","recipient email" "krs\@onpremesa2019 com","mor status" "success","msg read" "0"},{"delivered at" 1584574165,"mid" "3","from email" "kr\@mar esa com","recipient email" "krc\@mar esa com","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