列出警报 APIList alerts API

适用于:Applies to:

想要体验 Microsoft Defender for Endpoint?Want to experience Microsoft Defender for Endpoint? 注册免费试用版。Sign up for a free trial.

备注

如果你是美国政府客户,请使用 Microsoft Defender for Endpoint 中针对美国政府客户的 URI。If you are a US Government customer, please use the URIs listed in Microsoft Defender for Endpoint for US Government customers.

提示

为了提高性能,可以使用距离地理位置更近的服务器:For better performance, you can use server closer to your geo location:

  • api-us.securitycenter.microsoft.comapi-us.securitycenter.microsoft.com
  • api-eu.securitycenter.microsoft.comapi-eu.securitycenter.microsoft.com
  • api-uk.securitycenter.microsoft.comapi-uk.securitycenter.microsoft.com

API 说明API description

检索 Alerts 集合。Retrieves a collection of Alerts.
支持 OData V4 查询Supports OData V4 queries.
OData 支持的运算符:OData supported operators:
$filter``````alertCreationTime lastUpdateTime incidentId on:、、、、 InvestigationId statusseverity category 属性。$filter on: alertCreationTime, lastUpdateTime, incidentId,InvestigationId, status, severity and category properties.
$top 最大值为 10,000$top with max value of 10,000
$skip
$expand of evidence$expand of evidence
请参阅 Microsoft Defender for Endpoint 的 OData 查询示例See examples at OData queries with Microsoft Defender for Endpoint

限制Limitations

  1. 你可以根据配置的保留期获取上次更新的警报。You can get alerts last updated according to your configured retention period.
  2. 最大页面大小为 10,000。Maximum page size is 10,000.
  3. 此 API 的速率限制是每分钟 100 个调用和每小时 1500 个调用。Rate limitations for this API are 100 calls per minute and 1500 calls per hour.

权限Permissions

若要调用此 API,需要以下权限之一。One of the following permissions is required to call this API. 若要了解更多信息(包括如何选择权限),请参阅使用 Microsoft Defender for Endpoint APITo learn more, including how to choose permissions, see Use Microsoft Defender for Endpoint APIs

权限类型Permission type 权限Permission 权限显示名称Permission display name
ApplicationApplication Alert.Read.AllAlert.Read.All "读取所有警报"'Read all alerts'
ApplicationApplication Alert.ReadWrite.AllAlert.ReadWrite.All "读取和写入所有警报"'Read and write all alerts'
委派(工作或学校帐户)Delegated (work or school account) Alert.ReadAlert.Read "读取警报"'Read alerts'
委派(工作或学校帐户)Delegated (work or school account) Alert.ReadWriteAlert.ReadWrite "读取和写入警报"'Read and write alerts'

备注

使用用户凭据获取令牌时:When obtaining a token using user credentials:

  • 用户至少需要具有以下角色权限:"查看数据"权限 (有关详细信息,请参阅创建和管理) The user needs to have at least the following role permission: 'View Data' (See Create and manage roles for more information)
  • 响应将仅包含与用户可以访问的设备关联的警报,根据设备组设置 (请参阅创建和管理设备组,了解详细信息) The response will include only alerts that are associated with devices that the user can access, based on device group settings (See Create and manage device groups for more information)

HTTP 请求HTTP request

GET /api/alerts

请求标头Request headers

名称Name 类型Type 说明Description
AuthorizationAuthorization StringString Bearer {token}。Bearer {token}. 必需Required.

请求正文Request body

EmptyEmpty

响应Response

如果成功,此方法在响应正文中返回 200 OK 和 警报 对象列表。If successful, this method returns 200 OK, and a list of alert objects in the response body.

示例 1 - 默认值Example 1 - Default

请求Request

下面是一个请求示例。Here is an example of the request.

GET https://api.securitycenter.microsoft.com/api/alerts

响应Response

下面是一个响应示例。Here is an example of the response.

备注

为简洁起见,可能会截断此处显示的响应列表。The response list shown here may be truncated for brevity. 所有警报都将从实际呼叫中返回。All alerts will be returned from an actual call.

{
    "@odata.context": "https://api.securitycenter.microsoft.com/api/$metadata#Alerts",
    "value": [
        {
            "id": "da637308392288907382_-880718168",
            "incidentId": 7587,
            "investigationId": 723156,
            "assignedTo": "secop123@contoso.com",
            "severity": "Low",
            "status": "New",
            "classification": "TruePositive",
            "determination": null,
            "investigationState": "Queued",
            "detectionSource": "WindowsDefenderAv",
            "category": "SuspiciousActivity",
            "threatFamilyName": "Meterpreter",
            "title": "Suspicious 'Meterpreter' behavior was detected",
            "description": "Malware and unwanted software are undesirable applications that perform annoying, disruptive, or harmful actions on affected machines. Some of these undesirable applications can replicate and spread from one machine to another. Others are able to receive commands from remote attackers and perform activities associated with cyber attacks.\n\nA malware is considered active if it is found running on the machine or it already has persistence mechanisms in place. Active malware detections are assigned higher severity ratings.\n\nBecause this malware was active, take precautionary measures and check for residual signs of infection.",
            "alertCreationTime": "2020-07-20T10:53:48.7657932Z",
            "firstEventTime": "2020-07-20T10:52:17.6654369Z",
            "lastEventTime": "2020-07-20T10:52:18.1362905Z",
            "lastUpdateTime": "2020-07-20T10:53:50.19Z",
            "resolvedTime": null,
            "machineId": "12ee6dd8c833c8a052ea231ec1b19adaf497b625",
            "computerDnsName": "temp123.middleeast.corp.microsoft.com",
            "rbacGroupName": "MiddleEast",
            "aadTenantId": "a839b112-1253-6432-9bf6-94542403f21c",
            "threatName": null,
            "mitreTechniques": [
                "T1064",
                "T1085",
                "T1220"
            ],
            "relatedUser": {
                "userName": "temp123",
                "domainName": "MIDDLEEAST"
            },
            "comments": [
                {
                    "comment": "test comment for docs",
                    "createdBy": "secop123@contoso.com",
                    "createdTime": "2020-07-21T01:00:37.8404534Z"
                }
            ],
            "evidence": []
        }
        ...
    ]
}

请求Request

下面是一个请求示例。Here is an example of the request.

GET https://api.securitycenter.microsoft.com/api/alerts?$top=10&$expand=evidence

响应Response

下面是一个响应示例。Here is an example of the response.

备注

为简洁起见,可能会截断此处显示的响应列表。The response list shown here may be truncated for brevity. 所有警报都将从实际呼叫中返回。All alerts will be returned from an actual call.

{
    "@odata.context": "https://api.securitycenter.microsoft.com/api/$metadata#Alerts",
    "value": [
        {
            "id": "da637472900382838869_1364969609",
            "incidentId": 1126093,
            "investigationId": null,
            "assignedTo": null,
            "severity": "Low",
            "status": "New",
            "classification": null,
            "determination": null,
            "investigationState": "Queued",
            "detectionSource": "WindowsDefenderAtp",
            "detectorId": "17e10bbc-3a68-474a-8aad-faef14d43952",
            "category": "Execution",
            "threatFamilyName": null,
            "title": "Low-reputation arbitrary code executed by signed executable",
            "description": "Binaries signed by Microsoft can be used to run low-reputation arbitrary code. This technique hides the execution of malicious code within a trusted process. As a result, the trusted process might exhibit suspicious behaviors, such as opening a listening port or connecting to a command-and-control (C&C) server.",
            "alertCreationTime": "2021-01-26T20:33:57.7220239Z",
            "firstEventTime": "2021-01-26T20:31:32.9562661Z",
            "lastEventTime": "2021-01-26T20:31:33.0577322Z",
            "lastUpdateTime": "2021-01-26T20:33:59.2Z",
            "resolvedTime": null,
            "machineId": "111e6dd8c833c8a052ea231ec1b19adaf497b625",
            "computerDnsName": "temp123.middleeast.corp.microsoft.com",
            "rbacGroupName": "A",
            "aadTenantId": "a839b112-1253-6432-9bf6-94542403f21c",
            "threatName": null,
            "mitreTechniques": [
                "T1064",
                "T1085",
                "T1220"
            ],
            "relatedUser": {
                "userName": "temp123",
                "domainName": "MIDDLEEAST"
            },
            "comments": [
                {
                    "comment": "test comment for docs",
                    "createdBy": "secop123@contoso.com",
                    "createdTime": "2021-01-26T01:00:37.8404534Z"
                }
            ],
            "evidence": [
                {
                    "entityType": "User",
                    "evidenceCreationTime": "2021-01-26T20:33:58.42Z",
                    "sha1": null,
                    "sha256": null,
                    "fileName": null,
                    "filePath": null,
                    "processId": null,
                    "processCommandLine": null,
                    "processCreationTime": null,
                    "parentProcessId": null,
                    "parentProcessCreationTime": null,
                    "parentProcessFileName": null,
                    "parentProcessFilePath": null,
                    "ipAddress": null,
                    "url": null,
                    "registryKey": null,
                    "registryHive": null,
                    "registryValueType": null,
                    "registryValue": null,
                    "accountName": "eranb",
                    "domainName": "MIDDLEEAST",
                    "userSid": "S-1-5-21-11111607-1111760036-109187956-75141",
                    "aadUserId": "11118379-2a59-1111-ac3c-a51eb4a3c627",
                    "userPrincipalName": "temp123@microsoft.com",
                    "detectionStatus": null
                },
                {
                    "entityType": "Process",
                    "evidenceCreationTime": "2021-01-26T20:33:58.6133333Z",
                    "sha1": "ff836cfb1af40252bd2a2ea843032e99a5b262ed",
                    "sha256": "a4752c71d81afd3d5865d24ddb11a6b0c615062fcc448d24050c2172d2cbccd6",
                    "fileName": "rundll32.exe",
                    "filePath": "C:\\Windows\\SysWOW64",
                    "processId": 3276,
                    "processCommandLine": "rundll32.exe  c:\\temp\\suspicious.dll,RepeatAfterMe",
                    "processCreationTime": "2021-01-26T20:31:32.9581596Z",
                    "parentProcessId": 8420,
                    "parentProcessCreationTime": "2021-01-26T20:31:32.9004163Z",
                    "parentProcessFileName": "rundll32.exe",
                    "parentProcessFilePath": "C:\\Windows\\System32",
                    "ipAddress": null,
                    "url": null,
                    "registryKey": null,
                    "registryHive": null,
                    "registryValueType": null,
                    "registryValue": null,
                    "accountName": null,
                    "domainName": null,
                    "userSid": null,
                    "aadUserId": null,
                    "userPrincipalName": null,
                    "detectionStatus": "Detected"
                },
                {
                    "entityType": "File",
                    "evidenceCreationTime": "2021-01-26T20:33:58.42Z",
                    "sha1": "8563f95b2f8a284fc99da44500cd51a77c1ff36c",
                    "sha256": "dc0ade0c95d6db98882bc8fa6707e64353cd6f7767ff48d6a81a6c2aef21c608",
                    "fileName": "suspicious.dll",
                    "filePath": "c:\\temp",
                    "processId": null,
                    "processCommandLine": null,
                    "processCreationTime": null,
                    "parentProcessId": null,
                    "parentProcessCreationTime": null,
                    "parentProcessFileName": null,
                    "parentProcessFilePath": null,
                    "ipAddress": null,
                    "url": null,
                    "registryKey": null,
                    "registryHive": null,
                    "registryValueType": null,
                    "registryValue": null,
                    "accountName": null,
                    "domainName": null,
                    "userSid": null,
                    "aadUserId": null,
                    "userPrincipalName": null,
                    "detectionStatus": "Detected"
                }
            ]
        },
        ...
    ]
}

另请参阅See also