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.
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):
{
"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:
{
"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": ""
}
]
}
]
}