diff --git a/src/powershell/Initialize-Dependencies.ps1 b/src/powershell/Initialize-Dependencies.ps1 index ca315032c5..867252e541 100644 --- a/src/powershell/Initialize-Dependencies.ps1 +++ b/src/powershell/Initialize-Dependencies.ps1 @@ -100,8 +100,8 @@ function Initialize-Dependencies { [Microsoft.PowerShell.Commands.ModuleSpecification[]]$externalModuleDependencies = $moduleManifest.PrivateData.ExternalModuleDependencies [Microsoft.PowerShell.Commands.ModuleSpecification[]]$xPlatPowerShellRequiredModules = @( - @{ModuleName = 'Microsoft.Graph.Authentication'; GUID = '883916f2-9184-46ee-b1f8-b6a2fb784cee'; ModuleVersion = '2.32.0'; }, - @{ModuleName = 'Microsoft.Graph.Beta.Teams'; GUID = 'e264919d-7ae2-4a89-ba8b-524bd93ddc08'; ModuleVersion = '2.32.0'; }, + @{ModuleName = 'Microsoft.Graph.Authentication'; GUID = '883916f2-9184-46ee-b1f8-b6a2fb784cee'; ModuleVersion = '2.35.1'; }, + @{ModuleName = 'Microsoft.Graph.Beta.Teams'; GUID = 'e264919d-7ae2-4a89-ba8b-524bd93ddc08'; ModuleVersion = '2.35.1'; }, @{ModuleName = 'Az.Accounts'; GUID = '17a2feff-488b-47f9-8729-e2cec094624c'; ModuleVersion = '4.0.2'; }, @{ModuleName = 'ExchangeOnlineManagement'; GUID = 'b5eced50-afa4-455b-847a-d8fb64140a22'; RequiredVersion = '3.9.0'; } ) @@ -178,6 +178,7 @@ function Initialize-Dependencies { { if ($saveModuleCmd.Name -eq 'Save-PSResource') { + #TODO: use the find before piping result to Save-PSResource. $saveModuleCmdParamsClone['Name'] = $moduleSpec.Name # Save-PSResource uses NuGet version range syntax: https://learn.microsoft.com/en-us/nuget/concepts/package-versioning?tabs=semver20sort#version-ranges if ($moduleSpec.RequiredVersion) { diff --git a/src/powershell/ZeroTrustAssessment.psd1 b/src/powershell/ZeroTrustAssessment.psd1 index 5f5c6625a1..7f7d362086 100644 --- a/src/powershell/ZeroTrustAssessment.psd1 +++ b/src/powershell/ZeroTrustAssessment.psd1 @@ -75,7 +75,7 @@ FunctionsToExport = 'Connect-ZtAssessment', 'Disconnect-ZtAssessment', 'Get-ZtExportStatistics', 'Get-ZtGraphScope', 'Get-ZtTest', 'Get-ZtTestStatistics', 'Invoke-ZtAssessment', 'Invoke-ZtGraphRequest', 'Invoke-ZtAzureRequest', - 'Invoke-ZtAzureResourceGraphRequest' + 'Invoke-ZtAzureResourceGraphRequest', 'Clear-ZtRequiredModule' # Cmdlets to export from this module, for best performance, do not use wildcards and do not delete the entry, use an empty array if there are no cmdlets to export. CmdletsToExport = @() @@ -104,8 +104,8 @@ PrivateData = @{ ) XPlatPowerShellRequiredModules = @( - @{ModuleName = 'Microsoft.Graph.Authentication'; GUID = '883916f2-9184-46ee-b1f8-b6a2fb784cee'; ModuleVersion = '2.32.0'; }, - @{ModuleName = 'Microsoft.Graph.Beta.Teams'; GUID = 'e264919d-7ae2-4a89-ba8b-524bd93ddc08'; ModuleVersion = '2.32.0'; }, + @{ModuleName = 'Microsoft.Graph.Authentication'; GUID = '883916f2-9184-46ee-b1f8-b6a2fb784cee'; ModuleVersion = '2.35.1'; }, + @{ModuleName = 'Microsoft.Graph.Beta.Teams'; GUID = 'e264919d-7ae2-4a89-ba8b-524bd93ddc08'; ModuleVersion = '2.35.1'; }, @{ModuleName = 'Az.Accounts'; GUID = '17a2feff-488b-47f9-8729-e2cec094624c'; ModuleVersion = '4.0.2'; }, @{ModuleName = 'ExchangeOnlineManagement'; GUID = 'b5eced50-afa4-455b-847a-d8fb64140a22'; RequiredVersion = '3.9.0'; } ) diff --git a/src/powershell/public/Clear-ZtRequiredModule.ps1 b/src/powershell/public/Clear-ZtRequiredModule.ps1 new file mode 100644 index 0000000000..a56f05a7fe --- /dev/null +++ b/src/powershell/public/Clear-ZtRequiredModule.ps1 @@ -0,0 +1,70 @@ +param () + +function Clear-ZtRequiredModule { + <# + .SYNOPSIS + Remove all modules downloaded into the ~/.cache/ZeroTrustAssessment/Modules or %APPDATA%\ZeroTrustAssessment\Modules folder + by the Zero Trust Assessment module. + + .DESCRIPTION + This cmdlet removes all modules that were downloaded and installed by the Zero Trust Assessment module into the user's + cache or application data directories. + Since these modules are imported into the global session when the Zero Trust Assessment module is imported, + they cannot be removed until the session is closed. + + Since this command wouldn't work if running in a session where the Zero Trust Assessment module is currently loaded, + it detects if it's being called during module loading and exits with a warning message and instructions on how to run it successfully. + + .EXAMPLE + Clear-ZtRequiredModule + + # This won't remove the modules because it runs in the same session where ZeroTrustAssessment module is currently loaded + # Instead, it will show a warning message with instructions on how to run it successfully. + + .EXAMPLE + &'\Clear-ZtRequiredModule.ps1' + + # If this is run in a clean session, and you closed all other sessions where ZeroTrustAssessment module was loaded, + # it will remove all modules downloaded by the Zero Trust Assessment module. + + #> + [CmdletBinding()] + param ( + ) + + # If CallStack from the Module file (psm1), the module is being loaded. + if ((Get-PSCallStack).Position.File -like '*ZeroTrustAssessment.psm1') + { + Write-Verbose -Message 'Command is being called from module loading. Ignoring.' + return + } + elseif ($MyInvocation.MyCommand.Module) # Called when module is loaded. + { + Write-Warning -Message 'This command cannot be run when the module is loaded.' + Write-Warning -Message 'Please close all sessions where ZeroTrustAssessment module is loaded, then run the following...' + Write-Warning -Message ('&''{0}''' -f $PSCommandPath) + if ($isWindows -and (Get-Command -Name Set-Clipboard -ErrorAction SilentlyContinue)) { + Set-Clipboard -Value ('&''{0}''' -f $PSCommandPath) + Write-Warning -Message '(The command has been copied to your clipboard.)' + } + return + } + else + { + Write-Verbose -Message 'Clearing ZTA required modules from the current session.' + } + + # Remove all ZTA-related modules from the current session + if ($isWindows) { + $ZTAModulesFolder = Join-Path -Path $Env:APPDATA -ChildPath 'ZeroTrustAssessment\Modules' + } + else { + $ZTAModulesFolder = Join-Path -Path $Env:HOME -ChildPath '.cache/ZeroTrustAssessment/Modules' + } + + if (Test-Path -Path $ZTAModulesFolder) { + Remove-Item -Path $ZTAModulesFolder -Recurse -Force -ErrorAction Continue + } +} + +Clear-ZtRequiredModule @PSBoundParameters diff --git a/src/powershell/public/Connect-ZtAssessment.ps1 b/src/powershell/public/Connect-ZtAssessment.ps1 index 48b86161d3..e08dd87a35 100644 --- a/src/powershell/public/Connect-ZtAssessment.ps1 +++ b/src/powershell/public/Connect-ZtAssessment.ps1 @@ -1,16 +1,13 @@ function Connect-ZtAssessment { <# .SYNOPSIS - Helper method to connect to Microsoft Graph using Connect-MgGraph with the required scopes. + Helper method to connect to Microsoft Graph and other services with the appropriate parameters + and scopes for the Zero Trust Assessment. .DESCRIPTION - Use this cmdlet to connect to Microsoft Graph using Connect-MgGraph. - - This command is completely optional if you are already connected to Microsoft Graph and other services using Connect-MgGraph with the required scopes. - - ``` - Connect-MgGraph -Scopes (Get-ZtGraphScope) - ``` + Use this cmdlet to connect to Microsoft Graph and other services using the appropriate parameters and scopes + for the Zero Trust Assessment. + This cmdlet will import the necessary modules and establish connections based on the specified parameters. .PARAMETER UseDeviceCode If specified, the cmdlet will use the device code flow to authenticate to Graph and Azure. @@ -35,12 +32,14 @@ function Connect-ZtAssessment { If this certificate is also used for connecting to Azure, it must come from a certificate store on the local computer. .PARAMETER SkipAzureConnection - If specified, skips connecting to Azure and only connects to Microsoft Graph. + If specified, skips connecting to Azure and only connects to other services. .EXAMPLE PS C:\> Connect-ZtAssessment - Connects to Microsoft Graph using Connect-MgGraph with the required scopes. + Connects to Microsoft Graph and other services using Connect-MgGraph with the required scopes and other services. + By default, on Windows, this connects to Graph, Azure, Exchange Online, Security & Compliance, SharePoint Online, and Azure Information Protection. + On other platforms, this connects to Graph, Azure, Exchange and Security & Compliance (where supported). .EXAMPLE PS C:\> Connect-ZtAssessment -UseDeviceCode @@ -50,10 +49,10 @@ function Connect-ZtAssessment { .EXAMPLE PS C:\> Connect-ZtAssessment -SkipAzureConnection - Connects to Microsoft Graph only, skipping the Azure connection. The tests that require Azure connectivity will be skipped. + Connects to services but skipping the Azure connection. The tests that require Azure connectivity will be skipped. .EXAMPLE - PS C:\> Connect-ZtAssessment -ClientID $clientID -TenantID $tenantID -Certificate 'CN=ZeroTrustAssessment' + PS C:\> Connect-ZtAssessment -ClientID $clientID -TenantID $tenantID -Certificate 'CN=ZeroTrustAssessment' -Service Graph,Azure Connects to Microsoft Graph and Azure using the specified client/application ID & tenant ID, using the latest, valid certificate available with the subject 'CN=ZeroTrustAssessment'. This assumes the correct scopes and permissions are assigned to the application used. @@ -82,9 +81,9 @@ function Connect-ZtAssessment { [switch] $SkipAzureConnection, - # The services to connect to such as Azure and ExchangeOnline. Default is Graph. + # The services to connect to such as Azure and ExchangeOnline. Default is All. [ValidateSet('All', 'Azure', 'AipService', 'ExchangeOnline', 'Graph', 'SecurityCompliance', 'SharePointOnline')] - [string[]]$Service = 'Graph', + [string[]]$Service = 'All', # The Exchange environment to connect to. Default is O365Default. Supported values include O365China, O365Default, O365GermanyCloud, O365USGovDoD, O365USGovGCCHigh. [ValidateSet('O365China', 'O365Default', 'O365GermanyCloud', 'O365USGovDoD', 'O365USGovGCCHigh')] @@ -97,7 +96,6 @@ function Connect-ZtAssessment { [string]$SharePointAdminUrl ) - # Ensure ExchangeOnline is included if SecurityCompliance is requested if ($Service -contains 'SecurityCompliance' -and $Service -notcontains 'ExchangeOnline' -and $Service -notcontains 'All') { Write-Verbose "Adding ExchangeOnline to the list of services to connect to as it is required for SecurityCompliance." @@ -117,8 +115,8 @@ function Connect-ZtAssessment { } [Microsoft.PowerShell.Commands.ModuleSpecification[]]$xPlatPowerShellRequiredModules = @( - @{ModuleName = 'Microsoft.Graph.Authentication'; GUID = '883916f2-9184-46ee-b1f8-b6a2fb784cee'; ModuleVersion = '2.32.0'; }, - @{ModuleName = 'Microsoft.Graph.Beta.Teams'; GUID = 'e264919d-7ae2-4a89-ba8b-524bd93ddc08'; ModuleVersion = '2.32.0'; }, + @{ModuleName = 'Microsoft.Graph.Authentication'; GUID = '883916f2-9184-46ee-b1f8-b6a2fb784cee'; ModuleVersion = '2.35.1'; }, + @{ModuleName = 'Microsoft.Graph.Beta.Teams'; GUID = 'e264919d-7ae2-4a89-ba8b-524bd93ddc08'; ModuleVersion = '2.35.1'; }, @{ModuleName = 'Az.Accounts'; GUID = '17a2feff-488b-47f9-8729-e2cec094624c'; ModuleVersion = '4.0.2'; }, @{ModuleName = 'ExchangeOnlineManagement'; GUID = 'b5eced50-afa4-455b-847a-d8fb64140a22'; RequiredVersion = '3.9.0'; } )