Proofpoint TAP API client library
Project description
Proofpoint TAP API Client for Python
A python library for Proofpoint's Targeted Attack Protection (TAP) API
Installation
OS X & Linux:
python -m pip install proofpoint_tap
Windows:
py -m pip install proofpoint_tap
Usage and Tutorial
Create a front end script to import the TAPClient class and create a new TAPClient object with your TAP Sevice Principal and Key. Use the json module to browse data.
from proofpoint_tap import TAPClient
import json
sp = '<your service principal here>'
api_key = '<your api key here>'
tap = TAPClient(sp, api_key)
Class Object
ITMClient(service_principal, api_key, base_url=str)
Parameters:
- service_principal (pos, required) - str Service Principal obtained from TAP Dashboard
- api_key (pos, required) - str API Key obtained from TAP Dashbaord
- base_url (optional) - str TAP API Url, only used if a different url is needed, defaults to 'https://tap-api-v2.proofpoint.com/v2'
Class Methods
SIEM API
Data format: json, syslog
Methods:
- get_all_events - Get all TAP events
- get_clicks_blocked - Get all clicks_blocked events
- get_clicks_permitted - Get all clicks_permitted events
- get_messages_blocked - Get all messages_blocked events
- get_messages_delivered - Get all messages_delivered events
- get_issues - Get all clicks_permitted + messages_delivered events
Parameters:
- params - dict Dictionary of valid params
- sinceSeconds - int Integer representing seconds
- format - str String representing returned format
Valid params:
- 'interval' (if not included sinceSeconds will be used with default of 600)
- 'sinceSeconds' (Defaults to 600)
- 'sinceTime' (if not included sinceSeconds will be used with default of 600)
- 'format' ('json' or 'syslog', if not included will default to 'json')
- 'threatStatus' ('active', 'cleared', 'falsePositive)
- 'threatType' ('url', 'attachment', 'messageText')
sinceSeconds and format can be used as direct kwargs to provide easier syntax
see Proofpoint TAP documentations for valid parameter values
get_all_events(params=dict, sinceSeconds=int, format=str)
Parameters:
params (optional) - dict Dictionary of supported API parameters
sinceSeconds (optional) - int Integer representing the number of seconds to fetch events, defaults to 600
format (optional) - str String representing the returned format, defaults to 'json'
- Accepted values: 'syslog', 'json'
get_clicks_blocked(params=dict, sinceSeconds=int, format=str)
Parameters:
params (optional) - dict Dictionary of supported API parameters
sinceSeconds (optional) - int Integer representing the number of seconds to fetch events, defaults to 600
format (optional) - str String representing the returned format, defaults to 'json'
- Accepted values: 'syslog', 'json'
get_clicks_permitted(params=dict, sinceSeconds=int, format=str)
Parameters:
params (optional) - dict Dictionary of supported API parameters
sinceSeconds (optional) - int Integer representing the number of seconds to fetch events, defaults to 600
format (optional) - str String representing the returned format, defaults to 'json'
- Accepted values: 'syslog', 'json'
get_messages_blocked(params=dict, sinceSeconds=int, format=str)
Parameters:
params (optional) - dict Dictionary of supported API parameters
sinceSeconds (optional) - int Integer representing the number of seconds to fetch events, defaults to 600
format (optional) - str String representing the returned format, defaults to 'json'
- Accepted values: 'syslog', 'json'
get_messages_delivered(params=dict, sinceSeconds=int, format=str)
Parameters:
params (optional) - dict Dictionary of supported API parameters
sinceSeconds (optional) - int Integer representing the number of seconds to fetch events, defaults to 600
format (optional) - str String representing the returned format, defaults to 'json'
- Accepted values: 'syslog', 'json'
get_issues(params=dict, sinceSeconds=int, format=str)
Parameters:
params (optional) - dict Dictionary of supported API parameters
sinceSeconds (optional) - int Integer representing the number of seconds to fetch events, defaults to 600
format (optional) - str String representing the returned format, defaults to 'json'
- Accepted values: 'syslog', 'json'
Get SIEM events examples:
Get all events in the last 10 minutes returned as a dict
events = json.loads(tap.get_all_events())
Get clicks permitted in the last 30 minutes returned as a syslog string
events = tap.get_all_events(sinceSeconds=1800, format='syslog')
Get issues in the last 30 minutes with threatStatus=active, returned as json string
events = tap.get_issues(
params={
'sinceSeconds': 600,
'threatStatus': 'active',
'format': 'json'
})
Forensics API
Data format: json
Methods:
- get_forensics - Obtain forensic data for a specific threat or campaign
get_forensics(campaignID=str, threatID=str, includeCampaignForensics=bool)
Parameters:
threatID (required or campaignID) - str threatId obtained from SIEM API logs
campaignID (required or threatID) - str campaignId obtained from SIEM API logs
includeCampaignForensics (optional) - bool Defaults to False
Get forensics data examples:
Get threat forensics as json string
forensics = tap.get_forensics(threatID='<threatId>')
Get threat forensics with campaign info as dict
forensics = json.loads(tap.get_forensics(threatID='<threatId>', includeCampaignForensics=True))
Get campaign forensics as json string
forensics = tap.get_forensics(campaignID='<campaignId>')
Campaign API
Data format: json
Methods:
- get_campaign
- get_all_campaigns
get_campaign(campaignID)
Parameters:
campaignID (required) - str campaignId obtained from SIEM API logs
get_all_campaigns(params=dict, interval=str)
Parameters:
params (optional) - dict Dictionary of supported API parameters
- Valid params:
- 'interval' - str
- A string containing an ISO8601-formatted interval i.e '2020-05-01T12:00:00Z/2020-05-01T13:00:00Z'
- If not provided, a default interval of 1 day from now will be used
- 'size' - int
- The maximum number of campaign IDs to retrieve, defaults to 100, max is 200
- 'page' - int
- The page of results to return
- 'interval' - str
interval (optional) - str A string containing an ISO8601-formatted interval i.e '2020-05-01T12:00:00Z/2020-05-01T13:00:00Z'
- Can be used as a kwarg instead of in params to make syntax easier
- If not provided, a default interval of 1 day from now will be used
Get campaigns data examples:
Get campaignID as json string
campaign = tap.get_campaign('<campaignId>')
Get campaignID as dict
campaign = json.loads(tap.get_campaign('<campaignId>')
Get all campaign IDs in the last 24 hours
campaigns = tap.get_all_campaigns()
Threat API
Data format: json
Methods:
- get_threat_details
get_threat_details(threatID)
Parameters:
threatID (required) - str threatId obtained from SIEM logs
Get campaigns data examples:
Get threatID as json string
threat = tap.get_threat_details('<threatId>')
Get threatID as dict
threat = json.loads(tap.get_threat_details('<threatId>')
People API
Data format: json
Methods:
- get_vap_report
- get_top_clicker_report
get_vap_report(params=dict, window=int)
Parameters:
params (optional) - dict Dictionary of supported API parameters
- Valid params:
- 'window' - int Number of days back to report on
- Defaults to 30 days
- Accepted values are 14, 30 and 90
- 'size' - int Number of results to include
- 'page' - int Page number of results to return
- 'window' - int Number of days back to report on
window (optional) - int Number of days back to report on
- Can be used as a kwarg instead of in params to make syntax easier
- Defaults to 30 days
- Accepted values are 14, 30 and 90
get_top_clicker_report(params=dict, window=int)
Parameters:
params (optional) - dict Dictionary of supported API parameters
- Valid params:
- 'window' - int Number of days back to report on
- Defaults to 30 days
- Accepted values are 14, 30 and 90
- 'size' - int Number of results to include
- 'page' - int Page number of results to return
- 'window' - int Number of days back to report on
window (optional) - int Number of days back to report on
- Can be used as a kwarg instead of in params to make syntax easier
- Defaults to 30 days
- Accepted values are 14, 30 and 90
Get people report examples:
Get VAP report for last 30 days
vap = tap.get_vap_report()
Get VAP report for the last 90 days
vap = tap.get_vap_report(params={'window': 90})
Get Top Clicker report for the last 90 days as dict
clickers = json.loads(tap.get_top_clicker_report(window=90))
URL Decoder API
Data format: json
Methods:
- decode_url
decode_url(data=dict)
Parameters:
data (required) - dict Dictionary with a list of urls to decode
- Dictionary scheme:
{'urls': ['<url1>', '<url2>']}
URL Decode examples:
Decode urls as json string
urls = {
'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='
]
}
decoded = tap.decode_url(urls)
Decode multiple urls as dict
urls = {
"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",
"https://urldefense.com/v3/__https://google.com:443/search?q=a*test&gs=ps__;Kw!-612Flbf0JvQ3kNJkRi5Jg!Ue6tQudNKaShHg93trcdjqDP8se2ySE65jyCIe2K1D_uNjZ1Lnf6YLQERujngZv9UWf66ujQIQ$"
]
}
decoded = json.loads(tap.decode_url(urls))
Release History
- 0.0.1
- Work in progress
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for proofpoint_tap-0.0.2-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 69911c2b3b320055b9f4faa082135ec7e098b7c1be9c3ee46a964b77263de08e |
|
MD5 | 4f1a2d37492b99c8390ec2be40dbdc91 |
|
BLAKE2b-256 | 6c29c0922f655a093a38cca915454cd2267c3f62dd0a915c5638fd77e0579bc9 |