Proofpoint Targeted Attack Prevention (TAP) 3.0.0
App Vendor: Proofpoint
App Category: Analytics & SIEM, Data Enrichment & Threat Intelligence
Connector Version: 3.0.0
API Version: V2
Note
This app is currently released as a beta version.
About App
The app provides integration with Proofpoint Targeted Attack Prevention (TAP) Application. Proofpoint Targeted Attack Protection (TAP) helps detect, mitigate, and block advanced threats that target people through email, today’s top attack vector.
The Proofpoint Targeted Attack Prevention (TAP) app is configured with Cyware Orchestrate to perform the following actions:
Action Name | Description |
|---|---|
Decode URLs | This action decodes a comma-separated list of URLs that have been rewritten by TAP. |
Get All SIEM Events | This action retrieves events for all clicks and messages relating to known threats within the specified time period. |
Get Blocked Clicks | This action retrieves events for clicks to malicious URLs blocked in the specified time period. |
Get Blocked Messages | This action retrieves events for messages blocked in the specified time period which contained a known threat. |
Get Campaign Details | This action retrieves the detailed information for a given campaign. |
Get Delivered Messages | This action retrieves events for messages delivered in the specified time period which contained a known threat. |
Get Forensic Details | This action retrieves forensic information for a given threat or campaign. |
Get Issues | This action retrieves events for clicks to malicious URLs permitted and messages delivered containing a known attachment threat within the specified time period. |
Get List of Very Attacked People | This action retrieves the identities and attack index breakdown of Very Attacked People within your organization for a given period. |
Get Permitted Clicks | This action retrieves events for clicks to malicious URLs permitted in the specified time period. |
Get Top Clickers | This action retrieves the identities and attack index of your organization's top clickers for a given period. |
List Campaign IDs | This action retrieves the list of IDs of campaigns active in a time window sorted by the last updated timestamp. |
Generic Action | This is a generic action used to make requests to any Proofpoint TAP endpoint. |
Configuration Parameters
The following configuration parameters are required for the Proofpoint Targeted Attack Prevention (TAP) app to communicate with the Proofpoint Targeted Attack Prevention (TAP) enterprise application. The parameters can be configured by creating instances in the app.
Parameter | Description | Field Type | Required/Optional | Comments |
|---|---|---|---|---|
Cloud Domain | Enter your Proofpoint TAP cloud domain. Example: https://tap-api-v2.proofpoint.com | Text | Required | |
Service Principal | Enter the Proofpoint TAP service principal. Example: 34dccdd26c5c99ceb3af22f392b708bf | Text | Required | |
Service Secret | Enter the Proofpoint TAP service secret. Example: a8c7b7523b02xxxxf5a89bd21883e832 | Password | Required | |
Timeout | Enter the timeout value in seconds. This is the number of seconds that requests will wait to establish a connection with Proofpoint TAP. | Integer | Optional | Allowed range: 15-120 Default value: 15 |
SSL Verification | Choose your preference to verify SSL while making requests. It is recommended to set this option to yes. Passing no may result in incorrectly establishing the connection. | Boolean | Optional | By default, verification is disabled. |
Action: Decode URLs
This action decodes URLs that Proofpoint TAP has rewritten to their original, target URLs.
Action Input Parameters
Parameter | Description | Field Type | Required/Optional | Comments |
|---|---|---|---|---|
URLs | Enter the URLs that you want to decode. Example: $LIST[SampleURL1, SampleURL2, SampleURL3] | Text | Required |
Example Request
{
"urls": [
"https://sample.domain.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://sample.domain.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",
"https://sample.domain.com/v3/__https://google.com:443/search?q=a*test&gs=ps__;Kw!-612Flbf0JvQ3kNJkRi5Jg!Ue6tQudNKaShHg93trcdjqDP8se2ySE65jyCIe2K1D_uNjZ1Lnf6YLQERujngZv9UWf66ujQIQ$"
]
}Action: Get All SIEM Events
This action retrieves details of all SIEM events related to known threats within the specified time period.
Action Input Parameters
Parameter | Description | Field Type | Required/Optional | Comments |
|---|---|---|---|---|
Interval | Enter the time interval (in ISO 8601 format) for which you want to retrieve information. 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 - thirty minutes starting at noon UTC on 05-01-2016 and ending at 12:30 p.m. UTC 2016-05-01T05:00:00-0700/PT30M - the same interval as above, but using -0700 as the time zone | Text | Optional | Enter the time in the ISO 8601 format. Minimum interval: 30 seconds Maximum interval: 1 hour |
Since Seconds | Enter the time interval in seconds from when you want to retrieve details. Start time: Current API server time, rounded to the nearest minute, less the entered value. End time: Current API server time rounded to the nearest minute. Example: 300 | Integer | Optional | |
Since Time | Enter the date (in ISO 8601 format) from when you want to retrieve details. Start time: Entered value. End time: Current API server time rounded to the nearest minute. Example: 2016-05-01T12:00:00Z | Text | Optional | |
Extra parameters | Enter the required parameters as key-value pairs. Example: {"threatStatus": "active"} | Key Value | Optional | Allowed keys: threatstatus: (string) Enter the threat status for which you want to retrieve details. Allowed values: active, cleared, falsepositive threattype: (string) Enter the threat type for which you want to retrieve details. Allowed values: url, attachment, messagetext |
Example Request
[
{
"interval": " 2020-05-01T12:00:00Z/2020-05-01T13:00:00Z",
"extra_params": {
"threatStatus": "active"
}
}
]Action: Get Blocked Clicks
This action retrieves events for clicks to malicious URLs blocked in the specified time period. One of Interval, Since Seconds, or Since Time must be provided.
Action Input Parameters
Parameter | Description | Field Type | Required/Optional | Comments |
|---|---|---|---|---|
Interval | Enter the time interval (in ISO 8601 format) for which you want to retrieve information. 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 - thirty minutes starting at noon UTC on 05-01-2016 and ending at 12:30 p.m. UTC 2016-05-01T05:00:00-0700/PT30M - the same interval as above, but using -0700 as the time zone | Text | Optional | Enter time in the ISO 8601 format. Minimum interval: 30 seconds Maximum interval: 1 hour |
Since Seconds | Enter the time interval in seconds from when you want to retrieve details. Start time: Current API server time, rounded to the nearest minute, less the entered value. End time: Current API server time rounded to the nearest minute. Example: 300 | Integer | Optional | |
Since Time | Enter the date (in ISO 8601 format) from when you want to retrieve details. Start time: Entered value. End time: Current API server time rounded to the nearest minute. Example: 2016-05-01T12:00:00Z | Text | Optional | |
Extra Parameters | Enter the required parameters as key-value pairs. Example: {"threatStatus": "active"} | Key Value | Optional | Allowed keys: threatstatus: (string) Enter the threat status for which you want to retrieve details. Allowed values: active, cleared, falsepositive threattype: (string) Enter the threat type for which you want to retrieve details. Allowed values: url, attachment, messagetext |
Example Request
[
{
"interval": " 2020-05-01T12:00:00Z/2020-05-01T13:00:00Z",
"extra_params": {
"threatStatus": "active"
}
}
]Action: Get Blocked Messages
This action retrieves details of all blocked messages containing a known threat in the specified period. One of Interval, Since Seconds, or Since Time must be provided.
Action Input Parameters
Parameter | Description | Field Type | Required/Optional | Comments |
|---|---|---|---|---|
Interval | Enter the time interval (in ISO 8601 format) for which you want to retrieve information. 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 - thirty minutes starting at noon UTC on 05-01-2016 and ending at 12:30 p.m. UTC 2016-05-01T05:00:00-0700/PT30M - the same interval as above, but using -0700 as the time zone | Text | Optional | Enter time in the ISO 8601 format. Minimum interval: 30 seconds Maximum interval: 1 hour |
Since Seconds | Enter the time interval in seconds from when you want to retrieve details. Start time: Current API server time, rounded to the nearest minute, less the entered value. End time: Current API server time rounded to the nearest minute. Example: 300 | Integer | Optional | |
Since Time | Enter the date (in ISO 8601 format) from when you want to retrieve details. Start time: Entered value. End time: Current API server time rounded to the nearest minute. Example: 2016-05-01T12:00:00Z | Text | Optional | |
Extra Parameters | Enter the required parameters as key-value pairs. Example: {"threatStatus": "active"} | Key Value | Optional | Allowed keys: threatstatus: (string) Enter the threat status for which you want to retrieve details. Allowed values: active, cleared, falsepositive threattype: (string) Enter the threat type for which you want to retrieve details. Allowed values: url, attachment, messagetext |
Example Request
[
{
"interval": " 2020-05-01T12:00:00Z/2020-05-01T13:00:00Z",
"extra_params": {
"threatStatus": "active"
}
}
]Action: Get Campaign Details
This action retrieves details of the specified campaign.
Action Input Parameters
Parameter | Description | Field Type | Required/Optional | Comments |
|---|---|---|---|---|
Campaign ID | Enter the campaign ID for which you want to retrieve details. Example: 12345 | Text | Required |
Example Request
[
{
"campaign_id": "12345"
}
]Action: Get Delivered Messages
This action retrieves events for messages delivered in the specified time period which contained a known threat. One of Interval, Since Seconds, or Since Time must be provided.
Action Input Parameters
Parameter | Description | Field Type | Required/Optional | Comments |
|---|---|---|---|---|
Interval | Enter the time interval (in ISO 8601 format) for which you want to retrieve information. 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 - thirty minutes starting at noon UTC on 05-01-2016 and ending at 12:30 p.m. UTC 2016-05-01T05:00:00-0700/PT30M - the same interval as above, but using -0700 as the time zone | Text | Optional | Enter time in the ISO 8601 format. Minimum interval: 30 seconds Maximum interval: 1 hour |
Since Seconds | Enter the time interval in seconds from when you want to retrieve details. Start time: Current API server time, rounded to the nearest minute, less the entered value. End time: Current API server time rounded to the nearest minute. Example: 300 | Integer | Optional | |
Since Time | Enter the date (in ISO 8601 format) from when you want to retrieve details. Start time: Entered value. End time: Current API server time rounded to the nearest minute. Example: 2016-05-01T12:00:00Z | Text | Optional | |
Extra Parameters | Enter the required parameters as key-value pairs. Example: {"threatStatus": "active"} | Key Value | Optional | Allowed keys: threatstatus: (string) Enter the threat status for which you want to retrieve details. Allowed values: active, cleared, falsepositive threattype: (string) Enter the threat type for which you want to retrieve details. Allowed values: url, attachment, messagetext |
Example Request
[
{
"interval": " 2020-05-01T12:00:00Z/2020-05-01T13:00:00Z",
"extra_params": {
"threatStatus": "active"
}
}
]Action: Get Forensic Details
This action retrieves forensic information for a given threat or campaign.
Action Input Parameters
Parameter | Description | Field Type | Required/Optional | Comments |
|---|---|---|---|---|
Campaign ID or Threat ID | Enter the campaign ID or threat ID for which you want to retrieve forensic details. Example: 12345 | Text | Required | |
Is Threat ID | Specify if the ID provided against the Campaign ID or Threat ID parameter is the threat ID or campaign ID. Example: True | Boolean | Optional | Allowed values: True: Threat ID False: Campaign ID Default value: False |
Include Campaign Forensics | Specify if you want to retrieve aggregate forensics for the specified thread ID or the entire campaign. This parameter can only be used if you enter a thread ID against the Campaign ID or Threat ID parameter. Example: True | Boolean | Optional | Allowed values: True: Retrieves aggregate forensics for the entire campaign. False: Retrieves aggregate forensics for the specified thread ID. Default value: False |
Example Request
[
{
"id": "12345",
"is_threat_id": "true",
"include_campaignforensics": "true"
}
]Action: Get Issues
This action fetches events for clicks to malicious URLs permitted and messages delivered containing a known threat within the specified time period. One of Interval, Since Seconds, or Since Time must be provided.
Action Input Parameters
Parameter | Description | Field Type | Required/Optional | Comments |
|---|---|---|---|---|
Interval | Enter the time interval (in ISO 8601 format) for which you want to retrieve information. 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 - thirty minutes starting at noon UTC on 05-01-2016 and ending at 12:30 p.m. UTC 2016-05-01T05:00:00-0700/PT30M - the same interval as above, but using -0700 as the time zone | Text | Optional | Enter time in the ISO 8601 format. Minimum interval: 30 seconds Maximum interval: 1 hour |
Since Seconds | Enter the time interval in seconds from when you want to retrieve details. Start time: Current API server time, rounded to the nearest minute, less the entered value. End time: Current API server time rounded to the nearest minute. Example: 300 | Integer | Optional | |
Since Time | Enter the date (in ISO 8601 format) from when you want to retrieve details. Start time: Entered value. End time: Current API server time rounded to the nearest minute. Example: 2016-05-01T12:00:00Z | Text | Optional | |
Extra Parameters | Enter the required parameters as key-value pairs. Example: {"threatStatus": "active"} | Key Value | Optional | Allowed keys: threatstatus: (string) Enter the threat status for which you want to retrieve details. Allowed values: active, cleared, falsepositive threattype: (string) Enter the threat type for which you want to retrieve details. Allowed values: url, attachment, messagetext |
Example Request
[
{
"interval": " 2020-05-01T12:00:00Z/2020-05-01T13:00:00Z",
"extra_params": {
"threatStatus": "active"
}
}
]Action: Get List of Very Attacked People
This action fetches the identities and attack index breakdown of Very Attacked People within your organization for a given period.
Action Input Parameters
Parameter | Description | Field Type | Required/Optional | Comments |
|---|---|---|---|---|
Window | Enter an integer indicating for how many days the data should be retrieved. Example: 30 | Integer | Optional | Allowed values: 14, 30, 90 Default value: 14 |
Size | Enter the maximum number of VAPs to be returned in the response. The attackIndex value determines the order of results. Example: 50 | Integer | Optional | Default value: 1000 |
Page | Enter the page of results to return, in multiples of the specified size (or 1000, if no size is explicitly chosen). Example: 5 | Integer | Optional | Default value: 1 |
Example Request
[
{
"windows": 30,
"size": 50,
"page": 5
}
]Action: Get Permitted Clicks
This action retrieves a list of all clicks to malicious URLs (blocked by you) in the specified time period. One of Interval, Since Seconds, or Since Time must be provided.
Action Input Parameters
Parameter | Description | Field Type | Required/Optional | Comments |
|---|---|---|---|---|
Interval | Enter the time interval (in ISO 8601 format) for which you want to retrieve information. 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 - thirty minutes starting at noon UTC on 05-01-2016 and ending at 12:30 p.m. UTC 2016-05-01T05:00:00-0700/PT30M - the same interval as above, but using -0700 as the time zone | Text | Optional | Enter time in the ISO 8601 format. Minimum interval: 30 seconds Maximum interval: 1 hour |
Since Seconds | Enter the time interval in seconds from when you want to retrieve details. Start time: Current API server time, rounded to the nearest minute, less the entered value. End time: Current API server time rounded to the nearest minute. Example: 300 | Integer | Optional | |
Since Time | Enter the date (in ISO 8601 format) from when you want to retrieve details. Start time: Entered value. End time: Current API server time rounded to the nearest minute. Example: 2016-05-01T12:00:00Z | Text | Optional | |
Extra Parameters | Enter the required parameters as key-value pairs. Example: {"threatStatus": "active"} | Key Value | Optional | Allowed keys: threatstatus: (string) Enter the threat status for which you want to retrieve details. Allowed values: active, cleared, falsepositive threattype: (string) Enter the threat type for which you want to retrieve details. Allowed values: url, attachment, messagetext |
Example Request
[
{
"interval": " 2020-05-01T12:00:00Z/2020-05-01T13:00:00Z",
"extra_params": {
"threatStatus": "active"
}
}
]Action: Get Top Clickers
This action retrieves the identities and attack index of your organization's top clickers for a given period.
Action Input Parameters
Parameter | Description | Field Type | Required/Optional | Comments |
|---|---|---|---|---|
Window | Enter the number of days to retrieve data for. | Integer | Optional | Accepted Values: 14, 30 and 90 Default value: 90 |
Size | Enter the maximum number of top clickers to retrieve in the response. | Integer | Optional | Maximum Allowed Value: 200 Default value: 100 |
Page | Enter the page number to retrieve results from. | Integer | Optional | Default value is 1. |
Action: List Campaign IDs
This action retrieves a list of active campaign IDs.
Action Input Parameters
Parameter | Description | Field Type | Required/Optional | Comments |
|---|---|---|---|---|
Time From | Enter the time in ISO 8601 format to retrieve the ID of campaigns that are updated after this time. Example: 2020-05-01T12:00:00Z | Text | Required | |
Time To | Enter the time in ISO 8601 format to retrieve the ID of campaigns that are updated before this time. Example: 2020-05-01T13:00:00Z | Text | Required | |
Page Number | Enter the page number to retrieve campaign IDs. Example: 2 | Integer | Optional | Default value: 1 |
Page Size | Enter the maximum number of campaign IDs to retrieve. Example: 50 | Integer | Optional | Default value: 100 |
Example Request
[
{
"time_from": "2020-05-01T12:00:00Z",
"time_to": "2020-05-01T13:00:00Z",
"page": 2,
"size": 50
}
]Action: Generic Action
This is a generic action used to make requests to any Proofpoint TAP endpoint.
Action Input Parameters
Parameter | Description | Field Type | Required/Optional | Comments |
|---|---|---|---|---|
Method | Enter the HTTP method to make the request. | Text | Required | Allowed values: GET, PUT, POST, DELETE |
Endpoint | Enter the endpoint to make the request. Example: /people/top-clickers | Text | Required | |
Query Params | Enter the query parameters to pass to the API. Example: {'window': windows} | Key Value | Optional | |
Payload | Enter the payload to pass to the API. | Key Value | Optional | |
Extra Fields | Enter the extra fields to pass to the API. | Key Value | Optional | Allowed keys: payload_data, custom_output, download, filename, files, retry_wait, retry_count, response_type |
Example Request
[
{
"method": "GET",
"endpoint": "/people/top-clickers",
"extra_fields": {},
"query_params": {}
}
]