Merge branch '915-revise-msexo51-to-remove-note-about-exceptions' of h…

…ttps://github.com/cisagov/ScubaGear into 915-revise-msexo51-to-remove-note-about-exceptions

.github/workflows/run_secret_scan.yaml

@@ -0,0 +1,24 @@
+# Purpose: Run a secret scanner against the repo.
+
+name: Run Secret Scan
+
+on:
+  push:
+  pull_request:
+  workflow_call:
+  workflow_dispatch:
+
+jobs:
+  secret-scan:
+    name: MegaLint Gitleaks
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        shell: bash
+    steps:
+      - name: Checkout Repo
+        uses: actions/checkout@v4
+      - name: Setup Config File
+        run: cp Testing/Linting/MegaLinter/.mega-linter-secret.yml .mega-linter.yml
+      - name: Check Repo
+        uses: oxsecurity/megalinter/flavors/security@latest

CONTENTSTYLEGUIDE.md

@@ -395,4 +395,35 @@ ExampleArray contains OtherVar.name if {
 ```
 
 ## PowerShell
-[PoshCode's The PowerShell Best Practices and Style Guide](https://github.com/PoshCode/PowerShellPracticeAndStyle)
+[PoshCode's The PowerShell Best Practices and Style Guide](https://github.com/PoshCode/PowerShellPracticeAndStyle)
+
+## README Formatting
+This section is for standardizing how to format the README and it's table of contents (toc) for legibility.
+The formatting guidelines described in the sections below take formatting syntax from the VSCode [Markdown All in One](https://marketplace.visualstudio.com/items?itemName=yzhang.markdown-all-in-one) extension into account. The extension is not required for ScubaGear development but is used as the basis of this guide.
+To keep the README as a consistently formatted and compact resource for users, please follow the guidelines below.
+
+### Character Limit
+If the section header is at a level 2 or level 3 i.e.`## Getting Started` `### Download the Latest Release` keep the section header to at most around 55 characters.
+
+This is to limit text stretching in the toc in the README.
+
+### Omit the Section Headers Including and Above the Table of Contents
+Add the ` <!-- omit in toc -->` comment to the `## Table of Contents` and `# ScubaGear` headers.
+
+**Example**
+```
+ # ScubaGear <!-- omit in toc -->
+```
+These sections are located above the table of contents and are thus unnecessary.
+The comment will prevent the Markdown All in One extension from auto formatting the README with these headers.
+This should already be implemented in the current README but this guideline is to reinforce the decision.
+
+### Omit the Section Headers Level 4+
+If the section header is a level 4+ header i.e `#### Power Platform App Registration` add a omit comment.
+
+**Example**
+```
+#### Power Platform App Registration <!-- omit in toc -->
+```
+This is to prevent the depth of the table of contents in the README from becoming too deeply nested.
+Deeply nested sections disrupt legibility of the toc and should be avoided.

PowerShell/ScubaGear/Rego/AADConfig.rego

@@ -28,9 +28,9 @@ import data.utils.aad.INT_MAX
 # Constants #
 #############
 
-RESTRICTEDACCESS := "2af84b1e-32c8-42b7-82bc-daa82404023b"
+RESTRICTEDACCESS := "2af84b1e-32c8-42b7-82bc-daa82404023b" #gitleaks:allow
 
-LIMITEDACCESS := "10dae51f-b6af-4016-8d66-8c2a99b929b3"
+LIMITEDACCESS := "10dae51f-b6af-4016-8d66-8c2a99b929b3" #gitleaks:allow
 
 MEMBERUSER := "a0b1b346-4d3e-4e8b-98f8-753987be4970"
 

PowerShell/ScubaGear/Testing/Unit/PowerShell/Connection/Connect-Tenant.Tests.ps1

@@ -1,5 +1,4 @@
 Import-Module (Join-Path -Path $PSScriptRoot -ChildPath "../../../../Modules/Connection/Connection.psm1") -Function 'Connect-Tenant' -Force
-Import-Module (Join-Path -Path $PSScriptRoot -ChildPath "../../../../Modules/Connection/ConnectHelpers.psm1") -Force
 
 InModuleScope Connection {
     Describe -Tag 'Connection' -Name "Connect-Tenant" -ForEach @(
@@ -9,13 +8,15 @@ InModuleScope Connection {
         @{Endpoint = 'dod'}
     ){
         BeforeAll {
+            function Connect-MgGraph {throw 'this will be mocked'}
             Mock Connect-MgGraph -MockWith {}
             Mock Connect-PnPOnline -MockWith {}
             Mock Connect-SPOService -MockWith {}
+            function Connect-MicrosoftTeams{throw 'this will be mocked'}
             Mock Connect-MicrosoftTeams -MockWith {}
             Mock Add-PowerAppsAccount -MockWith {}
-            function Connect-EXOHelper {}
-            Mock Connect-EXOHelper -MockWith {}
+            function Connect-EXOHelper {throw 'this will be mocked'}
+            Mock -ModuleName Connection Connect-EXOHelper -MockWith {}
             Mock Get-MgBetaOrganization -MockWith {
                 return [pscustomobject]@{
                     DisplayName     = "DisplayName";
@@ -36,18 +37,45 @@ InModuleScope Connection {
             Mock -CommandName Write-Progress {
             }
         }
-        It 'With Endpoint:  <Endpoint>; ProductNames: <ProductNames>' -ForEach @(
-            @{ProductNames = "aad"}
-            @{ProductNames = "defender"}
-            @{ProductNames = "exo"}
-            @{ProductNames = "powerplatform"}
-            @{ProductNames = "sharepoint"}
-            @{ProductNames = "teams"}
-            @{ProductNames = "aad", "defender", "exo", "powerplatform", "sharepoint", "teams"}
+        Context 'With Endpoint:  <Endpoint>; ProductNames: <ProductNames>' -ForEach @(
+            @{ProductNames = "aad"; Services = @('Connect-MgGraph')}
+            @{ProductNames = "defender"; Services = @('Connect-EXOHelper')}
+            @{ProductNames = "exo"; Services = @('Connect-EXOHelper')}
+            @{ProductNames = "powerplatform"; Services = @('Add-PowerAppsAccount')}
+            @{ProductNames = "sharepoint"; Services = @('Connect-MgGraph', 'Connect-PnPOnline')}
+            @{ProductNames = "teams"; Services = @('Connect-MicrosoftTeams')}
+            @{
+                ProductNames = "aad", "defender", "exo", "powerplatform", "sharepoint", "teams"
+                Services = @(
+                    'Connect-MgGraph',
+                    'Connect-EXOHelper',
+                    'Add-PowerAppsAccount',
+                    'Connect-PnPOnline',
+                    'Connect-MicrosoftTeams'
+                )
+            }
 
         ){
-            $FailedAuthList = Connect-Tenant -ProductNames $ProductNames -M365Environment $Endpoint
-            $FailedAuthList.Length | Should -Be 0
+
+            It "No Service Principal" {
+                $FailedAuthList = Connect-Tenant -ProductNames $ProductNames -M365Environment $Endpoint
+                $FailedAuthList.Length | Should -Be 0
+            }
+            It "With Service Principal" {
+                $ServicePrincipalParams.CertThumbprintParams.CertificateThumbprint
+                $ServicePrincipalParams =@{
+                    CertThumbprintParams = @{
+                        AppID = "a"
+                        CertificateThumbprint = "b"
+                        Organization = "c"
+                    }
+                }
+                Connect-Tenant -ProductNames $ProductNames -M365Environment $Endpoint -ServicePrincipalParams $ServicePrincipalParams
+                foreach ($Service in $Services){
+                    Should -Invoke -CommandName $Service -Exactly -Times 1 -Because "only want to authenticate to needed service once"
+                }
+            }
+
         }
     }
 }

PowerShell/ScubaGear/Testing/Unit/PowerShell/Orchestrator/Get-ServicePrincipalParams.Tests.ps1

@@ -3,19 +3,54 @@ Import-Module (Join-Path -Path $PSScriptRoot -ChildPath $OrchestratorPath) -Func
 
 Describe -Tag 'Orchestrator' -Name 'Get-ServicePrincipalParams' {
     InModuleScope Orchestrator {
-        It 'Returns a CertficateThumbprint PSObject with no errors' {
-            $BoundParameters = @{
-                CertificateThumbprint = 'WPOEALFN425A';
-                AppID = '34289UFAHWFALL';
-                Organization = 'example.onmicrosoft.com';
+        Context "Service Principal provided"{
+            BeforeAll{
+                [Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSUseDeclaredVarsMoreThanAssignments', 'BoundParameters')]
+                $BoundParameters = @{
+                    CertificateThumbprint = 'WPOEALFN425A'
+                    AppID = '34289UFAHWFALL'
+                    Organization = 'example.onmicrosoft.com'
+                }
+            }
+            It 'Does not throw exception' {
+                {Get-ServicePrincipalParams -BoundParameters $BoundParameters} | Should -Not -Throw
+            }
+            It "All required items are present"{
+                $Results = Get-ServicePrincipalParams -BoundParameters $BoundParameters
+                $Results | Should -BeOfType [hashtable]
+                $Results.Count | Should -BeExactly 1
+                $Results.CertThumbprintParams.Count | Should -BeExactly 3
+            }
+        }
+        Context "Partial data for Service Principal"{
+            It "Only AppId"{
+                $BoundParameters = @{
+                    AppID = '34289UFAHWFALL'
+                }
+                {Get-ServicePrincipalParams -BoundParameters $BoundParameters} |
+                    Should -Throw  'Missing parameters required for authentication with Service Principal Auth; Run Get-Help Invoke-Scuba for details on correct arguments'
+            }
+            It "Only Thumbprint Only"{
+                $BoundParameters = @{
+                    CertificateThumbprint = 'WPOEALFN425A'
+                }
+                {Get-ServicePrincipalParams -BoundParameters $BoundParameters} |
+                    Should -Throw  'Missing parameters required for authentication with Service Principal Auth; Run Get-Help Invoke-Scuba for details on correct arguments'
+            }
+            It "Only Organization Only"{
+                $BoundParameters = @{
+                    Organization = 'example.onmicrosoft.com'
+                }
+                {Get-ServicePrincipalParams -BoundParameters $BoundParameters} |
+                    Should -Throw  'Missing parameters required for authentication with Service Principal Auth; Run Get-Help Invoke-Scuba for details on correct arguments'
             }
-            {Get-ServicePrincipalParams -BoundParameters $BoundParameters} | Should -Not -Throw
         }
-        It 'Throws an error if no correct Service Principal Params are passed in' {
-            $BoundParameters = @{
-                a = 'a';
+        Context "No Service Principal provided"{
+            It 'Throws an error if no correct Service Principal Params are passed in' {
+                $BoundParameters = @{
+                }
+                {Get-ServicePrincipalParams -BoundParameters $BoundParameters} | Should -Throw
             }
-            {Get-ServicePrincipalParams -BoundParameters $BoundParameters} | Should -Throw
         }
     }
 }

PowerShell/ScubaGear/Testing/Unit/PowerShell/Orchestrator/Invoke-Connection.Tests.ps1

@@ -0,0 +1,27 @@
+$OrchestratorPath = '../../../../Modules/Orchestrator.psm1'
+Import-Module (Join-Path -Path $PSScriptRoot -ChildPath $OrchestratorPath) -Function 'Invoke-Connection' -Force
+
+InModuleScope Orchestrator {
+    Describe -Tag 'Orchestrator' -Name 'Invoke-Connection' {
+        BeforeAll {
+            function Connect-Tenant {throw 'this will be mocked'}
+            Mock -ModuleName Orchestrator Connect-Tenant {@('aad')}
+        }
+        It 'Login is false'{
+            Invoke-Connection -Login $false -ProductNames 'aad' -BoundParameters @{} | Should -BeNullOrEmpty
+        }
+        It 'Login is true'{
+            Invoke-Connection -Login $true -ProductNames 'aad' -BoundParameters @{} | Should -Not -BeNullOrEmpty
+        }
+        It 'Has AppId'{
+            Mock -ModuleName Orchestrator Connect-Tenant {@('aad')}
+            $BoundParameters = @{
+                AppID = "a"
+                CertificateThumbprint = "b"
+                Organization = "c"
+            }
+            Invoke-Connection -Login $true -ProductNames 'aad' -BoundParameters $BoundParameters | Should -Not -BeNullOrEmpty
+            Should -Invoke -CommandName Connect-Tenant -Exactly -Times 1
+        }
+    }
+}

PowerShell/ScubaGear/Testing/Unit/PowerShell/Orchestrator/Invoke-Scuba.Tests.ps1

@@ -6,17 +6,16 @@ InModuleScope Orchestrator {
         BeforeAll {
             Mock -ModuleName Orchestrator Remove-Resources {}
             Mock -ModuleName Orchestrator Import-Resources {}
-            function Invoke-Connection {}
             Mock -ModuleName Orchestrator Invoke-Connection { @() }
-            function Get-TenantDetail {}
+            function Get-TenantDetail {throw 'this will be mocked'}
             Mock -ModuleName Orchestrator Get-TenantDetail { '{"DisplayName": "displayName"}' }
-            function Invoke-ProviderList {}
+            function Invoke-ProviderList {throw 'this will be mocked'}
             Mock -ModuleName Orchestrator Invoke-ProviderList {}
-            function Invoke-RunRego {}
+            function Invoke-RunRego {throw 'this will be mocked'}
             Mock -ModuleName Orchestrator Invoke-RunRego {}
 
             Mock -ModuleName Orchestrator Invoke-ReportCreation {}
-            function Disconnect-SCuBATenant {}
+            function Disconnect-SCuBATenant {throw 'this will be mocked'}
             Mock -ModuleName Orchestrator Disconnect-SCuBATenant {}
 
             function Get-ScubaDefault {throw 'this will be mocked'}
@@ -84,6 +83,29 @@ InModuleScope Orchestrator {
                 {Invoke-Scuba @SplatParams} | Should -Not -Throw
             }
         }
+        Context 'Service Principal provided'{
+            It 'All items given as not null or empty'{
+                $SplatParams += @{
+                    AppID = "a"
+                    CertificateThumbprint = "b"
+                    Organization = "c"
+                }
+                {Invoke-Scuba @SplatParams} | Should -Not -Throw
+                Should -Invoke -CommandName Invoke-Connection -Exactly -Times 1 -ParameterFilter {$BoundParameters['AppID'] -eq $SplatParams['AppId']}
+            }
+            It 'Items given as empty string'{
+                $SplatParams += @{
+                    AppID = ""
+                }
+                {Invoke-Scuba @SplatParams} | Should -Throw
+            }
+            It 'Items given as null'{
+                $SplatParams += @{
+                    AppID = $null
+                }
+                {Invoke-Scuba @SplatParams} | Should -Throw
+            }
+        }
         Context 'When checking module version' {
             It 'Given -Version should not throw' {
                 {Invoke-Scuba -Version} | Should -Not -Throw