Package: proofpoint-tap
Proofpoint TAP API Client for PythonA python library for Proofpoint's Targeted Attack Protection (TAP) APIInstallationOS X & Linux:python-mpipinstallproofpoint_tapWindows:py-mpipinstallproofpoint_tapUsage and TutorialCreate 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.fromproofpoint_tapimportTAPClientimportjsonsp='<your service principal here>'api_key='<your api key here>'tap=TAPClient(sp,api_key)Class ObjectITMClient(service_principal, api_key, base_url=str)Parameters:service_principal(pos, required) -strService Principal obtained from TAP Dashboardapi_key(pos, required) -strAPI Key obtained from TAP Dashbaordbase_url(optional) -strTAP API Url, only used if a different url is needed, defaults to 'https://tap-api-v2.proofpoint.com/v2'Class MethodsSIEM APIData format: json, syslogMethods:get_all_events - Get all TAP eventsget_clicks_blocked - Get all clicks_blocked eventsget_clicks_permitted - Get all clicks_permitted eventsget_messages_blocked - Get all messages_blocked eventsget_messages_delivered - Get all messages_delivered eventsget_issues - Get all clicks_permitted + messages_delivered eventsParameters:params -dictDictionary of valid paramssinceSeconds -intInteger representing secondsformat -strString representing returned formatValid 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 syntaxsee Proofpoint TAP documentations for valid parameter valuesget_all_events(params=dict, sinceSeconds=int, format=str)Parameters:params(optional) -dictDictionary of supported API parameterssinceSeconds(optional) -intInteger representing the number of seconds to fetch events, defaults to 600format(optional) -strString representing the returned format, defaults to 'json'Accepted values: 'syslog', 'json'get_clicks_blocked(params=dict, sinceSeconds=int, format=str)Parameters:params(optional) -dictDictionary of supported API parameterssinceSeconds(optional) -intInteger representing the number of seconds to fetch events, defaults to 600format(optional) -strString representing the returned format, defaults to 'json'Accepted values: 'syslog', 'json'get_clicks_permitted(params=dict, sinceSeconds=int, format=str)Parameters:params(optional) -dictDictionary of supported API parameterssinceSeconds(optional) -intInteger representing the number of seconds to fetch events, defaults to 600format(optional) -strString representing the returned format, defaults to 'json'Accepted values: 'syslog', 'json'get_messages_blocked(params=dict, sinceSeconds=int, format=str)Parameters:params(optional) -dictDictionary of supported API parameterssinceSeconds(optional) -intInteger representing the number of seconds to fetch events, defaults to 600format(optional) -strString representing the returned format, defaults to 'json'Accepted values: 'syslog', 'json'get_messages_delivered(params=dict, sinceSeconds=int, format=str)Parameters:params(optional) -dictDictionary of supported API parameterssinceSeconds(optional) -intInteger representing the number of seconds to fetch events, defaults to 600format(optional) -strString representing the returned format, defaults to 'json'Accepted values: 'syslog', 'json'get_issues(params=dict, sinceSeconds=int, format=str)Parameters:params(optional) -dictDictionary of supported API parameterssinceSeconds(optional) -intInteger representing the number of seconds to fetch events, defaults to 600format(optional) -strString 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 dictevents=json.loads(tap.get_all_events())Get clicks permitted in the last 30 minutes returned as a syslog stringevents=tap.get_all_events(sinceSeconds=1800,format='syslog')Get issues in the last 30 minutes with threatStatus=active, returned as json stringevents=tap.get_issues(params={'sinceSeconds':600,'threatStatus':'active','format':'json'})Forensics APIData format: jsonMethods:get_forensics - Obtain forensic data for a specific threat or campaignget_forensics(campaignID=str, threatID=str, includeCampaignForensics=bool)Parameters:threatID(required or campaignID) -strthreatId obtained from SIEM API logscampaignID(required or threatID) -strcampaignId obtained from SIEM API logsincludeCampaignForensics(optional) -boolDefaults to FalseGet forensics data examples:Get threat forensics as json stringforensics=tap.get_forensics(threatID='<threatId>')Get threat forensics with campaign info as dictforensics=json.loads(tap.get_forensics(threatID='<threatId>',includeCampaignForensics=True))Get campaign forensics as json stringforensics=tap.get_forensics(campaignID='<campaignId>')Campaign APIData format: jsonMethods:get_campaignget_all_campaignsget_campaign(campaignID)Parameters:campaignID(required) -strcampaignId obtained from SIEM API logsget_all_campaigns(params=dict, interval=str)Parameters:params(optional) -dictDictionary of supported API parametersValid params:'interval' -strA 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' -intThe maximum number of campaign IDs to retrieve, defaults to 100, max is 200'page' -intThe page of results to returninterval(optional) -strA 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 easierIf not provided, a default interval of 1 day from now will be usedGet campaigns data examples:Get campaignID as json stringcampaign=tap.get_campaign('<campaignId>')Get campaignID as dictcampaign=json.loads(tap.get_campaign('<campaignId>')Get all campaign IDs in the last 24 hourscampaigns=tap.get_all_campaigns()Threat APIData format: jsonMethods:get_threat_detailsget_threat_details(threatID)Parameters:threatID(required) -strthreatId obtained from SIEM logsGet campaigns data examples:Get threatID as json stringthreat=tap.get_threat_details('<threatId>')Get threatID as dictthreat=json.loads(tap.get_threat_details('<threatId>')People APIData format: jsonMethods:get_vap_reportget_top_clicker_reportget_vap_report(params=dict, window=int)Parameters:params(optional) -dictDictionary of supported API parametersValid params:'window' -intNumber of days back to report onDefaults to 30 daysAccepted values are 14, 30 and 90'size' -intNumber of results to include'page' -intPage number of results to returnwindow(optional) -intNumber of days back to report onCan be used as a kwarg instead of in params to make syntax easierDefaults to 30 daysAccepted values are 14, 30 and 90get_top_clicker_report(params=dict, window=int)Parameters:params(optional) -dictDictionary of supported API parametersValid params:'window' -intNumber of days back to report onDefaults to 30 daysAccepted values are 14, 30 and 90'size' -intNumber of results to include'page' -intPage number of results to returnwindow(optional) -intNumber of days back to report onCan be used as a kwarg instead of in params to make syntax easierDefaults to 30 daysAccepted values are 14, 30 and 90Get people report examples:Get VAP report for last 30 daysvap=tap.get_vap_report()Get VAP report for the last 90 daysvap=tap.get_vap_report(params={'window':90})Get Top Clicker report for the last 90 days as dictclickers=json.loads(tap.get_top_clicker_report(window=90))URL Decoder APIData format: jsonMethods:decode_urldecode_url(data=dict)Parameters:data(required) -dictDictionary with a list of urls to decodeDictionary scheme:{'urls': ['<url1>', '<url2>']}URL Decode examples:Decode urls as json stringurls={'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 dicturls={"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/&amp;k=oIvRg1%2BdGAgOoM1BIlLLqw%3D%3D%0A&amp;r=IKM5u8%2B%2F%2Fi8EBhWOS%2BqGbTqCC%2BrMqWI%2FVfEAEsQO%2F0Y%3D%0A&amp;m=Ww6iaHO73mDQpPQwOwfLfN8WMapqHyvtu8jM8SjqmVQ%3D%0A&amp;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 History0.0.1Work in progress