Edit

Alerts API

  • Article

The Alerts API provides you with information about immediate risks identified by Defender for Cloud Apps that require attention. Alerts can result from suspicious usage patterns or from files containing content that violates company policy.

The following lists the supported requests:

Deprecated requests

The following table lists the requests deprecated as obsolete, and the requests that replace them.

Obsolete request Alternative
Bulk dismiss Close false positive
Bulk resolve Close true positive
Dismiss alert Close false positive

Note

The deprecated requests have been mapped to their alternatives to avoid disruption. However, if you are using obsolete requests in your environment, we recommend updating them to their alternatives.

Properties

The response object defines the following properties.

Property Type Description
_id int Alert type identifier
timestamp long Timestamp of when the alert was raised
entities list A list of entities related to the alert
title string The title of the alert
description string The alert's description
isMarkdown bool Flag to indicate if the alert's description is already in HTML
statusValue int The alert's state. Possible values include:

0: UNREAD
1: READ
2: ARCHIVED
severityValue int The alert's severity. Possible values include:

0: LOW
1: MEDIUM
2: HIGH
3: INFORMATIONAL
resolutionStatusValue int Alert's status. Possible values include:

0: OPEN
1: DISMISSED
2: RESOLVED
3: FALSE_POSITIVE
4: BENIGN
5: TRUE_POSITIVE
stories list Risk category. Possible values include:

0: THREAT_DETECTION
1: PRIVILEGED_ACCOUNT_MONITORING
2: COMPLIANCE
3: DLP
4: DISCOVERY
5: SHARING_CONTROL
7: ACCESS_CONTROL
8: CONFIGURATION_MONITORING
evidence list List of short descriptions of main parts of the alert
intent list A field that specifies the kill chain related intent behind the alert. Multiple values can be reported in this field. The intent enumeration values follow the MITRE att@ck enterprise matrix model. Further guidance on the different techniques that make up each intent can be found in MITRE's documentation.
Possible values include:

0: UNKNOWN
1: PREATTACK
2: INITIAL_ACCESS
3: PERSISTENCE
4: PRIVILEGE_ESCALATION
5: DEFENSE_EVASION
6: CREDENTIAL_ACCESS
7: DISCOVERY
8: LATERAL_MOVEMENT
9: EXECUTION
10: COLLECTION
11: EXFILTRATION
12: COMMAND_AND_CONTROL
13: IMPACT
isPreview bool Alerts that have been recently released as GA
audits (optional) list List of event IDs that are related to the alert
threatScore int User investigation priority

Filters

For information about how filters work, see Filters.

The following table describes the supported filters:

Filter Type Operators Description
entity.entity entity pk eq,neq Filter alerts related to specified entities. Example: [{ "id": "entity-id", "inst": 0 }]
entity.ip string eq, neq Filter alerts related to specified IP addresses
entity.service integer eq, neq Filter alerts related to the specified service appId, e.g: 11770
entity.instance integer eq, neq Filter alerts related to the specified instances, e.g: 11770, 1059065
entity.policy string eq, neq Filter alerts related to the specified policies
entity.file string eq, neq Filter alerts related to specified file
alertOpen boolean eq If set to true, returns only open alerts, if set to false, returns only closed alerts
severity integer eq, neq Filter by severity. Possible values include:

0: Low
1: Medium
2: High
resolutionStatus integer eq, neq Filter by alert resolution status, possible values include:

0: Open
1: Dismissed (legacy status)
2: Resolved (legacy status)
3: Closed as false positive
4: Closed as benign
5: Closed as true positive
read boolean eq If set to true, returns only read alerts, if set to false, returns unread alerts
date timestamp lte, gte, range, lte_ndays, gte_ndays Filter by the time when an alert was triggered
resolutionDate timestamp lte, gte, range Filter by the time when an alert was resolved
risk integer eq, neq Filter by risk
alertType integer eq, neq Filter by alert type
ID string eq, neq Filter by alert IDs
source string eq The alert's origin, either built-in or policy

If you run into any problems, we're here to help. To get assistance or support for your product issue, please open a support ticket.