Skip to main content
McAfee Enterprise MVISION Cloud

Incidents API Knowledge Base

API Swagger Documentation

Before getting started or just to see a good example of Swagger very easily: 1) download the swagger definition file, then 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",

        "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 100 incidents. "?limit=xxx" parameter could not be higher than 100000.

API POST call end point:

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

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

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

                    "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|McAfee|MVISION Cloud|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|McAfee|MVISION Cloud|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|McAfee|MVISION Cloud|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

 

  • Was this article helpful?