Alerts API
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:
- List alerts
- Close benign
- Close false positive
- Close true positive
- Fetch alert
- Mark alert as read
- Mark alert as unread
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 |
Catatan
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.
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 |
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.