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

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

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