Note
We’ve renamed Microsoft Cloud App Security. It’s now called Microsoft Defender for Cloud Apps. In the coming weeks, we’ll update the screenshots and instructions here and in related pages. For more information about the change, see this announcement. To learn more about the recent renaming of Microsoft security services, see the Microsoft Ignite Security blog.
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
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 |
severityValue | int | The alert’s severity. Possible values include:
0: LOW |
resolutionStatusValue | int | Alert’s status. Possible values include:
0: OPEN |
stories | list | Risk category. Possible values include:
0: THREAT_DETECTION |
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 |
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", "saas": 11161, "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 |
resolutionStatus | integer | eq, neq | Filter by alert resolution status, possible values include:
0: Open |
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.