Skip to main content

Check out Interactive Visual Stories to gain hands-on experience with the SSE product features. Click here.

Skyhigh Security

Incidents API Knowledge Base

  1. Last updated
  2. Save as PDF

API Swagger Documentation

Before you begin, to review an example of Swagger, perform the following steps:

  1.  Download the swagger definition file. 
  2. Start Swagger Editor and import the downloaded file.

Example API curl request

curl -u <username>:<password> -H 'Content-Type: application/json' https://www.myshn.net/shnapi/rest/ex...queryIncidents -d '{"startTime":"2020-04-12T09:30:00.000", "incidentCriteria":{"categories":[{"incidentType":"Alert.Policy.Epo"}]}}'

queryIncidentInformationKeys API

API POST call end point:

https://www.myshn.net/shnapi/rest/ex...nformationKeys

The Query Incident Information Keys API retrieves list of Incident.information keys to access values from the Incident.information map.

Response:

{
"headers": {},
"body": [
{
"type": "AuditViolation",
"informationKeys": {
"accountId": "account id that was being audited",
"category": "category that the audit violation belongs to",
"configType": "configuration type that defines the violation",
"contentItemCreatedOn": "creation date of the item that the incident is reporting on",
"contentItemHierarchy": "hierarchy of the item that the incident is reporting on",
"contentItemId": "id of the item that the incident is reporting on",
"contentItemName": "name of the item that the incident is reporting on",
"contentItemParent": "parent name of the item that the incident is reporting on",
"contentItemSize": "size of the item that the incident is reporting on",
"contentItemType": "type of the item that the incident is reporting on",
"eventId": "unique identifier for an event that caused this incident to be created",
"fileTypes": "list of file metadata types in the specified item",
"isTokenized": "indicates if user identification was tokenized",
"matchLocations": "match locations",
"policyId": "id of the policy that was violated",
"policyName": "name of the policy that was violated",
"region": "region that the item occurred within",
"remediationResponse": "name of the action taken as a response to the incident",
"remediatorName": "name of the remediator",
"resolutionAction": "one of a few different resolution actions the incident can be marked in",
"scanName": "the name of the scan that was run",
"scanRunDate": "the last time the scan was run",
"totalMatchCount": "total match count that were found in the item",
"userAttributes": "custom Active Directory attributes"
}
},
{
"type": "CloudAccessPolicyViolation",
"informationKeys": {
"contentItemCreatedOn": "creation date of the item that the incident is reporting on",
"contentItemHierarchy": "hierarchy of the item that the incident is reporting on",
"contentItemId": "id of the item that the incident is reporting on",
"contentItemName": "name of the item that the incident is reporting on",
"contentItemParent": "parent name of the item that the incident is reporting on",
"contentItemSize": "size of the item that the incident is reporting on",
"contentItemType": "type of the item that the incident is reporting on",
"device": "device that was associated with the incident",
"eventId": "unique identifier for an event that caused this incident to be created",
"fileTypes": "list of file metadata types in the specified item",
"isTokenized": "indicates if user identification was tokenized",
"matchLocations": "match locations",
"policyId": "id of the policy that was violated",
"policyName": "name of the policy that was violated",
"region": "region that the item occurred within",
"remediationResponse": "name of the action taken as a response to the incident",
"remediatorName": "name of the remediator",
"resolutionAction": "one of a few different resolution actions the incident can be marked in",
"totalMatchCount": "total match count that were found in the item",
"userAttributes": "custom Active Directory attributes"
}
},
{
"type": "ConnectedAppsViolation",
"informationKeys": {
"contentItemCreatedOn": "creation date of the item that the incident is reporting on",
"contentItemHierarchy": "hierarchy of the item that the incident is reporting on",
"contentItemId": "id of the item that the incident is reporting on",
"contentItemName": "name of the item that the incident is reporting on",
"contentItemParent": "parent name of the item that the incident is reporting on",
"contentItemSize": "size of the item that the incident is reporting on",
"contentItemType": "type of the item that the incident is reporting on",
"eventId": "unique identifier for an event that caused this incident to be created",
"fileTypes": "list of file metadata types in the specified item",
"matchLocations": "match locations",
"policyId": "id of the policy that was violated",
"policyName": "name of the policy that was violated",
"region": "region that the item occurred within",
"remediationResponse": "name of the action taken as a response to the incident",
"remediatorName": "name of the remediator",
"resolutionAction": "one of a few different resolution actions the incident can be marked in",
"totalMatchCount": "total match count that were found in the item",
"userAttributes": "custom Active Directory attributes"
}
},
{
"type": "EpoViolation",
"informationKeys": {
"contentItemCreatedOn": "creation date of the item that the incident is reporting on",
"contentItemHierarchy": "hierarchy of the item that the incident is reporting on",
"contentItemId": "id of the item that the incident is reporting on",
"contentItemName": "name of the item that the incident is reporting on",
"contentItemParent": "parent name of the item that the incident is reporting on",
"contentItemSize": "size of the item that the incident is reporting on",
"contentItemType": "type of the item that the incident is reporting on",
"destinationUrl": "Destination url for web gateway incidents",
"eventId": "unique identifier for an event that caused this incident to be created",
"fileTypes": "list of file metadata types in the specified item",
"matchLocations": "match locations",
"policyId": "id of the policy that was violated",
"policyName": "name of the policy that was violated",
"region": "region that the item occurred within",
"remediationResponse": "name of the action taken as a response to the incident",
"remediatorName": "name of the remediator",
"resolutionAction": "one of a few different resolution actions the incident can be marked in",
"totalMatchCount": "total match count that were found in the item",
"userAttributes": "custom Active Directory attributes"
}
},
{
"type": "MalwarePolicyViolation",
"informationKeys": {
"accountId": "account id that was being audited",
"checksums": "checksums",
"collaborationSharedLink": "shared link collaboration",
"contentItemCreatedOn": "creation date of the item that the incident is reporting on",
"contentItemHierarchy": "hierarchy of the item that the incident is reporting on",
"contentItemId": "id of the item that the incident is reporting on",
"contentItemName": "name of the item that the incident is reporting on",
"contentItemParent": "parent name of the item that the incident is reporting on",
"contentItemSize": "size of the item that the incident is reporting on",
"contentItemType": "type of the item that the incident is reporting on",
"device": "device that was associated with the incident",
"eventId": "unique identifier for an event that caused this incident to be created",
"externalCollaborators": "List of external collaborators",
"externalCollaboratorsCount": "number of external collaborators",
"fileTypes": "list of file metadata types in the specified item",
"isTokenized": "indicates if user identification was tokenized",
"malwareCategory": "malware category",
"malwareConfidence": "confidence of the malware detection",
"malwareName": "malware name",
"matchLocations": "match locations",
"policyId": "id of the policy that was violated",
"policyName": "name of the policy that was violated",
"region": "region that the item occurred within",
"remediationResponse": "name of the action taken as a response to the incident",
"remediatorName": "name of the remediator",
"resolutionAction": "one of a few different resolution actions the incident can be marked in",
"scanName": "the name of the scan that was run",
"scanRunDate": "the last time the scan was run",
"totalMatchCount": "total match count that were found in the item",
"userAttributes": "custom Active Directory attributes"
}
},
{
"type": "PolicyViolation",
"informationKeys": {
"accountId": "account id that was being audited",
"collaborationSharedLink": "shared link collaboration",
"contentItemCreatedOn": "creation date of the item that the incident is reporting on",
"contentItemHierarchy": "hierarchy of the item that the incident is reporting on",
"contentItemId": "id of the item that the incident is reporting on",
"contentItemName": "name of the item that the incident is reporting on",
"contentItemParent": "parent name of the item that the incident is reporting on",
"contentItemSize": "size of the item that the incident is reporting on",
"contentItemType": "type of the item that the incident is reporting on",
"device": "device that was associated with the incident",
"eventId": "unique identifier for an event that caused this incident to be created",
"externalCollaborators": "list of external collaborators",
"externalCollaboratorsCount": "number of external collaborators",
"fileTypes": "list of file metadata types in the specified item",
"isTokenized": "indicates if user identification was tokenized",
"matchLocations": "match locations",
"policyId": "id of the policy that was violated",
"policyName": "name of the policy that was violated",
"region": "region that the item occurred within",
"remediationResponse": "name of the action taken as a response to the incident",
"remediatorName": "name of the remediator",
"resolutionAction": "one of a few different resolution actions the incident can be marked in",
"scanName": "the name of the scan that was run",
"scanRunDate": "the last time the scan was run",
"source": "source of the policy",
"totalMatchCount": "total match count that were found in the item",
"userAttributes": "custom Active Directory attributes"
}
},
{
"type": "SanctionedAnomaly",
"informationKeys": {
"activityCount": "number of stored activities associated with incident",
"anomalyCategory": "anomaly category that this incident belongs to",
"anomalyCause": "anomaly cause",
"anomalyValue": "event value that exceeded the threshold value which triggered the incident",
"cities": "list of all cities that were involved with incident",
"countries": "list of all countries that were involved with incident",
"emailDomain": "the email domain involved with incident",
"eventId": "unique identifier for an event that caused this incident to be created",
"isPartOfThreat": "indicates this particular incident is a part of a threat",
"isTokenized": "indicates if user identification was tokenized",
"remediationResponse": "name of the action taken as a response to the incident",
"remediatorName": "name of the remediator",
"resolutionAction": "one of a few different resolution actions the incident can be marked in",
"servicesAndAccountIds": "account ids associated with the services",
"sourceIpOrgs": "list of IP organizations associated with incident",
"sourceIps": "list of source IP addresses associated with incident",
"threatCategory": "category of threat that this incident would belong to",
"thresholdDuration": "threshold duration (hourly, daily, weekly, monthly)",
"thresholdValue": "the value of the threshold that triggered the incident",
"uniqueActivityNames": "list of unique activity names that this incident was formed from",
"userAttributes": "custom Active Directory attributes"
}
},
{
"type": "ShadowAnomaly",
"informationKeys": {
"anomalyValue": "event value that exceeded the threshold value which triggered the incident",
"customAttributeName1": "1st tenant defined custom attribute",
"customAttributeName2": "2nd tenant defined custom attribute",
"destinationHost": "destination for event defined as either host domain or IP address",
"thresholdValue": "the value of the threshold that triggered the incident",
"userAction": "action the user performed to trigger the event"
}
},
{
"type": "Threat",
"informationKeys": {
"anomalyCount": "number of underlying anomalies",
"anomalyIds": "comma separated list of underlying anomaly IDs",
"category": "threat category associated with the incident",
"device": "device that was associated with the incident",
"eventId": "unique identifier for an event that caused this incident to be created",
"isTokenized": "indicates if user identification was tokenized",
"remediationResponse": "name of the action taken as a response to the incident",
"remediatorName": "name of the remediator",
"resolutionAction": "one of a few different resolution actions the incident can be marked in",
"userAttributes": "custom Active Directory attributes"
}
},
{
"type": "VulnerabilityViolation",
"informationKeys": {
"accountId": "account id that was being audited",
"configType": "configuration type that defines the violation",
"contentItemCreatedOn": "creation date of the item that the incident is reporting on",
"contentItemHierarchy": "hierarchy of the item that the incident is reporting on",
"contentItemId": "id of the item that the incident is reporting on",
"contentItemName": "name of the item that the incident is reporting on",
"contentItemParent": "parent name of the item that the incident is reporting on",
"contentItemSize": "size of the item that the incident is reporting on",
"contentItemType": "type of the item that the incident is reporting on",
"eventId": "unique identifier for an event that caused this incident to be created",
"fileTypes": "list of file metadata types in the specified item",
"isTokenized": "indicates if user identification was tokenized",
"matchLocations": "match locations",
"policyId": "id of the policy that was violated",
"policyName": "name of the policy that was violated",
"region": "region that the item occurred within",
"remediationResponse": "name of the action taken as a response to the incident",
"remediatorName": "name of the remediator",
"resolutionAction": "one of a few different resolution actions the incident can be marked in",
"scanName": "the name of the scan that was run",
"scanRunDate": "the last time the scan was run",
"totalMatchCount": "total match count that were found in the item",
"userAttributes": "custom Active Directory attributes"
}
}
],
"statusCode": "OK",
"statusCodeValue": 200
}

queryIncidentGroups API

API POST call end point:

https://www.myshn.net/shnapi/rest/ex...IncidentGroups

The API produces a list of incident groups that could be used to by queryIncident API described below to retrieve incidents of specific type(s) and category(s)

Response:

{

    "headers": {},

    "body": [

        "Alert.Access.AnomalousAccessLocation",

        "Alert.Access.AnonymousDataExfiltration",

        "Alert.Access.BruteForceLogin",

        "Alert.Access.BruteForceLoginByLocation",

        "Alert.Access.LoginFailure",

        "Alert.Access.LoginSuccess",

        "Alert.Access.Superhuman",

        "Alert.Admin.Administration",

        "Alert.Admin.UserAccountCreation",

        "Alert.Admin.UserAccountDeletion",

        "Alert.Data.DataAccess",

        "Alert.Data.DataDelete",

        "Alert.Data.DataDownload",

        "Alert.Data.DataSharing",

        "Alert.Data.DataTransfer",

        "Alert.Data.DataUpdates",

        "Alert.Data.DataUpload",

        "Alert.Data.ExternalDataSharing",

        "Alert.Data.LargeReportDownload",

        "Alert.Data.MimeType",

        "Alert.Data.RepeatOffender",

        "Alert.Data.ReportExecution",

        "Alert.Data.ServiceAccessCount",

        "Alert.Data.ServiceUsage",

        "Alert.Policy.Audit",

        "Alert.Policy.CloudAccess",

        "Alert.Policy.ConnectedApps",

        "Alert.Policy.Dlp",

        "Alert.Policy.Epo",

        "Alert.Policy.Malware",

        “Alert.Policy.Vulnerability”,

        "Threat.CompromisedAccount.ExcessiveUsage",

        "Threat.CompromisedAccount.ExcessiveUsageAnomalousLocation",

        "Threat.CompromisedAccount.SuspiciousSuperhuman",

        "Threat.InsiderThreat.HighRiskDataExfiltration",

        "Threat.InsiderThreat.HighVolumeDataExfiltration",

        "Threat.InsiderThreat.InsiderAbnormalBehavior",

        "Threat.PrivilegeAccess.AbnormalUserProvisioning",

        "Threat.PrivilegeAccess.Exfiltration",

        "Threat.PrivilegeAccess.Misuse"

    ],

    "statusCode": "OK",

    "statusCodeValue": 200

}

queryIncident  API

queryIncident API without "?limit=xxx" parameter in the endpoint by default returns 50 incidents. "?limit=xxx" parameter could not be higher than 500.

API POST call end point:

https://www.myshn.net/shnapi/rest/external/api/v1/queryIncidents?limit=500

The API returns 50 incidents by default if "?limit=500" parameter is not specified. The max number of incidents for the "limit" parameter is 500.

NOTE: You can enable the queryIncident API for users with the Incident Management role and the Read Only privilege starting with 6.2.1.

The following are some examples of the API body:

To query incidents of of specific types and categories that were listed by the queryIncidentGroups API (see above)

{
"startTime":"2020-01-01T00:00:00Z",
"incidentCriteria": {
"categories":[
{"incidentType":"Alert","category":"Policy"},
{"incidentType":"Alert","category":"Access"},
{"incidentType":"Alert","category":"Data"}
]
}
}

To query only Shadow incidents

{
"startTime":"2020-01-01T00:00:00Z",
"incidentCriteria": {
"product":"SHADOW"
}
}

To query only Sanctioned incidents

{
"startTime":"2020-01-01T00:00:00Z",
"incidentCriteria": {
"product":"SANCTIONED"
}
}

To query incidents of all categories of type Alert:

{
"startTime":"2020-01-01T00:00:00Z",
"incidentCriteria":{
"categories":[
{"incidentType":"Alert"}
]
}
}

To query all incidents of type Threat

{
"startTime":"2020-01-01T00:00:00Z",
"incidentCriteria":{
"categories":[
{"incidentType":"Threat"}
]
}
}

Example of response:

If number of incidents is higher then API returned, then "nextStartTime" timestamp from a response should be used as "startTime" timestamp in a payload for subsequent API call to get next specified numer of incidents

 

{

    "headers": {},

    "body": {

        "responseInfo": {

            "actualLimit": 1,

            "apiElapsedMillis": 9,

            "error": null,

            "nextOffset": null,

            "nextStartTime": "2020-02-14T23:30:53.324Z",

            "source": "shnapi-08ce8b66c61bc873b.node.usprod.consul"

        },

        "incidents": [

            {

                "activityNames": [

                    "Uploaded"

                ],

                "actorId": "testdlpa1@reallymymail.com",

                "actorIdType": "USER",

                "incidentGroup": "Alert.Policy.Dlp",

                "incidentGroupId": null,

                "incidentId": "DLP-116",

                "incidentRiskScore": 10.0,

                "incidentRiskSeverity": "high",

                "information": {

                  "blockedCollaborators":[],

                    "collaborationSharedLink": false,

                    "contentItemCreatedOn": "2020-02-14T23:28:53.000Z",

                    "contentItemHierarchy": "All Files",

                    "contentItemId": "617008674256",

                    "contentItemName": "5.0.0.boxnote",

                    "contentItemParent": "All Files",

                    "contentItemSize": 263,

                    "contentItemType": "FILE",

                    "device": {

                        "ip": "161.69.122.12"

                    },

                    "externalCollaborators": [],

                    "externalCollaboratorsCount": 0,

                    "fileTypes": [

                        "ASCII Text"

                    ],

                    "matchLocations": [],

                    "policyId": 21780,

                    "policyName": "Box Policy Violation.",

                    "source": "API",

                    "totalMatchCount": 1,

                    "userAttributes": {}

                },

                "instanceId": 3270,

                "instanceName": "Default",

                "responses": [

                    "Allowed"

                ],

                "serviceNames": [

                    "Box"

                ],

                "significantlyUpdatedAt": "2020-02-14T23:30:53.323Z",

                "status": "new",

                "timeCreated": "2020-02-14T23:28:53.000Z",

                "timeModified": "2020-02-14T23:30:53.323Z"

            }

        ]

    },

    "statusCode": "OK",

    "statusCodeValue": 200

}

Additional fields to Incidents API

he below fields are stored in Watchtower so will fit into Incidents API

  1. Source: DLP
  2. Item Created On: APP, AUD, CAP, DLP, EPO, MAL – added "contentItemCreatedOn"
  3. External Collaborators Count: DLP, MAL
  4. Scan Name: AUD, DLP, MAL
  5. Path: DLP, MAL – already as "contentItemHierarchy"
  6. Incident Response (let's call it "incidentResponse" as there is already "response" for anomalies but of a different definition): AUD, APP, CAP, DLP, MAL, THR – already as "response"
  7. Scan Run Date: AUD, DLP, MAL
  8. Match Location (matchFileNames from PolicyResult): DLP, APP, AUD, CAP, EPO, MAL – matchLocations
  9. Custom Active Directory Attributes: DLP, ANO, AUD, APP, CAP, MAL, THR – userAttributes

 

informationContentItemCreatedOn, informationExternalCollaboratorsCount, informationScanName, informationScanRunDate, contentItemHierarchy, informationSource, UserAttributes, totalMatchCount:

syslog_service-2020-01-10T19-20-20.098Z.log:<14>Jan 10 19:19:48 lpvm02-new.app.qa.sjc.shn CEF:0|Skyigh Security|Skyhigh CASB|Anomalies.4.4.1.0|Dlp|Alert

.Policy|3|start=Nov 08 2019 20:33:11.000 UTC suser=viji@shnabc.net activityName=[Modified] actorIdType=USER incidentId=DLP-859 riskSeverity=low

collaborationSharedLink=false informationContentItemCreatedOn=2019-11-08T20:33:03.000Z contentItemHierarchy=All Files/viji/NRT Mw contentItemId=

554747336314 contentItemName=abc3.xls informationContentItemParent=NRT Mw FileSize=31232 contentItemType=FILE sourceIps=73.189.180.192 externalC

ollaborators=[] informationExternalCollaboratorsCount=0 informationFileTypes=[Microsoft Excel] informationMatchLocations=[<MAIN>, <MAIN>, <MAIN>, <MAIN>, <MAIN>, <MAIN>, <MAIN>, <MAIN>, <MAIN>, <MAIN>, <MAIN>, <MAIN>, <MAIN>, <MAIN>] policyId=405595 policyName=manualRem informationSource=API totalMatchCount=14 informationUserAttributesCity=[blahtest] informationUserAttributesCompany=[viji1] informationUserAttributesDepartment=[m

cafee] informationUserAttributesEmail=[viji@shnabc.net] informationUserAttributesName=[viji] informationUserAttributesTitle=[hr] informationUser

AttributesUsername=[viji] instanceId=10551 instanceName=vijishn response=[Allowed] serviceNames=[Box] status=new updatedOn=Nov 08 2019 20:34:30.182 UTC

 

syslog_service-2020-01-10T00-12-15.747Z.log:<14>Jan 10 00:11:44 lpvm02-new.app.qa.sjc.shn CEF:0|Skyhigh Security|Skyhigh CASB|Anomalies.4.4.1.0|Dlp|Alert

.Policy|7|start=Nov 04 2019 19:41:03.882 UTC suser=se-dlp@sedlp.us activityName=[On Demand Scan] actorIdType=USER incidentId=DLP-144 riskSeverit

y=medium collaborationSharedLink=false informationContentItemCreatedOn=2019-07-29T22:47:41.648Z contentItemHierarchy=1byhGTZM54uRsAcqX8bF-sQabWx

ZlcU8o contentItemId=1qTe6H_wrxzfxleY_DyCMAKFZz1MV4sbo contentItemName=nrtmwpol.gif informationContentItemParent=1byhGTZM54uRsAcqX8bF-sQabWxZlcU

8o FileSize=1065149 contentItemType=FILE externalCollaborators=[hdlpids@gmail.com] informationExternalCollaboratorsCount=1 informationFileTypes=

[GIF, Unknown] informationMatchLocations=[] policyId=405595 policyName=manualRem informationRemediationResponse=[Notified via Email] informationScanName=gdr informationScanRunDate=Mon Nov 04 19:40:05 UTC 2019 informationSource=API totalMatchCount=1 instanceId=10597 instanceName=testsedlp

 response=[Quarantined] serviceNames=[Google Drive] status=false positive updatedOn=Nov 04 2019 19:59:47.703 UTC

 

 

syslog_service-2020-01-10T00-12-15.747Z.log:<14>Jan 10 00:11:44 lpvm02-new.app.qa.sjc.shn CEF:0|Skyhigh Security|Skyhigh CASB|Anomalies.4.4.1.0|Dlp|Alert

.Policy|10|start=Nov 04 2019 22:53:48.000 UTC suser=patrick@shnabc.net activityName=[Email] actorIdType=USER incidentId=DLP-217 riskSeverity=hig

h collaborationSharedLink=false informationContentItemCreatedOn=2019-11-04T22:53:48.000Z contentItemId=2E51_78960_2799_10598/2E51327D-A455-440F-

8DB8-CD064A11B49A.1.eml contentItemName=pdf FileSize=2144852 contentItemType=EMAIL externalCollaborators=[] informationExternalCollaboratorsCoun

t=2 informationFileTypes=[Microsoft Outlook Express (EML), ASCII Text, Adobe PDF] informationMatchLocations=[] policyId=405595 policyName=manual

Rem informationSource=API totalMatchCount=1 informationUserAttributesCity=[campbell] informationUserAttributesCompany=[patrick] informationUserA

ttributesDepartment=[mpower] informationUserAttributesEmail=[patrick@shnabc.net] informationUserAttributesName=[patrick] informationUserAttribut

esTitle=[qa] informationUserAttributesUsername=[patrickshn] instanceId=10598 instanceName=patrickshnabc response=[Deleted] serviceNames=[Microso

ft Exchange Online] status=new updatedOn=Nov 04 2019 22:53:54.016 UTC

 

  1. Back to top
  • Was this article helpful?

Recommended articles

  1. Article type
    Topic
  2. Tags
    This page has no tags.