Incidents API Knowledge Base

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.

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

}

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