Skip to content

Commit f78ee23

Browse files
NnachtomyCopilot
Nnachtomy
and
Copilot
committed
Add getHuntingSchema API documentation for beta
Add API reference and resource type documentation for the new security.getHuntingSchema function in Microsoft Defender XDR. New files: - api/security-security-gethuntingschema.md - resources/security-huntingschemaresult.md - resources/security-huntingschematable.md - resources/security-huntingschematablecolumn.md - resources/security-huntingschemafunctions.md - resources/security-huntingschemabuiltinfunction.md - resources/security-huntingschemasavedfunction.md - resources/security-huntingschemafunctionparameter.md - changelog/Microsoft.M365.Defender.json (updated) Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
1 parent e40c35d commit f78ee23

9 files changed

Lines changed: 1397 additions & 821 deletions

‎api-reference/beta/api/security-security-gethuntingschema.md‎

Lines changed: 173 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,173 @@
1+
---
2+
title: "security: getHuntingSchema"
3+
description: "Retrieve the advanced hunting schema accessible to the signed-in user."
4+
author: "nitzanfrogel"
5+
ms.localizationpriority: medium
6+
ms.subservice: "security"
7+
doc_type: apiPageType
8+
ms.date: 05/13/2026
9+
---
10+
11+
# security: getHuntingSchema
12+
13+
Namespace: microsoft.graph.security
14+
15+
[!INCLUDE [beta-disclaimer](../../includes/beta-disclaimer.md)]
16+
17+
Retrieve the advanced hunting schema accessible to the signed-in user, including the tables and functions the user is authorized to query and invoke in [advanced hunting](/microsoft-365/security/defender/advanced-hunting-overview?view=o365-worldwide&preserve-view=true) with Microsoft Defender XDR.
18+
19+
The returned schema reflects the user's effective permissions. Each user within a tenant may have a different effective schema depending on their role and access level.
20+
21+
Common use cases include:
22+
23+
- **Preventing unauthorized queries**: Determine which tables and functions a user can access before executing Kusto queries, reducing the risk of authorization failures.
24+
- **Permission-aware query generation**: Enable applications and tools to construct queries dynamically based on the user's effective schema.
25+
26+
[!INCLUDE [national-cloud-support](../../includes/global-us.md)]
27+
28+
## Permissions
29+
30+
Choose the permission or permissions marked as least privileged for this API. Use a higher privileged permission or permissions [only if your app requires it](/graph/permissions-overview#best-practices-for-using-microsoft-graph-permissions). For details about delegated and application permissions, see [Permission types](/graph/permissions-overview#permission-types). To learn more about these permissions, see the [permissions reference](/graph/permissions-reference).
31+
32+
<!-- { "blockType": "permissions", "name": "security_security_gethuntingschema" } -->
33+
[!INCLUDE [permissions-table](../includes/permissions/security-security-gethuntingschema-permissions.md)]
34+
35+
## HTTP request
36+
37+
<!-- {
38+
"blockType": "ignored"
39+
}
40+
-->
41+
```http
42+
GET /security/getHuntingSchema
43+
```
44+
45+
## Request headers
46+
47+
|Name|Description|
48+
|:---|:---|
49+
|Authorization|Bearer {token}. Required. Learn more about [authentication and authorization](/graph/auth/auth-concepts).|
50+
51+
## Request body
52+
53+
Don't supply a request body for this method.
54+
55+
## Response
56+
57+
If successful, this function returns a `200 OK` response code and a [huntingSchemaResult](../resources/security-huntingschemaresult.md) in the response body.
58+
59+
## Examples
60+
61+
### Request
62+
63+
<!-- {
64+
"blockType": "request",
65+
"name": "security_gethuntingschema"
66+
}
67+
-->
68+
```http
69+
GET https://graph.microsoft.com/beta/security/getHuntingSchema
70+
```
71+
72+
### Response
73+
74+
<!-- {
75+
"blockType": "response",
76+
"@odata.type": "microsoft.graph.security.huntingSchemaResult",
77+
"truncated": true
78+
}
79+
-->
80+
```http
81+
HTTP/1.1 200 OK
82+
Content-type: application/json
83+
84+
{
85+
"tables": [
86+
{
87+
"name": "DeviceProcessEvents",
88+
"description": "Process creation and related events",
89+
"columns": [
90+
{
91+
"name": "Timestamp",
92+
"dataType": "DateTime",
93+
"description": "Date and time when the record was generated"
94+
},
95+
{
96+
"name": "DeviceId",
97+
"dataType": "String",
98+
"description": "Unique identifier for the device in the service"
99+
},
100+
{
101+
"name": "DeviceName",
102+
"dataType": "String",
103+
"description": "Fully qualified domain name (FQDN) of the device"
104+
}
105+
]
106+
},
107+
{
108+
"name": "DeviceNetworkEvents",
109+
"description": "Network connection and related events",
110+
"columns": [
111+
{
112+
"name": "Timestamp",
113+
"dataType": "DateTime",
114+
"description": "Date and time when the record was generated"
115+
},
116+
{
117+
"name": "DeviceId",
118+
"dataType": "String",
119+
"description": "Unique identifier for the device in the service"
120+
}
121+
]
122+
}
123+
],
124+
"functions": {
125+
"builtInFunctions": [
126+
{
127+
"huntingFunctionId": 1,
128+
"name": "FileProfile",
129+
"path": "Built-in",
130+
"documentation": "Enriches query results with file information such as file name, size, and hash.",
131+
"inputParameters": [
132+
{
133+
"name": "SHA1",
134+
"cslType": "string",
135+
"defaultValue": null
136+
}
137+
],
138+
"outputColumns": [
139+
{
140+
"name": "SHA1",
141+
"dataType": "String",
142+
"description": "SHA-1 hash of the file"
143+
},
144+
{
145+
"name": "SHA256",
146+
"dataType": "String",
147+
"description": "SHA-256 hash of the file"
148+
}
149+
]
150+
}
151+
],
152+
"savedFunctions": [
153+
{
154+
"huntingFunctionId": 100,
155+
"name": "MyCustomQuery",
156+
"path": "Shared",
157+
"description": "A custom query that filters device events by severity.",
158+
"createdBy": "user@contoso.com",
159+
"lastModifiedBy": "user@contoso.com",
160+
"lastModifiedDateTime": "2026-04-15T10:30:00Z",
161+
"inputParameters": [],
162+
"outputColumns": [
163+
{
164+
"name": "DeviceId",
165+
"dataType": "String",
166+
"description": "Unique identifier for the device"
167+
}
168+
]
169+
}
170+
]
171+
}
172+
}
173+
```

‎api-reference/beta/resources/security-huntingschemabuiltinfunction.md‎

Lines changed: 51 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,51 @@
1+
---
2+
title: "huntingSchemaBuiltInFunction resource type"
3+
description: "Represents a prebuilt function included with Microsoft Defender XDR advanced hunting."
4+
author: "nitzanfrogel"
5+
ms.localizationpriority: medium
6+
ms.subservice: "security"
7+
doc_type: resourcePageType
8+
ms.date: 05/13/2026
9+
---
10+
11+
# huntingSchemaBuiltInFunction resource type
12+
13+
Namespace: microsoft.graph.security
14+
15+
[!INCLUDE [beta-disclaimer](../../includes/beta-disclaimer.md)]
16+
17+
Represents a prebuilt function included with Microsoft Defender XDR advanced hunting. Built-in functions are available to all advanced hunting instances and can't be modified by users. Part of the [huntingSchemaFunctions](../resources/security-huntingschemafunctions.md) returned by the [getHuntingSchema](../api/security-security-gethuntingschema.md) function.
18+
19+
## Properties
20+
21+
|Property|Type|Description|
22+
|:---|:---|:---|
23+
|huntingFunctionId|Int64|Unique identifier for the function. Required.|
24+
|name|String|Name of the function. Required.|
25+
|path|String|Folder path of the function.|
26+
|documentation|String|Description of the function and its usage.|
27+
|inputParameters|[microsoft.graph.security.huntingSchemaFunctionParameter](../resources/security-huntingschemafunctionparameter.md) collection|Collection of input parameters accepted by the function.|
28+
|outputColumns|[microsoft.graph.security.huntingSchemaTableColumn](../resources/security-huntingschematablecolumn.md) collection|Collection of columns returned by the function.|
29+
30+
## Relationships
31+
32+
None.
33+
34+
## JSON representation
35+
36+
The following JSON representation shows the resource type.
37+
<!-- {
38+
"blockType": "resource",
39+
"@odata.type": "microsoft.graph.security.huntingSchemaBuiltInFunction"
40+
}
41+
-->
42+
``` json
43+
{
44+
"huntingFunctionId": 1,
45+
"name": "FileProfile",
46+
"path": "Built-in",
47+
"documentation": "Enriches query results with file information such as file name, size, and hash.",
48+
"inputParameters": [{"@odata.type": "microsoft.graph.security.huntingSchemaFunctionParameter"}],
49+
"outputColumns": [{"@odata.type": "microsoft.graph.security.huntingSchemaTableColumn"}]
50+
}
51+
```

‎api-reference/beta/resources/security-huntingschemafunctionparameter.md‎

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,45 @@
1+
---
2+
title: "huntingSchemaFunctionParameter resource type"
3+
description: "Represents an input parameter for an advanced hunting function."
4+
author: "nitzanfrogel"
5+
ms.localizationpriority: medium
6+
ms.subservice: "security"
7+
doc_type: resourcePageType
8+
ms.date: 05/13/2026
9+
---
10+
11+
# huntingSchemaFunctionParameter resource type
12+
13+
Namespace: microsoft.graph.security
14+
15+
[!INCLUDE [beta-disclaimer](../../includes/beta-disclaimer.md)]
16+
17+
Represents an input parameter for an advanced hunting function. Parameters allow callers to provide arguments when invoking a function. Used by both [huntingSchemaBuiltInFunction](../resources/security-huntingschemabuiltinfunction.md) and [huntingSchemaSavedFunction](../resources/security-huntingschemasavedfunction.md) resource types.
18+
19+
## Properties
20+
21+
|Property|Type|Description|
22+
|:---|:---|:---|
23+
|name|String|Name of the parameter. Required.|
24+
|cslType|String|Data type of the parameter in Kusto Query Language (KQL) CSL format. Required.|
25+
|defaultValue|String|Default value used when the caller doesn't provide a value for this parameter.|
26+
27+
## Relationships
28+
29+
None.
30+
31+
## JSON representation
32+
33+
The following JSON representation shows the resource type.
34+
<!-- {
35+
"blockType": "resource",
36+
"@odata.type": "microsoft.graph.security.huntingSchemaFunctionParameter"
37+
}
38+
-->
39+
``` json
40+
{
41+
"name": "SHA1",
42+
"cslType": "string",
43+
"defaultValue": null
44+
}
45+
```

‎api-reference/beta/resources/security-huntingschemafunctions.md‎

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
---
2+
title: "huntingSchemaFunctions resource type"
3+
description: "Contains the two categories of advanced hunting functions accessible to the user: built-in functions and saved functions."
4+
author: "nitzanfrogel"
5+
ms.localizationpriority: medium
6+
ms.subservice: "security"
7+
doc_type: resourcePageType
8+
ms.date: 05/13/2026
9+
---
10+
11+
# huntingSchemaFunctions resource type
12+
13+
Namespace: microsoft.graph.security
14+
15+
[!INCLUDE [beta-disclaimer](../../includes/beta-disclaimer.md)]
16+
17+
Contains the two categories of advanced hunting functions accessible to the user: built-in functions and saved functions. Part of the [huntingSchemaResult](../resources/security-huntingschemaresult.md) returned by the [getHuntingSchema](../api/security-security-gethuntingschema.md) function.
18+
19+
## Properties
20+
21+
|Property|Type|Description|
22+
|:---|:---|:---|
23+
|builtInFunctions|[microsoft.graph.security.huntingSchemaBuiltInFunction](../resources/security-huntingschemabuiltinfunction.md) collection|Prebuilt functions included with Microsoft Defender XDR advanced hunting.|
24+
|savedFunctions|[microsoft.graph.security.huntingSchemaSavedFunction](../resources/security-huntingschemasavedfunction.md) collection|Custom functions created by users, including shared functions accessible to all tenant users and personal functions visible only to their creator.|
25+
26+
## Relationships
27+
28+
None.
29+
30+
## JSON representation
31+
32+
The following JSON representation shows the resource type.
33+
<!-- {
34+
"blockType": "resource",
35+
"@odata.type": "microsoft.graph.security.huntingSchemaFunctions"
36+
}
37+
-->
38+
``` json
39+
{
40+
"builtInFunctions": [{"@odata.type": "microsoft.graph.security.huntingSchemaBuiltInFunction"}],
41+
"savedFunctions": [{"@odata.type": "microsoft.graph.security.huntingSchemaSavedFunction"}]
42+
}
43+
```

‎api-reference/beta/resources/security-huntingschemaresult.md‎

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
---
2+
title: "huntingSchemaResult resource type"
3+
description: "Contains the advanced hunting schema accessible to the signed-in user, including tables and functions."
4+
author: "nitzanfrogel"
5+
ms.localizationpriority: medium
6+
ms.subservice: "security"
7+
doc_type: resourcePageType
8+
ms.date: 05/13/2026
9+
---
10+
11+
# huntingSchemaResult resource type
12+
13+
Namespace: microsoft.graph.security
14+
15+
[!INCLUDE [beta-disclaimer](../../includes/beta-disclaimer.md)]
16+
17+
Contains the advanced hunting schema accessible to the signed-in user, including tables and functions. Returned by the [getHuntingSchema](../api/security-security-gethuntingschema.md) function.
18+
19+
## Properties
20+
21+
|Property|Type|Description|
22+
|:---|:---|:---|
23+
|tables|[microsoft.graph.security.huntingSchemaTable](../resources/security-huntingschematable.md) collection|Collection of advanced hunting tables the user is authorized to query.|
24+
|functions|[microsoft.graph.security.huntingSchemaFunctions](../resources/security-huntingschemafunctions.md)|Object containing the built-in functions and saved functions available to the user.|
25+
26+
## Relationships
27+
28+
None.
29+
30+
## JSON representation
31+
32+
The following JSON representation shows the resource type.
33+
<!-- {
34+
"blockType": "resource",
35+
"@odata.type": "microsoft.graph.security.huntingSchemaResult"
36+
}
37+
-->
38+
``` json
39+
{
40+
"tables": [{"@odata.type": "microsoft.graph.security.huntingSchemaTable"}],
41+
"functions": {"@odata.type": "microsoft.graph.security.huntingSchemaFunctions"}
42+
}
43+
```

0 commit comments

Comments
 (0)