Search for secured entities

URI - POST

To use this endpoint, send a POST request to retrieve multiple entities with flexible query criteria: /search/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": 
    {
        "entityFilter": 
        {
            "saas": "string",
            "saasEntity": "string",
            "startDate": "DateTime", 
            "endDate": "DateTime"
        },
        "entityExtendedFilter": [
        {
            "saasAttrName": "string", 
            "saasAttrOp": "string",
            "saasAttrValue": "string"
        }
        ],
        "scrollId": "string"
    }
}

Request Body Parameters

The JSON parameters:

Parameter

Type

Required

Format

Description/Sample

requestData

Object

 

 

A container for the action request

entityFilter

Object

 

 

A container for generic query filter (apply to all entities)

entityFilter/saas

string

Yes

 

Name of required SaaS. Possible values:

  • sharefile

  • slack ms_teams

  • office365_emails

  • office365_onedrive

  • office365_sharepoint

  • google_mail

  • box

  • dropbox

entityFilter/ saasEntity

String

 

 

Name of SaaS entity. Possible values:

office365_emails_email

entityFilter/ startDate

String

Yes

Date-time

Start of required time frame.

Example:

‘2019-04-10T09:12:33.001Z'

entityFilter/ endDate

String

Yes

Date-time

End of required time frame.

Example: '2019-04-11T09:12:33.001Z'

entityExtendedFilter

Object

 

 

A container for SaaS specific extended query filter

entityExtendedFilter/ saasAttrName

String

 

 

SaaS criteria attribute name

entityExtendedFilter/ saasAttrOp

String

 

 

SaaS criteria attribute Operator:

  • is

  • contains

  • startsWith

  • isEmpty

  • isNot

  • notContains

  • isNotEmpty

  • greaterThan

  • lessThan

entityExtendedFilter/ saasAttrValue

String

 

 

SaaS criteria attribute value

Additional Request Body Parameters for Email (specific saasAttrName used for email query)

The JSON parameters:

Parameter

Type

Required

Format

Description/Sample

entityExtendedFilter/ saasAttrName

 

 

String

Values for the address from the entity you want to match.

For example, entityPayload.subject

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 “
    {
        "requestData": 
        { 
            "entityFilter": 
            {
                "saas": "office365_emails",
                "saasEntity": "office365_emails_email",
                "startDate": "2020-01-01T00:00:00.000Z",
                "endDate": ""
            },
            "entityExtendedFilter": 
            [
                {
                    "saasAttrName": "entityPayload.fromEmail",
                    "saasAttrOp": "is",
                    "saasAttrValue": "developer@checkpoint.com"
                },
                {
                    "saasAttrName": "entityPayload.attachmentCount",
                    "saasAttrOp": "greaterThan",
                    "saasAttrValue": "0"
                }
            ],
            "scrollId": ""
        }
    }
    ” \
    https://cloudinfra-gw-us.portal.checkpoint.com/app/hec-api/v1.0/search/query

This request sample queries every email message sent from developer@checkpoint.com with attachments.

Response

The response obtained from the service includes an HTTP response code and JSON formatted structure.

The response format is the same as the single entity query. However, the returned entity array may include multiple entities.

If the number of returned SaaS entities is smaller than the entire number of possible responses, a consecutive call must be sent with the returned value of scrollId to continue paging.

Response Structure

The response structure obtained from the service (JSON format):

Copy 
{
    "responseEnvelope": 
    {
        "requestId": "string", 
        "responseCode": 0, 
        "responseText": "string", 
        "additionalText": "string",
        "recordsNumber": 1,
        "totalRecordsNumber": 1, 
        "scrollId": "string"
    },
    "responseData": [
    {
        "entityInfo": 
        { 
            "entityId": "string", 
            "customerId": "string", 
            "saas": "string",
            "saasEntityType": "string",
            "entityCreated": "dateTime",
            "entityUpdated": "dateTime", 
            "entityActionState": "string"
        },
        "entityPayload": {}, 
        "entitySecurityResults": 
        {
            "combinedVerdict": 
            { 
                "ap": "string",
                "dlp": "string", 
                "clicktimeProtection": "string",
                "shadowIt": "string",
                "av": "string"
            },
            "ap": 
            [{
                "entityId": "string", 
                "entityType": "string", 
                "payload": "object",
                "score": "string",
                "securityResultEntityId": "string", 
                "securityResultEntityType": "string", 
                "statusCode": "string", 
                "statusDescription": "string", 
                "verdict": "string"
            }],
            "dlp": "string", 
            "clicktimeProtection": "string",
            "shadowIt": 
                [{
                    "entityId": "string", 
                    "entityType": "string", 
                    "payload": 
                    { 
                        "subject": "string",
                        "from": "string"
                    },
                    "score": "string", 
                    "securityResultEntityId": "string", 
                    "securityResultEntityType": "string", 
                    "statusCode": "string",
                    "statusDescription": "string",
                    "verdict": "clean"
                }],
            "av": "object"
        }
        "entityActions": [
        {
            "entityActionName": "string", 
            "entityActionDate": "dateTime",
            "entityActionResponseCode": "integer",
            "entityActionResponseText": "string", 
            "entityActionState": "string"
        }
        ],
        "entityAvailableActions": [
        {
            "entityActionName": "string",
            "entityActionParam": "string"
        }
        ]
    }
    ]
}

Response Parameters

The response parameters:

Parameter

Type

Description

responseEnvelope

Object

A container of metadata properties.

 

requestId

String

Unique identifier for the event.

 

responseCode

Integer

Status code HTTP API code response.

 

responseTest

String

Human-readable message about the response status.

 

additionalText

String

Additional information.

 

recordsNumber

Integer

Number of records found.

 

totalRecordsNumber

Integer

Total number of records (always one here).

 

scrollId

String

Pagination id to get next batch of records.

responseData

Array

Array of entities.

responseData/entityInfo

Object

Generic SaaS entity details.

 

entityId

String

Unique identifier for the entity.

 

customerId

String

Customer identifier associated with the entity.

 

saas

String

SaaS platform associated with the entity (For example, Office 365, Gmail).

 

saasEntityType

String

Type of the entity in the SaaS context.

Refers to the application, currently office365_emails and google_mail are only supported.

 

entityCreated

DateTime

Timestamp when the entity was created.

 

entityUpdated

DateTime

Timestamp when the entity was last updated.

 

entityActionState

String

Current action state of the entity.

responseData/

entityPayload

 

Object

This object holds SaaS specific data for the Harmony Email & Collaboration entity (email entity data, Drive entity data etc.).

responseData/

entitySecurityResults

 

Array

This array of objects holds security tools scan data

 

combinedVerdict.ap

String

Anti phishing protection verdict.

 

combinedVerdict.dlp

String

Data loss prevention verdict.

 

combinedVerdict.clicktimeProtection

String

Clicktime protection verdict.

 

combinedVerdict.shadowIt

String

Shadow IT verdict.

 

combinedVerdict.av

String

Antivirus verdict.

 

entityId

String

ID of the analyzed entity.

 

entityType

String

ID of the impacted or triggering entity (For example, email Id).

Internal type id of the entity, currently can be only office365_emails_email or google_mail_email.

 

payload

Object

Payload details used for security analysis.

 

score

String

Security score assigned.

 

securityResultEntityId

String

ID of the security result entry.

 

securityResultEntityTy pe

String

Type of the security result entry.

 

statusCode

String

Status code of the security check.

 

statusDescription

String

Description of the security check status.

 

verdict

String

Final verdict of the security analysis.

detail

 

Array of String

List of available actions.

 

loc

String

Location of the error in the request payload (For example, which field caused it).

 

msg

String

Human-readable error message.

 

type

String

Type or category of the validation error.

entityActions

 

Array

List of available actions.

 

entityActionName

String

Action Name.

 

entityActionDate

DateTime

Action activation time.

 

entityActionResponse Code

integer

Action response code.

 

entityActionResponse Text

String

Action response text.

 

entityActionState

Integer

Indication for the action state.

entityAvailableActions

Array

A list of available actions for the entity.

 

entityActionName

String

Action name.

 

entityActionParam

String

Additional action parameter.

Additional Response Parameters for Email (responseData/entityPayload)

The entityPayload object specific details provided for email entity SaaS search:

Note - Some of these search details may appear in the response under the entityPayload response object.

Parameter

Type

Description

responseData/ entityPayload

Object

This object holds SaaS specific data for the Harmony Email & Collaboration entity (email entity data, Drive entity data etc).

 

internetMessageId

String

Unique message identifier.

 

subject

String

Subject line of the email or message.

 

received

DateTime

Timestamp when the message was received.

 

size

Integer

Size of the message in bytes.

 

emailLinks

Array

List of links contained in the email.

 

attachmentCount

Integer

Number of attachments in the message.

 

attachments

Array

List of attachments.

 

mode

String

Rendering mode of the message content (For example, inline).

 

recipients

Array

List of recipient email addresses.

 

fromEmail

String

Sender's email address.

 

fromDomain

String

Domain part of the sender's email.

 

fromUser

Object

Structured information about the sender.

 

fromName

String

Display name of the sender.

 

to

Array

List of 'To' email addresses.

 

toUser

Array

Structured user info for 'To' recipients.

 

cc

Array

List of 'CC' email addresses.

 

ccUser

Array

Structured user info for 'CC' recipients.

 

bcc

Array

List of 'BCC' email addresses.

 

bccUser

Array

Structured user info for 'BCC' recipients.

 

replyToEmail

String

Reply-to email address.

 

replyToNickname

String

Nickname for the reply-to address.

 

isRead

Boolean

Indicates whether the message has been read.

 

isDeleted

Boolean

Indicates whether the message has been deleted.

 

isIncoming

Boolean

Indicates whether the message is incoming.

 

isInternal

Boolean

Indicates whether the message is internal.

 

isOutgoing

Boolean

Indicates whether the message is outgoing.

 

isQuarantined

Boolean

Indicates whether the message is quarantined.

 

isQuarantineNotification

Boolean

Indicates whether it's a quarantine notification.

 

isRestored

Boolean

Indicates whether the message has been restored.

 

isRestoreRequested

Boolean

Indicates whether restore was requested.

 

isRestoreDeclined

Boolean

Indicates whether restore was declined.

 

saasSpamVerdict

String

Spam verdict given by the SaaS platform.

 

SpfResult

String

SPF check result for the email.

Response Sample

A valid response from the service:

Copy 
{
    "responseEnvelope": 
    {
        "requestId": "d290f1ee-6c54-4b01-90e6-d701748f3352",
        "responseCode": 0,
        "responseText": "Success", 
        "additionalText": "", 
        "recordsNumber": 1,
        "totalRecordsNumber": 1, 
        "scrollId": ""
    },
    "responseData": [
    {
        "entityInfo": 
        {
            "entityId": "b05f596bc33cf53b74ea75e37cf66b98", 
            "customerId": "customername",
            "saas": "office365_emails",
            "saasEntityType": "office365_emails_email",
            "entityCreated": "2020-08-29T09:12:33.001Z", 
            "entityUpdated": "2020-08-29T09:13:33.001Z",
            "entityActionState": "Clean"
        },
        "entityPayload": 
        {
            "internetMessageId": "<562714b9-aba3-719f-5286-0b030bbdff77@o365.com>",
            "subject": "this is a test email message",
            "received": "2020-08-29T09:12:33.001Z",
            "size": "35009",
            "emailLinks": "https://www.checkpoint.com",
            "attachmentCount": "",
            "attachments": "",
            "mode": "inline",
            "recipiants": "developer@checkpoint.com", 
            "fromEmail": "manager@gmail.com",
            "fromDomain": "gmail.com",
            "fromUser": "12d14cf0-9698-4bde-9d6d-e45065dd432de", 
            "fromName": "gmail manager",
            "to": "developer@checkpoint.com", "toUser": "
            {
                \"mail\":\"developer@checkpoint.com\",
                \"entity_id\":\"12d14cf0-9698-4bde-9d6d-e49843598595\",
                \"entity_type\":\ "office365_emails_user\"
            }",
            "cc": "",
            "ccUser": "",
            "bcc": "",
            "bccUser": "",
            "replyToEmail": "", "replyToNickName": "",
            "isRead": "true", "isDeleted": "flase", 
            "isIncoming": "true", "isInternal": "false",
            "isOutgoing": "false", "isQuarantined": "false",
            "isQuarantineNotification": "false",
            "isRestoreRequested": "false", 
            "isRestoreDenied": "false", "isRestored": "false",
            "saasSpamVerdict": "", "SpfResult": "pass"
        },
        "entitySecurityResults": 
        { 
            "combinedVerdict":
            { 
                "ap": "phishing", "dlp": null,
                "clicktimeProtection": null, "shadowIt": "clean",
                "av": null
            },
        "ap": 
        [{
            "entityId": "a60ca316d8c4f19a2923114380fb0070", 
            "entityType": "office365_emails_email",
            "payload": { "reasons_by_category": 
            {
                "sender_reputation": 
                [{
                    "short_text": "Insignificant historical reputation with sender",
                    "full_text": "The sending email address hasn't established significant historical reputation with your
                    domain"
                },
                {
                    "short_text": "Low-traffic 'From'-domain",
                    "full_text": "The sender's domain has very low traffic - often indicating low-trust domains"
                }
                ],
                "links": [{
                            "short_text": "Link to a low-traffic site",
                            "full_text": "The email contains link to low-traffic web-sites - often indicating low-trust domains"
                        }]
                }
                },
                "score": "526.670776",
                "securityResultEntityId": "a60ca316d8c4f19a2923114380fb0070", 
                "securityResultEntityType": "checkpoint_ap_scan",
                "statusCode": "0", "statusDescription": null, "verdict": "phishing"
            }],
            "dlp": null, "clicktimeProtection": null, 
            "shadowIt": [{
                "entityId": "a60ca316d8c4f19a2923114380fb0070", "entityType": "office365_emails_email",
                "payload": {
                    "subject": "TEST-0429-1619902351-15",
                    "from": "user@email.com"
                },
            "score": "0.0",
            "securityResultEntityId": "a60ca316d8c4f19a2923114380fb0070",
            "securityResultEntityType": "shadow_it_emails_scan", "statusCode": "clean",
            "statusDescription": "Clean", "verdict": "clean"
            }],
        "av": null
        },
        "entityActions": [
        {}
        ],
        "entityAvailableActions": [
        {
        "entityActionName": "quarantine", "entityActionParam": ""
        },
        {
        "entityActionName": "restore", "entityActionParam": ""
        }
        ]
    }
    ]
}