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

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

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	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 (always one here)
	scrollId	String	Unique ID used for scrolling
responseData		Array	Array of entities
responseData/entityInfo		Object	Generic SaaS entity details
	entityId	String	Unique ID of the Harmony Email & Collaboration entity
	customerId	String	Harmony Email & Collaboration customer ID
	saas	String	Harmony Email & Collaboration supported SaaS name
	saasEntityType	String	Harmony Email & Collaboration supported SaaS entity type name: message, user, file etc.
	entityCreated	DateTime	Time entity was created
	entityUpdated	DateTime	Time entity was updated
	entityActionState	String	If an action was taken on the entity, the entity SaaS state appears
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
	entityId	String	Unique ID of the relevant SaaS entity
	entityType	String	Harmony Email & Collaboration supported SaaS entity type name: message, user, file, etc.
	payload	Object	Complete payload of a security tool scan
	score	String	Security tool result score
	securityResultEntityId	String	Unique ID of the relevant security result entity
	securityResultEntityTy pe	String	Security result entity type
	statusCode	String	Security tool scan status code
	statusDescription	String	Security tool scan status description
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	Shows 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	Original Office 365 Mail/Gmail identifier
	subject	String	Email subject
	received	DateTime	Time email was received
	size	Integer	Email size in KB
	emailLinks	String	Included email links
	attachmentCount	Integer	Number of email attachments
	attachments	Object	An object that describes the email attachment files
	mode	String	inline\|monitor
	recipients	String	Comma-separated list of recipients
	fromEmail	String	Sender's email
	fromDomain	String	Sender's domain
	fromUser	Object	User object in Harmony Email & Collaboration platform
	fromName	String	Sender's name
	to	String	Comma-separated list of recipients
	toUser	Object	User object in Harmony Email & Collaboration platform
	cc	Object	User object in Harmony Email & Collaboration platform
	ccUser	Object	User object in Harmony Email & Collaboration platform
	bcc	String	Bcc email addresses
	bccUser	Object	User object in Harmony Email & Collaboration platform
	replyToEmail	String	Email “reply to” address
	replyToNickname	String	Email “reply to” nickname if used
	isRead	String	true\|false
	isDeleted	String	true\|false
	isIncoming	String	true\|false
	isInternal	String	true\|false
	isOutgoing	String	true\|false
	isQuarantined	String	true\|false
	isRestored	String	true\|false
	isRestoreRequested	String	true\|false
	isRestoreDenied	String	true\|false
	saasSpamVerdict	String	Spam verdict value
	SpfResult	String	SPF value combined

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