0
(0)

 Important

The improved Microsoft 365 Defender portal is now available. This new experience brings Defender for Endpoint, Defender for Office 365, Microsoft 365 Defender, and more into the Microsoft 365 Defender portal. Learn what’s new.

Applies to:

  • Microsoft 365 Defender

 Important

Some information relates to prereleased product which may be substantially modified before it’s commercially released. Microsoft makes no warranties, express or implied, with respect to the information provided here.

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. The advanced hunting API allows you to programatically query event data.

Quotas and resource allocation

The following conditions relate to all queries.

  1. Queries explore and return data from the past 30 days.
  2. Results can return up to 100,000 rows.
  3. You can make up to 45 calls per minute per tenant.
  4. Queries are blocked if the tenant has reached 100% until after the next 15-minute cycle.
  5. If a single request runs for more than 10 minutes, it will time out and return an error.
  6. 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.

 Note

All quotas listed above (for example 15 calls per min) are per tenant size. These quotas are the minimum.

Permissions

One of the following permissions is required to call the advanced hunting API. To learn more, including how to choose permissions, see Access the Microsoft 365 Defender Protection APIs

PERMISSIONS
Permission type Permission Permission display name
Application AdvancedHunting.Read.All Run advanced queries
Delegated (work or school account) AdvancedHunting.Read Run advanced queries

 Note

When obtaining a token using user credentials:

  • 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 request

HTTP

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

Request headers

REQUEST HEADERS
Header Value
Authorization Bearer {token} Note: required
Content-Type application/json

Request body

In the request body, supply a JSON object with the following parameters:

REQUEST BODY
Parameter Type Description
Query Text The query to run. Note: required

Response

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 – The schema of the response, a list of Name-Type pairs for each column.
  3. Results – A list of advanced hunting events.

Example

In the following example, a user sends the query below and receives an API response object containing StatsSchema, and Results.

Query

JSON

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

Response object

JSON

{
    "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"
        }
    ]
}

Source : Official Microsoft Brand
Editor by : BEST Antivirus KBS Team

How useful was this post?

Click on a star to rate it!

Average rating 0 / 5. Vote count: 0

No votes so far! Be the first to rate this post.