Managing Security Events

Get the details of a specific security event

URI - GET

To use this endpoint, send a GET request to receive a specific security event by its Harmony Email & Collaboration ID: /event/{eventId}

Request

The request includes HTTP headers obtained during the authentication/authorization process and used to sign the request together with request string parameters.

Request Headers

Header	Type	Required	Format	Description/Sample
x-av-req-id	String	Yes	UUID – Generated and supplied on the request.	d290f1ee-6c54-4b01-90e6
Authorization	Bearer Token	Yes	Bearer <API Access Token>	A string Bearer followed by the API Access Token. See Generating API Access Token. For example, assuming that the API Access Token is 1234, the Bearer Token will be Bearer 1234

Header

Type

Required

Format

Description/Sample

x-av-req-id

String

Yes

UUID – Generated and supplied on the request.

d290f1ee-6c54-4b01-90e6

Authorization

Bearer Token

Yes

Bearer <API Access Token>

A string Bearer followed by the API Access Token. See Generating API Access Token.

For example, assuming that the API Access Token is 1234, the Bearer Token will be Bearer 1234

Request String Parameters

Header	Type	Required	Format	Description/Sample
eventId	String	Yes		Harmony Email & Collaboration internal request ID, such as: “ebb3e4bc8a9b14d7a529bb54ea6991b6”

Request Body

Not applicable for GET method.

Request sample (CURL) format

This request sample shows URI base in USA region. For URI base in other regions, see URLs and URL Base.

Copy

curl -X GET -H "Accept: application/json" \
    -H "x-av-req-id: d290f1ee-6c54-4b01-90e6-d701748f0851" \
    -H "Authorization: Bearer 2462b23346ab0642b65d7d094aca5fb4c29fd96d0468deceae2704d258e81497" \
    https://cloudinfra-gw-us.portal.checkpoint.com/app/hec-api/v1.0/event/ebb3e4bc8a9b14d7a529bb54ea6991b6

Response

The response obtained from the service includes an HTTP response code and JSON formatted structure. It consists of responseEnvelope structure and a responseData object that holds an array of security events.

Each event consists of event details and an array of actions taken on the event entity (under the actions array). The response also includes an array of available actions to take on the event and their relevant parameters (availableEventActions array).

Response Structure

A valid response obtained from the service (JSON format):

Copy

{
    "responseEnvelope":
        {
            "requestId": "string",
            "responseCode": 0,
            "responseText": "string",
            "additionalText": "string",
            "recordsNumber": 1,
            "totalRecordsNumber": 1,
            "scrollId": "string"
        },
    "responseData": 
        [
            {
                "eventId": "string",
                "cusomerId": "string",
                "saas": "string",
                "entityId": "string",
                "state": "string",
                "type": "string",
                "confidenceIndicator": "string",
                "eventCreated": "string",
                "severity": "string",
                "description": "string",
                "data": "string",
                "additionalData": {},
                "availableEventActions": 
                    [
                        {
                            "actionName": "string",
                            "actionParameter": "string"
                        }
                    ],
                "actions": 
                    [
                        {
                            "actionType": "string",
                            "createTime": "string",
                            "relatedEntityId": "string"
                        }
                    ]
            }
        ]
}

Response Parameters

These are the response parameters:

Parameter		Type	Description
responseEnvelope		Object	Container for metadata properties.
	requestId	String	Request ID (from the request header x-av-req-id value)
	responseCode	Integer	0 = Success Other values = Failure
	responseTest	String	The text value of the response
	additionalText	String	Additional information
	recordsNumber	Integer	Number of records in response
	totalRecordsNumber	Integer	Total number of records
	scrollId	String	Unique ID used for scrolling
responseData		Object	An array of event entities
	eventId	String	A unique ID used for scrolling
	customerId	String	Harmony Email & Collaboration customer ID
	saas	String	Name of the relevant SaaS
	entityId	String	Unique ID of the relevant SaaS entity
	state	String	Current state of the security event
	type	String	Security event type
	confidenceIndicator	String	Confidence Indicator
	eventCreated	String	Time the security event was created
	severity	String	Lowest, Low, Medium, High, Critical
	description	String	Short explanation of the event
	data	String	Description in not resolved form
	additionalData	Object	Raw data in description field
availableEventActions		Array	List of available actions
	actionName	String	Name of available action
	actionParameter	String	Action name
actions		Array	A list of actions performed on this event
	actionType	String	Name of performed action
	createTime	String	Date when the action was performed
	relatedEntityId	String	Unique ID of the relevant SaaS entity

Response Sample

A valid response from the service:

Copy

{
    "responseEnvelope": 
    { 
        "responseCode": 0,
        "responseTest": "Success", 
        "additionalText": "", 
        "recordsNumber": 1,
        "totalRecordsNumber": 1,
        "scrollId": "34234345454353343"
    },
    "responseData": 
    {
        "eventId": "7ded0371a3e1475c9a877e452f23a049",
        "customerId": "us:customername",
        "saas": "office365_emails",
        "entityId": "639c16e1aaa3affd5d3fa4fda5e75765",
        "state": "dismissed",
        "type": "dlp",
        "confidenceIndicator": "malicious",
        "eventCreated": "2020-07-24T20:58:27.073355+00:00",
        "severity": "Low",
        "data": "",
        "description": "DLP Engine has detected a leak in ‘please see my credit data’ from user@customer.com", 
        "additionalData": "some links here and additional parameters",
        "availableEventActions": [
            {
                "actionName": "dismiss",
                "actionParameter": {"eventId":"7ded0371a3e1475c9a877e452f23a049"}
            },
            {
                "actionName": "severityChange", 
                "actionParameter": {"newSeverity":"Low"}
            },
            {
                "actionName": "severityChange",
                "actionParameter": {"newSeverity":"Medium"}
            },
            {
            "actionName": "severityChange",
            "actionParameter": {"newSeverity":"High"}
            },
            {
            "actionName": "severityChange",
            "actionParameter": {"newSeverity":"Highest"}
            },
        ]
    }
}