diff --git a/.circleci/workflows.yml b/.circleci/workflows.yml index c4aa026c1..5d627a52c 100755 --- a/.circleci/workflows.yml +++ b/.circleci/workflows.yml @@ -32,7 +32,7 @@ parameters: description: "Release Type. Accepted values [ Major, Minor, Patch ]" type: enum enum: ["Major", "Minor", "Patch"] - default: "Patch" + default: "Minor" RequiredModulesRepo: description: "PowerShell Repository for JumpCloud SDKs" type: enum @@ -49,7 +49,7 @@ parameters: PublishToPSGallery: description: "When `true` and when run against Master branch, this workflow will publish the latest code to PSGallery" type: boolean - default: false + default: true ManualModuleVersion: description: "When `true` the pipeline will use the Module Version specified in JumpCloud Module JumpCloud.psd1 file" type: boolean @@ -101,18 +101,18 @@ workflows: - Initial Setup - Build Modules context: aws-credentials - - Module Validation Tests: + - Invoke Git Commit: requires: - Initial Setup - Build Help and Test Files - Build Nuspec - - Invoke Git Commit - context: aws-credentials - - Invoke Git Commit: + - Module Validation Tests: requires: - Initial Setup - Build Help and Test Files - Build Nuspec + - Invoke Git Commit + context: aws-credentials - Pester Tests Windows: requires: - Initial Setup @@ -149,6 +149,7 @@ workflows: jobs: - Prepare for release - draft-github-release: + context: github-credentials-sa-releases requires: - Prepare for release - Approve Module: @@ -310,7 +311,7 @@ commands: steps: - add_ssh_keys: fingerprints: - - "89:e7:20:1b:b1:a2:c2:2e:b8:d6:34:2f:73:80:a6:70" + - "c9:0f:56:c9:00:42:98:3c:03:59:24:1e:a7:e7:08:7f" - checkout - run: name: Set URLs @@ -413,7 +414,7 @@ commands: - checkout - add_ssh_keys: fingerprints: - - "89:e7:20:1b:b1:a2:c2:2e:b8:d6:34:2f:73:80:a6:70" + - "c9:0f:56:c9:00:42:98:3c:03:59:24:1e:a7:e7:08:7f" - attach_workspace: at: . - run: @@ -427,7 +428,7 @@ commands: - checkout - add_ssh_keys: fingerprints: - - "89:e7:20:1b:b1:a2:c2:2e:b8:d6:34:2f:73:80:a6:70" + - "c9:0f:56:c9:00:42:98:3c:03:59:24:1e:a7:e7:08:7f" - attach_workspace: at: . - run: @@ -607,3 +608,4 @@ commands: root: . paths: - . +# VS Code Extension Version: 1.5.1 diff --git a/PowerShell/JumpCloud Module/Docs/Get-JCSystemApp.md b/PowerShell/JumpCloud Module/Docs/Get-JCSystemApp.md new file mode 100644 index 000000000..eb7e79f10 --- /dev/null +++ b/PowerShell/JumpCloud Module/Docs/Get-JCSystemApp.md @@ -0,0 +1,170 @@ +--- +external help file: JumpCloud-help.xml +Module Name: JumpCloud +online version: https://github.com/TheJumpCloud/support/wiki/ +schema: 2.0.0 +--- + +# Get-JCSystemApp + +## SYNOPSIS + +Returns the applications/programs/linux packages installed on JumpCloud managed system(s). This function queries separate system insights tables to get data for macOS/windows/linux devices. + +## SYNTAX + +### All (Default) +``` +Get-JCSystemApp [-SystemID ] [-SystemOS ] [-name ] [-version ] + [] +``` + +### Search +``` +Get-JCSystemApp [-SystemID ] [-SystemOS ] [-name ] [-version ] [-Search] + [] +``` + +## DESCRIPTION + +Get-JCSystem app function helps admins identify what applications/programs or linux packages exist on their JumpCloud managed systems. + +## EXAMPLES + +### Example 1 + +```powershell +PS C:\> Get-JCSystemApp -SystemId '6363237ec991136ae59892e4' +``` + +Returns the applications installed in the system with the given -SystemId + +### Example 2 + +```powershell +PS C:\> Get-JCSystemApp -SystemOs 'macOS' +``` + +Returns the 'macOS' systems and all the applications installed for each system + +### Example 3 + +```powershell +PS C:\> Get-JCSystemApp -SystemOs 'macOS' -Name 'Jumpcloud' +``` + +### Example 4 + +```powershell +PS C:\> Get-JCSystemApp -SystemOs 'macOS' -Name 'Jumpcloud' -Version 'v1.16.2' +``` + +Returns the 'macOS' systems that have a 'Jumpcloud' tray application with the version 'v1.16.2' + +### Example 5 + +```powershell +PS C:\> Get-JCSystemApp -Name 'jumpcloud' -Search +``` + +Returns any 'jumpcloud' software installed in all the OS systems (Windows/Linux/macOS) + +## PARAMETERS + +### -name + +The name of the application you want to search for ex. (Jumpcloud, Slack). Name will always query the "name" property from system insights. Note, for macOS systems, ".app" will be applied. This field is case sensitive. + +```yaml +Type: System.String +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Search + +Search for a specific application by from all systems in the org ex. +(Get-JCSystemApp -Search -Name "Jumpcloud") +THIS PARAMETER DOES NOT TAKE INPUT + +```yaml +Type: System.Management.Automation.SwitchParameter +Parameter Sets: Search +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -SystemID + +The System Id of the JumpCloud system you want to search for applications + +```yaml +Type: System.String +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -SystemOS + +The type (windows, mac, linux) of the JumpCloud Command you wish to search ex. +(Windows, macOs, Linux)) + +```yaml +Type: System.String +Parameter Sets: (All) +Aliases: +Accepted values: Windows, macOS, Linux + +Required: False +Position: Named +Default value: None +Accept pipeline input: True (ByPropertyName) +Accept wildcard characters: False +``` + +### -version + +The version of the application you want to search for ex. 1.1.2. Note: on Windows/ Linux devices, this parameter will filter on the 'version' property, for macOS applications this parameter will filter on the 'bundleShortVersion' property. + +```yaml +Type: System.String +Parameter Sets: (All) +Aliases: + +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](http://go.microsoft.com/fwlink/?LinkID=113216). + +## INPUTS + +### System.String + +## OUTPUTS + +### System.Object +## NOTES + +## RELATED LINKS diff --git a/PowerShell/JumpCloud Module/Docs/JumpCloud.md b/PowerShell/JumpCloud Module/Docs/JumpCloud.md index f0c80c1e5..3056fe7c7 100644 --- a/PowerShell/JumpCloud Module/Docs/JumpCloud.md +++ b/PowerShell/JumpCloud Module/Docs/JumpCloud.md @@ -2,7 +2,7 @@ Module Name: JumpCloud Module Guid: 31c023d1-a901-48c4-90a3-082f91b31646 Download Help Link: https://github.com/TheJumpCloud/support/wiki -Help Version: 2.1.3 +Help Version: 2.2.0 Locale: en-US --- @@ -86,6 +86,9 @@ Return JumpCloud radius server information. ### [Get-JCSystem](Get-JCSystem.md) Returns all JumpCloud Systems within a JumpCloud tenant or a single JumpCloud System using the -ByID Parameter. +### [Get-JCSystemApp](Get-JCSystemApp.md) +Returns the applications/programs/linux packages installed on JumpCloud managed system(s). This function queries separate system insights tables to get data for macOS/windows/linux devices. + ### [Get-JCSystemGroupMember](Get-JCSystemGroupMember.md) Returns the System Group members of a JumpCloud System Group. diff --git a/PowerShell/JumpCloud Module/Docs/Set-JCSettingsFile.md b/PowerShell/JumpCloud Module/Docs/Set-JCSettingsFile.md index ba6b37a0c..f8bf10130 100644 --- a/PowerShell/JumpCloud Module/Docs/Set-JCSettingsFile.md +++ b/PowerShell/JumpCloud Module/Docs/Set-JCSettingsFile.md @@ -14,7 +14,7 @@ Updates the JumpCloud Module Settings File ## SYNTAX ``` -Set-JCSettingsFile [-moduleBannerMessageCount ] [-parallelOverride ] [] +Set-JCSettingsFile [-parallelOverride ] [-moduleBannerMessageCount ] [] ``` ## DESCRIPTION diff --git a/PowerShell/JumpCloud Module/JumpCloud.nuspec b/PowerShell/JumpCloud Module/JumpCloud.nuspec index 372616672..5bcba3a57 100644 --- a/PowerShell/JumpCloud Module/JumpCloud.nuspec +++ b/PowerShell/JumpCloud Module/JumpCloud.nuspec @@ -2,7 +2,7 @@ JumpCloud - 2.1.3 + 2.2.0.7873-202302072022 PowerShell functions to manage a JumpCloud Directory-as-a-Service JumpCloud Solutions Architect Team JumpCloud diff --git a/PowerShell/JumpCloud Module/JumpCloud.psd1 b/PowerShell/JumpCloud Module/JumpCloud.psd1 index 862935eb5..e0e8790bf 100644 --- a/PowerShell/JumpCloud Module/JumpCloud.psd1 +++ b/PowerShell/JumpCloud Module/JumpCloud.psd1 @@ -3,7 +3,7 @@ # # Generated by: JumpCloud Solutions Architect Team # -# Generated on: 1/6/2023 +# Generated on: 2/7/2023 # @{ @@ -12,7 +12,7 @@ RootModule = 'JumpCloud.psm1' # Version number of this module. -ModuleVersion = '2.1.3' +ModuleVersion = '2.2.0' # Supported PSEditions # CompatiblePSEditions = @() @@ -80,15 +80,15 @@ FunctionsToExport = 'Add-JCAssociation', 'Add-JCCommandTarget', 'Get-JCOrganization', 'Get-JCPolicy', 'Get-JCPolicyResult', 'Get-JCPolicyTargetGroup', 'Get-JCPolicyTargetSystem', 'Get-JCRadiusReplyAttribute', 'Get-JCRadiusServer', 'Get-JCSystem', - 'Get-JCSystemGroupMember', 'Get-JCSystemInsights', 'Get-JCSystemUser', - 'Get-JCUser', 'Get-JCUserGroupMember', 'Import-JCCommand', - 'Import-JCUsersFromCSV', 'Invoke-JCCommand', 'Invoke-JCDeployment', - 'New-JCCommand', 'New-JCDeploymentTemplate', 'New-JCImportTemplate', - 'New-JCRadiusServer', 'New-JCSystemGroup', 'New-JCUser', - 'New-JCUserGroup', 'Remove-JCAssociation', 'Remove-JCCommand', - 'Remove-JCCommandResult', 'Remove-JCCommandTarget', - 'Remove-JCRadiusReplyAttribute', 'Remove-JCRadiusServer', - 'Remove-JCSystem', 'Remove-JCSystemGroup', + 'Get-JCSystemApp', 'Get-JCSystemGroupMember', 'Get-JCSystemInsights', + 'Get-JCSystemUser', 'Get-JCUser', 'Get-JCUserGroupMember', + 'Import-JCCommand', 'Import-JCUsersFromCSV', 'Invoke-JCCommand', + 'Invoke-JCDeployment', 'New-JCCommand', 'New-JCDeploymentTemplate', + 'New-JCImportTemplate', 'New-JCRadiusServer', 'New-JCSystemGroup', + 'New-JCUser', 'New-JCUserGroup', 'Remove-JCAssociation', + 'Remove-JCCommand', 'Remove-JCCommandResult', + 'Remove-JCCommandTarget', 'Remove-JCRadiusReplyAttribute', + 'Remove-JCRadiusServer', 'Remove-JCSystem', 'Remove-JCSystemGroup', 'Remove-JCSystemGroupMember', 'Remove-JCSystemUser', 'Remove-JCUser', 'Remove-JCUserGroup', 'Remove-JCUserGroupMember', 'Send-JCPasswordReset', 'Set-JCCommand', 'Set-JCOrganization', diff --git a/PowerShell/JumpCloud Module/Public/Systems/Get-JCSystemApp.ps1 b/PowerShell/JumpCloud Module/Public/Systems/Get-JCSystemApp.ps1 new file mode 100644 index 000000000..e846d82b7 --- /dev/null +++ b/PowerShell/JumpCloud Module/Public/Systems/Get-JCSystemApp.ps1 @@ -0,0 +1,353 @@ +function Get-JCSystemApp () { + [CmdletBinding(DefaultParameterSetName = 'All')] + param ( + [Parameter(Mandatory = $false, HelpMessage = 'The System Id of the system you want to search for applications')][ValidateNotNullorEmpty()] + [string]$SystemID, + [Parameter(Mandatory = $false , ValueFromPipelineByPropertyName, HelpMessage = 'The type (windows, macOS, linux) of the JumpCloud system you wish to search. Ex. (Windows, macOS, Linux))')] + [ValidateSet('Windows', 'macOS', 'Linux')][ValidateNotNullorEmpty()] + [string]$SystemOS, + [Parameter(Mandatory = $false, HelpMessage = 'The name of the application you want to search for ex. (JumpCloud-Agent, Slack). SoftwareName will always query the "name" property from system insights. Note, for macOS systems, ".app" will be applied. This field is case sensitive.' )][ValidateNotNullorEmpty()] + [string]$name, + [Parameter(Mandatory = $false, HelpMessage = 'The version of the application you want to search for ex. 1.1.2')][ValidateNotNullorEmpty()] + [string]$version, + [Parameter(Mandatory = $false, ParameterSetName = "Search", HelpMessage = "The Search parameter can be used in conjunction with the 'SoftwareName' parameter to perform a case-insensitive search for software. This is parameter switch is inherently slower than using just the 'softwareName' parameter but can be useful to identify the names of software titles on systems. If the exact name of a software title isn't known, the 'search' parameter can be used to find that name. Ex. Get-JCSoftwareApp -SystemID '63c9654cb357249876bfc05b' -name 'chrome' -Search will attempt to perform a match for the term 'chrome' on all applications/ programs for the specified system. If a match, partial-match, case-insensitive match is found, it would be returned in the results. In this case, the 'name' of the software title is 'Google Chrome'. A subsequent search could be run to return all macOS systems which have 'Google Chrome' installed. Ex. Get-JCSystemApp -SystemOS macOS -name 'Google Chrome', this would perform an exact match search for macOS systems that have google chrome which is substantially quicker than running: Get-JCSystemApp -SystemOS macOS -name 'google chrome' -Search. The search parameter is a tool to help identify the 'name' attribute of software titles when searching bulk systems its recommended to not use the search parameter and instead specify the exact (case sensitive) name of the software title.")] + [switch]$Search, + [Parameter(DontShow, Mandatory = $false, ParameterSetName = "All", HelpMessage = 'Search for a specific application by name from all systems in the org')] + [switch]$SearchAllSystems + ) + begin { + Write-Verbose 'Verifying JCAPI Key' + if ($JCAPIKEY.length -ne 40) { + Connect-JCOnline + } + $Parallel = $JCConfig.parallel.Calculated + $searchAppResultsList = New-Object -TypeName System.Collections.ArrayList + $resultsArrayList = New-Object -TypeName System.Collections.ArrayList + $commands = @("Get-JcSdkSystemInsightProgram", "Get-JcSdkSystemInsightApp", "Get-JcSdkSystemInsightLinuxPackage") + Write-Verbose "Parameter Set: $($PSCmdlet.ParameterSetName)" + } + process { + [int]$limit = '1000' + Write-Verbose "Setting limit to $limit" + + [int]$skip = '0' + Write-Verbose "Setting skip to $skip" + $applicationArray = @('programs', 'apps', 'linux_packages') + + switch ($PSCmdlet.ParameterSetName) { + All { + if ($SystemId -or $SystemOS) { + if ($SystemID -and $SystemOS) { + Throw "Cannot specify both SystemID and SystemOS" + } + # Get the OS Type + if ($SystemID) { + $OSType = Get-JcSdkSystem -ID $SystemID -Fields osFamily | Select-Object -ExpandProperty OSFamily + } else { + $OSType = $SystemOS + if ($OSType -eq 'macOS') { + $OSType = 'Darwin' + } + } + Write-Debug "OSType: $OSType" + # Switch for OS Type + switch ($OSType) { + # Check whether a systemId or systemOS is used + 'Windows' { + if ($version -and $name) { + + + if ($SystemID) { + Get-JcSdkSystemInsightProgram -Filter @("system_id:eq:$SystemID", "name:eq:$name", "version:eq:$version") | ForEach-Object { + [void]$resultsArrayList.Add($_) + } + } elseif ($SystemOS) { + Get-JcSdkSystemInsightProgram -Filter @("name:eq:$name", "version:eq:$version") | ForEach-Object { + [void]$resultsArrayList.Add($_) + } + } + } elseif ($name) { + + + if ($SystemID) { + Get-JcSdkSystemInsightProgram -Filter @("system_id:eq:$SystemID", "name:eq:$name") | ForEach-Object { + [void]$resultsArrayList.Add($_) + } + } elseif ($SystemOS) { + Get-JcSdkSystemInsightProgram -Filter @("name:eq:$name") | ForEach-Object { + [void]$resultsArrayList.Add($_) + } + } + } elseif ($SystemID) { + if ($version) { + Write-Error "Cannot search for software version on Windows without software name." + } else { + Get-JcSdkSystemInsightProgram -Filter @("system_id:eq:$SystemID") | ForEach-Object { + [void]$resultsArrayList.Add($_) + } + } + } elseif ($SystemOS) { + if ($version) { + Write-Error "Cannot search for software version on Windows without software name." + } else { + Get-JcSdkSystemInsightProgram | ForEach-Object { + [void]$resultsArrayList.Add($_) + } + } + } + } + 'Darwin' { + + if ($name) { + # Check for .app at the end of the software name + $macOsSoftwareName = $name + $ending = $macOsSoftwareName.Substring($macOsSoftwareName.Length - 4) + If ($ending -match '.app') { + $macOsSoftwareName = $macOsSoftwareName.Replace($ending, $ending.toLower()) + Write-Debug "$macOsSoftwareName" + } else { + $macOsSoftwareName = "$macOsSoftwareName.app" + Write-Debug "$macOsSoftwareName" + } + } + + # If Software title, version, and system ID are passed then return specific app + if ($version -and $macOsSoftwareName) { + + Write-Debug "Trying to get app with name $macOsSoftwareName and version $version" + + if ($SystemID) { + + Get-JcSdkSystemInsightApp -Filter @("system_id:eq:$SystemID", "name:eq:$macOsSoftwareName", "bundle_short_version:eq:$version") | ForEach-Object { + [void]$resultsArrayList.Add($_) + } + } elseif ($SystemOS) { + Get-JcSdkSystemInsightApp -Filter @("name:eq:$macOsSoftwareName", "bundle_short_version:eq:$version") | ForEach-Object { + [void]$resultsArrayList.Add($_) + } + } + } elseif ($macOsSoftwareName) { + + + if ($SystemID) { + Get-JcSdkSystemInsightApp -Filter @("system_id:eq:$SystemID", "name:eq:$macOsSoftwareName") | ForEach-Object { + [void]$resultsArrayList.Add($_) + } + } elseif ($SystemOS) { + Get-JcSdkSystemInsightApp -Filter @("name:eq:$macOsSoftwareName") | ForEach-Object { + [void]$resultsArrayList.Add($_) + } + } + } elseif ($SystemID) { + if ($version) { + Write-Error "Cannot search for software version on MacOs without software name." + } else { + Get-JcSdkSystemInsightApp -Filter @("system_id:eq:$SystemID") | ForEach-Object { + [void]$resultsArrayList.Add($_) + } + } + } elseif ($SystemOS) { + if ($version) { + Write-Error "Cannot search for software version on MacOs without software name." + } else { + Get-JcSdkSystemInsightApp | ForEach-Object { + [void]$resultsArrayList.Add($_) + } + } + } + + } + 'Linux' { + if ($version -and $name) { + if ($SystemID) { + Get-JcSdkSystemInsightLinuxPackage -Filter @("system_id:eq:$SystemID", "name:eq:$name", "version:eq:$version") | ForEach-Object { + [void]$resultsArrayList.Add($_) + } + } elseif ($SystemOS) { + Get-JcSdkSystemInsightLinuxPackage -Filter @("name:eq:$name", "version:eq:$version") | ForEach-Object { + [void]$resultsArrayList.Add($_) + } + } + } elseif ($name) { + if ($SystemID) { + Get-JcSdkSystemInsightLinuxPackage -Filter @("system_id:eq:$SystemID", "name:eq:$name") | ForEach-Object { + [void]$resultsArrayList.Add($_) + } + } elseif ($SystemOS) { + Get-JcSdkSystemInsightLinuxPackage -Filter @("name:eq:$name") | ForEach-Object { + [void]$resultsArrayList.Add($_) + } + } + } elseif ($SystemID) { + if ($version) { + Write-Error "Cannot search for software version on Linux without software name." + } else { + Get-JcSdkSystemInsightLinuxPackage -Filter @("system_id:eq:$SystemID") | ForEach-Object { + [void]$resultsArrayList.Add($_) + } + } + + } elseif ($SystemOS) { + if ($version) { + Write-Error "Cannot search for software version on Linux without software name." + } else { + Get-JcSdkSystemInsightLinuxPackage | ForEach-Object { + [void]$resultsArrayList.Add($_) + } + } + } + } + } + # IF no systemOs or systemID is passed with name + } elseif ($name) { + # Loop through each OS and get the results + Write-Debug "name and or version only passed. Getting all software with name $name" + + foreach ($os in @('Windows', 'MacOs', 'Linux')) { + if ($os -eq 'Windows') { + if ($version) { + Get-JcSdkSystemInsightProgram -Filter @("name:eq:$name", "version:eq:$version") | ForEach-Object { + [void]$resultsArrayList.Add($_) + } + } else { + Get-JcSdkSystemInsightProgram -Filter @("name:eq:$name") | ForEach-Object { + [void]$resultsArrayList.Add($_) + } + } + + } elseif ($os -eq 'MacOs') { + $macOsSoftwareName = $name + $ending = $macOsSoftwareName.Substring($macOsSoftwareName.Length - 4) + If ($ending -match '.app') { + $macOsSoftwareName = $macOsSoftwareName.Replace($ending, $ending.toLower()) + Write-Debug "$macOsSoftwareName" + } else { + $macOsSoftwareName = "$macOsSoftwareName.app" + Write-Debug "$macOsSoftwareName" + } + if ($version) { + Get-JcSdkSystemInsightApp -Filter @("name:eq:$macOsSoftwareName", "bundle_short_version:eq:$version") | ForEach-Object { + [void]$resultsArrayList.Add($_) + } + } else { + Get-JcSdkSystemInsightApp -Filter @("name:eq:$macOsSoftwareName") | ForEach-Object { + [void]$resultsArrayList.Add($_) + } + } + + } elseif ($os -eq 'Linux') { + if ($version) { + Get-JcSdkSystemInsightLinuxPackage -Filter @("name:eq:$name", "version:eq:$version") | ForEach-Object { + [void]$resultsArrayList.Add($_) + } + } else { + Get-JcSdkSystemInsightLinuxPackage -Filter @("name:eq:$name") | ForEach-Object { + [void]$resultsArrayList.Add($_) + } + } + + } + } + } # End of name and or version only passed + else { + # Get all software in all systems in the org + # Default/All + Write-Debug "Get All" + if ($Parallel) { + Write-Debug "Getting all software in parallel" + $result = $commands | ForEach-Object -Parallel { & $_ } + $resultsArrayList = $result + } else { + $result = $commands | ForEach-Object { & $_ } + $resultsArrayList = $result + } + } + } Search { + # Case-insensitive search + # Search for softwareName + Write-Debug "Search $name" + if ($name) { + if ($version) { + Throw 'You cannot specify software version when using -search for a software name' + } elseif ($SystemId) { + $OSType = Get-JcSdkSystem -ID $SystemID | Select-Object -ExpandProperty OSFamily + Switch ($OSType) { + "Windows" { + $result = Get-JcSdkSystemInsightProgram -Filter @("system_id:eq:$SystemID") + if ($result) { + $searchAppResultsList.AddRange($result) + } + } + "Darwin" { + $result = Get-JcSdkSystemInsightApp -Filter @("system_id:eq:$SystemID") + if ($result) { + $searchAppResultsList.AddRange($result) + } + } + "Linux" { + $result = Get-JcSdkSystemInsightLinuxPackage -Filter @("system_id:eq:$SystemID") + if ($result) { + $searchAppResultsList.AddRange($result) + } + } + } + $filteredResults = $searchAppResultsList | Where-Object { ($_.name -match $name) } + $resultsArrayList = $filteredResults + } elseif ($SystemOS) { + Write-Debug "SystemOS $SystemOS" + if ($SystemOS -eq 'Windows') { + $result = Get-JcSdkSystemInsightProgram + if ($result) { + $searchAppResultsList.AddRange($result) + } + } elseif ($SystemOS -eq 'MacOs') { + $result = Get-JcSdkSystemInsightApp + if ($result) { + $searchAppResultsList.AddRange($result) + } + } elseif ($SystemOS -eq 'Linux') { + $result = Get-JcSdkSystemInsightLinuxPackage + if ($result) { + $searchAppResultsList.AddRange($result) + } + } + $filteredResults = $searchAppResultsList | Where-Object { ($_.name -match $name) } + $resultsArrayList = $filteredResults + } else { + + if ($Parallel) { + Write-Debug "Parallel" + $result = $commands | ForEach-Object -Parallel { & $_ } + if ($result) { + [void]$searchAppResultsList.AddRange($result) + } + + } else { + $result = $commands | ForEach-Object { & $_ } + if ($result) { + [void]$searchAppResultsList.AddRange($result) + } + } + $filteredResults = $searchAppResultsList | Where-Object { ($_.name -match $name) } + $resultsArrayList = $filteredResults + + } + + } else { + Throw "You must specify a software name and/or systemId when using -search" + } + } + + } + } + end { + switch ($PSCmdlet.ParameterSetName) { + Search { + return $resultsArrayList + } + All { + return $resultsArrayList + } + } + } +} \ No newline at end of file diff --git a/PowerShell/JumpCloud Module/Tests/Public/Systems/Get-JCSystemApp.tests.ps1 b/PowerShell/JumpCloud Module/Tests/Public/Systems/Get-JCSystemApp.tests.ps1 new file mode 100644 index 000000000..028c84744 --- /dev/null +++ b/PowerShell/JumpCloud Module/Tests/Public/Systems/Get-JCSystemApp.tests.ps1 @@ -0,0 +1,232 @@ +Describe -Tag:('JCSystemApp') 'Get-JCSystemApp' { + BeforeAll { + $systems = Get-JCsystem + $mac = $systems | Where-Object { $_.osFamily -match "darwin" } | Select-Object -First 1 + $windows = $systems | Where-Object { $_.osFamily -match "windows" } | Select-Object -First 1 + $linux = $systems | Where-Object { $_.osFamily -match "linux" } | Select-Object -First 1 + } + It "Returns all the software" { + $AllApps = Get-JCSystemApp + $AllApps | Should -Not -BeNullOrEmpty + } + + It "Tests that Get-JCSystemApp returns packages/apps/programs for all systems in the org" { + # Should return linuxPackages for all systems in the org + { Get-JCSystemApp -SystemOS linux } | Should -Not -Throw + # Should return mac apps for all systems in the org + { Get-JCSystemApp -SystemOS macOS } | Should -Not -Throw + # Should return windows programs for all systems in the org + { Get-JCSystemApp -SystemOS windows } | Should -Not -Throw + } + It "Tests that given a systemID, each type of app can be returned" { + { Get-JCSystemApp -SystemID $mac._id } | Should -Not -Throw + { Get-JCSystemApp -SystemID $windows._id } | Should -Not -Throw + { Get-JCSystemApp -SystemID $linux._id } | Should -Not -Throw + } + + It "Tests that given a systemID, SoftwareName, an app is returned" { + # Chess is always installed on MacOS and it CAN NOT be removed no matter what + Get-JCSystemApp -SystemID $mac._id -name "Chess" | Should -Not -BeNullOrEmpty + Get-JCSystemApp -SystemID $linux._id -name "curl" | Should -Not -BeNullOrEmpty + Get-JCSystemApp -SystemID $windows._id -name "Microsoft Edge" | Should -Not -BeNullOrEmpty + } + It "Tests that given a name and version, app is returned" { + # Chess is always installed on MacOS and it CAN NOT be removed no matter what + $macApp = Get-JCSystemApp -SystemID $mac._id -name "Chess" + $linuxApp = Get-JCSystemApp -SystemID $linux._id -name "curl" + $windowsApp = Get-JCSystemApp -SystemID $windows._id -name "Microsoft Edge" + { Get-JCSystemApp -name "Chess" -version $macApp.bundleshortversion } | Should -Not -BeNullOrEmpty + { Get-JCSystemApp -name "curl" -version $linuxApp.version } | Should -Not -BeNullOrEmpty + { Get-JCSystemApp -name "Microsoft Edge" -version $windowsApp.version } | Should -Not -BeNullOrEmpty + } + It "Tests that given a macOS systemID, SoftwareName, SoftwareVersion, an app is returned" { + # MacOS + $macApp = Get-JCSystemApp -SystemID $mac._id -name "Chess" + # A null value version shouldn't be accepted + { Get-JCSystemApp -SystemID $mac._id -name "Chess" -version "" } | Should -Throw + # A null value Name shouldn't be accepted + { Get-JCSystemApp -SystemID $mac._id -name "" } | Should -Throw + # Using a version that doesn't exist should return nothing + Get-JCSystemApp -SystemID $mac._id -name "Chess" -version "48.49.50.51" | Should -Be $null + } + It "Tests that given a windows systemID, SoftwareName, SoftwareVersion, an app is returned" { + + #Windows + $windowsApp = Get-JCSystemApp -SystemID $windows._id -name "Microsoft Edge" + # A null value version shouldn't be accepted + { Get-JCSystemApp -SystemID $windows._id -name "Microsoft Edge" -version "" } | Should -Throw + # A null value Name shouldn't be accepted + { Get-JCSystemApp -SystemID $windows._id -name "" } | Should -Throw + # Using a version that doesn't exist should return nothing + Get-JCSystemApp -SystemID $windows._id -name "Microsoft Edge" -version "48.49.50.51" | Should -Be $null + } + It "Tests that given a linux systemID, SoftwareName, SoftwareVersion, an app is returned" { + #Linux + #Windows + $linuxApp = Get-JCSystemApp -SystemID $linux._id -name "curl" + # A null value version shouldn't be accepted + { Get-JCSystemApp -SystemID $linux._id -name "curl" -version "" } | Should -Throw + # A null value Name shouldn't be accepted + { Get-JCSystemApp -SystemID $linux._id -name "" } | Should -Throw + # Using a version that doesn't exist should return nothing + Get-JCSystemApp -SystemID $linux._id -name "curl" -version "48.49.50.51" | Should -Be $null + } + # Create tests for Search + It "Tests for search given SystemOs and SoftwareName for MacOS Systems" { + # Chess is always installed on MacOS and it CAN NOT be removed no matter what + { Get-JCSystemApp -Search | Should -Throw } + { Get-JCSystemApp -Search -name "Chess" -SystemID $mac.Id } | should -Not -Throw + { Get-JCSystemApp -Search -name "Chess" } | should -Not -Throw + { Get-JCSystemApp -Search -name "Chess" -SystemOs "MacOs" } | should -Not -Throw + # A null value version shouldn't be accepted + { Get-JCSystemApp -Search -name "Chess" -SystemOs "" | Should -Throw } + # A null value version shouldn't be accepted + { Get-JCSystemApp -Search -name "" -SystemOs "MacOs" | Should -Throw } + # Searching chess on MacOs should return a result + { Get-JCSystemApp -Search -name "Chess" -SystemOs "MacOs" } | should -Not -Throw + } + It "Tests for search given SystemOs and SoftwareName for Linux Systems" { + # Curl is always installed on linux + { Get-JCSystemApp -Search | Should -Throw } + { Get-JCSystemApp -Search -name "Curl" -SystemID $linux._Id } | should -Not -Throw + { Get-JCSystemApp -Search -name "Curl" } | should -Not -Throw + { Get-JCSystemApp -Search -name "Curl" -SystemOs "linux" } | should -Not -Throw + # A null value version shouldn't be accepted + { Get-JCSystemApp -Search -name "Curl" -SystemOs "" | Should -Throw } + # A null value version shouldn't be accepted + { Get-JCSystemApp -Search -name "" -SystemOs "linux" | Should -Throw } + # Searching Curl on linux should return a result + { Get-JCSystemApp -Search -name "Curl" -SystemOs "linux" } | should -Not -Throw + } + It "Tests for search given SystemOs and SoftwareName for Windows Systems" { + # Microsoft Edge is always installed on windows + { Get-JCSystemApp -Search | Should -Throw } + { Get-JCSystemApp -Search -name "Microsoft Edge" -SystemID $windows._Id } | should -Not -Throw + { Get-JCSystemApp -Search -name "Microsoft Edge" } | should -Not -Throw + { Get-JCSystemApp -Search -name "Microsoft Edge" -SystemOs "windows" } | should -Not -Throw + # A null value version shouldn't be accepted + { Get-JCSystemApp -Search -name "Microsoft Edge" -SystemOs "" | Should -Throw } + # A null value version shouldn't be accepted + { Get-JCSystemApp -Search -name "" -SystemOs "windows" | Should -Throw } + # Searching Microsoft Edge on windows should return a result + { Get-JCSystemApp -Search -name "Microsoft Edge" -SystemOs "windows" } | should -Not -Throw + } + + It "Tests the search functionatily of a software app" { + #Tests for each OS + # results with no data should be null or empty + Get-JCSystemApp -name "chess" | Should -BeNullOrEmpty + Get-JCSystemApp -name "microsoft edge" | Should -BeNullOrEmpty + # when search is used to find an app the results should not be null or empty + Get-JCSystemApp -name "chess" -Search | Should -Not -BeNullOrEmpty + Get-JCSystemApp -name "microsoft edge" -Search | Should -Not -BeNullOrEmpty + Get-JCSystemApp -name "curl" -Search | Should -Not -BeNullOrEmpty + } + + It "Tests the search param with systemID" { + + $macApps = Get-JCSystemApp -Systemid $mac._id -name "a" -search + $windowsApps = Get-JCSystemApp -Systemid $windows._id -name "a" -search + $linuxApps = Get-JCSystemApp -Systemid $linux._id -name "a" -search + $foundMacSystems = $macApps.systemid | Select-Object -Unique + $foundWindowsSystems = $windowsApps.systemid | Select-Object -Unique + $foundLinuxSystems = $linuxApps.systemid | Select-Object -Unique + # if you specify a systemID and Search, results should not contain multiple systems + $foundMacSystems.count | should -Be 1 + $foundWindowsSystems.count | should -Be 1 + $foundLinuxSystems.count | should -Be 1 + } + It "Tests the search param with macos SystemOS" { + # MacOS + $apps = Get-JCSystemApp -SystemOS "macos" -name "a" -search + $foundMacSystems = $apps.systemid | Select-Object -Unique + # if you specify a systemOS and Search, results should not contain multiple systems + foreach ($system in $foundSystems) { + $foundMacSystems = Get-JCSystem -SystemID $system + $foundMacSystems.osfamily | Should -be 'darwin' + } + } + It "Tests the search param with windows SystemOS" { + # Windows + $apps = Get-JCSystemApp -SystemOS "windows" -name "a" -search + $foundWindowsSystems = $apps.systemid | Select-Object -Unique + # if you specify a systemOS and Search, results should not contain multiple systems + foreach ($system in $foundWindowsSystems) { + $foundWindowsSystems = Get-JCSystem -SystemID $system + $foundWindowsSystems.osfamily | Should -be 'windows' + } + } + It "Tests the search param with linux SystemOS" { + # Linux + $apps = Get-JCSystemApp -SystemOS "linux" -name "a" -search + $foundLinuxSystems = $apps.systemid | Select-Object -Unique + # if you specify a systemOS and Search, results should not contain multiple systems + foreach ($system in $foundLinuxSystems) { + $foundLinuxSystems = Get-JCSystem -SystemID $system + $foundLinuxSystems.osfamily | Should -be 'linux' + } + } + + It "Tests compatability macOS with the SDKs" { + #MacOS + $sdkMac = Get-JcSdkSystemInsightApp -filter @("system_id:eq:$($mac._id)", "name:eq:Chess.app") + $moduleMac = Get-JCSystemApp -SystemID $mac._id -name "Chess" + $moduleMacSearch = Get-JCSystemApp -SystemID $mac._id -name "chess" -Search + # SDK Results should look exactly like module results when exact name is specified + $sdkMac.id | Should -Be $moduleMac.id + $sdkMac.name | Should -Be $moduleMac.name + # SDK Results should look exactly like module results when search is provided + $sdkMac.id | Should -Be $moduleMacSearch.id + $moduleMacSearch.name | Should -Contain $sdkMac.name + } + It "Tests compatability windows with the SDKs" { + #Windows + $sdkWindows = Get-JcSdkSystemInsightProgram -filter @("system_id:eq:$($windows._id)", "name:eq:Microsoft Edge") + $moduleWindows = Get-JCSystemApp -SystemID $windows._id -name "Microsoft Edge" + $moduleWindowsSearch = Get-JCSystemApp -SystemID $windows._id -name "microsoft edge" -Search + # SDK Results should look exactly like module results when exact name is specified + $sdkWindows.id | Should -Be $moduleWindows.id + $sdkWindows.name | Should -Be $moduleWindows.name + # SDK Results should look exactly like module results when search is provided + $sdkWindows.id | Should -Be $moduleWindowsSearch.id + $moduleWindowsSearch.name | Should -Contain $sdkWindows.name + } + It "Tests compatability linux with the SDKs" { + #Linux + $sdkLinux = Get-JcSdkSystemInsightLinuxPackage -filter @("system_id:eq:$($linux._id)", "name:eq:curl") + $moduleLinux = Get-JCSystemApp -SystemID $linux._id -name "curl" + $moduleLinuxSearch = Get-JCSystemApp -SystemID $linux._id -name "curl" -Search + # SDK Results should look exactly like module results when exact name is specified + $sdkLinux.id | Should -Be $moduleLinux.id + $sdkLinux.name | Should -Be $moduleLinux.name + # SDK Results should look exactly like module results when search is provided + $sdkLinux.id | Should -Be $moduleLinuxSearch.id + $moduleLinuxSearch.name | Should -Contain $sdkLinux.name + } + + It "Tests that incompatible parameters should not be used together" { + # -version should not be specified with -Search + { Get-JCSystemApp -name "chess" -Search -version "3.1.2" } | Should -Throw + # -SystemOS should not be specified with -SystemID + { Get-JCsystemApp -SystemID $mac._id -SystemOS "windows" } | Should -Throw + { Get-JCsystemApp -SystemID $mac._id -SystemOS "windows" } | Should -Throw + { Get-JCsystemApp -SystemID $mac._id -SystemOS "windows" -name "Chess" } | Should -Throw + { Get-JCsystemApp -SystemID $mac._id -SystemOS "windows" -name "Chess" -version "1.2.3" } | Should -Throw + } + + It "Tests the exporability of a list of software apps" { + { Get-JCSystemApp -SystemOS linux | ConvertTo-Csv } | Should -Not -Throw + # Should return mac apps for all systems in the org + { Get-JCSystemApp -SystemOS macOS | ConvertTo-Csv } | Should -Not -Throw + # Should return windows programs for all systems in the org + { Get-JCSystemApp -SystemOS windows | ConvertTo-Csv } | Should -Not -Throw + { Get-JCSystemApp -SystemID $mac._id | ConvertTo-Csv } | Should -Not -Throw + { Get-JCSystemApp -SystemID $windows._id | ConvertTo-Csv } | Should -Not -Throw + { Get-JCSystemApp -SystemID $linux._id | ConvertTo-Csv } | Should -Not -Throw + } + It "Tests macos functionatily to append .app to softwareName" { + Get-JCSystemApp -SystemID $mac._id -name "Chess.app" | Should -Not -BeNullOrEmpty + Get-JCSystemApp -SystemID $mac._id -name "Chess.App" | Should -Not -BeNullOrEmpty + Get-JCSystemApp -SystemID $mac._id -name "Chess" | Should -Not -BeNullOrEmpty + } +} \ No newline at end of file diff --git a/PowerShell/JumpCloud Module/en-Us/JumpCloud-help.xml b/PowerShell/JumpCloud Module/en-Us/JumpCloud-help.xml index 697fbd989..a6138f089 100644 --- a/PowerShell/JumpCloud Module/en-Us/JumpCloud-help.xml +++ b/PowerShell/JumpCloud Module/en-Us/JumpCloud-help.xml @@ -7048,6 +7048,218 @@ PS C:\> $BackupJcOrganizationResults.User + + + Get-JCSystemApp + Get + JCSystemApp + + Returns the applications/programs/linux packages installed on JumpCloud managed system(s). This function queries separate system insights tables to get data for macOS/windows/linux devices. + + + + Get-JCSystem app function helps admins identify what applications/programs or linux packages exist on their JumpCloud managed systems. + + + + Get-JCSystemApp + + name + + The name of the application you want to search for ex. (Jumpcloud, Slack). Name will always query the "name" property from system insights. Note, for macOS systems, ".app" will be applied. This field is case sensitive. + + System.String + + System.String + + + None + + + Search + + Search for a specific application by from all systems in the org ex. (Get-JCSystemApp -Search -Name "Jumpcloud") THIS PARAMETER DOES NOT TAKE INPUT + + + System.Management.Automation.SwitchParameter + + + False + + + SystemID + + The System Id of the JumpCloud system you want to search for applications + + System.String + + System.String + + + None + + + SystemOS + + The type (windows, mac, linux) of the JumpCloud Command you wish to search ex. (Windows, macOs, Linux)) + + + Windows + macOS + Linux + + System.String + + System.String + + + None + + + version + + The version of the application you want to search for ex. 1.1.2. Note: on Windows/ Linux devices, this parameter will filter on the 'version' property, for macOS applications this parameter will filter on the 'bundleShortVersion' property. + + System.String + + System.String + + + None + + + + + + name + + The name of the application you want to search for ex. (Jumpcloud, Slack). Name will always query the "name" property from system insights. Note, for macOS systems, ".app" will be applied. This field is case sensitive. + + System.String + + System.String + + + None + + + Search + + Search for a specific application by from all systems in the org ex. (Get-JCSystemApp -Search -Name "Jumpcloud") THIS PARAMETER DOES NOT TAKE INPUT + + System.Management.Automation.SwitchParameter + + System.Management.Automation.SwitchParameter + + + False + + + SystemID + + The System Id of the JumpCloud system you want to search for applications + + System.String + + System.String + + + None + + + SystemOS + + The type (windows, mac, linux) of the JumpCloud Command you wish to search ex. (Windows, macOs, Linux)) + + System.String + + System.String + + + None + + + version + + The version of the application you want to search for ex. 1.1.2. Note: on Windows/ Linux devices, this parameter will filter on the 'version' property, for macOS applications this parameter will filter on the 'bundleShortVersion' property. + + System.String + + System.String + + + None + + + + + + System.String + + + + + + + + + + System.Object + + + + + + + + + + + + + + -------------------------- Example 1 -------------------------- + PS C:\> Get-JCSystemApp -SystemId '6363237ec991136ae59892e4' + + Returns the applications installed in the system with the given -SystemId + + + + -------------------------- Example 2 -------------------------- + PS C:\> Get-JCSystemApp -SystemOs 'macOS' + + Returns the 'macOS' systems and all the applications installed for each system + + + + -------------------------- Example 3 -------------------------- + PS C:\> Get-JCSystemApp -SystemOs 'macOS' -Name 'Jumpcloud' + + + + + + -------------------------- Example 4 -------------------------- + PS C:\> Get-JCSystemApp -SystemOs 'macOS' -Name 'Jumpcloud' -Version 'v1.16.2' + + Returns the 'macOS' systems that have a 'Jumpcloud' tray application with the version 'v1.16.2' + + + + -------------------------- Example 5 -------------------------- + PS C:\> Get-JCSystemApp -Name 'jumpcloud' -Search + + Returns any 'jumpcloud' software installed in all the OS systems (Windows/Linux/macOS) + + + + + + Online Version: + https://github.com/TheJumpCloud/support/wiki/ + + + Get-JCSystemGroupMember diff --git a/PowerShell/ModuleChangelog.md b/PowerShell/ModuleChangelog.md index 10894ef9b..42621d474 100644 --- a/PowerShell/ModuleChangelog.md +++ b/PowerShell/ModuleChangelog.md @@ -1,3 +1,20 @@ +## 2.2.0 + +Release Date: February 7, 2023 + +#### RELEASE NOTES + +``` +This release adds new function Get-JCSystemApp which enables admins to search for 'x' software and 'y' version on specific device, devices in a specific os, or all managed JumpCloud devices. +``` + +#### FEATURES: + +- Get-JCSystemApp command enables search by: + - applications installed in a specific system + - applications installed from all the systems specified by OS + - Software Name and or Version + ## 2.1.3 Release Date: January 5, 2023