Proofpoint TAP Connector for VMware Carbon Black Cloud
This is an integration between Proofpoint's TAP product and VMware Carbon Black Cloud (CBC).
Latest Version: v1.3
Release Date: February 2021
This is an integration between Proofpoint TAP and VMware Carbon Black Cloud (CBC). Depending on the configuration of Proofpoint TAP, users are able to access attachments while they're being analyzed by Proofpoint. If the attachment is found to be malicious, Proofpoint TRAP can remove the email from all corporate inboxes, however, if the attachment was downloaded prior to the email being deleted, the malicious file could still be present in the environment on end-user machines.
This integration will pull all email deliveries from x minutes ago (configurable, allows time for detonation, default 30) from Proofpoint TAP. For each attachment collected from Proofpoint, Carbon Black Cloud will search for any processes that match the malicious attachments' SHA256 hash value for a preset, custom time frame (up to 2 weeks). The process GUID's are stored in a local database to prevent duplication in searches and minimize API queries. Once the processes have been identified, the script will take action.
Action options consist of:
- Adding to a CBC Enterprise EDR Watchlist Feed
- Passing the SHA256, process information, and email information to a webhook
- Running a script (kills process/deletes file with CBC Live Response by default)
- Isolating the endpoint
- Moving the endpoint into a different or updated policy
- Python 3.x with sqlite3 - VMware Carbon Black Cloud Endpoint Standard or Enterprise EDR - Proofpoint TAP
Use of the Carbon Black API is governed by the license found in the LICENSE.md file.
This integration is an open sourced project. Please submit a Pull Request for any changes.
Clone the repository into a local folder.
git clone https://github.com/cbcommunity/cbc-proofpoint-malicious-file-detection.git
Install the requirements
pip install -r requirements.txt
config.conf file and update with your configurations
All of the configurable settings for the integration can be found in
Carbon Black Configuration
You will need to create 1 API Access Level and 2 API keys
Custom Access Level Permissions
|Category||Permission Name||.Notation Name||Create||Read||Update||Delete||Execute|
|Live Response||Live Response Session||org.liveresponse.session|
|Live Response||Live Response File||org.liveresponse.file|
|Live Response||Live Response Process||org.liveresponse.process|
Access Levels (API key type)
- Custom [select your Custom Access Level]
The Organization Key can be found in the upper-left of the Settings > API Keys page.
|CarbonBlack||Configure Carbon Black Cloud|
||URL of CBC instance|
||Custom API ID|
||Custom API Secret Key|
||API Secret Secret Key|
||Window of time to search for SHA256 processes. Maximum 2 weeks|
The Service Credentials section allows you to define sets of credentials which are used to authenticate to Proofpoint TAP’s Application Program Interfaces ("API"). You can define as many sets of credentials as you need for different purposes.
To create a service principal, navigate to the Connected Applications tab, click the Create New Credential button. You will then be prompted to define a friendly name, which should be descriptive of the purpose of the credential. After hitting Generate, a lightbox will be displayed with the service principal (username) and secret (password). It is important that you copy these credentials; they will not be redisplayed and are not retrievable after the lightbox has been dismissed.
|Proofpoint||Configure Proofpoint TAP|
||URL for Proofpoint|
||Search for the hashes of attachments that Proofpoint delivered to the inbox|
||Search for the hashes of attachments that Proofpoint blocked|
||Duration of time to search for delivered messages. Max 1 hour|
An optional action is to add a NSX tag to a device. This could be used to isolate the endpoint on a VLAN, enable certain features to inspect network traffic, or just segreate for investigation.
Ensure to add a tag to the
actions section if you complete this section.
||URL for NSX|
Python 3.x ships by default with sqlite. If for some reason you don't have sqlite, you will need to install it (
pip install sqlite3). This database is used to keep track of and de-dupe lookups on the same process.
||Filename of the sqlite3 database|
||Amount of time the records will live in the database|
When a process with the a malicious hash is detected, actions are triggered. By default all actions are disabled. Uncomment and populate with a value to enable.
||Name of watchlist to populate|
||A script to execute|
||Isolate the endpoint?|
||Policy to move offending devices|
||Add the hash to a repuation override (ban the hash)|
||Add a NSX tag to the device|
Running the Script
The script has the following CLI options:
optional arguments: -h, --help show this help message and exit --start-time START_TIME Set the start time in ISO8601 format --end-time END_TIME Set the end time in ISO8601 format --now Output the current GMT time in ISO8601 format. Does not pull any data.
To manually specify a timeframe (min 30 seconds, max 1 hour) use the
Specify a timeframe:
python app.py --start-time 2021-01-01T12:00:00Z --end-time 2021-01-01T13:00:00Z
A Dockerfile is included. First build the image using the following command from the project's root folder:
docker build -t cbc-proofpoint .
Make sure your app/config.conf file is populated with the correct values.
Run the script with the following command:
docker run --rm -it -v $PWD/app:/app --name=cbc-proofpoint cbc-proofpoint
Want to load a dev environment locally to test and tweak the code? Use the following command in the root of the repo folder to launch a dev environment on port 3000 of your local machine.
# Linux, macOS, or PowerShell docker run -it --init \ --name cbc-proofpoint \ -p 3000:3000 \ -v "$(pwd):/home/project:cached" \ theiaide/theia-python:next # Windows (cmd.exe) docker run -it --init \ --name cbc-proofpoint \ -p 3000:3000 \ -v "%cd%:/home/project:cached" \ theiaide/theia-python:next
Once the container is running, open a browser and go to http://localhost:3000. After the console loads, run the following command in the IDE's terminal:
This will update the instance and install the required modules. Use
python3 to execute the scripts.