Search for a security event

URI - POST

To use this endpoint, send a POST request to retrieve a specific security event or multiple events by flexible query criteria: /event/query

Request

The request includes HTTP headers (obtained in the authentication/authorization process and used to sign the request) with request parameters posted on the request body.

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-d701748f085 1
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-d701748f085 1

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

None

Request Body

All applicable request parameters are posted on the request body JSON:

Copy

{
    "requestData": 
        {
            "eventTypes": ["string"],
            "eventStates": ["string"],
            "severities": ["string"],
            "saas": ["string"],
            "eventIds": ["string"],
            "confidenceIndicator": "string", 
            "startDate": "string", 
            "endDate": "string", 
            "description": "string", 
            "scrollId": "string"
        }
}

Request Body Parameters

The JSON parameters:

Parameter	Type	Required	Format	Description/Sample
eventTypes	Array of String			List of event types to include (For example, phishing, malware).
eventStates	Array of String			States of the events to filter.
severities	Array of String			Severity levels to include (For example, low, medium, high).
startDate	String	Yes	Date- time	Start date of the time window for event search. Example: ‘2016-08-29T09:12:33.001Z'
endDate	String		Date- time	End date of the time window for event search. Example: '2016-08-29T09:12:33.001Z'
saas	Array of String			SaaS provider/source (For example, Office 365, Gmail).
description	String			Readable summary of the event.
eventIds	Array of String			List of specific event IDs to retrieve.
confidenceIndicator	String			Confidence level or score for filtering events.
scrollId	String	Yes (paging)		Pagination id to get next batch of records.

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 POST -H "Accept: application/json" \
    -H "x-av-req-id: d290f1ee-6c54-4b01-90e6-d701748f0851" \
    -H "Authorization: Bearer 2462b23346ab0642b65d7d094aca5fb4c29fd96d0468deceae2704d258e81497" \
    -d "{"startDate":" "2020-01-01T00:00:00.000Z"}" \
    https://cloudinfra-gw-us.portal.checkpoint.com/app/hec-api/v1.0/event/query

This sample queries every security event.

Response

The response obtained from the service includes an HTTP response code and JSON formatted structure. It is similar to the GET request per entity (which returns a single security event in an array) but returns possibly an array of security events.

If the number of returned events is smaller than the total number of possible responses, send a consecutive call with the returned value of scrollId to continue.

Response Structure

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

Copy

{
    "responseEnvelope": 
    { 
        "requestId": "string", 
        "responseCode": 0,
        "responseText": "string", 
        "additionalText": "string", 
        "recordsNumber": 0,
        "totalRecordsNumber": 0,
        "scrollId": "string"
    },
    "responseData": [
    {
        "eventId": "string", 
        "customerId": "string", 
        "saas": "string",
        "state": "string",
        "entityId": "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

The response parameters:

Parameter		Type	Description
responseEnvelope		Object	Container for metadata properties.
	requestId	String	Unique ID to trace the request-response cycle. Helpful for debugging and support.
	responseCode	Integer	HTTP API code response.
	responseTest	String	Human-readable description of the status or error.
	additionalText	String	Need to see an example.
	recordsNumber	Integer	Number of records found.
	totalRecordsNumber	Integer	Total number of records.
	scrollId	String	Pagination ID to get next batch of records.
responseData		Object	An array of event entities.
	eventId	String	Unique identifier for the event.
	customerId	String	Identifier of the customer associated with the event.
	saas	String	SaaS provider/source (For example, Office 365, Gmail).
	entityId	String	ID of the impacted or triggering entity (For example, Email ID).
	state	String	Current state of the event.
	type	String	Type/Category of event (For example, Phishing, Malware).
	confidenceIndicator	String	Indicator of the event's credibility.
	eventCreated	String	Timestamp when the event was created.
	severity	String	Severity of the event (For example, low, medium, high, critical).
	description	String	Readable summary of the event.
	data	String	Security event description (longer description).
	additionalData	Object	Additional information.
availableEventActions		Array	List of available actions.
	actionName	String	List of actions that can be performed ( For example, quarantine, restore, sent to admin).
	actionParameter	Object	List of parameters needed for each action that can be performed (parameter= admin email).
actions		Array	A list of actions performed on this event.
	actionType	String	Action type that was executed (For example, quarantine).
	createTime	String	Timestamp when the action was performed.
	relatedEntityId	String	Returns the security event that triggered the action (quarentine).

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"}
                },
            ]
        }
    }