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

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:

A common generic area with general SaaS entity details (common to all SaaS entities) entityInfo.
Specific SaaS - Related payload details entityPayload. This section is SaaS-specific and holds all related entity data.
An array of security tools scan results that appears under the entitySecurityResults.
An array of actions taken on the entity that appears under the entityActions.
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": ""
        }
        ]
    }
    ]
}