POWERSHELL COMMAND
Invoke-XdrXspmHuntingQuery
Executes a hunting query against the Microsoft Defender XDR XSPM attack surface API.
Executes a custom hunting query against the XSPM (Extended Security Posture Management) attack surface API. Supports pagination through top and skip parameters. This function is designed to be used as a base for more specific attack surface queries.
Syntax
Invoke-XdrXspmHuntingQuery [-Query] <string> [[-Top] <int>] [[-Skip] <int>] [-ScenarioName] <string> [-Force] [<CommonParameters>]
Parameters
-Query
| Property | Value |
|---|---|
| Type | String |
| Required | Yes |
| Position | 1 |
| Pipeline input | No |
| Default | Not documented |
The hunting query string to execute. Should follow XSPM query syntax.
-Top
| Property | Value |
|---|---|
| Type | Int32 |
| Required | No |
| Position | 2 |
| Pipeline input | No |
| Default | 0 |
The maximum number of records to return. Default is 100.
-Skip
| Property | Value |
|---|---|
| Type | Int32 |
| Required | No |
| Position | 3 |
| Pipeline input | No |
| Default | 0 |
The number of records to skip for pagination. Default is 0.
-ScenarioName
| Property | Value |
|---|---|
| Type | String |
| Required | Yes |
| Position | 4 |
| Pipeline input | No |
| Default | Not documented |
The scenario name to include in the request header (x-ms-scenario-name). This might be used for telemetry or logging purposes on the server side. Be careful out there.
-Force
| Property | Value |
|---|---|
| Type | SwitchParameter |
| Required | No |
| Position | named |
| Pipeline input | No |
| Default | False |
Bypasses the cache and forces a fresh retrieval from the API.
Examples
Invoke-XdrXspmHuntingQuery -Query "AttackPathsV2 | take 10"
Executes a query to retrieve 10 attack paths.
Invoke-XdrXspmHuntingQuery -Query "AttackPathsV2" -Top 50 -Skip 100
Executes a query with pagination, skipping the first 100 records and returning up to 50.
Invoke-XdrXspmHuntingQuery -Query "AttackPathsV2 | where RiskLevel == 'High'" -Force
Executes a filtered query, bypassing the cache.
Invoke-XdrXspmHuntingQuery -Query "AttackPathsV2" -ScenarioName "CustomAnalysis"
Executes a query with a custom scenario name in the request header.
Output
Type: Object
Returns the query results including totalRecords, count, skipToken, and data array.