Get-XdrCloudAppsDiscovery
SYNOPSIS
Retrieves Cloud Discovery data from Microsoft Defender for Cloud Apps.
SYNTAX
Default (Default)
Get-XdrCloudAppsDiscovery -Type <String> [-StreamId <String>] [-StreamName <String>] [-EntityType <String>]
[-TopType <String>] [-TopEntityField <String>] [-Timeframe <Int32>] [-AppId <Int32>] [-Limit <Int32>]
[-Skip <Int32>] [-Offset <Int32>] [-SortField <String>] [-SortDirection <String>] [-Filters <Hashtable>]
[-CategoryFilter <String>] [-Metric <String>] [-LocationType <String>] [-Search <String>]
[-LocationId <String>] [-ExcludeSanctioned] [-ExcludeUnsanctioned] [-ExcludeOther] [-Force]
[-ProgressAction <ActionPreference>] [<CommonParameters>]
ListStreams
Get-XdrCloudAppsDiscovery [-ListStreams] [-Force] [-ProgressAction <ActionPreference>] [<CommonParameters>]
DeanonymizeUser
Get-XdrCloudAppsDiscovery [-DeanonymizeUser] -Usernames <String[]> -Justification <String> [-Force]
[-ProgressAction <ActionPreference>] [<CommonParameters>]
DESCRIPTION
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.
EXAMPLES
EXAMPLE 1
Get-XdrCloudAppsDiscovery -ListStreams
Lists all available discovery streams.
EXAMPLE 2
Get-XdrCloudAppsDiscovery -DeanonymizeUser -Usernames "User_aaaaaabbbbb=" -Justification "Incident response investigation"
Deanonymizes a Cloud Discovery username.
EXAMPLE 3
Get-XdrCloudAppsDiscovery -Type Category
Retrieves all app category definitions.
EXAMPLE 4
Get-XdrCloudAppsDiscovery -Type Constant
Retrieves discovery constants and enumerations.
EXAMPLE 5
Get-XdrCloudAppsDiscovery -Type Location -LocationType branch
Retrieves branch office locations.
EXAMPLE 6
Get-XdrCloudAppsDiscovery -Type CategoryStat
Retrieves category statistics from ALL streams (includes stream context on results).
EXAMPLE 7
Get-XdrCloudAppsDiscovery -Type CategoryStat -StreamName "Defender*"
Retrieves category statistics from streams matching the wildcard pattern.
EXAMPLE 8
Get-XdrCloudAppsDiscovery -Type Entity -EntityType IP
Retrieves discovered IP addresses from ALL streams.
EXAMPLE 9
Get-XdrCloudAppsDiscovery -Type Entity -StreamId "64a75731967076e7d6bd00ea" -EntityType User -Limit 50
Retrieves up to 50 discovered users from a specific stream.
EXAMPLE 10
Get-XdrCloudAppsDiscovery -Type Top -TopType App
Retrieves top discovered apps from ALL streams.
EXAMPLE 11
Get-XdrCloudAppsDiscovery -Type Top -StreamName "Defender-managed endpoints" -TopType Entity -TopEntityField users
Retrieves top users by app usage from a specific stream.
EXAMPLE 12
Get-XdrCloudAppsDiscovery -Type UnsanctionedApp
Retrieves apps marked as unsanctioned from ALL streams.
EXAMPLE 13
Get-XdrCloudAppsConfiguration -Type DiscoveryStream | Get-XdrCloudAppsDiscovery -Type Entity -EntityType Machine
Retrieves discovered machines from all streams via pipeline.
PARAMETERS
-Type
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
Type: String
Parameter Sets: Default
Aliases:
Required: True
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
-ListStreams
When specified, lists all available discovery streams. Useful for discovering stream IDs and names before querying data.
Type: SwitchParameter
Parameter Sets: ListStreams
Aliases:
Required: True
Position: Named
Default value: False
Accept pipeline input: False
Accept wildcard characters: False
-DeanonymizeUser
When specified, deanonymizes Cloud Discovery usernames using the provided justification text.
Type: SwitchParameter
Parameter Sets: DeanonymizeUser
Aliases:
Required: True
Position: Named
Default value: False
Accept pipeline input: False
Accept wildcard characters: False
-Usernames
One or more anonymized Cloud Discovery usernames to deanonymize.
Type: String[]
Parameter Sets: DeanonymizeUser
Aliases: Username
Required: True
Position: Named
Default value: None
Accept pipeline input: True (ByPropertyName, ByValue)
Accept wildcard characters: False
-Justification
Required justification for deanonymizing Cloud Discovery usernames.
Type: String
Parameter Sets: DeanonymizeUser
Aliases:
Required: True
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
-StreamId
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.
Type: String
Parameter Sets: Default
Aliases: _id
Required: False
Position: Named
Default value: None
Accept pipeline input: True (ByPropertyName)
Accept wildcard characters: False
-StreamName
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.
Type: String
Parameter Sets: Default
Aliases:
Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: True
-EntityType
Required when Type is Entity. Specifies the entity type to retrieve. Valid values are: IP, Machine, User, Resource
Type: String
Parameter Sets: Default
Aliases:
Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
-TopType
Required when Type is Top. Specifies what top data to retrieve. Valid values are: App, Category, Entity (use with -TopEntityField)
Type: String
Parameter Sets: Default
Aliases:
Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
-TopEntityField
Required when Type is Top and TopType is Entity. Specifies the entity field. Valid values are: users, machines, ipAddresses
Type: String
Parameter Sets: Default
Aliases:
Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
-Timeframe
The number of days to include in the results. Default is 30 days. Applies to CategoryStat, Entity, Top, and UnsanctionedApp types.
Type: Int32
Parameter Sets: Default
Aliases:
Required: False
Position: Named
Default value: 30
Accept pipeline input: False
Accept wildcard characters: False
-AppId
Optional app ID to filter entities by a specific application. Only applies to Entity type (not Resource EntityType).
Type: Int32
Parameter Sets: Default
Aliases:
Required: False
Position: Named
Default value: 0
Accept pipeline input: False
Accept wildcard characters: False
-Limit
Maximum number of results to return. Applies to Entity and Top types.
Type: Int32
Parameter Sets: Default
Aliases:
Required: False
Position: Named
Default value: 0
Accept pipeline input: False
Accept wildcard characters: False
-Skip
Number of results to skip for pagination. Applies to Entity type.
Type: Int32
Parameter Sets: Default
Aliases:
Required: False
Position: Named
Default value: 0
Accept pipeline input: False
Accept wildcard characters: False
-Offset
Number of results to skip for pagination. Applies to Top type.
Type: Int32
Parameter Sets: Default
Aliases:
Required: False
Position: Named
Default value: 0
Accept pipeline input: False
Accept wildcard characters: False
-SortField
The field to sort results by. Applies to Entity type. Default is "lastSeen".
Type: String
Parameter Sets: Default
Aliases:
Required: False
Position: Named
Default value: LastSeen
Accept pipeline input: False
Accept wildcard characters: False
-SortDirection
The sort direction. Valid values are "asc" or "desc". Default is "desc".
Type: String
Parameter Sets: Default
Aliases:
Required: False
Position: Named
Default value: Desc
Accept pipeline input: False
Accept wildcard characters: False
-Filters
A hashtable of filters to apply to the query. Applies to Entity type.
Type: Hashtable
Parameter Sets: Default
Aliases:
Required: False
Position: Named
Default value: @
Accept pipeline input: False
Accept wildcard characters: False
-CategoryFilter
Filter top apps to a specific category. Only applies to Top type with TopType App.
Type: String
Parameter Sets: Default
Aliases:
Required: False
Position: Named
Default value: All
Accept pipeline input: False
Accept wildcard characters: False
-Metric
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.
Type: String
Parameter Sets: Default
Aliases:
Required: False
Position: Named
Default value: Traffic
Accept pipeline input: False
Accept wildcard characters: False
-LocationType
The type of location to retrieve. Valid values are "hq", "branch", or "". Only applies to Location type. Default is "hq".
Type: String
Parameter Sets: Default
Aliases:
Required: False
Position: Named
Default value: Hq
Accept pipeline input: False
Accept wildcard characters: False
-Search
A search string to filter locations. Only applies to Location type.
Type: String
Parameter Sets: Default
Aliases:
Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
-LocationId
A specific location ID to retrieve. Only applies to Location type.
Type: String
Parameter Sets: Default
Aliases:
Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
-ExcludeSanctioned
Excludes sanctioned apps. Only applies to Top type with TopType Category.
Type: SwitchParameter
Parameter Sets: Default
Aliases:
Required: False
Position: Named
Default value: False
Accept pipeline input: False
Accept wildcard characters: False
-ExcludeUnsanctioned
Excludes unsanctioned apps. Only applies to Top type with TopType Category.
Type: SwitchParameter
Parameter Sets: Default
Aliases:
Required: False
Position: Named
Default value: False
Accept pipeline input: False
Accept wildcard characters: False
-ExcludeOther
Excludes apps with no sanction status. Only applies to Top type with TopType Category.
Type: SwitchParameter
Parameter Sets: Default
Aliases:
Required: False
Position: Named
Default value: False
Accept pipeline input: False
Accept wildcard characters: False
-Force
Bypasses the cache and forces a fresh retrieval from the API.
Type: SwitchParameter
Parameter Sets: (All)
Aliases:
Required: False
Position: Named
Default value: False
Accept pipeline input: False
Accept wildcard characters: False
-ProgressAction
The ProgressAction parameter is a common parameter, not a cmdlet parameter. For more information, see about_CommonParameters.
Type: ActionPreference
Parameter Sets: (All)
Aliases: proga
Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
CommonParameters
This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters.