Managing Secured Entities

Get the details of a specific entity

URI - GET

Use this endpoint to retrieve Harmony Email & Collaboration SaaS entity details, if you have the Harmony Email & Collaboration entity ID. Harmony Email & Collaboration keeps a unique global entity identifier for every entity in the system. If you have a single entity ID, you can extract all entity details and related details in a single API call: /search/entity/{entityId}

Request

The request includes HTTP headers (obtained in the authentication/authorization process and used to sign the request) 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-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

Parameter

Type

Required

Format

Description/Sample

entityId

String

Yes

 

Harmony Email & Collaboration internal entity ID, such as: “f05b74da3ee859eea41aeac40aaad3c2”

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-jjshduhuh" \
    -H "Authorization: Bearer 2462b23346ab0642b65d7d094aca5fb4c29fd96d0468deceae2704d258e81497" \
    https://cloudinfra-gw-us.portal.checkpoint.com/app/hec-api/v1.0/search/entity/f05b74da3ee859eea41aeac40aaad3c2

Response

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

The structure includes a responseEnvelope structure and a responseData object that holds an array of returned SaaS entities (a single entity in this case). A SaaS entity structure includes:

  1. A common generic area with general SaaS entity details (common to all SaaS entities) entityInfo.

  2. Specific SaaS - Related payload details entityPayload. This section is SaaS-specific and holds all related entity data.

  3. An array of security tools scan results that appears under the entitySecurityResults.

  4. An array of actions taken on the entity that appears under the entityActions.

  5. An array of possible actions that can be taken on the entity with the corresponding parameters (entityAvailableActions array).

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": {},
            "score": "string"
            "securityResultEntityId": "string"
            "securityResultEntityType": "string"
            "statusCode": "string"
            "statusDescription": "string"
            "verdict": "string"
        },
        "dlp"
        {
            "entityId": "string",
            "entityType": "string"
            "payload": {},
            "score": "string"
            "securityResultEntityId": "string",
            "securityResultEntityType": "string"
            "statusCode": "string"
            "statusDescription": "string",
            "verdict": "string"
        },
        "clicktimeProtection"
        [
        { 
            "entityId": "string",
            "entityType": "string",
            "payload": {},
            "score": "string",
            "securityResultEntityId": "string"
            "securityResultEntityType": "string"
            "statusCode": "string"
            "statusDescription": "string"
            "verdict": "string"]},
            "shadowIt": [
            { 
                "entityId": "string"
                "entityType": "string"
                "payload": {},
                "score": "string"
                "securityResultEntityId": "string",
                "securityResultEntityType": "string"
                "statusCode": "string"
                "statusDescription": "string"
                "verdict": "string"
            ]}, 
            "av": [
                {
                    "entityId": "string"
                    "entityType": "string",
                    "payload": {},
                    "score": "string"
                    "securityResultEntityId": "string",
                    "securityResultEntityType": "string",
                    "statusCode": "string",
                    "statusDescription": "string",
                    "verdict": "string"]
                }
            },
            "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 the 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, then it shows the entity SaaS state.

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

An entire 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

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 the SaaS search 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/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 address

 

fromDomain

String

Senders domain

 

fromUser

Object

User object in Harmony Email & Collaboration platform

 

fromName

String

Sender 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 on 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

 

isRestoreDeclined

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:12: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": "false"
            "isIncoming": "true",
            "isInternal": "false"
            "isOutgoing": "false",
            "isQuarantined": "false",
            "isRestoreRequested": "false"
            "isRestoreDeclined": "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": ""
        }
        ]
    }
    ]
}