From 0b1ab0cbe9a5890b24ddabf51741bccae3df0301 Mon Sep 17 00:00:00 2001 From: Richard Crutchfield Date: Wed, 28 Feb 2024 12:15:11 -0500 Subject: [PATCH 01/10] Update dependencies --- PowerShell/ScubaGear/Dependencies.ps1 | 26 +++++++++++++++++++++----- 1 file changed, 21 insertions(+), 5 deletions(-) diff --git a/PowerShell/ScubaGear/Dependencies.ps1 b/PowerShell/ScubaGear/Dependencies.ps1 index 0a759a6d99..faf780d8c8 100644 --- a/PowerShell/ScubaGear/Dependencies.ps1 +++ b/PowerShell/ScubaGear/Dependencies.ps1 @@ -3,6 +3,8 @@ .SYNOPSIS This script verifies the required Powershell modules used by the assessment tool are installed. + .PARAMETER Force + This will cause all required dependencies to be installed and updated to latest. .DESCRIPTION Verifies a supported version of the modules required to support SCuBAGear are installed. #> @@ -18,7 +20,8 @@ if (!$ModuleList){ $SupportModulesPath = Join-Path -Path $PSScriptRoot -ChildPath "Modules/Support/Support.psm1" Import-Module -Name $SupportModulesPath -Initialize-SCuBA -SkipUpdate -NoOPA + +$MissingModules = @() foreach ($Module in $ModuleList) { Write-Debug "Evaluating module: $($Module.ModuleName)" @@ -34,13 +37,26 @@ foreach ($Module in $ModuleList) { } if (-not $FoundAcceptableVersion) { - throw [System.IO.FileNotFoundException] "No acceptable installed version found for module: $($Module.ModuleName) - Required Min Version: $($Module.ModuleVersion) | Max Version: $($Module.MaximumVersion) - Run Get-InstalledModule to see a list of currently installed modules - Run Install-Module $($Module.ModuleName) -Force -MaximumVersion $($Module.MaximumVersion) to install the latest acceptable version of $($Module.ModuleName)" + $MissingModules += $Module } } +if ($MissingModules.Count -gt 0){ + # Set preferences for writing messages + $PreferenceStack = New-Object -TypeName System.Collections.Stack + $PreferenceStack.Push($WarningPreference) + $WarningPreference = "Continue" + + Write-Warning " + The required supporting PowerShell modules are not installed. + Run Initialize-SCuBA to install all required dependencies. + See Get-Help Initialize-SCuBA for more help." + Write-Debug "The following modules are not installed:" + foreach ($Module in $MissingModules){ + Write-Debug "`t$($Module.ModuleName)" + } + $WarningPreference = $PreferenceStack.Pop() +} From 697b3b66bc50be4e1cefa7bac0d41f70b2039559 Mon Sep 17 00:00:00 2001 From: Richard Crutchfield Date: Wed, 28 Feb 2024 13:12:15 -0500 Subject: [PATCH 02/10] Add init for scuba --- .github/workflows/run_smoke_test.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/run_smoke_test.yaml b/.github/workflows/run_smoke_test.yaml index f0b14614eb..a39586e367 100644 --- a/.github/workflows/run_smoke_test.yaml +++ b/.github/workflows/run_smoke_test.yaml @@ -37,7 +37,7 @@ jobs: ##### Install all the dependencies Install-SmokeTestExternalDependencies Import-Module -Name .\PowerShell\ScubaGear\ScubaGear.psd1 - Install-OPA + Initialize-SCuBA -SkipUpdate # Workaround for Selenium. Loading psm1 instead of psd1 Import-Module -Name (Get-Module -Name Selenium -ListAvailable).Path -Force From cde7adaf33f4a74d29d130f6db4b4a74930057b1 Mon Sep 17 00:00:00 2001 From: Richard Crutchfield Date: Wed, 28 Feb 2024 13:48:35 -0500 Subject: [PATCH 03/10] Remove SkipUpdate --- .github/workflows/run_smoke_test.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/run_smoke_test.yaml b/.github/workflows/run_smoke_test.yaml index a39586e367..b26f68a12c 100644 --- a/.github/workflows/run_smoke_test.yaml +++ b/.github/workflows/run_smoke_test.yaml @@ -37,7 +37,7 @@ jobs: ##### Install all the dependencies Install-SmokeTestExternalDependencies Import-Module -Name .\PowerShell\ScubaGear\ScubaGear.psd1 - Initialize-SCuBA -SkipUpdate + Initialize-SCuBA # Workaround for Selenium. Loading psm1 instead of psd1 Import-Module -Name (Get-Module -Name Selenium -ListAvailable).Path -Force From b882625fdaaedc7613d056bfa29a5d0439fce1dc Mon Sep 17 00:00:00 2001 From: Richard Crutchfield Date: Wed, 28 Feb 2024 14:14:04 -0500 Subject: [PATCH 04/10] Relpace OPA.ps1 --- PowerShell/ScubaGear/Modules/Support/Support.psm1 | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/PowerShell/ScubaGear/Modules/Support/Support.psm1 b/PowerShell/ScubaGear/Modules/Support/Support.psm1 index c3746c4325..63020ddddb 100644 --- a/PowerShell/ScubaGear/Modules/Support/Support.psm1 +++ b/PowerShell/ScubaGear/Modules/Support/Support.psm1 @@ -178,8 +178,7 @@ function Initialize-SCuBA { } else { try { - $ScriptDir = Split-Path -Path $MyInvocation.MyCommand.Definition -Parent - . $ScriptDir\OPA.ps1 -name $OPAExe -version $ExpectedVersion -os $OperatingSystem -ScubaParentDirectory $ScubaParentDirectory + Install-OPA -OPAExe $OPAExe -ExpectedVersion $ExpectedVersion -OperatingSystem $OperatingSystem -ScubaParentDirectory $ScubaParentDirectory } catch { $Error[0] | Format-List -Property * -Force | Out-Host From a8e62b48ce2cb9807eadde8397d9e678bbf3dd06 Mon Sep 17 00:00:00 2001 From: Richard Crutchfield Date: Wed, 28 Feb 2024 14:36:14 -0500 Subject: [PATCH 05/10] Call Initialize-SCuBA --- .github/workflows/run_functional_product_tests.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/run_functional_product_tests.yaml b/.github/workflows/run_functional_product_tests.yaml index d05a4d1bb7..62021a6443 100644 --- a/.github/workflows/run_functional_product_tests.yaml +++ b/.github/workflows/run_functional_product_tests.yaml @@ -48,7 +48,7 @@ jobs: Import-Module -Name Selenium ./Testing/Functional/SmokeTest/UpdateSelenium.ps1 Import-Module -Name .\PowerShell\ScubaGear\ScubaGear.psd1 - Install-OPA + Initialize-SCuBA # Workaround for Selenium. Loading psm1 instead of psd1 Import-Module -Name (Get-Module -Name Selenium -ListAvailable).Path -Force - name: Test Products From 2b813ec968c0211fa408a150ff5ee4f18987d02f Mon Sep 17 00:00:00 2001 From: Richard Crutchfield Date: Thu, 29 Feb 2024 07:09:21 -0500 Subject: [PATCH 06/10] Update README --- README.md | 53 +++++++++++++++++++++++++++-------------------------- 1 file changed, 27 insertions(+), 26 deletions(-) diff --git a/README.md b/README.md index d7cb61a563..4dd22c14c5 100644 --- a/README.md +++ b/README.md @@ -10,8 +10,6 @@ Developed by CISA, ScubaGear is an assessment tool that verifies a Microsoft 365 - [M365 Product License Assumptions](#m365-product-license-assumptions) - [Getting Started](#getting-started) - [Download the Latest Release](#download-the-latest-release) - - [Installing the Required PowerShell Modules](#installing-the-required-powershell-modules) - - [Download the Required OPA executable](#download-the-required-opa-executable) - [PowerShell Execution Policies](#powershell-execution-policies) - [Usage](#usage) - [Importing the module](#importing-the-module) @@ -57,30 +55,6 @@ To download ScubaGear: 2. Click `ScubaGear-v1-1-1.zip` (or latest version) to download the release. 3. Extract the folder in the zip file. -### Installing the Required PowerShell Modules -> [!NOTE] -> Only PowerShell 5.1 is currently supported. PowerShell 7 may work, but has not been tested. Full PowerShell 7 support will be added in a future release. - -To install the module dependencies, open a new PowerShell 5.1 terminal and navigate to the repository folder. - -Then run: - -```powershell -Import-Module -Name .\PowerShell\ScubaGear # Imports module and minimum required dependencies -``` - -### Download the Required OPA executable -> [!IMPORTANT] -> The `Install-OPA` cmdlet is called by default when running `Initialize-SCuBA`. The `Install-OPA` cmdlet can also be run by itself to download the executable. -In the event of an unsuccessful download, users can manually download the OPA executable with the following steps: -1. Go to OPA download site (https://www.openpolicyagent.org/docs/latest/#running-opa) -2. Check the acceptable OPA version (Currently v0.61.0) for ScubaGear and select the corresponding version on top left of the website -3. Navigate to the menu on left side of the screen: Introduction - Running OPA - Download OPA -4. Locate the downloaded file, add the file to the root directory of this repository, open PowerShell, and use the following command to check the downloaded OPA version -```powershell -.\opa_windows_amd64.exe version -``` - ### PowerShell Execution Policies Starting with release 0.3.0, ScubaGear is signed by a commonly trusted CA. On Windows Servers, the default [execution policy](https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.security/set-executionpolicy?view=powershell-5.1) is `RemoteSigned`, which will allow ScubaGear to run after the publisher (CISA) is agreed to once. @@ -92,6 +66,9 @@ Windows clients with an execution policy of `Unrestricted` generate a warning ab ScubaGear can be invoked interactively or non-interactively. See [Required Permissions](#required-permissions) for the permissions needed to execute the tool in either mode. The interactive authentication mode will prompt the user for credentials via Microsoft's popup windows. Non-interactive mode is for invoking ScubaGear using an Azure AD application service principal and supports running the tool in automated scenarios such as pipelines or scheduled jobs. Examples 1-3 provide examples for running with interactive mode and example 4 provides an example for running in non-interactive mode. ### Importing the module +> [!NOTE] +> Only PowerShell 5.1 is currently supported. PowerShell 7 may work, but has not been tested. Full PowerShell 7 support will be added in a future release. + ScubaGear currently must be imported into each new PowerShell terminal session to execute. To import the module, navigate to the repository folder in a PowerShell 5.1 terminal. @@ -100,6 +77,30 @@ Then run: Import-Module -Name .\PowerShell\ScubaGear # Imports the module into your session ``` +If you receive a warning that _The required supporting PowerShell modules are not installed._ + +Then run: + +```powershell +Initialize-SCuBA # Imports module and minimum required dependencies +``` + +For additional help on __Initialize-SCuBA__ run: + +```powershell +Get-Help Initialize-SCuBA +``` + +> [!IMPORTANT] +> The `Install-OPA` cmdlet is called by default when running `Initialize-SCuBA`. The `Install-OPA` cmdlet can also be run by itself to download the executable. +In the event of an unsuccessful download, users can manually download the OPA executable with the following steps: +1. Go to OPA download site (https://www.openpolicyagent.org/docs/latest/#running-opa) +2. Check the acceptable OPA version (Currently v0.61.0) for ScubaGear and select the corresponding version on top left of the website +3. Navigate to the menu on left side of the screen: Introduction - Running OPA - Download OPA +4. Locate the downloaded file, add the file to your desired location (default is ~\\.scubagear\Tools), open PowerShell, and use the following command to check the downloaded OPA version +```powershell +.\opa_windows_amd64.exe version +``` ### Examples #### Example 1: Run an assessment against all products (except PowerPlatform) From 3a31e107f5d8793d1d4162ad230de26052a3f537 Mon Sep 17 00:00:00 2001 From: Richard Crutchfield Date: Fri, 1 Mar 2024 07:33:29 -0500 Subject: [PATCH 07/10] Update PowerShell/ScubaGear/Dependencies.ps1 Co-authored-by: David Bui <105074908+buidav@users.noreply.github.com> --- PowerShell/ScubaGear/Dependencies.ps1 | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/PowerShell/ScubaGear/Dependencies.ps1 b/PowerShell/ScubaGear/Dependencies.ps1 index faf780d8c8..5c541add29 100644 --- a/PowerShell/ScubaGear/Dependencies.ps1 +++ b/PowerShell/ScubaGear/Dependencies.ps1 @@ -48,7 +48,7 @@ if ($MissingModules.Count -gt 0){ $WarningPreference = "Continue" Write-Warning " - The required supporting PowerShell modules are not installed. + The required supporting PowerShell modules are not installed with a supported version. Run Initialize-SCuBA to install all required dependencies. See Get-Help Initialize-SCuBA for more help." From c8b69ba144c54daac82d3c6b144102b2ca8b5333 Mon Sep 17 00:00:00 2001 From: Richard Crutchfield Date: Fri, 1 Mar 2024 07:34:49 -0500 Subject: [PATCH 08/10] Update README.md Co-authored-by: Addam Schroll <108814318+schrolla@users.noreply.github.com> --- README.md | 11 +---------- 1 file changed, 1 insertion(+), 10 deletions(-) diff --git a/README.md b/README.md index 4dd22c14c5..f1c2716514 100644 --- a/README.md +++ b/README.md @@ -77,19 +77,10 @@ Then run: Import-Module -Name .\PowerShell\ScubaGear # Imports the module into your session ``` -If you receive a warning that _The required supporting PowerShell modules are not installed._ - -Then run: +If you receive a warning that _The required supporting PowerShell modules are not installed_, run the following cmdlet: ```powershell Initialize-SCuBA # Imports module and minimum required dependencies -``` - -For additional help on __Initialize-SCuBA__ run: - -```powershell -Get-Help Initialize-SCuBA -``` > [!IMPORTANT] > The `Install-OPA` cmdlet is called by default when running `Initialize-SCuBA`. The `Install-OPA` cmdlet can also be run by itself to download the executable. From 3a801ee19bace5f75f9e78cb79fce0875ba076cf Mon Sep 17 00:00:00 2001 From: Richard Crutchfield Date: Fri, 1 Mar 2024 09:59:07 -0500 Subject: [PATCH 09/10] Update readme --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index f1c2716514..7ad6909ddc 100644 --- a/README.md +++ b/README.md @@ -81,7 +81,7 @@ If you receive a warning that _The required supporting PowerShell modules are no ```powershell Initialize-SCuBA # Imports module and minimum required dependencies - +``` > [!IMPORTANT] > The `Install-OPA` cmdlet is called by default when running `Initialize-SCuBA`. The `Install-OPA` cmdlet can also be run by itself to download the executable. In the event of an unsuccessful download, users can manually download the OPA executable with the following steps: From f1408bd861bd58152ddfcd93cb329e3399516c3a Mon Sep 17 00:00:00 2001 From: Richard Crutchfield Date: Wed, 6 Mar 2024 06:25:19 -0500 Subject: [PATCH 10/10] Update README.md Co-authored-by: David Bui <105074908+buidav@users.noreply.github.com> --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 7ad6909ddc..839840c1e6 100644 --- a/README.md +++ b/README.md @@ -80,7 +80,7 @@ Import-Module -Name .\PowerShell\ScubaGear # Imports the module into your sessio If you receive a warning that _The required supporting PowerShell modules are not installed_, run the following cmdlet: ```powershell -Initialize-SCuBA # Imports module and minimum required dependencies +Initialize-SCuBA # Installs the minimum required dependencies ``` > [!IMPORTANT] > The `Install-OPA` cmdlet is called by default when running `Initialize-SCuBA`. The `Install-OPA` cmdlet can also be run by itself to download the executable.