경고 API 나열
적용 대상:
엔드포인트용 Microsoft Defender를 경험하고 싶으신가요? 무료 평가판을 신청하세요.
참고
미국 정부 고객인 경우 미국 정부 고객을 위해 엔드포인트용 Microsoft Defender 나열된 URI를 사용하세요.
팁
성능을 향상시키려면 서버를 지리적 위치에 더 가깝게 사용할 수 있습니다.
- api-us.securitycenter.microsoft.com
- api-eu.securitycenter.microsoft.com
- api-uk.securitycenter.microsoft.com
- api-au.securitycenter.microsoft.com
API 설명
경고 컬렉션을 검색합니다.
OData 지원 연산자:
$filteron:alertCreationTime,lastUpdateTime, ,InvestigationIdincidentId,id,asssignedTo,detectionSource,lastEventTime, ,status및categoryseverity속성.$top최대값이 10,000인 경우$skip$expand의evidence- 엔드포인트용 Microsoft Defender 있는 OData 쿼리의 예제를 참조하세요.
제한 사항
구성된 보존 기간에 따라 마지막으로 업데이트된 경고를 받을 수 있습니다.
최대 페이지 크기는 10,000입니다.
이 API의 속도 제한은 분당 100개의 호출과 시간당 1,500건의 호출입니다.
권한
이 API를 호출하려면 다음 권한 중 하나가 필요합니다. 사용 권한을 선택하는 방법을 포함하여 자세한 내용은 엔드포인트용 Microsoft Defender API 사용을 참조하세요.
| 사용 권한 유형 | 사용 권한 | 사용 권한 표시 이름 |
|---|---|---|
| 응용 프로그램 | Alert.Read.All | Read all alerts |
| 응용 프로그램 | Alert.ReadWrite.All | Read and write all alerts |
| 위임됨(회사 또는 학교 계정) | Alert.Read | Read alerts |
| 위임됨(회사 또는 학교 계정) | Alert.ReadWrite | Read and write alerts |
참고
사용자 자격 증명을 사용하여 토큰을 가져오는 경우:
- 사용자에게는 적어도 다음 역할 권한이
View Data있어야 합니다( 자세한 내용은 역할 Create 및 관리 참조). - 응답에는 디바이스 그룹 설정에 따라 사용자가 액세스할 수 있는 디바이스와 연결된 경고만 포함됩니다(자세한 내용은 디바이스 그룹 Create 및 관리 참조).
디바이스 그룹 만들기는 엔드포인트용 Defender 플랜 1 및 플랜 2에서 지원됩니다.
HTTP 요청
GET /api/alerts
요청 헤더
| 이름 | 유형 | 설명 |
|---|---|---|
| 권한 부여 | String | 전달자 {token}. 필수입니다. |
요청 본문
빈
응답
성공하면 이 메서드는 200 OK 및 응답 본문의 경고 개체 목록을 반환합니다.
예제 1 - 기본값
요청
다음은 요청의 예입니다.
GET https://api.securitycenter.microsoft.com/api/alerts
응답
다음은 응답의 예입니다.
참고
여기에 표시된 응답 목록은 간결하게 잘립니다. 모든 경고는 실제 호출에서 반환됩니다.
{
"@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": "DOMAIN"
},
"comments": [
{
"comment": "test comment for docs",
"createdBy": "secop123@contoso.com",
"createdTime": "2020-07-21T01:00:37.8404534Z"
}
],
"evidence": []
}
...
]
}
예제 2 - 관련 증거가 있는 10개의 최신 경고 가져오기
요청
다음은 요청의 예입니다.
GET https://api.securitycenter.microsoft.com/api/alerts?$top=10&$expand=evidence
응답
다음은 응답의 예입니다.
참고
여기에 표시된 응답 목록은 간결하게 잘립니다. 모든 경고는 실제 호출에서 반환됩니다.
{
"@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": "DOMAIN"
},
"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": "name",
"domainName": "DOMAIN",
"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"
}
]
},
...
]
}
참고 항목
엔드포인트용 Microsoft Defender 사용하는 OData 쿼리
팁
더 자세히 알아보고 싶으신가요? 기술 커뮤니티: 엔드포인트용 Microsoft Defender Tech Community의 Microsoft 보안 커뮤니티와 Engage.
피드백
출시 예정: 2024년 내내 콘텐츠에 대한 피드백 메커니즘으로 GitHub 문제를 단계적으로 폐지하고 이를 새로운 피드백 시스템으로 바꿀 예정입니다. 자세한 내용은 다음을 참조하세요. https://aka.ms/ContentUserFeedback
다음에 대한 사용자 의견 제출 및 보기