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 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 enddate string required date value icid number required unique identifier mid number required unique identifier serialnumber string optional parameter for amp details startdate string required date value output parameter type description status code number http status code of the response reason string response reason phrase data object response data messages object response message showampdetails boolean output field showampdetails direction string output field direction smtpauthid string unique identifier sender string output field sender midheader string unique identifier timestamp string output field timestamp hostname string name of the resource mid array unique identifier sendinghostsummary object output field sendinghostsummary attachments array output field attachments messagesize string response message ampdetails array output field ampdetails timestamp string output field timestamp description string output field description lastevent boolean output field lastevent sendergroup string output field sendergroup recipient array output field recipient subject string output field subject example \[ { "status code" 200, "response headers" {}, "reason" "ok", "json body" { "data" {} } } ] 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 enddate string required date value icid number required unique identifier mid number required unique identifier serialnumber string optional parameter for connection details startdate string required date value 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 summary array output field summary timestamp string output field timestamp description string output field description lastevent boolean output field lastevent sbrs string output field sbrs example \[ { "status code" 200, "response headers" {}, "reason" "ok", "json body" { "sendergroup" "relaylist", "messages" {}, "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 enddate string required date value icid number required unique identifier mid number required unique identifier serialnumber string optional parameter for dlp details startdate string required date value output parameter type description status code number http status code of the response reason string response reason phrase data object response data messages object response message direction string output field direction smtpauthid string unique identifier sender string output field sender midheader string unique identifier timestamp string output field timestamp hostname string name of the resource mid array unique identifier sendinghostsummary object output field sendinghostsummary attachments array output field attachments messagesize string response message dlpdetails object output field dlpdetails violationseverity string output field violationseverity dlpmatchedcontent array response content messagepartmatch array response message messagepart string response message mid string unique identifier riskfactor number output field riskfactor dlppolicy string output field dlppolicy showdlpdetails boolean output field showdlpdetails sendergroup string output field sendergroup recipient array output field recipient example \[ { "status code" 200, "response headers" {}, "reason" "ok", "json body" { "data" {} } } ] 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 enddate string required date value icid number required unique identifier mid number required unique identifier serialnumber string optional parameter for message details startdate string required date value output parameter type description status code number http status code of the response reason string response reason phrase data object response data messages object response message direction string output field direction smtpauthid string unique identifier sender string output field sender midheader string unique identifier timestamp string output field timestamp showamp boolean output field showamp hostname string name of the resource mid array unique identifier sendinghostsummary object output field sendinghostsummary reversednshostname string name of the resource ipaddress string output field ipaddress sbrsscore string score value summary array output field summary timestamp string output field timestamp description string output field description lastevent boolean output field lastevent attachments array output field attachments messagesize string response message iscompletedata boolean response data showdlp boolean output field showdlp messagestatus string status value example \[ { "status code" 200, "response headers" {}, "reason" "ok", "json body" { "data" {} } } ] 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 startdate string required date value enddate string required date value senderip string optional parameter for rejected connections searchoption string optional parameter for rejected connections offset number required parameter for rejected connections limit number required parameter for rejected connections output parameter type description status code number http status code of the response reason string response reason phrase meta object output field meta num bad records number output field num bad records totalcount number count value data array response data attributes object output field attributes icid number unique identifier timestamp string output field timestamp hostname string name of the resource rejected string output field rejected messagestatus string status value senderip string output field senderip sendergroup string output field sendergroup sbrs string output field sbrs serialnumber string output field serialnumber example \[ { "status code" 200, "response headers" {}, "reason" "ok", "json body" { "meta" {}, "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 batchid string required unique identifier enddate string required date value searchoption string optional parameter for remediation details startdate string required date value 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 b init username string name of the resource mor action string output field mor action b init time number time value batch name string name of the resource batch desc string output field batch desc b init source string output field b init source message details array response message delivered at number output field delivered at mid string unique identifier from email string output field from email recipient email string output field recipient email mor status string status value msg read string output field msg read example \[ { "status code" 200, "response headers" {}, "reason" "ok", "json body" { "batch details" {}, "message details" \[] } } ] 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 startdate string required date value enddate string required date value ciscohost string optional parameter for retrieving all incoming messages mailpolicyname string optional name of the resource mailpolicydirection string optional parameter for retrieving all incoming messages searchoption string optional parameter for retrieving all incoming messages offset number required parameter for retrieving all incoming messages limit number required parameter for retrieving all incoming messages output parameter type description status code number http status code of the response reason string response reason phrase meta object output field meta num bad records number output field num bad records totalcount number count value data array response data attributes object output field attributes hostname string name of the resource friendly from array output field friendly from iscompletedata string response data messagestatus object status value 2325234 string output field 2325234 recipientmap object output field recipientmap 2325232 array output field 2325232 2325234 array output field 2325234 senderip string output field senderip mailpolicy array output field mailpolicy sendergroup string output field sendergroup subject string output field subject mid array unique identifier senderdomain string output field senderdomain finalsubject object output field finalsubject 2325234 string output field 2325234 direction string output field direction icid number unique identifier example \[ { "status code" 200, "response headers" {}, "reason" "ok", "json body" { "meta" {}, "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 startdate string required date value enddate string required date value ciscohost string optional parameter for retrieving all outgoing messages mailpolicyname string optional name of the resource mailpolicydirection string optional parameter for retrieving all outgoing messages searchoption string optional parameter for retrieving all outgoing messages offset number required parameter for retrieving all outgoing messages limit number required parameter for retrieving all outgoing messages output parameter type description status code number http status code of the response reason string response reason phrase meta object output field meta num bad records number output field num bad records totalcount number count value data array response data attributes object output field attributes hostname string name of the resource friendly from array output field friendly from iscompletedata string response data messagestatus object status value 2325166 string output field 2325166 recipientmap object output field recipientmap 2325166 array output field 2325166 senderip string output field senderip mailpolicy array output field mailpolicy sendergroup string output field sendergroup subject string output field subject mid array unique identifier senderdomain string output field senderdomain finalsubject object output field finalsubject 2325166 string output field 2325166 direction string output field direction icid number unique identifier mordetails object output field mordetails example \[ { "status code" 200, "response headers" {}, "reason" "ok", "json body" { "meta" {}, "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 startdate string required date value enddate string required date value ciscohost string optional parameter for searching for messages searchoption string optional parameter for searching for messages offset number required parameter for searching for messages limit number required parameter for searching for messages output parameter type description status code number http status code of the response reason string response reason phrase meta object output field meta num bad records number output field num bad records totalcount number count value data array response data attributes object output field attributes direction string output field direction icid number unique identifier sendergroup string output field sendergroup sender string output field sender replyto string output field replyto timestamp string output field timestamp hostname string name of the resource subject string output field subject mid array unique identifier iscompletedata boolean response data messagestatus string status value mailpolicy array output field mailpolicy senderip string output field senderip verdictchart string output field verdictchart senderdomain string output field senderdomain recipient array output field recipient sbrs string output field sbrs serialnumber string output field serialnumber example \[ { "status code" 200, "response headers" {}, "reason" "ok", "json body" { "meta" {}, "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 enddate string required date value icid number required unique identifier mid number required unique identifier serialnumber string optional parameter for url details startdate string required date value output parameter type description status code number http status code of the response reason string response reason phrase data object response data messages object response message direction string output field direction smtpauthid string unique identifier sdrage string output field sdrage sender string output field sender midheader string unique identifier urldetails array url endpoint for the request timestamp string output field timestamp description string output field description sdrcategory string output field sdrcategory hostname string name of the resource mid array unique identifier sendinghostsummary object output field sendinghostsummary attachments array output field attachments file name string name of the resource file string output field file sdrreputation string output field sdrreputation showurldetails boolean url endpoint for the request sendergroup string output field sendergroup recipient array output field recipient subject string output field subject example \[ { "status code" 200, "response headers" {}, "reason" "ok", "json body" { "data" {} } } ] notes api documentation 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