POWERSHELL COMMAND
Get-XdrCloudAppsDiscovery
Retrieves Cloud Discovery data from Microsoft Defender for Cloud Apps.
Gets Cloud Discovery data from Microsoft Defender for Cloud Apps. This consolidated cmdlet provides access to discovery data types including categories, entities, top rankings, locations, constants, unsanctioned apps, and user deanonymization through a single interface. This function includes caching support to reduce API calls.
When no StreamId or StreamName is specified for types that require streams, queries ALL available discovery streams and includes StreamId/StreamName properties on each result.
Syntax
Get-XdrCloudAppsDiscovery -Type <string> [-StreamId <string>] [-StreamName <string>] [-EntityType <string>] [-TopType <string>] [-TopEntityField <string>] [-Timeframe <int>] [-AppId <int>] [-Limit <int>] [-Skip <int>] [-Offset <int>] [-SortField <string>] [-SortDirection <string>] [-Filters <hashtable>] [-CategoryFilter <string>] [-Metric <string>] [-LocationType <string>] [-Search <string>] [-LocationId <string>] [-ExcludeSanctioned] [-ExcludeUnsanctioned] [-ExcludeOther] [-Force] [<CommonParameters>]
Get-XdrCloudAppsDiscovery -ListStreams [-Force] [<CommonParameters>]
Get-XdrCloudAppsDiscovery -DeanonymizeUser -Usernames <string[]> -Justification <string> [-Force] [<CommonParameters>]
Parameters
-Type
| Property | Value |
|---|---|
| Type | String |
| Required | Yes |
| Position | named |
| Pipeline input | No |
| Default | Not documented |
The type of discovery data to retrieve. Valid values are:
- Category: App category definitions (no StreamId required)
- CategoryStat: Category statistics with traffic/user data
- Constant: Discovery constants and enumerations (no StreamId required)
- Entity: Entities (IP, Machine, User, Resource) - use with -EntityType
- Location: Discovery service locations (no StreamId required)
- Top: Top apps, categories, or entities - use with -TopType
- UnsanctionedApp: Apps marked as unsanctioned/blocked
-ListStreams
| Property | Value |
|---|---|
| Type | SwitchParameter |
| Required | Yes |
| Position | named |
| Pipeline input | No |
| Default | False |
When specified, lists all available discovery streams. Useful for discovering stream IDs and names before querying data.
-DeanonymizeUser
| Property | Value |
|---|---|
| Type | SwitchParameter |
| Required | Yes |
| Position | named |
| Pipeline input | No |
| Default | False |
When specified, deanonymizes Cloud Discovery usernames using the provided justification text.
-Usernames
| Property | Value |
|---|---|
| Type | String[] |
| Required | Yes |
| Position | named |
| Pipeline input | true (ByValue, ByPropertyName) |
| Default | Not documented |
One or more anonymized Cloud Discovery usernames to deanonymize.
-Justification
| Property | Value |
|---|---|
| Type | String |
| Required | Yes |
| Position | named |
| Pipeline input | No |
| Default | Not documented |
Required justification for deanonymizing Cloud Discovery usernames.
-StreamId
| Property | Value |
|---|---|
| Type | String |
| Required | No |
| Position | named |
| Pipeline input | true (ByPropertyName) |
| Default | Not documented |
The ID of the discovery stream to query. If not specified for types that require it, queries all available streams. Accepts pipeline input from Get-XdrCloudAppsConfiguration -Type DiscoveryStream via the _id property.
-StreamName
| Property | Value |
|---|---|
| Type | String |
| Required | No |
| Position | named |
| Pipeline input | No |
| Default | Not documented |
The name of the discovery stream to query. Supports wildcards (e.g., “Defender*”). If not specified along with StreamId, queries all available streams for types that require it.
-EntityType
| Property | Value |
|---|---|
| Type | String |
| Required | No |
| Position | named |
| Pipeline input | No |
| Default | Not documented |
Required when Type is Entity. Specifies the entity type to retrieve. Valid values are: IP, Machine, User, Resource
-TopType
| Property | Value |
|---|---|
| Type | String |
| Required | No |
| Position | named |
| Pipeline input | No |
| Default | Not documented |
Required when Type is Top. Specifies what top data to retrieve. Valid values are: App, Category, Entity (use with -TopEntityField)
-TopEntityField
| Property | Value |
|---|---|
| Type | String |
| Required | No |
| Position | named |
| Pipeline input | No |
| Default | Not documented |
Required when Type is Top and TopType is Entity. Specifies the entity field. Valid values are: users, machines, ipAddresses
-Timeframe
| Property | Value |
|---|---|
| Type | Int32 |
| Required | No |
| Position | named |
| Pipeline input | No |
| Default | 30 |
The number of days to include in the results. Default is 30 days. Applies to CategoryStat, Entity, Top, and UnsanctionedApp types.
-AppId
| Property | Value |
|---|---|
| Type | Int32 |
| Required | No |
| Position | named |
| Pipeline input | No |
| Default | 0 |
Optional app ID to filter entities by a specific application. Only applies to Entity type (not Resource EntityType).
-Limit
| Property | Value |
|---|---|
| Type | Int32 |
| Required | No |
| Position | named |
| Pipeline input | No |
| Default | 0 |
Maximum number of results to return. Applies to Entity and Top types.
-Skip
| Property | Value |
|---|---|
| Type | Int32 |
| Required | No |
| Position | named |
| Pipeline input | No |
| Default | 0 |
Number of results to skip for pagination. Applies to Entity type.
-Offset
| Property | Value |
|---|---|
| Type | Int32 |
| Required | No |
| Position | named |
| Pipeline input | No |
| Default | 0 |
Number of results to skip for pagination. Applies to Top type.
-SortField
| Property | Value |
|---|---|
| Type | String |
| Required | No |
| Position | named |
| Pipeline input | No |
| Default | lastSeen |
The field to sort results by. Applies to Entity type. Default is “lastSeen”.
-SortDirection
| Property | Value |
|---|---|
| Type | String |
| Required | No |
| Position | named |
| Pipeline input | No |
| Default | desc |
The sort direction. Valid values are “asc” or “desc”. Default is “desc”.
-Filters
| Property | Value |
|---|---|
| Type | Hashtable |
| Required | No |
| Position | named |
| Pipeline input | No |
| Default | @{} |
A hashtable of filters to apply to the query. Applies to Entity type.
-CategoryFilter
| Property | Value |
|---|---|
| Type | String |
| Required | No |
| Position | named |
| Pipeline input | No |
| Default | all |
Filter top apps to a specific category. Only applies to Top type with TopType App.
-Metric
| Property | Value |
|---|---|
| Type | String |
| Required | No |
| Position | named |
| Pipeline input | No |
| Default | traffic |
The metric used to rank results. Valid values are traffic, users, transactions, upload. Applies to Top type with TopType App or Category. Default is traffic.
-LocationType
| Property | Value |
|---|---|
| Type | String |
| Required | No |
| Position | named |
| Pipeline input | No |
| Default | hq |
The type of location to retrieve. Valid values are “hq”, “branch”, or “”. Only applies to Location type. Default is “hq”.
-Search
| Property | Value |
|---|---|
| Type | String |
| Required | No |
| Position | named |
| Pipeline input | No |
| Default | Not documented |
A search string to filter locations. Only applies to Location type.
-LocationId
| Property | Value |
|---|---|
| Type | String |
| Required | No |
| Position | named |
| Pipeline input | No |
| Default | Not documented |
A specific location ID to retrieve. Only applies to Location type.
-ExcludeSanctioned
| Property | Value |
|---|---|
| Type | SwitchParameter |
| Required | No |
| Position | named |
| Pipeline input | No |
| Default | False |
Excludes sanctioned apps. Only applies to Top type with TopType Category.
-ExcludeUnsanctioned
| Property | Value |
|---|---|
| Type | SwitchParameter |
| Required | No |
| Position | named |
| Pipeline input | No |
| Default | False |
Excludes unsanctioned apps. Only applies to Top type with TopType Category.
-ExcludeOther
| Property | Value |
|---|---|
| Type | SwitchParameter |
| Required | No |
| Position | named |
| Pipeline input | No |
| Default | False |
Excludes apps with no sanction status. Only applies to Top type with TopType Category.
-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
Get-XdrCloudAppsDiscovery -ListStreams
Lists all available discovery streams.
Get-XdrCloudAppsDiscovery -DeanonymizeUser -Usernames "User_aaaaaabbbbb=" -Justification "Incident response investigation"
Deanonymizes a Cloud Discovery username.
Get-XdrCloudAppsDiscovery -Type Category
Retrieves all app category definitions.
Get-XdrCloudAppsDiscovery -Type Constant
Retrieves discovery constants and enumerations.
Get-XdrCloudAppsDiscovery -Type Location -LocationType branch
Retrieves branch office locations.
Get-XdrCloudAppsDiscovery -Type CategoryStat
Retrieves category statistics from ALL streams (includes stream context on results).
Get-XdrCloudAppsDiscovery -Type CategoryStat -StreamName "Defender*"
Retrieves category statistics from streams matching the wildcard pattern.
Get-XdrCloudAppsDiscovery -Type Entity -EntityType IP
Retrieves discovered IP addresses from ALL streams.
Get-XdrCloudAppsDiscovery -Type Entity -StreamId "64a75731967076e7d6bd00ea" -EntityType User -Limit 50
Retrieves up to 50 discovered users from a specific stream.
Get-XdrCloudAppsDiscovery -Type Top -TopType App
Retrieves top discovered apps from ALL streams.
Get-XdrCloudAppsDiscovery -Type Top -StreamName "Defender-managed endpoints" -TopType Entity -TopEntityField users
Retrieves top users by app usage from a specific stream.
Get-XdrCloudAppsDiscovery -Type UnsanctionedApp
Retrieves apps marked as unsanctioned from ALL streams.
Get-XdrCloudAppsConfiguration -Type DiscoveryStream | Get-XdrCloudAppsDiscovery -Type Entity -EntityType Machine
Retrieves discovered machines from all streams via pipeline.
Output
Type: Returns discovery data objects based on the Type parameter. Each type returns
appropriately typed objects (XdrCloudAppsDiscoveryCategory, XdrCloudAppsDiscoveryEntity, etc.) When querying multiple streams, includes SourceStreamId and SourceStreamName properties.
XdrCloudAppsConfigurationDiscoveryStream[] When -ListStreams is specified, returns available discovery streams.
XdrCloudAppsDiscoveryDeanonymizedUser[] When -DeanonymizeUser is specified, returns deanonymized Cloud Discovery usernames.