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
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 required event types. Possible values are:

  • Phishing

  • Malware

  • Suspicious malware

  • DLP

  • anomaly

  • Shadow_it

  • Malicious_url_click

  • Malicious_url

eventStates

Array of String

 

 

List of required event states. Possible values are:

  • new

  • detected

  • pending

  • remediated

  • dismissed

  • exception

severities

Array of String

 

 

List of required event severity. Possible values are:

  • lowest

  • low

  • medium

  • high

  • critical

startDate

String

Yes

Date- time

Start of required time frame.

Example: ‘2016-08-29T09:12:33.001Z'

endDate

String

 

Date- time

End of required time frame.

Example: '2016-08-29T09:12:33.001Z'

saas

Array of String

 

 

Name of required SaaS. Possible values:

  • office365_emails

  • office365_onedrive

  • office365_sharepoint

  • sharefile

  • slack

  • ms_teams

  • google_mail

description

String

 

 

Substring of the event description. Used to search for the text in the event description field. For example, if the value of this parameter is inbox@email.com then this condition is True if a string inbox@email.com is included in the event description field.

eventIds

Array of String

 

 

This parameter is used to retrieve a list of events by event ID which only requires.

confidenceIndicator

String

 

 

Confidence indicator.

Example: 'malicious'

scrollId

String

Yes (paging)

 

This parameter is used to retrieve large sets of results. The first response includes this parameter and partial result. Use this parameter to retrieve the rest of the results.
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

A container of 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

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

Security event creation time

 

severity

String

Lowest, Low, Medium, High, Critical

 

description

String

Short explanation of the event

 

data

String

Description in the not resolved form

 

additionalData

Object

Raw data of description field

availableEventActions

Array

List of available actions

 

actionName

String

Name of available action

 

actionParameter

String

Action parameter name

 

actions

Array

A list of actions performed on this event

 

actionType

String

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