Skip to main content
McAfee MVISION Cloud

Incidents API Definitions

Criteria

Request object informing system of request filtering criteria.

Name Description Schema

actorIdType
optional

Filter events based on the inclusive actor identifier type recorded. Case sensitive.

enum (USER, IP_ADDRESS)

actorIds
optional

List of inclusive actor identifiers that are either user name or IP address (may be tokenized depending on product configuration), which will be applied to limit response. Empty list implies all users and IP addresses for authenticated tenant.

< string > array

category
optional
Threat category associated with the incident. < string > array

deviceTypes
optional

Filter events based on selected list of inclusive device types. Default (empty) :== all. Case sensitive values :== [ AndroidMobile | BlackberryMobile | iPadMobile | iPhoneMobile | iPodMobile | JavaApplication | LinuxDesktop | MacDesktop | PlaystationGaming | SymbianMobile | WiiGaming | WindowsDesktop | WindowsPhoneMobile | Unknown ]

< string > array

endTime
optional

Filter for ending date-time, exclusive. Default (empty) :== now. Format :== yyyy-mm-ddThh:mm:ss[Z([+-]hh:mm)]
Example"2016-06-15T08:00:00.000Z"

string (date-time)

incidentCriteria
optional

 

IncidentCriteria

permissionType
optional

Filter events based on whether the event was allowed or not. Case sensitive.

enum (ALLOWED, DENIED)

protocolTypes
optional

Filter events based on list of inclusive protocol used. The values for protocols are kept in a database table; here are some case sensitive values :== [ dns | http | https | ntp | Unknown ]

< string > array

savedFilter
optional

If provided, name of a saved filter to use.

string

serviceCategories
optional

Filter events based on list of inclusive service categories used. The values for categories are kept in a database table; here are some case sensitive values :== [ Backup and Archiving | Business Intelligence | Cloud Infrastructure | Cloud Storage | Collaboration | Content Sharing | CRM | Development | e-Commerce | ERP | Finance | Health Care | HR | IaaS Admin Console | IT Services | Legal | Logistics | Marketing | Media | Networking | Procurement | Project Management | Security | Service Desk and Support | Service Proxy | Social Media | Tracking | Uncategorized | Virtual Data Rooms | Web Application ]

< string > array

serviceNames
optional

List of inclusive service names that will be applied to restrict the response. Empty list implies all services of the authenticated tenant.

< string > array

serviceRiskMaximum
optional

Filter events with service risk scores at or greater than this value, inclusive. Higher values reflect more risk. Value must be >= serviceRiskMinimum.
Default10
Minimum value0
Maximum value10

integer (int32)

serviceRiskMinimum
optional

Filter events with service risk scores at or less than this value, inclusive. Higher values reflect more risk. Value must be <= serviceRiskMaximum.
Default0
Minimum value0
Maximum value10

integer (int32)

servicesAndAccountIds
optional
Lists the account IDs associated with the services  

startTime
optional

Filter for starting date-time, inclusive. Default (empty) :== now. Format :== yyyy-mm-ddThh:mm:ss[Z([+-]hh:mm)]
Example"2016-06-15T00:00:00.000Z"
IMPORTANT: Although the API limits 10,000 responses, incidents with the same start time are never split into two API responses. Any subsequent incidents that have the identical start time as the 10,000th incident are returned in the same API response. See Managing API Responses.

string (date-time)

uploadDataMinimum
optional

Filter events to those that have at least upload data of this minimum size, inclusive.

integer (int64)

userRiskMaximum
optional

Filter events with user risk scores at or greater than this value, inclusive. Higher values reflect more risk. Value must be >= userRiskMinimum.
Default10
Minimum value0
Maximum value10

integer (int32)

userRiskMinimum
optional

Filter events with user risk scores at or less than this value, inclusive. Higher values reflect more risk. Value must be <= userRiskMaximum.
Default0
Minimum value0
Maximum value10

integer (int32)

Error

Unexpected error code and description.

Name Description Schema

code
optional

HTTP status codes :== 2xx success, 4xx client error, or 5xx server error.
Minimum value100
Maximum value600
Example400

integer (int32)

details
optional

Additional smaller errors that caused the main error.

Error > array

message
optional

English equivalence of HTTP status code used.
Example"Missing the required parameter 'criteria' when calling getUsersUsage"

string

target
optional

Optional comma-separated field name(s) with issue to resolve.
Example"phoneNumber"

string

Incident

The incident.

Name Description Schema

activityNames
optional

List of names of activities that caused the incident.
Example"Upload Over Time"

< string > array

actorId
optional

Actor identifier that was involved in the incident which may either be user name or IP address (may be tokenized depending on product configuration); see actorIdType.
Example"sam@corp.com"

string

actorIdType
optional

Indicates if the actor identifier is user name or IP address.

enum (User, IpAddress)

incidentGroup
optional

Concatenated incidentType.category.name fields.
Example"Threat.InsiderThreat.HighVolumeDataExfiltration"

string

incidentId
optional

Unique identifier for this particular incident, which includes a three-letter prefix and dash to identify the type of incident:

SHW – Shadow Anomaly
ANO – Sanctioned Anomaly
THR – Threat
APP – Connected Apps Policy Incident
AUD – Audit Policy Incident
CAP – Cloud Access Policy Incident
DLP – Data Loss Policy Incident
EPO – ePO Violation
MAL – Malware Violation

string

incidentRiskScore
optional

Risk score associated with the incident.

number (double)

incidentRiskSeverity
optional

Indication showing amount of risk involved in the incident. Values ::= [ low | medium | high ]

string

information
optional

List of other key:value pairs that are associated with the incident. For a list of the keys, use the queryIncidentInformationKeys command.

KeyValue > array

responses
optional

List of actionable responses for the incident.
Example"Quarantine"

< string > array

serviceNames
optional

List of names of services that were involved in the incident.
Example"google"

< string > array

status
optional

Current state of incident. Values ::= [ new | opened | false positive | resolved | suppressed | archived ]

string

timeCreated
optional

Time the incident was created. Format :== yyyy-mm-ddThh:mm:ss.sssZ
Example: "2016-06-15T00:00:00.000Z"

string (date-time)

timeModified
optional

Time the incident was last modified. Start time and end time filters work with this modified time. Format :== yyyy-mm-ddThh:mm:ss.sssZ
Example"2016-06-15T00:00:00.000Z"

string (date-time)

IncidentCategory

Identifies an incident group by incidentType and category for purposes of filtering. The incidentType is required. Category is optional, if not provided then all categories for incidentType will be included.

Name Description Schema

category
optional

Qualifying category within incidentType; categories are only valid for parenthesized incidentType. Case sensitive values ::= [ Access (Alert) | Admin (Alert) | Audit (Alert) | CompromisedAccount (Threat) | Data (Alert) | InsiderThreat (Threat) | Machine (Alert) | Policy (Alert) | PrivilegeAccess (Threat) ]

string

incidentType
optional

A type of incident. Incident type 'Event' is not yet supported. Case sensitive values ::= [ Alert | Event* | Threat ]

string

IncidentCriteria

Request criteria informing system of inclusive incident filtering. Only categories may be specified per request.

Name Description Schema

categories
optional

Inclusively filter incidents based on a incident group of incidentType and category.

IncidentCategory > array

product
optional

Inclusively filter incidents based on the product.
Default : "SANCTIONED"

enum (SANCTIONED, SHADOW)

Fields

Inclusively filter sanctioned incidents based on incident fields. Multiple fields are ANDed and multiple values are ORed.

The only field names currently supported are policyName and policyId.

Example

"incidentCriteria": {
    "fields": {
        "policyName": ["PII", "Encrypted files"]
    }
}

IncidentInformationKeysByType

The list of information keys available per incident type. The information keys consist of two fields, key ::= key to access value from information map, and value ::= description of the value that will be retrieved.

Name Description Schema

informationKeys
optional

Example{ "accountId" : "account id that was being audited" }

KeyValue > array

type
optional

Type of incident. Values :== [ AuditViolation (Alert.Audit…) | PolicyViolation (Alert.Policy.Dlp) | SanctionedAnomaly (Alert…) | ShadowAnomaly (Alert…) | Threat (Threat…) ]
Example"AuditViolation"

string

IncidentResponse

The response information and incidents.

Name Schema

incidents
optional

Incident > array

responseInfo
optional

ResponseInfo

 

Anomaly

Information about the anomaly.

Name Description Schema
anomalyCategory
optional
Lists the anomaly category an incident belongs to. < string > array
anomalyCount
optional
Number of underlying anomalies < string > array
anomalyIds
optional
Comma separated list of underlying anomaly IDs. ANO- prefix is added to identify that incidents are anomaly. < string > arra

Example:


<14>Aug 15 16:58:16 EC-test00.app.qa.sjc.shn activityNames
[-1],actorId=tp_realtime_activity_enrichment_0_1558064392_19817@shn.com,actorIdType=USER,incidentGroup=Alert.Access.
AnomalousAccessLocation,incidentId=ANO-94483,incidentRiskScore=10.0,incidentRiskSeverity=high,
anomalyCategory="Access Anomalies",anomalyCause="CUSTOMER BLACKLIST",anomalyValue=NA,
informationCities="[shimajiri, nowshera, oslo, moscow, beijing]",countries="[NO, RU, JP, CN, PK]",isPartOfThreat=false,
informationServicesAndAccountIds="
{""Box"":""""}
",informationSourceIpOrgs="[knet techonlogy beijing co. ltd., 
kddi corporation, telenor norge as, channel one russia worldwide, pakistan telecommuication company limited]",
sourceIps="[80.64.104.97, 39.43.30.58, 14.12.145.139, 1.2.2.78, 2.148.4.85]",threatCategory="Compromised Accounts",
thresholdDuration=weekly,thresholdValue=-1,responses="[Admin Login, Admin Login, Admin Login, Admin Login, Admin Login]",
serviceNames=[Box],status=opened,timeCreated="May 17 2019 03:31:52.000 UTC",timeModified="May 17 2019 03:51:01.525 UTC"

Audit

Name Description Schema
alert.policy.audit incidentGroup name (previously alert.audit.category) . < string > array

Example:

<14>Aug 15 17:06:04 EC-test00.app.qa.sjc.shn activityNames=[],actorId=N/A,actorIdType=USER,
incidentGroup=Alert.Policy.Audit,incidentId=AUD-2014,incidentRiskScore=3.0,incidentRiskSeverity=low,
informationAccountId=dc960d72-efdf-4b89-adb8-4c78eb969c83,category=SecurityCenterRecommendations,
informationConfigType=SUBSCRIPTION,informationContentItemId=dc960d72-efdf-4b89-adb8-4c78eb969c83,
informationContentItemName="Microsoft Azure",informationContentItemType=SUBSCRIPTION,informationPolicyId=405763,
informationPolicyName="MFA for accounts with read permissions on subscription not enabled",instanceId=6840,
instanceName=Azure,responses="[Violation Detected]",serviceNames="[Microsoft Azure]",status=new,
timeCreated="Jun 14 2019 06:56:13.518 UTC",timeModified="Aug 15 2019 08:05:59.826 UTC"

KeyValue

A pair of key and value (standard map entry).

Name Description Schema

key
optional

Name of value.

string

value
optional

Actual value.

object

ResponseInfo

Additional information regarding the response.

Name Description Schema

actualLimit
optional

Number of items being returned in this response.

integer (int32)

apiElapsedMillis
optional

Number of milliseconds this response took to execute internally.

integer (int64)

error
optional

 

Error

nextOffset
optional

Offset to be passed as parameter 'offset' to read next block of current query. If nextOffset set to '-1' then no more entries to be read. In time-based queries this field will be set to 'null'.

integer (int64)

nextStartTime
optional

Starting time to be passed as Criteria 'startTime' to read next block continuing current query. This value will be 'null' if not a time-based query else indicating no more entries. Format :== yyyy-mm-ddThh:mm:ss[Z([+-]hh:mm)].
Example"2016-06-15T00:00:00.000Z"

string (date-time)

source
optional

An identifier of the host(s) that were involved in gathering the response. FOR DEBUG PURPOSES.

string

  • Was this article helpful?