Proofpoint TAP v1.0.2

About the connector

Proofpoint Targeted Attack Protection (TAP) stays ahead of today's attackers with an innovative approach that detects, analyzes, and blocks advanced threats before they reach your inbox.

This document provides information about the Proofpoint TAP connector, which facilitates automated interactions with a Proofpoint TAP server using FortiSOAR™ playbooks. Add the Proofpoint TAP connector as a step in FortiSOAR™ playbooks and perform automated operations, such as retrieving events for clicks to malicious URLs blocked in the specified time period and retrieving details of a campaign based on the specified campaign ID.

Version information

Connector Version: 1.0.2

Authored By: Community

Certified: No

Release Notes for version 1.0.2

Following enhancements have been made to the Proofpoint TAP connector in version 1.0.2:

• Updated the Get Blocked Malicious URL Events, Get Permitted Malicious URL Events, Get Blocked Threat Message Events, Get Delivered Threat Message Events, Get All Events, and Get Events operations as follows:
  • Added the “Time Interval" parameter drop-down list, with ‘Seconds’ and ‘Time’ as options.
    If you select the "Time" option, then the 'Since Time' parameter gets displayed. Similarily, if you select the "Seconds" option, then the 'Since Seconds' parameter gets displayed
  • Search Hash
• Fixed the issue that the connector "Health Check" was failing and showing "Disconnected" even when valid credentials were specified in the connector configuration. Now, if you enter valid credentials in the connector configuration, then the "Health Check" will not fail and will display "Available".

Installing the connector

From FortiSOAR™ 5.0.0 onwards, use the Connector Store to install the connector. For the detailed procedure to install a connector, click here.
You can also use the following yum command as a root user to install connectors from an SSH session:

yum install cyops-connector-proofpoint-tap

Prerequisites to configuring the connector

• You must have the URL of the Proofpoint TAP server to which you will connect and perform the automated operations and credentials (username-password pair to access that server.
• The FortiSOAR™ server should have outbound connectivity to port 443 on Proofpoint TAP.

Configuring the connector

For the procedure to configure a connector, click here.

Configuration parameters

In FortiSOAR™, on the Connectors page, click the Proofpoint TAP connector row (if you are in the Grid view on the Connectors page), and in the Configurations tab enter the required configuration details:

Parameter	Description
Server URL	URL of the Proofpoint TAP server to which you will connect and perform automated operations.
Username	Username to access the Proofpoint TAP server to which you will connect and perform automated operations.
Password	Password to access the Proofpoint TAP server to which you will connect and perform automated operations.
Verify SSL	Specifies whether the SSL certificate for the server is to be verified or not.

Actions supported by the connector

The following automated operations can be included in playbooks and you can also use the annotations to access operations from FortiSOAR™ release 4.10.0 onwards:

Function	Description	Annotation and Category
Get Blocked Malicious URL Events	Retrieves events associated with clicks to malicious URLs that were blocked on Proofpoint TAP within the specified time period and other input parameters such as threat status, threat type, etc.	get_events Investigation
Get Permitted Malicious URL Events	Retrieves events associated with clicks to malicious URLs that were permitted on Proofpoint TAP within the specified time period and other input parameters such as threat status, threat type etc.	get_events Investigation
Get Blocked Threat Message Events	Retrieves events associated with messages that contained a known threat, and were blocked on Proofpoint TAP within the specified time period and other input parameters such as threat status, threat type, etc.	get_events Investigation
Get Delivered Threat Message Events	Retrieves events associated with messages that contained a known threat, and which were delivered within the specified time period and other input parameters such as threat status, threat type, etc.	get_events Investigation
Get All Events	Retrieves events associated with all clicks and all messages related to known threats within the specified time period and other input parameters such as threat status, threat type, etc.	get_events Investigation
Get Events for All Issues	Retrieves events associated with all clicks to malicious URLs and all messages delivered that contained a known threat within the specified time period and other input parameters such as threat status, threat type, etc.	get_events Investigation
Get Campaign Details	Retrieves details of a campaign from Proofpoint TAP based on the campaign ID specified.	get_campaign_details Investigation
Get Forensic Details	Retrieves forensic details of a campaign from Proofpoint TAP based on the threat or campaign ID specified.	get_forensic Investigation

operation: Get Blocked Malicious URL Events

Input parameters

Parameter	Description
Time Interval	Time period for which you want to fetch events associated with clicks to malicious URLs that were blocked on Proofpoint TAP. You can choose between Seconds or Time. If you choose Seconds, then in the Since Seconds field, specify the time window in seconds from when you want to fetch events associated with clicks to malicious URLs that were blocked on Proofpoint TAP. If you choose Time, then in the Since TIme field, specify the time window from when you want to fetch events associated with clicks to malicious URLs that were blocked on Proofpoint TAP.
Format	(Optional) Format in which you want to fetch events associated with clicks to malicious URLs that were blocked on Proofpoint TAP. You can choose between JSON or Syslog.
Threat Type	(Optional) Type of threats based on which you want to fetch events associated with clicks to malicious URLs that were blocked on Proofpoint TAP. You can choose URL, Attachments, Message Text, or a combination of these threat types.
Threat Status	(Optional) Status of threats based on which you want to fetch events associated with clicks to malicious URLs that were blocked on Proofpoint TAP. You can choose Active, Cleared, False Positive, or a combination of these threat types.

Output

The output contains a non-dictionary value.

operation: Get Permitted Malicious URL Events

Input parameters

Parameter	Description
Time Interval	Time period for which you want to fetch events associated with clicks to malicious URLs that were permitted on Proofpoint TAP. You can choose between Seconds or Time. If you choose Seconds, then in the Since Seconds field, specify the time window in seconds from when you want to fetch events associated with clicks to malicious URLs that were permitted on Proofpoint TAP. If you choose Time, then in the Since TIme field, specify the time window from when you want to fetch events associated with clicks to malicious URLs that were permitted on Proofpoint TAP.
Format	(Optional) Format in which you want to fetch events associated with clicks to malicious URLs that were permitted on Proofpoint TAP. You can choose between JSON or Syslog.
Threat Type	(Optional) Type of threats based on which you want to fetch events associated with clicks to malicious URLs that were permitted on Proofpoint TAP. You can choose URL, Attachments, Message Text, or a combination of these threat types.
Threat Status	(Optional) Status of threats based on which you want to fetch events associated with clicks to malicious URLs that were permitted on Proofpoint TAP. You can choose Active, Cleared, False Positive, or a combination of these threat types.

Output

The output contains the following populated JSON schema:
{
"clicksPermitted": [
{
"campaignId": "",
"classification": "",
"clickIP": "",
"clickTime": "",
"messageID": "",
"recipient": "",
"sender": "",
"senderIP": "",
"threatID": "",
"threatTime": "",
"threatURL": "",
"url": "",
"userAgent": ""
}
]
}

operation: Get Blocked Threat Message Events

Input parameters

Parameter	Description
Time Interval	Time period for which you want to fetch events associated with messages that contain known threats and which were blocked on Proofpoint TAP. You can choose between Seconds or Time. If you choose Seconds, then in the Since Seconds field, specify the time window in seconds from when you want to fetch events associated with messages that contain known threats and which were blocked on Proofpoint TAP. If you choose Time, then in the Since TIme field, specify the time window from when you want to fetch events associated with messages that contain known threats and which were blocked on Proofpoint TAP.
Format	(Optional) Format in which you want to fetch events associated with messages that contain known threats and which were blocked on Proofpoint TAP. You can choose between JSON or Syslog.
Threat Type	(Optional) Type of threats based on which you want to fetch events associated with messages that contain known threats and which were blocked on Proofpoint TAP. You can choose URL, Attachments, Message Text, or a combination of these threat types.
Threat Status	(Optional) Status of threats based on which you want to fetch events associated with messages that contain known threats and which were blocked on Proofpoint TAP. You can choose Active, Cleared, False Positive, or a combination of these threat types.

Output

The output contains the following populated JSON schema:
{
"messagesBlocked": [
{
"ccAddresses": [],
"fromAddress": "",
"headerCC": "",
"headerFrom": "",
"headerReplyTo": "",
"headerTo": "",
"impostorScore": "",
"malwareScore": "",
"messageID": "",
"messageParts": [
{
"contentType": "",
"disposition": "",
"filename": "",
"md5": "",
"oContentType": "",
"sandboxStatus": "",
"sha256": ""
}
],
"threatsInfoMap": [
{
"campaignId": "",
"classification": "",
"threat": "",
"threatId": "",
"threatTime": "",
"threatType": "",
"threatUrl": ""
}
],
"messageTime": "",
"phishScore": "",
"recipient": [],
"replyToAddress": "",
"sender": "",
"senderIP": "",
"spamScore": "",
"subject": ""
}
],
"queryEndTime": ""
}

operation: Get Delivered Threat Message Events

Input parameters

Parameter	Description
Time Interval	Time period for which you want to fetch events associated with delivered messages that contained known threats. You can choose between Seconds or Time. If you choose Seconds, then in the Since Seconds field, specify the time window in seconds from when you want to fetch events associated with delivered messages that contained known threats. If you choose Time, then in the Since TIme field, specify the time window from when you want to fetch events associated with delivered messages that contained known threats.
Format	(Optional) Format in which you want to fetch events associated with delivered messages that contained known threats. You can choose between JSON or Syslog.
Threat Type	(Optional) Type of threats based on which you want to fetch events associated with delivered messages that contained known threats. You can choose URL, Attachments, Message Text, or a combination of these threat types.
Threat Status	(Optional) Status of threats based on which you want to fetch events associated with delivered messages that contained known threats. You can choose Active, Cleared, False Positive, or a combination of these threat types.

Output

The output contains a non-dictionary value.

operation: Get All Events

Input parameters

Parameter	Description
Time Interval	Time period for which you want to fetch events associated with all clicks and all messages related to known threats on Proofpoint TAP. You can choose between Seconds or Time. If you choose Seconds, then in the Since Seconds field, specify the time window in seconds from when you want to fetch events associated with all clicks and all messages related to known threats on Proofpoint TAP. If you choose Time, then in the Since TIme field, specify the time window from when you want to fetch events associated with all clicks and all messages related to known threats on Proofpoint TAP.
Format	(Optional) Format in which you want to fetch events associated with all clicks and all messages related to known threats on Proofpoint TAP. You can choose between JSON or Syslog.
Threat Type	(Optional) Type of threats based on which you want to fetch events associated with all clicks and all messages related to known threats on Proofpoint TAP. You can choose URL, Attachments, Message Text, or a combination of these threat types.
Threat Status	(Optional) Status of threats based on which you want to fetch events associated with all clicks and all messages related to known threats on Proofpoint TAP. You can choose Active, Cleared, False Positive, or a combination of these threat types.

Output

The output contains a non-dictionary value.

operation: Get Events for All Issues

Input parameters

Parameter	Description
Time Interval	Time period for which you want to fetch events associated with all clicks to malicious URLs and all messages delivered that contained a known threat. You can choose between Seconds or Time. If you choose Seconds, then in the Since Seconds field, specify the time window in seconds from when you want to fetch events associated with all clicks to malicious URLs and all messages delivered that contained a known threat. If you choose Time, then in the Since TIme field, specify the time window from when you want to fetch events associated with all clicks to malicious URLs and all messages delivered that contained a known threat.
Format	(Optional) Format in which you want to fetch events associated with all clicks to malicious URLs and all messages delivered that contained a known threat. You can choose between JSON or Syslog.
Threat Type	(Optional) Type of threats based on which you want to fetch events associated with all clicks to malicious URLs and all messages delivered that contained a known threat. You can choose URL, Attachments, Message Text, or a combination of these threat types.
Threat Status	(Optional) Status of threats based on which you want to fetch events associated with all clicks to malicious URLs and all messages delivered that contained a known threat. You can choose Active, Cleared, False Positive, or a combination of these threat types.

Output

The output contains a non-dictionary value.

operation: Get Campaign Details

Input parameters

Parameter	Description
Campaign ID	ID of the campaign whose details you want to retrieve from Proofpoint TAP.

Output

The output contains the following populated JSON schema:
{
"name": "",
"description": "",
"startDate": "",
"campaignMembers": [
{
"subType": "",
"id": "",
"type": "",
"threat": "",
"threatTime": ""
}
],
"actors": [
{
"id": "",
"name": ""
}
],
"malware": [
{
"id": "",
"name": ""
}
],
"techniques": [
{
"id": "",
"name": ""
}
]
}

operation: Get Forensic Details

Input parameters

Parameter	Description
ID Type	Type of ID whose forensic details you want to retrieve from Proofpoint TAP. You can choose between Campaign ID or Threat ID.
Value	Value of the campaign ID or threat ID whose forensic details you want to retrieve from Proofpoint TAP.
Include Campaign Forensics	Select this option to include campaign forensics in the details that you want to retrieve from Proofpoint TAP.

Output

The output contains the following populated JSON schema:
{
"generated": "",
"reports": [
{
"name": "",
"scope": "",
"type": "",
"id": "",
"forensics": [
{
"type": "",
"display": "",
"malicious": "",
"time": "",
"what": {},
"platforms": [
{
"name": "",
"os": "",
"version": ""
}
]
}
]
}
]
}

Included playbooks

The Sample - Proofpoint TAP - 1.0.2 playbook collection comes bundled with the Proofpoint TAP connector. This playbook contains steps using which you can perform all supported actions. You can see the bundled playbooks in the Automation > Playbooks section in FortiSOAR™ after importing the Proofpoint TAP connector.

• Get All Events
• Get Blocked Malicious URL Events
• Get Blocked Threat Message Events
• Get Campaign Details
• Get Delivered Threat Message Events
• Get Events for All Issues
• Get Forensic Details
• Get Permitted Malicious URL Events

Note: If you are planning to use any of the sample playbooks in your environment, ensure that you clone those playbooks and move them to a different collection since the sample playbook collection gets deleted during the connector upgrade and delete.