Microsoft 365 Defender 고급 헌팅 APIMicrosoft 365 Defender Advanced hunting API

중요

개선된 Microsoft 365 보안 센터를 사용할 수 있습니다.The improved Microsoft 365 security center is now available. 이 새로운 환경은 엔드포인트용 Defender, Office 365용 Defender, Microsoft 365 Defender 등을 Microsoft 365 보안 센터에 제공합니다.This new experience brings Defender for Endpoint, Defender for Office 365, Microsoft 365 Defender, and more into the Microsoft 365 security center. 새로운 기능에 대해 알아보세요.Learn what's new.

적용 대상:Applies to:

  • Microsoft 365 DefenderMicrosoft 365 Defender

중요

일부 정보는 상용으로 출시되기 전에 실질적으로 수정될 수 있는 사전 릴리스된 제품과 관련이 있습니다.Some information relates to prereleased product which may be substantially modified before it's commercially released. Microsoft는 여기에서 제공하는 정보와 관련하여 명시적이거나 묵시적인 어떠한 보증도 제공하지 않습니다.Microsoft makes no warranties, express or implied, with respect to the information provided here.

고급 헌팅은 특수하게 생성한 쿼리를 사용하여 Defender에서 지난 30일 동안의 이벤트 데이터를 Microsoft 365 위협 헌팅 도구입니다.Advanced hunting is a threat-hunting tool that uses specially constructed queries to examine the past 30 days of event data in Microsoft 365 Defender. 고급 헌팅 쿼리를 사용하여 비정상적인 활동을 검사하고, 가능한 위협을 감지하고, 공격에 대응할 수 있습니다.You can use advanced hunting queries to inspect unusual activity, detect possible threats, and even respond to attacks. 고급 헌팅 API를 사용하면 프로그래밍적으로 이벤트 데이터를 쿼리할 수 있습니다.The advanced hunting API allows you to programatically query event data.

할당량 및 리소스 할당Quotas and resource allocation

다음 조건은 모든 쿼리와 관련이 있습니다.The following conditions relate to all queries.

  1. 쿼리는 지난 30일 동안의 데이터를 탐색하고 반환합니다.Queries explore and return data from the past 30 days.
  2. 결과는 최대 100,000개 행을 반환할 수 있습니다.Results can return up to 100,000 rows.
  3. 테넌트당 분당 최대 15통의 통화를 만들 수 있습니다.You can make up to 15 calls per minute per tenant.
  4. 다음 15분 주기 후에 테넌트가 100%에 도달하면 쿼리가 차단됩니다.Queries are blocked if the tenant has reached 100% until after the next 15-minute cycle.
  5. 단일 요청이 10분 이상 실행되는 경우 시간이 너무 까다로우며 오류가 반환됩니다.If a single request runs for more than 10 minutes, it will time out and return an error.
  6. HTTP 응답 코드는 전송된 요청 수 또는 할당된 실행 시간으로 할당량에 도달했다는 429 메시지를 나타냅니다.A 429 HTTP response code indicates that you've reached a quota, either by number of requests sent, or by allotted running time. 응답 본문을 읽고 도달한 제한을 이해합니다.Read the response body to understand the limit you have reached.

참고

위에 나열된 모든 할당량(예: 분당 통화 수 15개)은 테넌트 크기당입니다.All quotas listed above (for example 15 calls per min) are per tenant size. 이러한 할당량은 최소값입니다.These quotas are the minimum.

사용 권한Permissions

고급 헌팅 API를 호출하려면 다음 권한 중 하나가 필요합니다.One of the following permissions is required to call the advanced hunting API. 권한을 선택하는 방법을 포함하여 자세한 내용은 Access the Microsoft 365 Defender Protection API를 참조합니다.To learn more, including how to choose permissions, see Access the Microsoft 365 Defender Protection APIs

사용 권한 유형Permission type 사용 권한Permission 사용 권한 표시 이름Permission display name
응용 프로그램Application AdvancedHunting.Read.AllAdvancedHunting.Read.All 고급 쿼리 실행Run advanced queries
위임(직장 또는 학교 계정)Delegated (work or school account) AdvancedHunting.ReadAdvancedHunting.Read 고급 쿼리 실행Run advanced queries

참고

사용자 자격 증명을 사용하여 토큰을 얻을 때:When obtaining a token using user credentials:

  • 사용자에게 '데이터 보기' AD 역할이 필요합니다.The user needs to have the 'View Data' AD role
  • 사용자는 장치 그룹 설정에 따라 장치에 액세스할 수 있습니다.The user needs to have access to the device, based on device group settings.

HTTP 요청HTTP request

POST https://api.security.microsoft.com/api/advancedhunting/run

요청 헤더Request headers

머리글Header Value
권한 부여Authorization Bearer {token} 참고: 필수Bearer {token} Note: required
Content-TypeContent-Type application/jsonapplication/json

요청 본문Request body

요청 본문에 다음 매개 변수를 사용하여 JSON 개체를 제공합니다.In the request body, supply a JSON object with the following parameters:

매개 변수Parameter 유형Type 설명Description
QueryQuery 텍스트Text 실행할 쿼리입니다.The query to run. 참고: 필수Note: required

응답Response

성공하면 이 메서드는 응답 본문에 200 OKQueryResponse 개체를 반환합니다.If successful, this method will return 200 OK, and a QueryResponse object in the response body.

응답 개체에는 세 가지 최상위 속성이 포함되어 있습니다.The response object contains three top-level properties:

  1. 통계 - 쿼리 성능 통계 사전입니다.Stats - A dictionary of query performance statistics.
  2. Schema - 응답의 schema, 각 열에 Name-Type 쌍의 목록입니다.Schema - The schema of the response, a list of Name-Type pairs for each column.
  3. 결과 - 고급 헌팅 이벤트 목록입니다.Results - A list of advanced hunting events.

예시Example

다음 예제에서는 사용자가 아래 쿼리를 보내고 , 및 가 포함된 API 응답 개체를 Stats Schema Results 수신합니다.In the following example, a user sends the query below and receives an API response object containing Stats, Schema, and Results.

QueryQuery

{
    "Query":"DeviceProcessEvents | where InitiatingProcessFileName =~ \"powershell.exe\" | project Timestamp, FileName, InitiatingProcessFileName | order by Timestamp desc | limit 2"
}

응답 개체Response object

{
    "Stats": {
        "ExecutionTime": 4.621215,
        "resource_usage": {
            "cache": {
                "memory": {
                    "hits": 773461,
                    "misses": 4481,
                    "total": 777942
                },
                "disk": {
                    "hits": 994,
                    "misses": 197,
                    "total": 1191
                }
            },
            "cpu": {
                "user": "00:00:19.0468750",
                "kernel": "00:00:00.0156250",
                "total cpu": "00:00:19.0625000"
            },
            "memory": {
                "peak_per_node": 236822432
            }
        },
        "dataset_statistics": [
            {
                "table_row_count": 2,
                "table_size": 102
            }
        ]
    },
    "Schema": [
        {
            "Name": "Timestamp",
            "Type": "DateTime"
        },
        {
            "Name": "FileName",
            "Type": "String"
        },
        {
            "Name": "InitiatingProcessFileName",
            "Type": "String"
        }
    ],
    "Results": [
        {
            "Timestamp": "2020-08-30T06:38:35.7664356Z",
            "FileName": "conhost.exe",
            "InitiatingProcessFileName": "powershell.exe"
        },
        {
            "Timestamp": "2020-08-30T06:38:30.5163363Z",
            "FileName": "conhost.exe",
            "InitiatingProcessFileName": "powershell.exe"
        }
    ]
}