ProofPoint
The ProofPoint connector enables automated interactions with ProofPoint's security services, facilitating threat detection and response activities.
ProofPoint is a leading cybersecurity and compliance company that protects organizations' people, data, and brand against advanced threats and compliance risks. The ProofPoint connector for Swimlane Turbine enables users to automate the decoding of URLs, retrieval of forensic data, and extraction of SIEM events. By integrating with ProofPoint, Swimlane Turbine users can enhance their security operations with streamlined threat intelligence and incident response capabilities, leveraging ProofPoint's advanced email protection and targeted attack analysis.
Prerequisites
To effectively utilize the ProofPoint connector with Swimlane Turbine, ensure you have the following prerequisites:
- HTTP Basic Authentication with the following parameters:
- URL: The endpoint URL for the ProofPoint API.
- Principal: Your ProofPoint account username.
- Secret: Your ProofPoint account password.
Capabilities
The Proofpoint integration provides the following capabilities:
- Decode URLs
- Decode URLs - Offline (This uses a local script to decode the URLs.)
- Forensics Campaign Lookup
- Forensics Threat Lookup
- SIEM All
- SIEM Messages Blocked
- SIEM Messages Delivered
- SIEM Clicks Blocked
- SIEM Clicks Delivered
Limitations
The URLs passed to the decode tasks are case sensitive.
Proofpoint encodes the URLs with base64, if you are passing extracted IOCs from the Swilane Utilites plugin with the IOC Parser task, please make sure that you have the input To Lower marked as False.
Notes
In the case of using SIEM API action, we must have to pass the one of the following fields in query parameters
- Interval
- Since Seconds
- Since Time
interval
A string containing an ISO8601-formatted interval. If this interval overlaps with previous requests for data, records from the previous request may be duplicated. The minimum interval is thirty seconds. The maximum interval is one hour.
Example
- 2016-05-01T12:00:00Z/2016-05-01T13:00:00Z - an hour interval, beginning at noon UTC on 05-01-2016
- PT30M/2016-05-01T12:30:00Z - the thirty minutes beginning at noon UTC on 05-01-2016 and ending at 12:30pm UTC
- 2016-05-01T05:00:00-0700/PT30M - the same interval as above, but using -0700 as the time zone
sinceSeconds
An integer representing a time window in seconds from the current API server time. The start of the window is the current API server time, rounded to the nearest minute, less the number of seconds provided. The end of the window is the current API server time rounded to the nearest minute. If JSON output is selected, the end time is included in the returned result.
sinceTime
A string containing an ISO8601 date. It represents the start of the data retrieval period. The end of the period is determined by current API server time rounded to the nearest minute. If JSON output is selected, the end time is included in the returned result.
format A string specifying the format in which response data is returned. If no format is specified, syslog will be used as the default. The following values are accepted:
- syslog
- JSON
Notes
Additional Documentation
Configurations
HTTP Basic Authentication
Authenticates using username and password.
Configuration Parameters
Parameter | Description | Type | Required |
|---|---|---|---|
url | A URL to the target host. | string | Required |
username | Principal | string | Required |
password | Secret | string | Required |
verify_ssl | Verify SSL certificate | boolean | Optional |
http_proxy | A proxy to route requests through. | string | Optional |
Actions
Decode Urls
Reverts ProofPoint TAP-rewritten URLs back to their original form, requiring a list of URLs in the JSON body.
Endpoint
- URL: /v2/url/decode
- Method: POST
Input
Argument Name | Type | Required | Description |
|---|---|---|---|
urls | array | Optional | URL endpoint for the request |
Input Example
{"json_body":{"urls":["https://urldefense.proofpoint.com/v2/url u=http-3A__links.mkt3337.com_ctt-3Fkn-3D3-26ms-3DMzQ3OTg3MDQS1-26r-3DMzkxNzk3NDkwMDA0S0-26b-3D0-26j-3DMTMwMjA1ODYzNQS2-26mt-3D1-26rt-3D0&d=DwMFaQ&c=Vxt5e0Osvvt2gflwSlsJ5DmPGcPvTRKLJyp031rXjhg&r=MujLDFBJstxoxZI_GKbsW7wxGM7nnIK__qZvVy6j9Wc&m=QJGhloAyfD0UZ6n8r6y9dF-khNKqvRAIWDRU_K65xPI&s=ew-rOtBFjiX1Hgv71XQJ5BEgl9TPaoWRm_Xp9Nuo8bk&e=","https://urldefense.proofpoint.com/v1/url?u=http://www.bouncycastle.org/&k=oIvRg1%2BdGAgOoM1BIlLLqw%3D%3D%0A&r=IKM5u8%2B%2F%2Fi8EBhWOS%2BqGbTqCC%2BrMqWI%2FVfEAEsQO%2F0Y%3D%0A&m=Ww6iaHO73mDQpPQwOwfLfN8WMapqHyvtu8jM8SjqmVQ%3D%0A&s=d3583cfa53dade97025bc6274c6c8951dc29fe0f38830cf8e5a447723b9f1c9a"]}}
Output
Parameter | Type | Description |
|---|---|---|
status_code | number | HTTP status code of the response |
reason | string | Response reason phrase |
urls | array | URL endpoint for the request |
urls.encodedUrl | string | URL endpoint for the request |
urls.success | boolean | URL endpoint for the request |
urls.decodedUrl | string | URL endpoint for the request |
Output Example
{"status_code":200,"response_headers":{"Date":"Fri, 13 Oct 2023 09:06:25 GMT","Content-Type":"application/json","Content-Length":"853","Connection":"keep-alive","Vary":"Accept-Encoding","X-Content-Type-Options":"nosniff","Strict-Transport-Security":"max-age=15724800; includeSubDomains"},"reason":"OK","json_body":{"urls":[{},{}]}}
Decode Urls Offline
Decode ProofPoint-encoded URLs locally, compatible with v1, v2, and v3 formats. Requires a list of URLs to process.
Input
Argument Name | Type | Required | Description |
|---|---|---|---|
url | string | Optional | URL endpoint for the request |
Input Example
{"json_body":{"urls":"https://tap-api-v2.proofpoint.com/"}}
Output
Parameter | Type | Description |
|---|---|---|
status_code | number | HTTP status code of the response |
reason | string | Response reason phrase |
headers | object | HTTP headers for the request |
decoded_urls | array | URL endpoint for the request |
Output Example
{"status_code":200,"reason":"OK","headers":{},"json_body":{"decoded_urls":["https://urldefense.proofpoint.com/v2/url?u=http-3A__links.mkt3337.com_ctt-3Fkn-3D3-26ms-3DMzQ3OTg3MDQS1-26r-3DMzkxNzk3NDkwMDA0S0-26b-3D0-26j-3DMTMwMjA1ODYzNQS2-26mt-3D1-26rt-3D0&d=DwMFaQ&c=Vxt5e0Osvvt2gflwSlsJ5DmPGcPvTRKLJyp031rXjhg&r=MujLDFBJstxoxZI_GKbsW7wxGM7nnIK__qZvVy6j9Wc&m=QJGhloAyfD0UZ6n8r6y9dF-khNKqvRAIWDRU_K65xPI&s=ew-rOtBFjiX1Hgv71XQJ5BEgl9TPaoWRm_Xp9Nuo8bk&e=","https://urldefense.proofpoint.com/v1/url?u=http:...
Forensics Campaign
Retrieve aggregate forensics data for a specified campaign in ProofPoint using the campaignId parameter.
Endpoint
- URL: /v2/forensics
- Method: GET
Input
Argument Name | Type | Required | Description |
|---|---|---|---|
parameters.campaignId | string | Required | Parameters for the Forensics Campaign action |
Input Example
{"parameters":{"campaignId":"e144426d-7bcd-4695-98a7-c9f6551f3d48"}}
Output
Parameter | Type | Description |
|---|---|---|
status_code | number | HTTP status code of the response |
reason | string | Response reason phrase |
generated | string | Output field: generated |
reports | array | Output field: reports |
reports.scope | string | Output field: reports.scope |
reports.id | string | Unique identifier |
reports.name | string | Name of the resource |
reports.forensics | array | Output field: reports.forensics |
reports.forensics.file_name | string | Name of the resource |
reports.forensics.file | string | Output field: reports.forensics.file |
Output Example
{"status_code":200,"response_headers":{"Date":"Wed, 18 Oct 2023 13:42:53 GMT","Content-Type":"application/json","Content-Length":"188","Connection":"keep-alive","X-Content-Type-Options":"nosniff","Vary":"Accept-Encoding, User-Agent","Content-Encoding":"gzip","Strict-Transport-Security":"max-age=15724800; includeSubDomains"},"reason":"OK","json_body":{"generated":"2023-10-18T13:42:53.056Z","reports":[{}]}}
Forensics Threat
Retrieve aggregate forensics data for a specified threat in ProofPoint using the threatId parameter.
Endpoint
- URL: /v2/forensics
- Method: GET
Input
Argument Name | Type | Required | Description |
|---|---|---|---|
parameters.threatId | string | Required | Parameters for the Forensics Threat action |
parameters.includeCampaignForensics | boolean | Optional | Parameters for the Forensics Threat action |
Input Example
{"parameters":{"threatId":"fc31eb2b503d8df30b509aa56e3685174071b966a7cbc58c74392c3f87bbcbe8","includeCampaignForensics":false}}
Output
Parameter | Type | Description |
|---|---|---|
status_code | number | HTTP status code of the response |
reason | string | Response reason phrase |
generated | string | Output field: generated |
reports | array | Output field: reports |
reports.scope | string | Output field: reports.scope |
reports.id | string | Unique identifier |
reports.name | string | Name of the resource |
reports.threatStatus | string | Status value |
reports.forensics | array | Output field: reports.forensics |
reports.forensics.type | string | Type of the resource |
reports.forensics.display | string | Output field: reports.forensics.display |
reports.forensics.engine | string | Output field: reports.forensics.engine |
reports.forensics.malicious | boolean | Output field: reports.forensics.malicious |
reports.forensics.time | number | Time value |
reports.forensics.what | object | Output field: reports.forensics.what |
reports.forensics.what.url | string | URL endpoint for the request |
reports.forensics.platforms | array | Output field: reports.forensics.platforms |
reports.forensics.platforms.name | string | Name of the resource |
reports.forensics.platforms.os | string | Output field: reports.forensics.platforms.os |
reports.forensics.platforms.version | string | Output field: reports.forensics.platforms.version |
reports.forensics.note | string | Output field: reports.forensics.note |
Output Example
{"status_code":200,"response_headers":{"Date":"Wed, 18 Oct 2023 13:44:40 GMT","Content-Type":"application/json","Transfer-Encoding":"chunked","Connection":"keep-alive","X-Content-Type-Options":"nosniff","Vary":"Accept-Encoding, User-Agent","Content-Encoding":"gzip","Strict-Transport-Security":"max-age=15724800; includeSubDomains"},"reason":"OK","json_body":{"generated":"2023-10-18T13:44:39.664Z","reports":[{}]}}
SIEM All
Retrieve all click and message events related to identified threats within a defined time frame from ProofPoint.
Endpoint
- URL: /v2/siem/all
- Method: GET
Input
Argument Name | Type | Required | Description |
|---|---|---|---|
parameters.sinceSeconds | string | Optional | An integer representing a time window in seconds from the current API server time. The start of the window is the current API server time, rounded to the nearest minute, less the number of seconds provided. The end of the window is the current API server time rounded to the nearest minute. If JSON output is selected, the end time is included in the returned result. |
parameters.sinceTime | string | Optional | A string containing an ISO8601 date. It represents the start of the data retrieval period. The end of the period is determined by current API server time rounded to the nearest minute. If JSON output is selected, the end time is included in the returned result. |
parameters.interval | string | Optional | A string containing an ISO8601-formatted interval. If this interval overlaps with previous requests for data, records from the previous request may be duplicated. The minimum interval is thirty seconds. The maximum interval is one hour. |
parameters.format | string | Optional | A string specifying the format in which data is returned. If no format is specified, syslog will be used as the default. |
parameters.threatType | string | Optional | A string specifying which threat type will be returned in the data. If no value is specified, all threat types are returned. |
parameters.threatStatus | string | Optional | A string specifying which threat statuses will be returned in the data. If no value is specified, active and cleared threats are returned. |
Input Example
{"parameters":{"sinceSeconds":"100","sinceTime":"2024-04-26T5:42:45Z","interval":"PT30M/2024-04-26T10:12:45Z","format":"syslog","threatType":"url","threatStatus":"active"}}
Output
Parameter | Type | Description |
|---|---|---|
status_code | number | HTTP status code of the response |
reason | string | Response reason phrase |
response_text | string | Output field: response_text |
Output Example
{"status_code":200,"response_headers":{"Date":"Fri, 26 Apr 2024 04:59:00 GMT","Content-Type":"text/plain","Content-Length":"1286","Connection":"keep-alive","Server-Timing":"traceparent;desc=\"00-f0905c6c701404804fdd783e49829bd3-504a48747fd43b4f-01\"","Access-Control-Expose-Headers":"Server-Timing","Vary":"Accept-Encoding, User-Agent","Content-Encoding":"gzip","Strict-Transport-Security":"max-age=15724800; includeSubDomains"},"reason":"OK","response_text":"<38>1 2024-04-26T04:32:51Z - ProofpointT...
Siem Clicks Blocked
Fetch events for clicks to malicious URLs that were blocked by ProofPoint within a specified time period.
Endpoint
- URL: /v2/siem/clicks/blocked
- Method: GET
Input
Argument Name | Type | Required | Description |
|---|---|---|---|
parameters.interval | string | Optional | Parameters for the Siem Clicks Blocked action |
parameters.sinceSeconds | number | Optional | Parameters for the Siem Clicks Blocked action |
parameters.sinceTime | string | Optional | Parameters for the Siem Clicks Blocked action |
parameters.format | string | Optional | Parameters for the Siem Clicks Blocked action |
parameters.threatType | string | Optional | Parameters for the Siem Clicks Blocked action |
parameters.threatStatus | string | Optional | Parameters for the Siem Clicks Blocked action |
Input Example
{"parameters":{"interval":"PT30M/2023-10-11T12:30:00Z","sinceSeconds":5,"sinceTime":"3","format":"JSON","threatType":"url","threatStatus":"active"}}
Output
Parameter | Type | Description |
|---|---|---|
status_code | number | HTTP status code of the response |
reason | string | Response reason phrase |
response_text | string | Output field: response_text |
Output Example
{"status_code":204,"response_headers":{"Date":"Mon, 16 Oct 2023 09:02:15 GMT","Connection":"keep-alive","Strict-Transport-Security":"max-age=15724800; includeSubDomains"},"reason":"No Content","response_text":""}
Siem Clicks Permitted
Fetch events for clicks to malicious URLs that were permitted within a specified time period in ProofPoint.
Endpoint
- URL: /v2/siem/clicks/permitted
- Method: GET
Input
Argument Name | Type | Required | Description |
|---|---|---|---|
parameters.interval | string | Optional | Parameters for the Siem Clicks Permitted action |
parameters.sinceSeconds | number | Optional | Parameters for the Siem Clicks Permitted action |
parameters.sinceTime | string | Optional | Parameters for the Siem Clicks Permitted action |
parameters.format | string | Optional | Parameters for the Siem Clicks Permitted action |
parameters.threatType | string | Optional | Parameters for the Siem Clicks Permitted action |
parameters.threatStatus | string | Optional | Parameters for the Siem Clicks Permitted action |
Input Example
{"parameters":{"interval":"PT30M/2023-10-11T12:30:00Z","sinceSeconds":5,"sinceTime":"3","format":"JSON","threatType":"url","threatStatus":"active"}}
Output
Parameter | Type | Description |
|---|---|---|
status_code | number | HTTP status code of the response |
reason | string | Response reason phrase |
response_text | string | Output field: response_text |
Output Example
{"status_code":204,"response_headers":{"Date":"Mon, 16 Oct 2023 09:27:36 GMT","Connection":"keep-alive","Strict-Transport-Security":"max-age=15724800; includeSubDomains"},"reason":"No Content","response_text":""}
Siem Messages Blocked
Retrieve events for messages that were blocked within a specified time frame due to recognized threats in ProofPoint.
Endpoint
- URL: /v2/siem/messages/blocked
- Method: GET
Input
Argument Name | Type | Required | Description |
|---|---|---|---|
parameters.interval | string | Optional | Parameters for the Siem Messages Blocked action |
parameters.sinceSeconds | number | Optional | Parameters for the Siem Messages Blocked action |
parameters.sinceTime | string | Optional | Parameters for the Siem Messages Blocked action |
parameters.format | string | Optional | Parameters for the Siem Messages Blocked action |
parameters.threatType | string | Optional | Parameters for the Siem Messages Blocked action |
parameters.threatStatus | string | Optional | Parameters for the Siem Messages Blocked action |
Input Example
{"parameters":{"interval":"PT30M/2023-10-10T12:30:00Z","sinceSeconds":30,"sinceTime":"1","format":"JSON","threatType":"url","threatStatus":"active"}}
Output
Parameter | Type | Description |
|---|---|---|
status_code | number | HTTP status code of the response |
reason | string | Response reason phrase |
response_text | string | Output field: response_text |
Output Example
{"status_code":200,"response_headers":{"Date":"Mon, 16 Oct 2023 09:05:21 GMT","Content-Type":"application/json","Transfer-Encoding":"chunked","Connection":"keep-alive","Vary":"Accept-Encoding, User-Agent","Content-Encoding":"gzip","Strict-Transport-Security":"max-age=15724800; includeSubDomains"},"reason":"OK","response_text":"<38>1 2023-10-10T12:07:34Z - ProofpointTAP - MSGBLK [tapmsg@21139 messageTime=\"2..."}
Siem Messages Delivered
Fetch events for messages delivered within a specified time frame that contained a known threat, requiring specific parameters.
Endpoint
- URL: /v2/siem/messages/delivered
- Method: GET
Input
Argument Name | Type | Required | Description |
|---|---|---|---|
parameters.interval | string | Optional | Parameters for the Siem Messages Delivered action |
parameters.sinceSeconds | number | Optional | Parameters for the Siem Messages Delivered action |
parameters.sinceTime | string | Optional | Parameters for the Siem Messages Delivered action |
parameters.format | string | Optional | Parameters for the Siem Messages Delivered action |
parameters.threatType | string | Optional | Parameters for the Siem Messages Delivered action |
parameters.threatStatus | string | Optional | Parameters for the Siem Messages Delivered action |
Input Example
{"parameters":{"interval":"PT30M/2023-10-15T02:30:00Z","sinceSeconds":30,"sinceTime":"1","format":"JSON","threatType":"url","threatStatus":"active"}}
Output
Parameter | Type | Description |
|---|---|---|
status_code | number | HTTP status code of the response |
reason | string | Response reason phrase |
response_text | string | Output field: response_text |
Output Example
{"status_code":200,"response_headers":{"Date":"Mon, 16 Oct 2023 09:34:21 GMT","Content-Type":"application/json","Transfer-Encoding":"chunked","Connection":"keep-alive","Vary":"Accept-Encoding, User-Agent","Content-Encoding":"gzip","Strict-Transport-Security":"max-age=15724800; includeSubDomains"},"reason":"OK","response_text":""}
Response Headers
Header | Description | Example |
|---|---|---|
Access-Control-Expose-Headers | HTTP response header: Access-Control-Expose-Headers | Server-Timing |
Connection | HTTP response header: Connection | keep-alive |
Content-Encoding | HTTP response header: Content-Encoding | gzip |
Content-Length | The length of the response body in bytes | 853 |
Content-Type | The media type of the resource | text/plain |
Date | The date and time at which the message was originated | Mon, 16 Oct 2023 09:02:15 GMT |
Server-Timing | HTTP response header: Server-Timing | traceparent;desc="00-f0905c6c701404804fdd783e49829bd3-504a48747fd43b4f-01" |
Strict-Transport-Security | HTTP response header: Strict-Transport-Security | max-age=15724800; includeSubDomains |
Transfer-Encoding | HTTP response header: Transfer-Encoding | chunked |
Vary | HTTP response header: Vary | Accept-Encoding |
X-Content-Type-Options | HTTP response header: X-Content-Type-Options | nosniff |