The content and samples on this page are created by the pfptcommunity and not created, validated or supported by Proofpoint Inc. Official Proofpoint, out of box (partner) integrations can be found on the Proofpoint Technology Partners page.
Please ★ Star on the top of this page if you like this page! Did you create something cool, we are looking for your help, to extend this page with some cool samples. Please contact us at pfptcommunity@gmail.com if you want to join the pfptcommunity.
- Introduction to REST APIs
- Targeted Attack Protection (TAP)
- Nexus People Risk Explorer (NPRE)
- Spreadsheet or BI Tools - Most Popular
- Code snippets
- Threat Response Auto-Pull (TRAP)
- Protection On Demand (POD)
- Isolation
- Essentials
- Security Awareness Training (PSAT)
- Cloud Access Security Broker (CASB)
- Meta Networks (META)
- Insider Threat Management (ITM)
- Emerging Threats Intelligence (ETI)
Representational State Transfer (REST) Application Programming Interface (API) is a way for applications to seamlessly share data via HTTPS. An API is a building block of code that is used to send data requests from one application to another and deliver data responses back. It’s the messenger who takes a request to the system and returns a response from it. The building block contains endpoints, headers, parameters, and fields. Therefore, you can use the Proofpoint Results API endpoints to request raw data from the platform for use in your Business Intelligence (BI) analysis tools.
A familiar example often used to explain APIs involves ordering food at a restaurant. In this scenario, the waiter is the API. You give him your food request, he takes your food request to the kitchen, the kitchen staff prepares the food, and the waiter returns the food to you. You made a request of the kitchen for food and used the waiter to deliver the request and receive a response (that being the food). So, back to the Proofpoint Results API and how it works. If a customer wants certain data results (the food) from the platform (the kitchen) to use in their business analysis tool, they can use the API (the waiter) to deliver the data request and receive the data response (the food).
What is consuming a REST API? Similarly, the act of consuming or using a REST API means to eat it all up. In context, it means to eat it, swallow it, and digest it — leaving any others in the pile exposed.
JSON stands for JavaScript Object Notation and it is a completely language-independent text format that is mainly used to transmit data between a server and client. The structure of a JSON object is derived from JavaScript object notation syntax, meaning that data is organised in key/value pairs separated by commas, with the whole of the object being wrapped by curly braces and arrays being wrapped by square brackets, like so:
"identity": {
"name": "Winston Wolf",
"email": [
"thewolf@fixaprob.com",
"mr.wolf@fixaprob.com",
"w.wolf@jmail.com"
],
"department": "Operations",
"location": "Amsterdam",
"title": "Problem solver"
}
// * JSON Object Structure Sample
REST implements multiple 'methods' for different types of http request, the following are most popular: - GET: Get resource from the server. - POST: Create resource to the server. You can read more about 4 Most Used REST API Authentication Methods.
Proofpoint provides some lovely REST APIs that can be used to gather information. Below code snippets and reference will help you getting started.
To shift to data-driven security decision making start with the right data. You can think of many, many, many use cases to integrate the cool proofpoint data with other security/risk domains. The Proofpoint data (VAPS) is gold for Security and risk management (SRM) leaders.
Many SRM leaders are creating their own organization specific risk metrics and monitor these with their own dashboarding tools. Key risk indicators from multiple domains (data silos) can be consolidated into a single pane of glass. We have created several Power BI and Excel examples on howto consume proofpoint data directly/natively into BI tools. Below image is an example of NPRE data that is directly pulled into Power BI. This example can be easily adjusted or extended to include other risk indicators for your organization. See the NPRE or TAP section on this page for more details.
Key players BI and their REST API support
Microsoft Power BI - howto Build connector
Tableau (Salesforce) - howto Build connector
Google Data Studio - howto Build connector
Some organizations do not (want to) sync all user data to Azure AD and/or Proofpoint TAP. As a result the TAP Dashboard only shows email addresses. On-prem BI Tooling is very good in collecting data from multiple sources, correlate the data and present it in a friendly way. With these tools, one can collect data from both Proofpoint TAP and Active Directory on-prem and present this in a single pane of glass.
Identity governance is about making sure each person has exactly the access they need to do their jobs without causing risk to the organization. The Proofpoint Very Attacked Person (VAP) data can be easily integrated into your IGA solution to enhance the IGA dataset for decision making. IGA calculates risk scores for users based on authorizations/access. It makes a lot of sense to enrich the data with VAP data. See:
IGA vendors: Atos (Evidian), Brainwave, Broadcom (CA), Clear Skye, Forgerock, Hitachi ID, IBM, Micro Focus, Okta, Omada, One Identity (Quest), Sailpoint, SAP, Saviyint, SecZetta.
Push events to Security Information and Event Management (SIEM) or User / Entity Behavior Analytics (UBA/UEBA) Risk scores are calculated for each user in UB tools.
Many, many other use cases exist; from network infrastructure, endpoint. CrowdStrike, Okta, Palo Alto Networks, Amazon Web Services, Splunk, IBM, ZScaler, Imperva, CyberArk, Deciso, Sailpoint, VMware Carbon Black. See Proofpoint Technology Partners page.
The Threat Insight Dashboard (Targeted Attack Protection) provides several different API endpoints for integration with other products in your security ecosystem.
Official Documentation - Threat Insight Dashboard
Several BI and spreadsheet tools, like Microsoft Power BI and/or Excel or Google's toolset can directly fetch JSON data from an REST endpoint. See the Microsoft doc for more information. Below you can see and download a sample Excel sheet that fetches data from the People endpoint(s).
| Action | Description |
|---|---|
| MS Excel : YouTube Howto Video | Watch getting started with the tap_api_people.xlsx sample sheet |
| MS Excel : YouTube Troubleshoot Video | Watch troubleshoot authorizations and understand the tap_api_people.xlsx sample sheet |
| MS Excel : Download the Spreadsheet | Download the tap_api.xlsx sheet |
| MS Power BI : YouTube Video | Short video tap_api_people.xlsx sample Power BI file |
| MS Power BI : Download the Power BI file | Download the tap_api.pbix sheet |
| MS Power BI : Screenshot | Power BI screenshot Advanced Editor |
| Google Sheets : YouTube Video | Short video tap_api google sheets sample |
| Google Sheets : Download sheet | Download the sheet/script and run |
| Google Data Studio : YouTube Video | Short video Google Data Studio VAP Connector |
Howto: Getting started with Power BI.
- Open Power BI. I recommend downloading Power BI desktop.
- Download the pbix sample from this page and open it in Power BI
- click Transform data
- Select function 'Api call keys'
- Open Advanced Editor
- Set your API credentials in the script
- Go back
- Click Refresh
Howto: Getting started with Excel sheet.
- Download and Open the xlsx sheet and pop-in your API credentials in the Settings tab
- Press Data / Refresh All
- When asked, select "Use anonymous access for this Web content"
The API uses GET requests to retrieve resource representation/information only – and not modify it in any way.
Basic authentication is a simple authentication scheme built into the HTTP protocol. The client sends HTTP requests with the Authorization header that contains the word Basic word followed by a space and a base64-encoded string.
The TAP REST APIrequest uses the following request structure:
method = get
uri = base api path + endpoint + parameter
headers.Authorization = "Basic " + encode.base64 ( principal + ":" + secret )
Below code snippets will help you to get started with the initial authentication and get some data from an endpoint.
| Basic Request Samples | Language |
|---|---|
| tap_api_private.js | Javascript / Node.js Request |
| tap_api_private.py | Python Request |
| tap_api_private.cs | C# (.net framework) Request |
| tap_api_private.java | Java Request |
| tap_api_private.gs | Google Apps Script (GAS) Request |
| tap_api_private.php | PHP Request |
| tap_api_private.pqs | M Code for Excel or Power BI |
| tap_api_private.ps1 | Powershell Request |
| GDS tap connector | Google Data Studio Connector VAPs |
| Useful Code Snippets | Language |
|---|---|
| tap_api_return_vaps.py | Python - returns VAPs with Pandas (analysis) |
Some projects we found on GitHub:
- Powershell wrapper by jfviana
- Powershell wrapper by lambdac0de
- Powershell wrapper by Midnigh7
- Python client by drizzo-tech ***
- Python client by Jason Ford ***
- Python SIEM API Humio Package
- Python SDK for decoding safeurls from Proofpoint, Microsoft, etc
- Python VMware Carbon Black Cloud Endpoint Standard or Enterprise EDR
- Python Splunk Soar Connectors
- Node-RED Client by Anamico
- Javascript URL revealer for Gmail chrome extension by qubitslover
- Javascript URL revealer by Manikantapayasam
- Javascript Link Decoder
- Django project to find decoded urls
- Go Client Library by greenpau
- PHP Link Decode
Nexus People Risk Explorer (NPRE) gives you a unified view of your people-centric risk across the Proofpoint platform and third-party products.
The NPRE API allows you to download a csv file using an API call.
The API is documented in the NPRE Admin Guide that can be found on the community website.
Several BI and spreadsheet tools, like Microsoft Power BI and/or Excel or Google's toolset can directly fetch JSON data from an REST endpoint. See the Microsoft doc for more information. See below some samples that fetches data directly from the NPRE endpoint.
| Action | Description |
|---|---|
| MS Excel : YouTube Video | Short demonstration of the npre_api_people.xlsx sample sheet |
| MS Excel : Download spreadsheet | Download the npre_api_people.xlsx sample |
| MS Power BI : YouTube Demo Video | Short demonstration of the npre_api_csv.pbix Power BI sample file |
| MS Power BI : YouTube Howto Video | Howto getting started with the npre_api_csv.pbix Power BI sample file |
| MS Power BI : Download pbix file | Download the npre_api_csv.pbix Power BI sample file |
| Google Sheets : copy spreadsheet | Copy sheet/gscript and run |
| Google Data Studio : YouTube Demo Video | Short demonstration of NPRE dataset in GDS |
Howto: Getting started with Power BI.
- Try the Excel version first! Both use the same Microsoft M-code, so it's good to see that working as well..
- Open Power BI and download Power BI desktop.
- Download the pbix sample from this page and open it in Power BI
- Watch the howto video
The NPRE API uses mulitple requests to finaly get a pointer to a CSV file.
method = POST
request1 = Get the Bearer Token
request2 = Get the Uri to CSV file using the Bearer Token
request3 = Get CSV file
Below code snippets will help you to get started with the initial authentication and get some data from an endpoint.
| Basic Request Samples | Language |
|---|---|
| npre_api_csv.js | Javascript / Node.js Request |
| npre_api_csv.py | Python Request |
| npre_api_csv.gs | Google Apps Script (GAS) Request |
| npre_api_csv.pqs | M Code for Excel or Power BI |
| npre_sample.csv | Sample CSV file |
| Useful Code Snippets | Language |
|---|---|
| npre_api_csv_test.py | Python test script - output to file |
Threat Response Auto-Pull (TRAP) enables messaging and security administrators to analyze emails and move malicious or unwanted emails to quarantine, after delivery. It follows forwarded mail and distribution lists and creates an auditable activity trail.
e.g. CLEAR Dispositions
https://ptr-docs.proofpoint.com/extensibility-guides/ptr-api/#threat-response-api
Proofpoint Security Awareness Training Results API Documentation and this article on proofpointcommunity.
The PSAT Results API contains five endpoints from which you can retrieve and filter data for your business needs:
- CyberStrength – returns information from CyberStrength
- PhishAlarm – returns information from PhishAlarm information
- Phishing – returns information from ThreatSim simulated phishing campaigns
- Training – returns information from Training assignments
- Users – returns information about Users
- Training Enrollments – returns information from the (beta) User Enrollments Report
| Action | Description |
|---|---|
| MS Excel : YouTube Howto Video | Video PSAT Results API Explorer in Excel |
| MS Excel : Download the Spreadsheet | PSAT Results API Explorer in Excel |
| M Code script | M Code for Excel or Power BI |
Below code snippets will help you to get started with the initial authentication and get some data from an endpoint.
| Code Snippet | Language |
|---|---|
| psat_api_private.js | Javascript / Node.js Request |
| psat_api_private.py | Python Request |
| psat_api_private.gs | Google Apps Script (GAS) Request |
US: results.us.securityeducation.com
EU: results.eu.securityeducation.com
AP: results.ap.securityeducation.com
Cool projects from our friends:
Python module to interact with the Proofpoint Security Awareness Training (PSAT) Results API
PSAT API via Python by ludvikjerabek
------------
The Proofpoint on Demand (PoD) Logging API documentation
https://proofpointcommunities.force.com/community/s/article/Proofpoint-Isolation-API-Guide
Github projects:
Node.Js client subscriber for Proofpoint On-demand's (PoD) Log API
This is a client subscriber to Proofpoint On-demand's (PoD) Log API. The Log API is a websocket service (wss) awaiting connections from clients. You can subscibe to either filter (message) logs or MTA (maillog) logs.
Reporting API will return the past 30 days of data and must be used regularly if full historical data is needed.
https://proofpointcommunities.force.com/community/s/article/Proofpoint-Isolation-API-Guide
API keys and endpoint doc is available in: https://proofpointisolation.com/console
https://urlisolation.com/api/reporting/usage-data
https://proofpointisolation.com/api/reporting/usage-data
https://github.com/sgtdolos/Proofpoint/blob/main/isolation_logs.py
The Proofpoint Essentials API documentation
The API is available across all stacks. As a reference point, you can get to the API documentation here:
Found on Github
The Proofpoint CASB API documentation
The CASB API uses the following request structure:
method = POST
request1 = Get the Bearer Token with your API id(key)/secret
request2 = Get the Data from the endpoint
Some of the commands that are supported by the api:
- Alerts
- Metadata Lookup
- Events API
The Proofpoint META API documentation TODO
The Proofpoint ITM API documentation TODO
https://documentation.observeit.com/saas/threat_library/threat_library_items.htm
https://documentation.observeit.com/configuration_guide/integration_custom.htm
Proofpoint Emerging Threat Intelligence delivers the most timely and accurate threat intelligence. Our fully verified intel provides deeper context and integrates seamlessly with your security tools to enhance your decision-making.
- Features
- ET Intelligence API documentation
- Emerging Threats datasheet
- Admin login console
- Threat Intel Portal
- ETpro vs ETopen
| Action | Description |
|---|---|
| MS Excel : Download Sample | Download the eti_api.xlsx sheet DRAFT |
| Google Sheets : Video demo | Watch Google Sheets sample |
| Google Sheets : Download Sample | Download Google Sheets sample |
| Code Snippet | Language |
|---|---|
| eti_api.js | Javascript / Node.js Request |
| eti_api.py | Python Request |
| eti_api.cs | C# (.net framework) Request |
| eti_api.gs | Google Apps Script (GAS) Request |