Namespace: microsoft.graph.security
Wichtig
Die APIs unter der /beta Version in Microsoft Graph können sich ändern. Die Verwendung dieser APIs in Produktionsanwendungen wird nicht unterstützt. Um festzustellen, ob eine API in v1.0 verfügbar ist, verwenden Sie die Version Selektor.
Fragen Sie einen angegebenen Satz von Ereignis-, Aktivitäts- oder Entitätsdaten ab, die von Microsoft Defender XDR unterstützt werden, um proaktiv nach bestimmten Bedrohungen in Ihrer Umgebung zu suchen.
Diese Methode ist für die erweiterte Suche in Microsoft Defender XDR vorgesehen. Diese Methode umfasst eine Abfrage in der Kusto-Abfragesprache (KQL). Sie gibt eine Datentabelle im erweiterten Suchschema und eine weitergeleitete Sequenz von Operatoren an, um diese Daten zu filtern oder zu durchsuchen und die Abfrageausgabe auf bestimmte Weise zu formatieren.
Erfahren Sie mehr über die Suche nach Bedrohungen über Geräte, E-Mails, Apps und Identitäten hinweg. Erfahren Sie mehr über KQL.
Informationen zur Verwendung der erweiterten Suche im Microsoft Defender-Portal finden Sie unter Proaktives Suchen nach Bedrohungen mit erweiterter Suche in Microsoft Defender XDR.
Diese API ist in den folgenden nationalen Cloudbereitstellungen verfügbar.
| Weltweiter Service |
US Government L4 |
US Government L5 (DOD) |
China, betrieben von 21Vianet |
| ✅ |
✅ |
✅ |
❌ |
Berechtigungen
Wählen Sie die Berechtigungen aus, die für diese API als am wenigsten privilegiert markiert sind. Verwenden Sie eine höhere Berechtigung oder Berechtigungen nur, wenn Ihre App dies erfordert. Ausführliche Informationen zu delegierten Berechtigungen und Anwendungsberechtigungen finden Sie unter Berechtigungstypen. Weitere Informationen zu diesen Berechtigungen finden Sie in der Berechtigungsreferenz.
| Berechtigungstyp |
Berechtigungen mit den geringsten Berechtigungen |
Berechtigungen mit höheren Berechtigungen |
| Delegiert (Geschäfts-, Schul- oder Unikonto) |
ThreatHunting.Read.All |
Nicht verfügbar. |
| Delegiert (persönliches Microsoft-Konto) |
Nicht unterstützt |
Nicht unterstützt |
| Application |
ThreatHunting.Read.All |
Nicht verfügbar. |
Wichtig
Der angemeldete Benutzer benötigt außerdem eine der folgenden Rollen:
HTTP-Anforderung
POST /security/runHuntingQuery
Hinweis
Wenn Sie in Ihrer Abfrage Nicht-ANSI-Zeichen verwenden, z. B. um E-Mail-Betreffzeilen mit falsch formatierten oder ähnlichen Zeichen abzufragen, verwenden Sie application/json; charset=utf-8 sie für den Content-Type-Header.
Anforderungstext
Geben Sie im Anforderungstext ein JSON-Objekt für den query Parameter an, und fügen Sie optional einen Parameter und einen timespanworkspaceId Parameter ein.
| Parameter |
Typ |
Beschreibung |
Beispiel |
| Abfrage |
Zeichenfolge |
Erforderlich. Die Suchabfrage in Kusto-Abfragesprache (KQL). Weitere Informationen finden Sie unter KQL-Kurzübersicht. |
|
| Zeitraum |
Zeichenfolge |
Optional. Das Zeitintervall für die Abfragen von Daten im ISO 8601-Format. Die Standardeinstellung beträgt 30 Tage. Wenn sowohl in der Abfrage als auch im Parameter timespan ein Zeitfilter angegeben ist, wird die kürzere Zeitspanne angewendet. |
|
| workspaceId |
GUID |
Optional. Die GUID eines bestimmten Log Analytics-Arbeitsbereichs, auf den abgezielt werden soll. Wenn diese Angabe weggelassen wird, verwendet der Dienst den primären Arbeitsbereich des Aufrufers. Wenn der Arbeitsbereich nicht gefunden wird oder nicht zugänglich ist, greift der Dienst auf den primären Arbeitsbereich des Aufrufers zurück. |
00000000-0000-0000-0000-000000000001 |
Die folgenden Beispiele zeigen die möglichen Formate für den timespan Parameter:
-
Datum/Datum: "2024-02-01T08:00:00Z/2024-02-15T08:00:00Z" – Start- und Enddatum.
-
Dauer/Enddatum: "P30D/2024-02-15T08:00:00Z" – Ein Zeitraum vor dem Enddatum.
-
Start/Dauer: "2024-02-01T08:00:00Z/P30D" – Startdatum und Dauer.
-
ISO8601 Dauer: "P30D" – Dauer von jetzt an rückwärts.
-
Einzeldatum/-uhrzeit: "2024-02-01T08:00:00Z" – Startzeit, wobei die Endzeit standardmäßig auf die aktuelle Uhrzeit festgelegt ist.
Antwort
Bei erfolgreicher Ausführung gibt diese Aktion einen 200 OK Antwortcode und ein huntingQueryResults im Antworttext zurück.
Beispiele
Beispiel 1: Abfrage mit Standardzeitraum
Anforderung
Das folgende Beispiel gibt eine KQL-Abfrage an und:
- Untersucht die DeviceProcessEvents-Tabelle im erweiterten Suchschema.
- Filter nach der Bedingung, dass der powershell.exe Prozess das Ereignis initiiert.
- Gibt die Ausgabe von drei Spalten aus derselben Tabelle für jede Zeile an:
Timestamp, FileName, InitiatingProcessFileName.
- Sortiert die Ausgabe nach dem
Timestamp Wert.
- Beschränkt die Ausgabe auf zwei Datensätze (zwei Zeilen).
POST https://graph.microsoft.com/beta/security/runHuntingQuery
{
"query": "DeviceProcessEvents | where InitiatingProcessFileName =~ \"powershell.exe\" | project Timestamp, FileName, InitiatingProcessFileName | order by Timestamp desc | limit 2"
}
// Code snippets are only available for the latest version. Current version is 5.x
// Dependencies
using Microsoft.Graph.Beta.Security.MicrosoftGraphSecurityRunHuntingQuery;
var requestBody = new RunHuntingQueryPostRequestBody
{
Query = "DeviceProcessEvents | where InitiatingProcessFileName =~ \"powershell.exe\" | project Timestamp, FileName, InitiatingProcessFileName | order by Timestamp desc | limit 2",
};
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.Security.MicrosoftGraphSecurityRunHuntingQuery.PostAsync(requestBody);
// Code snippets are only available for the latest major version. Current major version is $v0.*
// Dependencies
import (
"context"
msgraphsdk "github.com/microsoftgraph/msgraph-beta-sdk-go"
graphsecurity "github.com/microsoftgraph/msgraph-beta-sdk-go/security"
//other-imports
)
requestBody := graphsecurity.NewRunHuntingQueryPostRequestBody()
query := "DeviceProcessEvents | where InitiatingProcessFileName =~ \"powershell.exe\" | project Timestamp, FileName, InitiatingProcessFileName | order by Timestamp desc | limit 2"
requestBody.SetQuery(&query)
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=go
microsoftGraphSecurityRunHuntingQuery, err := graphClient.Security().MicrosoftGraphSecurityRunHuntingQuery().Post(context.Background(), requestBody, nil)
// Code snippets are only available for the latest version. Current version is 6.x
GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);
com.microsoft.graph.beta.security.microsoftgraphsecurityrunhuntingquery.RunHuntingQueryPostRequestBody runHuntingQueryPostRequestBody = new com.microsoft.graph.beta.security.microsoftgraphsecurityrunhuntingquery.RunHuntingQueryPostRequestBody();
runHuntingQueryPostRequestBody.setQuery("DeviceProcessEvents | where InitiatingProcessFileName =~ \"powershell.exe\" | project Timestamp, FileName, InitiatingProcessFileName | order by Timestamp desc | limit 2");
var result = graphClient.security().microsoftGraphSecurityRunHuntingQuery().post(runHuntingQueryPostRequestBody);
const options = {
authProvider,
};
const client = Client.init(options);
const huntingQueryResults = {
query: 'DeviceProcessEvents | where InitiatingProcessFileName =~ \"powershell.exe\" | project Timestamp, FileName, InitiatingProcessFileName | order by Timestamp desc | limit 2'
};
await client.api('/security/runHuntingQuery')
.version('beta')
.post(huntingQueryResults);
<?php
use Microsoft\Graph\Beta\GraphServiceClient;
use Microsoft\Graph\Beta\Generated\Security\MicrosoftGraphSecurityRunHuntingQuery\RunHuntingQueryPostRequestBody;
$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);
$requestBody = new RunHuntingQueryPostRequestBody();
$requestBody->setQuery('DeviceProcessEvents | where InitiatingProcessFileName =~ \"powershell.exe\" | project Timestamp, FileName, InitiatingProcessFileName | order by Timestamp desc | limit 2');
$result = $graphServiceClient->security()->microsoftGraphSecurityRunHuntingQuery()->post($requestBody)->wait();
Import-Module Microsoft.Graph.Beta.Security
$params = @{
query = "DeviceProcessEvents | where InitiatingProcessFileName =~ "powershell.exe" | project Timestamp, FileName, InitiatingProcessFileName | order by Timestamp desc | limit 2"
}
Start-MgBetaSecurityHuntingQuery -BodyParameter $params
# Code snippets are only available for the latest version. Current version is 1.x
from msgraph_beta import GraphServiceClient
from msgraph_beta.generated.security.microsoft_graph_security_run_hunting_query.run_hunting_query_post_request_body import RunHuntingQueryPostRequestBody
# To initialize your graph_client, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=python
request_body = RunHuntingQueryPostRequestBody(
query = "DeviceProcessEvents | where InitiatingProcessFileName =~ \"powershell.exe\" | project Timestamp, FileName, InitiatingProcessFileName | order by Timestamp desc | limit 2",
)
result = await graph_client.security.microsoft_graph_security_run_hunting_query.post(request_body)
Antwort
HTTP/1.1 200 OK
Content-type: application/json
{
"@odata.context": "https://graph.microsoft.com/beta/$metadata#microsoft.graph.security.huntingQueryResults",
"schema": [
{
"name": "Timestamp",
"type": "DateTime"
},
{
"name": "FileName",
"type": "String"
},
{
"name": "InitiatingProcessFileName",
"type": "String"
}
],
"results": [
{
"Timestamp": "2024-03-26T09:39:50.7688641Z",
"FileName": "cmd.exe",
"InitiatingProcessFileName": "powershell.exe"
},
{
"Timestamp": "2024-03-26T09:39:49.4353788Z",
"FileName": "cmd.exe",
"InitiatingProcessFileName": "powershell.exe"
}
]
}
Beispiel 2: Abfrage mit optional angegebenem timespan-Parameter
Anforderung
Dieses Beispiel gibt eine KQL-Abfrage an und untersucht die deviceProcessEvents-Tabelle im erweiterten Suchschema von vor 60 Tagen.
POST https://graph.microsoft.com/beta/security/runHuntingQuery
{
"query": "DeviceProcessEvents",
"timespan": "P90D"
}
// Code snippets are only available for the latest version. Current version is 5.x
// Dependencies
using Microsoft.Graph.Beta.Security.MicrosoftGraphSecurityRunHuntingQuery;
var requestBody = new RunHuntingQueryPostRequestBody
{
Query = "DeviceProcessEvents",
Timespan = "P90D",
};
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.Security.MicrosoftGraphSecurityRunHuntingQuery.PostAsync(requestBody);
// Code snippets are only available for the latest major version. Current major version is $v0.*
// Dependencies
import (
"context"
msgraphsdk "github.com/microsoftgraph/msgraph-beta-sdk-go"
graphsecurity "github.com/microsoftgraph/msgraph-beta-sdk-go/security"
//other-imports
)
requestBody := graphsecurity.NewRunHuntingQueryPostRequestBody()
query := "DeviceProcessEvents"
requestBody.SetQuery(&query)
timespan := "P90D"
requestBody.SetTimespan(×pan)
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=go
microsoftGraphSecurityRunHuntingQuery, err := graphClient.Security().MicrosoftGraphSecurityRunHuntingQuery().Post(context.Background(), requestBody, nil)
// Code snippets are only available for the latest version. Current version is 6.x
GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);
com.microsoft.graph.beta.security.microsoftgraphsecurityrunhuntingquery.RunHuntingQueryPostRequestBody runHuntingQueryPostRequestBody = new com.microsoft.graph.beta.security.microsoftgraphsecurityrunhuntingquery.RunHuntingQueryPostRequestBody();
runHuntingQueryPostRequestBody.setQuery("DeviceProcessEvents");
runHuntingQueryPostRequestBody.setTimespan("P90D");
var result = graphClient.security().microsoftGraphSecurityRunHuntingQuery().post(runHuntingQueryPostRequestBody);
const options = {
authProvider,
};
const client = Client.init(options);
const huntingQueryResults = {
query: 'DeviceProcessEvents',
timespan: 'P90D'
};
await client.api('/security/runHuntingQuery')
.version('beta')
.post(huntingQueryResults);
<?php
use Microsoft\Graph\Beta\GraphServiceClient;
use Microsoft\Graph\Beta\Generated\Security\MicrosoftGraphSecurityRunHuntingQuery\RunHuntingQueryPostRequestBody;
$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);
$requestBody = new RunHuntingQueryPostRequestBody();
$requestBody->setQuery('DeviceProcessEvents');
$requestBody->setTimespan('P90D');
$result = $graphServiceClient->security()->microsoftGraphSecurityRunHuntingQuery()->post($requestBody)->wait();
Import-Module Microsoft.Graph.Beta.Security
$params = @{
query = "DeviceProcessEvents"
timespan = "P90D"
}
Start-MgBetaSecurityHuntingQuery -BodyParameter $params
# Code snippets are only available for the latest version. Current version is 1.x
from msgraph_beta import GraphServiceClient
from msgraph_beta.generated.security.microsoft_graph_security_run_hunting_query.run_hunting_query_post_request_body import RunHuntingQueryPostRequestBody
# To initialize your graph_client, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=python
request_body = RunHuntingQueryPostRequestBody(
query = "DeviceProcessEvents",
timespan = "P90D",
)
result = await graph_client.security.microsoft_graph_security_run_hunting_query.post(request_body)
Antwort
Hinweis: Das hier gezeigte Antwortobjekt kann zur besseren Lesbarkeit gekürzt werden.
HTTP/1.1 200 OK
Content-type: application/json
{
"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"
}
]
}
Beispiel 3: Abfragen für einen bestimmten Arbeitsbereich
Anforderung
Das folgende Beispiel gibt eine KQL-Abfrage an und zielt auf einen bestimmten Log Analytics-Arbeitsbereich ab, indem der optionale workspaceId-Parameter übergeben wird.
POST https://graph.microsoft.com/beta/security/runHuntingQuery
Content-Type: application/json
{
"query": "DeviceProcessEvents | where InitiatingProcessFileName =~ \"powershell.exe\" | project Timestamp, FileName, InitiatingProcessFileName | order by Timestamp desc | limit 2",
"timespan": "P1D",
"workspaceId": "00000000-0000-0000-0000-000000000001"
}
// Code snippets are only available for the latest version. Current version is 5.x
// Dependencies
using Microsoft.Graph.Beta.Security.MicrosoftGraphSecurityRunHuntingQuery;
var requestBody = new RunHuntingQueryPostRequestBody
{
Query = "DeviceProcessEvents | where InitiatingProcessFileName =~ \"powershell.exe\" | project Timestamp, FileName, InitiatingProcessFileName | order by Timestamp desc | limit 2",
Timespan = "P1D",
WorkspaceId = Guid.Parse("00000000-0000-0000-0000-000000000001"),
};
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.Security.MicrosoftGraphSecurityRunHuntingQuery.PostAsync(requestBody);
// Code snippets are only available for the latest major version. Current major version is $v0.*
// Dependencies
import (
"context"
"github.com/google/uuid"
msgraphsdk "github.com/microsoftgraph/msgraph-beta-sdk-go"
graphsecurity "github.com/microsoftgraph/msgraph-beta-sdk-go/security"
//other-imports
)
requestBody := graphsecurity.NewRunHuntingQueryPostRequestBody()
query := "DeviceProcessEvents | where InitiatingProcessFileName =~ \"powershell.exe\" | project Timestamp, FileName, InitiatingProcessFileName | order by Timestamp desc | limit 2"
requestBody.SetQuery(&query)
timespan := "P1D"
requestBody.SetTimespan(×pan)
workspaceId := uuid.MustParse("00000000-0000-0000-0000-000000000001")
requestBody.SetWorkspaceId(&workspaceId)
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=go
microsoftGraphSecurityRunHuntingQuery, err := graphClient.Security().MicrosoftGraphSecurityRunHuntingQuery().Post(context.Background(), requestBody, nil)
// Code snippets are only available for the latest version. Current version is 6.x
GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);
com.microsoft.graph.beta.security.microsoftgraphsecurityrunhuntingquery.RunHuntingQueryPostRequestBody runHuntingQueryPostRequestBody = new com.microsoft.graph.beta.security.microsoftgraphsecurityrunhuntingquery.RunHuntingQueryPostRequestBody();
runHuntingQueryPostRequestBody.setQuery("DeviceProcessEvents | where InitiatingProcessFileName =~ \"powershell.exe\" | project Timestamp, FileName, InitiatingProcessFileName | order by Timestamp desc | limit 2");
runHuntingQueryPostRequestBody.setTimespan("P1D");
runHuntingQueryPostRequestBody.setWorkspaceId(UUID.fromString("00000000-0000-0000-0000-000000000001"));
var result = graphClient.security().microsoftGraphSecurityRunHuntingQuery().post(runHuntingQueryPostRequestBody);
const options = {
authProvider,
};
const client = Client.init(options);
const huntingQueryResults = {
query: 'DeviceProcessEvents | where InitiatingProcessFileName =~ \"powershell.exe\" | project Timestamp, FileName, InitiatingProcessFileName | order by Timestamp desc | limit 2',
timespan: 'P1D',
workspaceId: '00000000-0000-0000-0000-000000000001'
};
await client.api('/security/runHuntingQuery')
.version('beta')
.post(huntingQueryResults);
<?php
use Microsoft\Graph\Beta\GraphServiceClient;
use Microsoft\Graph\Beta\Generated\Security\MicrosoftGraphSecurityRunHuntingQuery\RunHuntingQueryPostRequestBody;
$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);
$requestBody = new RunHuntingQueryPostRequestBody();
$requestBody->setQuery('DeviceProcessEvents | where InitiatingProcessFileName =~ \"powershell.exe\" | project Timestamp, FileName, InitiatingProcessFileName | order by Timestamp desc | limit 2');
$requestBody->setTimespan('P1D');
$requestBody->setWorkspaceId('00000000-0000-0000-0000-000000000001');
$result = $graphServiceClient->security()->microsoftGraphSecurityRunHuntingQuery()->post($requestBody)->wait();
Import-Module Microsoft.Graph.Beta.Security
$params = @{
query = "DeviceProcessEvents | where InitiatingProcessFileName =~ "powershell.exe" | project Timestamp, FileName, InitiatingProcessFileName | order by Timestamp desc | limit 2"
timespan = "P1D"
workspaceId = "00000000-0000-0000-0000-000000000001"
}
Start-MgBetaSecurityHuntingQuery -BodyParameter $params
# Code snippets are only available for the latest version. Current version is 1.x
from msgraph_beta import GraphServiceClient
from msgraph_beta.generated.security.microsoft_graph_security_run_hunting_query.run_hunting_query_post_request_body import RunHuntingQueryPostRequestBody
# To initialize your graph_client, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=python
request_body = RunHuntingQueryPostRequestBody(
query = "DeviceProcessEvents | where InitiatingProcessFileName =~ \"powershell.exe\" | project Timestamp, FileName, InitiatingProcessFileName | order by Timestamp desc | limit 2",
timespan = "P1D",
workspace_id = UUID("00000000-0000-0000-0000-000000000001"),
)
result = await graph_client.security.microsoft_graph_security_run_hunting_query.post(request_body)
Antwort
Hinweis: Das hier gezeigte Antwortobjekt kann zur besseren Lesbarkeit gekürzt werden.
HTTP/1.1 200 OK
Content-type: application/json
{
"schema": [
{
"name": "Timestamp",
"type": "DateTime"
},
{
"name": "FileName",
"type": "String"
},
{
"name": "InitiatingProcessFileName",
"type": "String"
}
],
"results": [
{
"Timestamp": "2026-03-10T06:38:35.766Z",
"FileName": "conhost.exe",
"InitiatingProcessFileName": "powershell.exe"
},
{
"Timestamp": "2026-03-10T06:38:30.516Z",
"FileName": "conhost.exe",
"InitiatingProcessFileName": "powershell.exe"
}
]
}