ProofPoint Threat Response

this connector integrates threat response with swimlane turbine it provides functionality and supports customizations and custom integrations prerequisites to utilize the proofpoint threat response connector within swimlane turbine, ensure you have the following prerequisites api key authentication with the following parameters url endpoint for the proofpoint threat response api api token unique identifier used to authenticate requests to the proofpoint api capabilities this connector provides the following capabilities add member to list add incident comments add user to incident block urls, domains, hashes, or ips close incident close multiple incidents delete member of list get alert details get all list members get incident details get incidents get investigation details get single list member ingest an alert update incident description and so on update incident description setting "overwrite" to false will append the specified description to the existing value in the incident setting "overwrite" to true will overwrite the specified description over the existing value in the incident ingest alert overview the proofpoint threat response connector enables automated interactions with the proofpoint platform, facilitating incident management and response activities proofpoint threat response is a robust threat management platform that enables security teams to efficiently manage incidents and automate responses this connector allows swimlane turbine users to integrate with proofpoint to add comments to incidents, manage lists and members, block malicious indicators, and retrieve detailed threat intelligence by leveraging this integration, users can streamline their security operations, enhance incident response times, and enforce proactive threat mitigation within their environment inputs input example email attachments \[{"content type" "jpeg", "date" "2014 01 01t10 11 12z ", "md5" "somemd5sumhere", "name" "attachment1 atch", "sha256" "somesha256here", "size" 567}] classification supported classifications malware policy violation vulnerability network spam phish command and control data match authentication system behavior impostor reported abuse unknown cnc hosts \[ { "host" "cnc1 com", "port" 443 }, { "host" "cnc2 com", "port" 22 } ] forensics hosts \['{"host" "forensics1 com","port" 80}', '{"host" "forensics2 com","port" 443}'] link attribute supported attributes for linking target ip address target hostname target machine name target user target mac address attacker ip address attacker hostname attacker machine name attacker user attacker mac address email recipient email sender email subject message id threat filename threat filehash severity supported values info minor moderate major critical informational low medium high critical custom fields { "custom field 1" "custom value string 1", "custom field 2" "custom value string 2", "custom field 3" "custom value string 3", "custom field 4" "custom value string 4", "custom field 5" "custom value string 5", "custom field 6" "custom value string 6" } api documentation for more information, click here https //ptr docs proofpoint com/extensibility guides/ptr api/# configurations api key authentication authenticates using an api key configuration parameters parameter description type required url a url to the target host string required authorization api token string required verify ssl verify ssl certificate boolean optional http proxy a proxy to route requests through string optional actions add incident comments add a user defined comment to an existing incident in proofpoint threat response using the specified incident id and summary endpoint url /api/incidents/{{incident id}}/comments json method post input argument name type required description incident id number required unique identifier summary string required parameter for add incident comments detail string optional parameter for add incident comments output parameter type description status code number http status code of the response reason string response reason phrase id number unique identifier incident id number unique identifier response id object unique identifier user id object unique identifier history type string type of the resource state from string output field state from state to string output field state to summary string output field summary detail string output field detail created at string output field created at updated at string output field updated at example \[ { "status code" 200, "response headers" { "content length" "140", "content type" "application/json", "date" "wed, 23 aug 2023 20 37 23 gmt" }, "reason" "ok", "json body" { "id" 56, "incident id" 16, "response id" null, "user id" null, "history type" "comment", "state from" "none", "state to" "none", "summary" "comments here", "detail" "details here", "created at" "2017 01 17t20 58 38z", "updated at" "2017 01 17t20 58 38z" } } ] add member to list adds a specified member to a designated list in proofpoint threat response by using the provided list id endpoint url /api/lists/{{list id}}/members json method post input argument name type required description list id number required unique identifier member string required parameter for add member to list description string optional parameter for add member to list expiration string optional timestamp to expire member format 2017 01 11t03 47 15z duration string optional (#) of milliseconds after which to expire membership expiration takes precedence output parameter type description status code number http status code of the response reason string response reason phrase id number unique identifier list id number unique identifier host id number unique identifier response id object unique identifier reverse user id object unique identifier hash reputation id object unique identifier user id object unique identifier enabled boolean output field enabled deleted boolean output field deleted description string output field description expiration string output field expiration created at string output field created at updated at string output field updated at host object output field host created at string output field created at host string output field host id number unique identifier resolution state number output field resolution state ttl number output field ttl updated at string output field updated at example \[ { "status code" 200, "response headers" { "content length" "140", "content type" "application/json", "date" "wed, 23 aug 2023 20 37 23 gmt" }, "reason" "ok", "json body" { "id" 8, "list id" 2, "host id" 20, "response id" null, "reverse user id" null, "hash reputation id" null, "user id" null, "enabled" true, "deleted" false, "description" "ip to block", "expiration" "2018 12 18t19 08 56z", "created at" "2017 01 11t03 47 15z", "updated at" "2017 01 11t03 47 15z", "host" {} } } ] add user to incident adds specified users as targets or attackers to an existing incident in proofpoint threat response using the provided incident id endpoint url /api/incidents/{{incident id}}/users json method post input argument name type required description incident id number required unique identifier targets array required parameter for add user to incident attackers array required parameter for add user to incident output parameter type description status code number http status code of the response reason string response reason phrase example \[ { "status code" 200, "response headers" { "content length" "140", "content type" "application/json", "date" "wed, 23 aug 2023 20 37 23 gmt" }, "reason" "ok", "json body" {} } ] block urls, domains, hashes, or ips blocks urls, domains, hashes, or ip addresses in proofpoint threat response by utilizing a specified list id and blacklist elements endpoint url /api/lists/{{list id}}/members json method post input argument name type required description list id number required unique identifier blacklist elements array required parameter for block urls, domains, hashes, or ips expiration string optional parameter for block urls, domains, hashes, or ips output parameter type description status code number http status code of the response reason string response reason phrase host host string output field host host host id array unique identifier host created at string output field host created at expiration string output field expiration hash reputation id string unique identifier list id number unique identifier raw json object output field raw json updated at string output field updated at enabled boolean output field enabled host ttl number output field host ttl description string output field description created at string output field created at user id string unique identifier host resolution state number output field host resolution state id number unique identifier reverse user id string unique identifier deleted boolean output field deleted host updated at string output field host updated at response id string unique identifier example \[ { "status code" 200, "response headers" { "content length" "140", "content type" "application/json", "date" "wed, 23 aug 2023 20 37 23 gmt" }, "reason" "ok", "json body" { "host host" "host", "host id" \[], "host created at" "2017 12 18 18 59 51 545783", "expiration" "2018 12 18 18 59 51 545783", "hash reputation id" "hash reputation id", "list id" 3, "raw json" {}, "updated at" "2018 12 18 18 59 51 545783", "enabled" true, "host ttl" 13, "description" "description", "created at" "2018 12 18 18 59 51 545783", "user id" "1", "host resolution state" 5, "id" 7 } } ] close incident closes an incident in proofpoint threat response by using the unique incident id and includes a summary with detailed explanation endpoint url /api/incidents/{{incident id}}/close json method post input argument name type required description incident id number required unique identifier summary string required parameter for close incident detail string required parameter for close incident output parameter type description status code number http status code of the response reason string response reason phrase example \[ { "status code" 200, "response headers" { "content length" "140", "content type" "application/json", "date" "wed, 23 aug 2023 20 37 23 gmt" }, "reason" "ok", "json body" {} } ] close multiple incidents closes multiple incidents in proofpoint threat response using specified ids and a creation date range endpoint url /api/incidents/close json method post input argument name type required description incidentids string required this should be a comma separated list of incidents ids created after string required created after cannot be a greater date than created before accepted format is yyyy mm dd created before string required created before must be a lesser date than created after accepted format is yyyy mm dd close summary string optional this optional parameter allows for a closing summary to be placed into each closed incident close detail string optional this optional parameter allows for a closing details to be placed into each closed incident output parameter type description status code number http status code of the response reason string response reason phrase status string status value example \[ { "status code" 200, "response headers" {}, "reason" "ok", "json body" { "status" "incidents closed " } } ] delete member of list removes a specific member from a designated list in proofpoint threat response using unique list and member identifiers endpoint url /api/lists/{{list id}}/members/{{member id}} json method delete input argument name type required description list id number required unique identifier member id number required unique identifier output parameter type description status code number http status code of the response reason string response reason phrase example \[ { "status code" 200, "response headers" { "content length" "140", "content type" "application/json", "date" "wed, 23 aug 2023 20 37 23 gmt" }, "reason" "ok", "json body" {} } ] get alert details retrieve detailed information for a specific alert in proofpoint threat response using the provided alert id endpoint url /api/v1/alerts method get input argument name type required description id number required unique identifier output parameter type description status code number http status code of the response reason string response reason phrase id number unique identifier severity string output field severity source string output field source state string output field state attackdirection string output field attackdirection received string output field received emails array output field emails sender object output field sender email string output field email recipient object output field recipient email string output field email subject string output field subject messageid string unique identifier body string request body data bodytype string request body data headers object http headers for the request thread index string output field thread index received string output field received x ms tnef correlator string output field x ms tnef correlator thread topic string output field thread topic message id string unique identifier content transfer encoding string response content x ms exchange organization authas string output field x ms exchange organization authas example \[ { "status code" 200, "response headers" { "content length" "140", "content type" "application/json", "date" "wed, 23 aug 2023 20 37 23 gmt" }, "reason" "ok", "json body" { "id" 3, "severity" "info", "source" "abuse mailbox monitor", "state" "linked", "attackdirection" "inbound", "received" "2019 02 25t17 22 48z", "emails" \[] } } ] get all list members retrieve all members from a specified list in proofpoint threat response, requiring list id and member type endpoint url /api/lists/{{list id}}/{{member type}} method get input argument name type required description list id number required unique identifier member type string required the information format to get in return available options include members pan(for published lists) members bluecoat(for published lists) members json output parameter type description status code number http status code of the response reason string response reason phrase example \[ { "status code" 200, "response headers" { "content length" "140", "content type" "application/json", "date" "wed, 23 aug 2023 20 37 23 gmt" }, "reason" "ok", "json body" \[ {}, {} ] } ] get incident details retrieve detailed information for a specific incident by providing the incident id in proofpoint threat response endpoint url /api/incidents/{{incident id}} json method get input argument name type required description incident id number required unique identifier expand events boolean optional parameter for get incident details output parameter type description status code number http status code of the response reason string response reason phrase id number unique identifier type string type of the resource summary string output field summary description string output field description score number score value state string output field state created at string output field created at false positive count number count value event count number count value event sources array output field event sources users array output field users assignee string output field assignee team string output field team hosts object output field hosts attacker array output field attacker forensics array output field forensics incident field values array unique identifier name string name of the resource value string value for the parameter events array output field events id number unique identifier category string output field category severity string output field severity example \[ { "status code" 200, "response headers" { "content length" "140", "content type" "application/json", "date" "wed, 23 aug 2023 20 37 23 gmt" }, "reason" "ok", "json body" { "id" 1, "type" "malware", "summary" "unsolicited bulk email", "description" "evilscheme test message", "score" 4200, "state" "open", "created at" "2018 05 26t21 07 17z", "false positive count" 0, "event count" 3, "event sources" \[], "users" \[], "assignee" "unassigned", "team" "unassigned", "hosts" {}, "incident field values" \[] } } ] get incidents gathers detailed information from multiple incidents within proofpoint threat response for analysis and response endpoint url /api/incidents method get input argument name type required description state string optional state of the incidents to retrive created after string optional retrieve incidents that were created after specified date, in iso 8601 format (utc) created before string optional retrieve incidents that were created before specified date, in iso 8601 format (utc) closed after string optional retrieve incidents that were closed after specified date, in iso 8601 format (utc) closed before string optional retrieve incidents that were closed before specified date, in iso 8601 format (utc) closed at string optional retrieve incidents that were closed at on a specific date example closed at=yyyy mm dd updated at string optional retrieve incidents that were updated at on a specific date example updated at=yyyy mm dd format to timezone string optional when specified the all time values in the response will be in the specified timezone please note that the typical + is represented with ’%2b’ in the call, where as the use of is accepted as is example request format to timezone=utc%2b6 00 for specifying a + symbol in utc+6 00 whereas the use of utc 6 00 may be represented as format to timezone=utc 6 00 expand events string optional retrieve incidents with events data expanded sender string optional retrieve incidents with a specific sender this parameter accepts single or multiple entries separate multiple entries with a comma as shown recipient string optional retrieve incidents with a specific recipient this parameter accepts single or multiple entries separate multiple entries with a comma as shown ip string optional retrieve incidents by the attacker’s (sender’s) ip address message id string optional retrieve incidents by the message id enclosed in <> this parameter accepts single or multiple entries multiple entries shold be separated with a comma as shown in the example file hash string optional retrieve incidents which contain the specified file hash source type string optional retrieve incidents only belong to that source url string optional retrieve incidents contain the specified url this will look to match on the partial and full url file name string optional retrieve incidents which contain an attachment with the specified name file type string optional retrieve incidents which contain a certain type of attachment incident value fields to json boolean optional specify if the response’s incident field values section should be returned as json disposition string optional specify if the response’s incident field values section should be returned as json sub disposition string optional retrieve incidents which have either a needs manual review or likely harmless sub disposition this parameter accepts either needs manual review or likely harmless target user string optional retrieve incidents where the target user is specified threat name string optional retrieve incidents where the alert threat name is specified attack vector string optional retrieve incidents where the attack vector is specified exclude message body boolean optional when set to true this will exclude the message body from the json response output parameter type description status code number http status code of the response reason string response reason phrase example \[ { "status code" 200, "response headers" { "content length" "140", "content type" "application/json", "date" "wed, 23 aug 2023 20 37 23 gmt" }, "reason" "ok", "json body" \[ {}, {} ] } ] get investigation details retrieve detailed information for a specific investigation in proofpoint threat response using the provided investigation id endpoint url /api/investigations/{{investigation id}} json method get input argument name type required description investigation id number required unique identifier expand incidents boolean optional unique identifier expand events boolean optional parameter for get investigation details output parameter type description status code number http status code of the response reason string response reason phrase id number unique identifier created at string output field created at updated at string output field updated at name string name of the resource assignee string output field assignee team string output field team description string output field description investigation field values array value for the parameter name string name of the resource value string value for the parameter incident ids array unique identifier incidents array unique identifier file name string name of the resource file string output field file example \[ { "status code" 200, "response headers" { "content length" "140", "content type" "application/json", "date" "wed, 23 aug 2023 20 37 23 gmt" }, "reason" "ok", "json body" { "id" 1, "created at" "2021 01 08t17 20 07z", "updated at" "2021 03 11t05 49 15z", "name" "test", "assignee" "system administrator", "team" "script admins", "description" "asdadad", "investigation field values" \[], "incident ids" \[], "incidents" \[] } } ] get single list member retrieves a specific member from a list in proofpoint threat response using the provided list and member ids endpoint url /api/lists/{{list id}}/members/{{member id}} json method get input argument name type required description list id number required unique identifier member id number required unique identifier output parameter type description status code number http status code of the response reason string response reason phrase id number unique identifier list id number unique identifier host id number unique identifier response id object unique identifier reverse user id object unique identifier hash reputation id object unique identifier user id object unique identifier enabled boolean output field enabled deleted boolean output field deleted description string output field description expiration object output field expiration created at string output field created at updated at string output field updated at host object output field host created at string output field created at host string output field host id number unique identifier resolution state number output field resolution state ttl number output field ttl updated at string output field updated at example \[ { "status code" 200, "response headers" { "content length" "140", "content type" "application/json", "date" "wed, 23 aug 2023 20 37 23 gmt" }, "reason" "ok", "json body" { "id" 6, "list id" 2, "host id" 6, "response id" null, "reverse user id" null, "hash reputation id" null, "user id" null, "enabled" true, "deleted" false, "description" "test", "expiration" null, "created at" "2017 01 11t03 43 54z", "updated at" "2017 01 11t03 43 54z", "host" {} } } ] ingest an alert ingest an alert into proofpoint threat response using a specified source id, requiring path parameters and json body endpoint url /threat/json event/events/{{json source id}} method post input argument name type required description json source id string required unique identifier json version string optional parameter for ingest an alert attacker object optional parameter for ingest an alert host name string optional name of the resource ip address string optional parameter for ingest an alert port number optional parameter for ingest an alert url string optional url endpoint for the request user string optional parameter for ingest an alert classification string optional parameter for ingest an alert cnc hosts array optional parameter for ingest an alert host string optional parameter for ingest an alert port number optional parameter for ingest an alert custom fields object optional parameter for ingest an alert custom field 1 string optional parameter for ingest an alert custom field 2 string optional parameter for ingest an alert custom field 3 string optional parameter for ingest an alert custom field 4 string optional parameter for ingest an alert custom field 5 string optional parameter for ingest an alert custom field 6 string optional parameter for ingest an alert description string optional parameter for ingest an alert detector object optional parameter for ingest an alert action string optional parameter for ingest an alert event category string optional parameter for ingest an alert host name string optional name of the resource ip address string optional parameter for ingest an alert output parameter type description status code number http status code of the response reason string response reason phrase example \[ { "status code" 200, "response headers" { "content length" "140", "content type" "application/json", "date" "wed, 23 aug 2023 20 37 23 gmt" }, "reason" "ok", "json body" {} } ] update incident description updates an incident's description in proofpoint threat response using the provided incident id endpoint url /api/incidents/{{incident id}}/description json method post input argument name type required description incident id number required unique identifier description string required parameter for update incident description overwrite string optional parameter for update incident description output parameter type description status code number http status code of the response reason string response reason phrase example \[ { "status code" 200, "response headers" { "content length" "140", "content type" "application/json", "date" "wed, 23 aug 2023 20 37 23 gmt" }, "reason" "ok", "json body" {} } ] update member of list updates a specific member within a list using the provided list and member ids in proofpoint threat response endpoint url /api/lists/{{list id}}/members/{{member id}} json method put input argument name type required description list id number required unique identifier member id number required unique identifier output parameter type description status code number http status code of the response reason string response reason phrase id number unique identifier list id number unique identifier host id number unique identifier response id object unique identifier reverse user id object unique identifier hash reputation id object unique identifier user id object unique identifier enabled boolean output field enabled deleted boolean output field deleted description string output field description expiration string output field expiration created at string output field created at updated at string output field updated at host object output field host created at string output field created at host string output field host id number unique identifier resolution state number output field resolution state ttl number output field ttl updated at string output field updated at example \[ { "status code" 200, "response headers" { "content length" "140", "content type" "application/json", "date" "wed, 23 aug 2023 20 37 23 gmt" }, "reason" "ok", "json body" { "id" 4, "list id" 2, "host id" 4, "response id" null, "reverse user id" null, "hash reputation id" null, "user id" null, "enabled" true, "deleted" false, "description" "hello ptr", "expiration" "2017 12 03t10 15 30z", "created at" "2016 12 29t01 52 33z", "updated at" "2017 01 13t00 55 27z", "host" {} } } ] response headers header description example content length the length of the response body in bytes 140 content type the media type of the resource application/json date the date and time at which the message was originated wed, 23 aug 2023 20 37 23 gmt