Functions/Get-MCASDiscoveredApp.ps1

<#
.Synopsis
    Gets a list of discovered apps based on uploaded log files.
.DESCRIPTION
    This function retrives traffic and usage information about discovered apps.
.EXAMPLE
    PS C:\> Get-MCASDiscoveredApp -StreamId $streamid | select name -First 5
 
    name
    ----
    1ShoppingCart
    ABC News
    ACTIVE
    AIM
    AT&T
 
    Retrieves the first 5 app names sorted alphabetically.
 
.EXAMPLE
    PS C:\> Get-MCASDiscoveredApp -StreamId $streamid -Category SECURITY | select name,@{N='Total (MB)';E={"{0:N2}" -f ($_.trafficTotalBytes/1MB)}}
 
    name Total (MB)
    ---- ----------
    Blue Coat 19.12
    Globalscape 0.00
    McAfee Control Console 1.28
    Symantec 0.20
    Websense 0.06
 
    In this example we pull back only discovered apps in the security category and display a table of names and Total traffic which we format to 2 decimal places and divide the totalTrafficBytes property by 1MB to show the traffic in MB.
 
#>

function Get-MCASDiscoveredApp {
    [CmdletBinding()]
    param
    (
        # Specifies the credential object containing tenant as username (e.g. 'contoso.us.portal.cloudappsecurity.com') and the 64-character hexadecimal Oauth token as the password.
        [Parameter(Mandatory=$false)]
        [ValidateNotNullOrEmpty()]
        [System.Management.Automation.PSCredential]$Credential = $CASCredential,

        <#
        # Specifies the property by which to sort the results. Set to 'Name' by default. Possible Values: 'UserName','LastSeen'.
        [Parameter(ParameterSetName='List', Mandatory=$false)]
        [ValidateSet('IpCount','LastUsed','Name','Transactions','Upload','UserCount')]
        [ValidateNotNullOrEmpty()]
        [string]$SortBy='Name',
 
        # Specifies the direction in which to sort the results. Set to 'Ascending' by default. Possible Values: 'Ascending','Descending'.
        [Parameter(ParameterSetName='List', Mandatory=$false)]
        [ValidateSet('Ascending','Descending')]
        [ValidateNotNullOrEmpty()]
        [string]$SortDirection='Ascending',
        #>


        # Specifies the maximum number of results to retrieve when listing items matching the specified filter criteria. Set to 100 by default.
        [Parameter(ParameterSetName='List', Mandatory=$false)]
        [ValidateRange(1,100)]
        [ValidateNotNullOrEmpty()]
        [int]$ResultSetSize = 100,

        # Specifies the number of records, from the beginning of the result set, to skip. Set to 0 by default.
        [Parameter(ParameterSetName='List', Mandatory=$false)]
        [ValidateScript({$_ -gt -1})]
        [int]$Skip = 0,

        ##### FILTER PARAMS #####

        <#
        # Limits results by category type. A preset list of categories are included.
        [Parameter(ParameterSetName='List', Mandatory=$false)]
        [ValidateNotNullOrEmpty()]
        [app_category]$Category,
        #>


        <#
        # Limits the results by risk score range, for example '3-9'. Set to '1-10' by default.
        [Parameter(ParameterSetName='List', Mandatory=$false)]
        [ValidatePattern('^([1-9]|10)-([1-9]|10)$')]
        [ValidateNotNullOrEmpty()]
        [string]$ScoreRangeMin='1-10',
        #>


        <#
        [Parameter(ParameterSetName='List', Mandatory=$false)]
        [ValidateRange(1,10)]
        [ValidateNotNullOrEmpty()]
        [string]$ScoreRangeMin='1',
 
        [Parameter(ParameterSetName='List', Mandatory=$false)]
        [ValidateRange(1,10)]
        [ValidateNotNullOrEmpty()]
        [string]$ScoreRangeMax='10',
        #>


        # Limits the results by stream ID, for example '577d49d72b1c51a0762c61b0'. The stream ID can be found in the URL bar of the console when looking at the Discovery dashboard.
        [Parameter(ParameterSetName='List', Mandatory=$false, Position=0)]
        [ValidatePattern('^[A-Fa-f0-9]{24}$')]
        [ValidateNotNullOrEmpty()]
        [string]$StreamId,

        # Limits the results by time frame in days. Set to 90 days by default. (Options: 7, 30, or 90)
        [Parameter(ParameterSetName='List', Mandatory=$false)]
        [ValidateSet('7','30','90')]
        [ValidateNotNullOrEmpty()]
        [int]$TimeFrame=90,

        # Limits the results based on user count.
        [Parameter(ParameterSetName='List', Mandatory=$false)]
        [ValidateNotNullOrEmpty()]
        [int]$UsersLessThan,

        # Limits the results based on user count.
        [Parameter(ParameterSetName='List', Mandatory=$false)]
        [ValidateNotNullOrEmpty()]
        [int]$UsersGreaterThan,

        # Limits the results based on user count.
        [Parameter(ParameterSetName='List', Mandatory=$false)]
        [ValidateNotNullOrEmpty()]
        [int]$RiskScoreMin = 0,

        # Limits the results based on user count.
        [Parameter(ParameterSetName='List', Mandatory=$false)]
        [ValidateNotNullOrEmpty()]
        [int]$RiskScoreMax = 10,
       
        # Limits the results to apps with the specified tag(s).
        [Parameter(ParameterSetName='List', Mandatory=$false)]
        [ValidateSet('Sanctioned','Unsanctioned','None')]
        [ValidateNotNullOrEmpty()]
        [string[]]$Tag
    )

    if ($StreamId) {
        $stream = $StreamId
    }
    else {
        $stream = (Get-MCASStream | Where-Object {$_.displayName -eq 'Global View'}).Identity
    }

    #$body = @{'skip'=$Skip;'limit'=$ResultSetSize;'streamId'=$stream;'timeframe'=$TimeFrame} # Base request body


    $body = @{
        'skip'=$Skip;
        'limit'=$ResultSetSize;
        #'score'=$ScoreRange;
        'timeframe'=$TimeFrame;
        'streamId'=$stream
    } # Base request body


    <#
    if ($Category) {
        $body += @{'category'="SAASDB_CATEGORY_$Category"}
    }
    #>




    #region ----------------------------SORTING----------------------------
<#
    if ($SortBy -xor $SortDirection) {throw 'Error: When specifying either the -SortBy or the -SortDirection parameters, you must specify both parameters.'}
 
    # Add sort direction to request body, if specified
    if ($SortDirection) {$body.Add('sortDirection',$SortDirection.TrimEnd('ending').ToLower())}
 
    # Add sort field to request body, if specified
    switch ($SortBy) {
        'Name' {$body.Add('sortField','name')}
        'UserCount' {$body.Add('sortField','usersCount')}
        'IpCount' {$body.Add('sortField','ipAddressesCount')}
        'LastUsed' {$body.Add('sortField','lastUsed')}
        'Upload' {$body.Add('sortField','trafficUploadedBytes')}
        'Transactions' {$body.Add('sortField','trafficTotalEvents')}
    }
    #if ($SortBy) {$body.Add('sortField',$SortBy)}
#>

    #endregion ----------------------------SORTING----------------------------


    #region ----------------------------FILTERING----------------------------

    $filterSet = @() # Filter set array

    #if ($Tag) {$filterSet += @{'tag'= @{'eq'=$Tag}}} # Not working

    # UsersLessThan / UsersGreaterThan
        if ($UsersLessThan -or $UsersGreaterThan){ 
            $filterSet += @{'users' = @{} 
            }
            $FilterName = "users"
        }
        # UsersLessThan
        if ($UsersLessThan) { $filterSet.($FilterName).add('lt', $UsersLessThan ) }
        # UsersGreaterThan
        if ($UsersGreaterThan) { $filterSet.($FilterName).add('gt' , $UsersGreaterThan ) }

        
    # RiskScoreMin / RiskScoreMax
        if ($RiskScoreMin -or $RiskScoreMax){ 
            $filterSet += @{'score' = @{} 
            }
            $FilterName = "score"
        }
        # RiskScoreRange
        if ($RiskScoreMin -or $RiskScoreMax) { $filterSet.($FilterName).add('eq', @($RiskScoreMin, $RiskScoreMax) ) }     # UsersGreaterThan


    #endregion ----------------------------FILTERING----------------------------

    try {
        #$response = Invoke-MCASRestMethod -Credential $Credential -Path "/cas/api/discovery/" -Method Post -Body $body #-FilterSet $filterSet
        $response = Invoke-MCASRestMethod -Credential $Credential -Path "/cas/api/v1/discovery/discovered_apps/" -Method Post -Body $body -FilterSet $filterSet
    }
    catch {
        throw "Error calling MCAS API. The exception was: $_"
    }

    $response = $response.data

    try {
        Write-Verbose "Adding alias property to results, if appropriate"
        $response = $response | Add-Member -MemberType AliasProperty -Name Identity -Value 'appId' -PassThru
    }
    catch {}

    $response
}