Changes from the 1.5 SIEM API

Last updated
Save as PDF

Introduction

As part of the release of Threat Insight Dashboard 2.0, the API offered to pull SIEM-compatible events about clicks and messages will change in a variety of ways. In addition to some new fields, there are a few breaking changes in every output format. You will need to update any process which consumes this data to accommodate the changes. See the documentation for the 2.0 API for additional details about the API's data.

The older 1.5 version of the SIEM API will continue to be available for a limited period after the 2.0 dashboard becomes the default. We expect to decommission the 1.5 API in October of 2016. Please update your systems to use the 2.0 API as soon as possible.

General Service Changes

Scope of Change	Change Description	Action Required
Breaking change	A new host and path are used to access the API.	Point queries to https://tap-api-v2.proofpoint.com/v2.
Breaking change	Authentication is no longer provided via CTS credentials. Instead, special-purpose service credentials are used to authenticate against the service.	Establish service credentials on the 2.0 dashboard, under the Settings page.
Breaking change	The POST HTTP method is no longer supported by the API.	If you're currently using the POST method, you must switch to the HTTP GET method for all calls to the API.

JSON Format Changes

Scope of Change	Event Type	Change Description	Action Required
Breaking change	MSG events	The messageURL field has been removed	It is replaced with per-threat threatURL field in the threatsInfoMap structure.
Breaking change	MSG events	The issueFound field has been removed.	It is replaced with a per-threat threatTime field in the threatsInfoMap structure.
Breaking change	MSG events	The threatIDs field has been removed.	It is replaced with a per-threat threatID field in the threatsInfoMap structure.
Breaking change	MSG events	The recipients field is now an array type instead of a string type.	Messages may have multiple recipients, so an array type must be used instead of a string.
Breaking change	MSGDLV events	The deliveryTime field has been removed.	It is replaced with the messageTime field.
Breaking change	MSGBLK events	The blockTime field has been removed.	It is replaced with the messageTime field.
Change	MSG events	threatTime, threatURL, threat, and campaignID fields added in threatsInfoMap array.	None.
Breaking change	CLK events	The issueFound field has been removed.	It is replaced with the threatTime field.
Breaking change	CLK events	The score field has been removed.	The field was not replaced, so it should not be used.
Breaking change	CLK events	The threatIDs field has been removed.	It is replaced with the threatID field
Breaking change	CLK events	The clickID field has been removed.	The field was not replaced, so it should not be used.
Breaking change	CLK events	The messageID field has been removed.	It is replaced with the GUID field.
Change	CLK events	Added a campaignID field to all CLK events.	None.
Change	CLK events	Added a userAgent field to all CLK events	None.

CEF Format Changes

Scope of Change	Event Type	Change Description	Action Required
Breaking change	All events	The Vendor Device Version has been incremented to "2.0".	Any code which expects version 1.0 should be modified.
Breaking change	All events	The sourceUserName field has been removed.	It is replaced with the suser field, in compliance with the CEF standard.
Change	All events	A leading space in the Extensions field was removed.	None.
Breaking change	MSG events	The Message URL field that was present in cs2 is removed.	cs2 is now used for QID.
Breaking change	MSG events	The Threat IDs field that was present in cs3 is removed.	It is replaced with a per-threat threatID field in the threatsInfoMap structure. cs3 is now used for GUID.
Breaking change	MSG events	The QID field has been moved from cs4 to cs2.	Check for QID values in cs2. cs4 is now used for the scores.
Breaking change	MSG events	The GUID field has been moved from cs5 to cs3.	Check for GUID values in cs3.
Breaking change	MSG events	The threatsInfoMap structure now has key=value pairs, instead of just an array of values.	The field names should be extracted and ignored.
Breaking change	MSG events	The scores fields (cn1, cn1Label, cn2, and cn2Label) have been removed.	All scores are now in a single structure inside the cs4 field.
Breaking change	MSG events	The recipients field is now an array type instead of a string type.	Messages may have multiple recipients, so an array type must be used instead of a string.
Change	MSG events	The deviceCustomDate1Label has been changed to "Threat Time"	None.
Change	MSG events	threatTime, threatURL, threat, and campaignID fields added in threatsInfoMap structure.	None.
Breaking change	CLK events	The cs4 and cs4Label fields which were used for click ID have been removed.	cs4 is now used for Campaign ID.
Change	CLK events	The cs1Label field has been changed to "GUID"	None.
Change	CLK events	The cs3Label field has been changed to "Threat ID"	None.
Change	CLK events	The deviceCustomDate1Label has been changed to "Threat Time"	None.
Change	CLK events	Added campaign ID to all CLK events in cs4 field. Added cs4Label value of "Campaign ID".	None.
Change	CLK events	Added a requestClientApplication field to all CLK events	None.

syslog Format Changes

Scope of Change	Event Type	Change Description	Action Required
Breaking change	All events	All data has been moved into the structured-data section, to be compliant with RFC 5424. The freeform message section is now blank.	Data must now be extracted from the structured data section of the syslog event.
Breaking change	All events	Fields without data have the literal string "null", instead of a blank value	Parsers must extract data correctly.
Breaking change	MSG events	The messageURL field has been removed	It is replaced with per-threat threatURL field in the threatsInfoMap structure.
Breaking change	MSG events	The issueFound field has been removed.	It is replaced with a per-threat threatTime field in the threatsInfoMap structure.
Breaking change	MSG events	The threatIDs field has been removed.	It is replaced with a per-threat threatID field in the threatsInfoMap structure.
Breaking change	MSG events	The recipients field is now an array type instead of a string type.	Messages may have multiple recipients, so an array type must be used instead of a string.
Breaking change	MSGDLV events	The deliveryTime field has been removed.	It is replaced with the messageTime field.
Breaking change	MSGBLK events	The blockTime field has been removed.	It is replaced with the messageTime field.
Breaking change	MSGBLK events	The threatsInfoMap structure now has key=value pairs, instead of just an array of values.	The field names should be extracted and ignored.
Change	MSG events	threatTime, threatURL, threat, and campaignID fields added in threatsInfoMap structure.	None.
Breaking change	CLK events	The issueFound field has been removed.	It is replaced with the threatTime field.
Breaking change	CLK events	The score field has been removed.	The field was not replaced, so it should not be used.
Breaking change	CLK events	The threatIDs field has been removed.	It is replaced with the threatID field
Breaking change	CLK events	The clickID field has been removed.	The field was not replaced, so it should not be used.
Breaking change	CLK events	The messageID field has been removed.	It is replaced with the GUID field.
Change	CLK events	Added a campaignID field to all CLK events.	None.
Change	CLK events	Added a userAgent field to all CLK events	None.