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