M365FoundationsCISReport

0.1.3

M365FoundationsCISReport.psm1

#Region '.\Classes\CISAuditResult.ps1' -1

class CISAuditResult {
    [string]$Status
    [string]$ELevel
    [string]$ProfileLevel
    [bool]$Automated
    [string]$Connection
    [string]$Rec
    [string]$RecDescription
    [string]$CISControlVer = 'v8'
    [string]$CISControl
    [string]$CISDescription
    [bool]$IG1
    [bool]$IG2
    [bool]$IG3
    [bool]$Result
    [string]$Details
    [string]$FailureReason
}
#EndRegion '.\Classes\CISAuditResult.ps1' 19
#Region '.\Private\Assert-ModuleAvailability.ps1' -1

function Assert-ModuleAvailability {
    param(
        [string]$ModuleName,
        [string]$RequiredVersion,
        [string]$SubModuleName
    )

    try {
        $module = Get-Module -ListAvailable -Name $ModuleName | Where-Object { $_.Version -ge [version]$RequiredVersion }

        if ($null -eq $module) {$auditResult.Profile
            Write-Host "Installing $ModuleName module..."
            Install-Module -Name $ModuleName -RequiredVersion $RequiredVersion -Force -AllowClobber -Scope CurrentUser | Out-Null
        }
        elseif ($module.Version -lt [version]$RequiredVersion) {
            Write-Host "Updating $ModuleName module to required version..."
            Update-Module -Name $ModuleName -RequiredVersion $RequiredVersion -Force | Out-Null
        }
        else {
            Write-Host "$ModuleName module is already at required version or newer."
        }

        if ($SubModuleName) {
            Import-Module -Name "$ModuleName.$SubModuleName" -RequiredVersion $RequiredVersion -ErrorAction Stop | Out-Null
        }
        else {
            Import-Module -Name $ModuleName -RequiredVersion $RequiredVersion -ErrorAction Stop | Out-Null
        }
    }
    catch {
        Write-Warning "An error occurred with module $ModuleName`: $_"
    }
}
#EndRegion '.\Private\Assert-ModuleAvailability.ps1' 34
#Region '.\Private\Connect-M365Suite.ps1' -1

function Connect-M365Suite {
    [CmdletBinding()]
    param (
        # Parameter to specify the SharePoint Online Tenant Admin URL
        [Parameter(Mandatory)]
        [string]$TenantAdminUrl
    )
$VerbosePreference = "SilentlyContinue"
    try {

        # Attempt to connect to Azure Active Directory
        Write-Host "Connecting to Azure Active Directory..." -ForegroundColor Cyan
        Connect-AzureAD | Out-Null
        Write-Host "Successfully connected to Azure Active Directory." -ForegroundColor Green

        # Attempt to connect to Exchange Online
        Write-Host "Connecting to Exchange Online..." -ForegroundColor Cyan
        Connect-ExchangeOnline | Out-Null
        Write-Host "Successfully connected to Exchange Online." -ForegroundColor Green
        try {
            # Attempt to connect to Microsoft Graph with specified scopes
            Write-Host "Connecting to Microsoft Graph with scopes: Directory.Read.All, Domain.Read.All, Policy.Read.All, Organization.Read.All" -ForegroundColor Cyan
            Connect-MgGraph -Scopes "Directory.Read.All", "Domain.Read.All", "Policy.Read.All", "Organization.Read.All" -NoWelcome | Out-Null
            Write-Host "Successfully connected to Microsoft Graph with specified scopes." -ForegroundColor Green
        }
        catch {
            Write-Host "Failed to connect o MgGraph, attempting device auth." -ForegroundColor Yellow
            # Attempt to connect to Microsoft Graph with specified scopes
            Write-Host "Connecting to Microsoft Graph using device auth with scopes: Directory.Read.All, Domain.Read.All, Policy.Read.All, Organization.Read.All" -ForegroundColor Cyan
            Connect-MgGraph -Scopes "Directory.Read.All", "Domain.Read.All", "Policy.Read.All", "Organization.Read.All" -UseDeviceCode -NoWelcome | Out-Null
            Write-Host "Successfully connected to Microsoft Graph with specified scopes." -ForegroundColor Green
        }

        # Validate SharePoint Online Tenant Admin URL
        if (-not $TenantAdminUrl) {
            throw "SharePoint Online Tenant Admin URL is required."
        }

        # Attempt to connect to SharePoint Online
        Write-Host "Connecting to SharePoint Online..." -ForegroundColor Cyan
        Connect-SPOService -Url $TenantAdminUrl | Out-Null
        Write-Host "Successfully connected to SharePoint Online." -ForegroundColor Green

        # Attempt to connect to Microsoft Teams
        Write-Host "Connecting to Microsoft Teams..." -ForegroundColor Cyan
        Connect-MicrosoftTeams | Out-Null
        Write-Host "Successfully connected to Microsoft Teams." -ForegroundColor Green
    }
    catch {
        $VerbosePreference = "Continue"
        Write-Host "There was an error establishing one or more connections: $_" -ForegroundColor Red
        throw $_
    }
    $VerbosePreference = "Continue"
}

#EndRegion '.\Private\Connect-M365Suite.ps1' 57
#Region '.\Private\Disconnect-M365Suite.ps1' -1

function Disconnect-M365Suite {
    # Clean up sessions
    try {
        Write-Host "Disconnecting from Exchange Online..." -ForegroundColor Green
        Disconnect-ExchangeOnline -Confirm:$false | Out-Null
    }
    catch {
        Write-Warning "Failed to disconnect from Exchange Online: $_"
    }
    try {
        Write-Host "Disconnecting from Azure AD..." -ForegroundColor Green
        Disconnect-AzureAD | Out-Null
    }
    catch {
        Write-Warning "Failed to disconnect from Azure AD: $_"
    }
    try {
        Write-Host "Disconnecting from Microsoft Graph..." -ForegroundColor Green
        Disconnect-MgGraph | Out-Null
    }
    catch {
        Write-Warning "Failed to disconnect from Microsoft Graph: $_"
    }
    try {
        Write-Host "Disconnecting from SharePoint Online..." -ForegroundColor Green
        Disconnect-SPOService | Out-Null
    }
    catch {
        Write-Warning "Failed to disconnect from SharePoint Online: $_"
    }
    try {
        Write-Host "Disconnecting from Microsoft Teams..." -ForegroundColor Green
        Disconnect-MicrosoftTeams | Out-Null
    }
    catch {
        Write-Warning "Failed to disconnect from Microsoft Teams: $_"
    }
    Write-Host "All sessions have been disconnected." -ForegroundColor Green
}
#EndRegion '.\Private\Disconnect-M365Suite.ps1' 40
#Region '.\Private\Initialize-CISAuditResult.ps1' -1

function Initialize-CISAuditResult {
    param (
        [Parameter(Mandatory = $true)]
        [string]$Rec,

        [Parameter(Mandatory = $true)]
        [bool]$Result,

        [Parameter(Mandatory = $true)]
        [string]$Status,

        [Parameter(Mandatory = $true)]
        [string]$Details,

        [Parameter(Mandatory = $true)]
        [string]$FailureReason
    )

    # Import the test definitions CSV file
    $testDefinitions = $script:TestDefinitionsObject

    # Find the row that matches the provided recommendation (Rec)
    $testDefinition = $testDefinitions | Where-Object { $_.Rec -eq $Rec }

    # Create an instance of CISAuditResult and populate it
    $auditResult = [CISAuditResult]::new()
    $auditResult.Rec = $Rec
    $auditResult.ELevel = $testDefinition.ELevel
    $auditResult.ProfileLevel = $testDefinition.ProfileLevel
    $auditResult.IG1 = [bool]::Parse($testDefinition.IG1)
    $auditResult.IG2 = [bool]::Parse($testDefinition.IG2)
    $auditResult.IG3 = [bool]::Parse($testDefinition.IG3)
    $auditResult.RecDescription = $testDefinition.RecDescription
    $auditResult.CISControl = $testDefinition.CISControl
    $auditResult.CISDescription = $testDefinition.CISDescription
    $auditResult.Automated = [bool]::Parse($testDefinition.Automated)
    $auditResult.Connection = $testDefinition.Connection
    $auditResult.CISControlVer = 'v8'
    $auditResult.Result = $Result
    $auditResult.Status = $Status
    $auditResult.Details = $Details
    $auditResult.FailureReason = $FailureReason

    return $auditResult
}
#EndRegion '.\Private\Initialize-CISAuditResult.ps1' 46
#Region '.\Private\Merge-CISExcelAndCsvData.ps1' -1

function Merge-CISExcelAndCsvData {
    [CmdletBinding()]
    param (
        [Parameter(Mandatory = $true)]
        [string]$ExcelPath,

        [Parameter(Mandatory = $true)]
        [string]$WorksheetName,

        [Parameter(Mandatory = $true)]
        [string]$CsvPath
    )

    process {
        # Import data from Excel and CSV
        $import = Import-Excel -Path $ExcelPath -WorksheetName $WorksheetName
        $csvData = Import-Csv -Path $CsvPath

        # Define a function to create a merged object
        function CreateMergedObject($excelItem, $csvRow) {
            $newObject = New-Object PSObject

            foreach ($property in $excelItem.PSObject.Properties) {
                $newObject | Add-Member -MemberType NoteProperty -Name $property.Name -Value $property.Value
            }

            $newObject | Add-Member -MemberType NoteProperty -Name 'CSV_Status' -Value $csvRow.Status
            $newObject | Add-Member -MemberType NoteProperty -Name 'CSV_Details' -Value $csvRow.Details
            $newObject | Add-Member -MemberType NoteProperty -Name 'CSV_FailureReason' -Value $csvRow.FailureReason

            return $newObject
        }

        # Iterate over each item in the imported Excel object and merge with CSV data
        $mergedData = foreach ($item in $import) {
            $csvRow = $csvData | Where-Object { $_.Rec -eq $item.'recommendation #' }
            if ($csvRow) {
                CreateMergedObject -excelItem $item -csvRow $csvRow
            } else {
                CreateMergedObject -excelItem $item -csvRow ([PSCustomObject]@{Status=$null; Details=$null; FailureReason=$null})
            }
        }

        # Return the merged data
        return $mergedData
    }
}
#EndRegion '.\Private\Merge-CISExcelAndCsvData.ps1' 48
#Region '.\Private\Update-CISExcelWorksheet.ps1' -1

function Update-CISExcelWorksheet {
    [CmdletBinding()]
    param (
        [Parameter(Mandatory = $true)]
        [string]$ExcelPath,

        [Parameter(Mandatory = $true)]
        [string]$WorksheetName,

        [Parameter(Mandatory = $true)]
        [psobject[]]$Data,

        [Parameter(Mandatory = $false)]
        [int]$StartingRowIndex = 2 # Default starting row index, assuming row 1 has headers
    )

    process {
        # Load the existing Excel sheet
        $excelPackage = Open-ExcelPackage -Path $ExcelPath
        $worksheet = $excelPackage.Workbook.Worksheets[$WorksheetName]

        if (-not $worksheet) {
            throw "Worksheet '$WorksheetName' not found in '$ExcelPath'"
        }


        # Update the worksheet with the provided data
        Update-WorksheetCells -Worksheet $worksheet -Data $Data -StartingRowIndex $StartingRowIndex

        # Save and close the Excel package
        Close-ExcelPackage $excelPackage
    }
}
#EndRegion '.\Private\Update-CISExcelWorksheet.ps1' 34
#Region '.\Private\Update-WorksheetCells.ps1' -1

        function Update-WorksheetCells {
            param (
                $Worksheet,
                $Data,
                $StartingRowIndex
            )

            # Check and set headers
            $firstItem = $Data[0]
            $colIndex = 1
            foreach ($property in $firstItem.PSObject.Properties) {
                if ($StartingRowIndex -eq 2 -and $Worksheet.Cells[1, $colIndex].Value -eq $null) {
                    $Worksheet.Cells[1, $colIndex].Value = $property.Name
                }
                $colIndex++
            }

            # Iterate over each row in the data and update cells
            $rowIndex = $StartingRowIndex
            foreach ($item in $Data) {
                $colIndex = 1
                foreach ($property in $item.PSObject.Properties) {
                    $Worksheet.Cells[$rowIndex, $colIndex].Value = $property.Value
                    $colIndex++
                }
                $rowIndex++
            }
        }
#EndRegion '.\Private\Update-WorksheetCells.ps1' 29
#Region '.\Public\Get-AdminRoleUserLicense.ps1' -1

<#
.SYNOPSIS
    Retrieves user licenses and roles for administrative accounts from Microsoft 365 via the Graph API.
.DESCRIPTION
    The Get-AdminRoleUserLicense function connects to Microsoft Graph and retrieves all users who are assigned administrative roles along with their user details and licenses. This function is useful for auditing and compliance checks to ensure that administrators have appropriate licenses and role assignments.
.PARAMETER SkipGraphConnection
    A switch parameter that, when set, skips the connection to Microsoft Graph if already established. This is useful for batch processing or when used within scripts where multiple calls are made and the connection is managed externally.
.EXAMPLE
    PS> Get-AdminRoleUserLicense
 
    This example retrieves all administrative role users along with their licenses by connecting to Microsoft Graph using the default scopes.
.EXAMPLE
    PS> Get-AdminRoleUserLicense -SkipGraphConnection
 
    This example retrieves all administrative role users along with their licenses without attempting to connect to Microsoft Graph, assuming that the connection is already established.
.INPUTS
    None. You cannot pipe objects to Get-AdminRoleUserLicense.
.OUTPUTS
    PSCustomObject
    Returns a custom object for each user with administrative roles that includes the following properties: RoleName, UserName, UserPrincipalName, UserId, HybridUser, and Licenses.
.NOTES
    Creation Date: 2024-04-15
    Purpose/Change: Initial function development to support Microsoft 365 administrative role auditing.
.LINK
    https://criticalsolutionsnetwork.github.io/M365FoundationsCISReport/#Get-AdminRoleUserLicense
#>
function Get-AdminRoleUserLicense {
    [CmdletBinding()]
    param (
        [Parameter(Mandatory = $false)]
        [switch]$SkipGraphConnection
    )

    begin {
        if (-not $SkipGraphConnection) {
            Connect-MgGraph -Scopes "Directory.Read.All", "Domain.Read.All", "Policy.Read.All", "Organization.Read.All" -NoWelcome
        }

        $adminRoleUsers = [System.Collections.ArrayList]::new()
        $userIds = [System.Collections.ArrayList]::new()
    }

    Process {
        $adminroles = Get-MgRoleManagementDirectoryRoleDefinition | Where-Object { $_.DisplayName -like "*Admin*" }

        foreach ($role in $adminroles) {
            $usersInRole = Get-MgRoleManagementDirectoryRoleAssignment -Filter "roleDefinitionId eq '$($role.Id)'"

            foreach ($user in $usersInRole) {
                $userDetails = Get-MgUser -UserId $user.PrincipalId -Property "DisplayName, UserPrincipalName, Id, onPremisesSyncEnabled" -ErrorAction SilentlyContinue

                if ($userDetails) {
                    [void]($userIds.Add($user.PrincipalId))
                    [void](
                        $adminRoleUsers.Add(
                            [PSCustomObject]@{
                                RoleName          = $role.DisplayName
                                UserName          = $userDetails.DisplayName
                                UserPrincipalName = $userDetails.UserPrincipalName
                                UserId            = $userDetails.Id
                                HybridUser        = $userDetails.onPremisesSyncEnabled
                                Licenses          = $null  # Initialize as $null
                            }
                        )
                    )
                }
            }
        }

        foreach ($userId in $userIds.ToArray() | Select-Object -Unique) {
            $licenses = Get-MgUserLicenseDetail -UserId $userId -ErrorAction SilentlyContinue
            if ($licenses) {
                $licenseList = ($licenses.SkuPartNumber -join '|')
                $adminRoleUsers.ToArray() | Where-Object { $_.UserId -eq $userId } | ForEach-Object {
                    $_.Licenses = $licenseList
                }
            }
        }
    }

    End {
        Write-Host "Disconnecting from Microsoft Graph..." -ForegroundColor Green
        Disconnect-MgGraph | Out-Null
        return $adminRoleUsers
    }
}
#EndRegion '.\Public\Get-AdminRoleUserLicense.ps1' 87
#Region '.\Public\Invoke-M365SecurityAudit.ps1' -1

<#
    .SYNOPSIS
    Invokes a security audit for Microsoft 365 environments.
    .DESCRIPTION
    The Invoke-M365SecurityAudit cmdlet performs a comprehensive security audit based on the specified parameters. It allows auditing of various configurations and settings within a Microsoft 365 environment, such as compliance with CIS benchmarks.
    .PARAMETER TenantAdminUrl
    The URL of the tenant admin. This parameter is mandatory.
    .PARAMETER DomainName
    The domain name of the Microsoft 365 environment. This parameter is mandatory.
    .PARAMETER ELevel
    Specifies the E-Level (E3 or E5) for the audit. This parameter is optional and can be combined with the ProfileLevel parameter.
    .PARAMETER ProfileLevel
    Specifies the profile level (L1 or L2) for the audit. This parameter is optional and can be combined with the ELevel parameter.
    .PARAMETER IncludeIG1
    If specified, includes tests where IG1 is true.
    .PARAMETER IncludeIG2
    If specified, includes tests where IG2 is true.
    .PARAMETER IncludeIG3
    If specified, includes tests where IG3 is true.
    .PARAMETER IncludeRecommendation
    Specifies specific recommendations to include in the audit. Accepts an array of recommendation numbers.
    .PARAMETER SkipRecommendation
    Specifies specific recommendations to exclude from the audit. Accepts an array of recommendation numbers.
    .PARAMETER DoNotConnect
    If specified, the cmdlet will not establish a connection to Microsoft 365 services.
    .PARAMETER DoNotDisconnect
    If specified, the cmdlet will not disconnect from Microsoft 365 services after execution.
    .PARAMETER NoModuleCheck
    If specified, the cmdlet will not check for the presence of required modules.
    .EXAMPLE
    PS> Invoke-M365SecurityAudit -TenantAdminUrl "https://contoso-admin.sharepoint.com" -DomainName "contoso.com" -ELevel "E5" -ProfileLevel "L1"
 
    Performs a security audit for the E5 level and L1 profile in the specified Microsoft 365 environment.
    .EXAMPLE
    PS> Invoke-M365SecurityAudit -TenantAdminUrl "https://contoso-admin.sharepoint.com" -DomainName "contoso.com" -IncludeIG1
 
    Performs an audit including all tests where IG1 is true.
    .EXAMPLE
    PS> Invoke-M365SecurityAudit -TenantAdminUrl "https://contoso-admin.sharepoint.com" -DomainName "contoso.com" -SkipRecommendation '1.1.3', '2.1.1'
 
    Performs an audit while excluding specific recommendations 1.1.3 and 2.1.1.
    .EXAMPLE
    PS> $auditResults = Invoke-M365SecurityAudit -TenantAdminUrl "https://contoso-admin.sharepoint.com" -DomainName "contoso.com"
    PS> $auditResults | Export-Csv -Path "auditResults.csv" -NoTypeInformation
 
    Captures the audit results into a variable and exports them to a CSV file.
    .INPUTS
    None. You cannot pipe objects to Invoke-M365SecurityAudit.
    .OUTPUTS
    CISAuditResult[]
    The cmdlet returns an array of CISAuditResult objects representing the results of the security audit.
    .NOTES
        - This module is based on CIS benchmarks.
        - Governed by the Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License.
        - Commercial use is not permitted. This module cannot be sold or used for commercial purposes.
        - Modifications and sharing are allowed under the same license.
        - For full license details, visit: https://creativecommons.org/licenses/by-nc-sa/4.0/deed.en
        - Register for CIS Benchmarks at: https://www.cisecurity.org/cis-benchmarks
    .LINK
    https://criticalsolutionsnetwork.github.io/M365FoundationsCISReport/#Invoke-M365SecurityAudit
#>

function Invoke-M365SecurityAudit {
    [CmdletBinding(SupportsShouldProcess = $true, DefaultParameterSetName = 'Default')]
    [OutputType([CISAuditResult[]])]
    param (
        [Parameter(Mandatory = $true)]
        [string]$TenantAdminUrl,

        [Parameter(Mandatory = $true)]
        [string]$DomainName,

        # E-Level with optional ProfileLevel selection
        [Parameter(ParameterSetName = 'ELevelFilter')]
        [ValidateSet('E3', 'E5')]
        [string]$ELevel,

        [Parameter(ParameterSetName = 'ELevelFilter')]
        [ValidateSet('L1', 'L2')]
        [string]$ProfileLevel,

        # IG Filters, one at a time
        [Parameter(ParameterSetName = 'IG1Filter')]
        [switch]$IncludeIG1,

        [Parameter(ParameterSetName = 'IG2Filter')]
        [switch]$IncludeIG2,

        [Parameter(ParameterSetName = 'IG3Filter')]
        [switch]$IncludeIG3,

        # Inclusion of specific recommendation numbers
        [Parameter(ParameterSetName = 'RecFilter')]
        [ValidateSet(
            '1.1.1','1.1.3', '1.2.1', '1.2.2', '1.3.1', '1.3.3', '1.3.6', '2.1.1', '2.1.2', `
                '2.1.3', '2.1.4', '2.1.5', '2.1.6', '2.1.7', '2.1.9', '3.1.1', '5.1.2.3', `
                '5.1.8.1', '6.1.1', '6.1.2', '6.1.3', '6.2.1', '6.2.2', '6.2.3', '6.3.1', `
                '6.5.1', '6.5.2', '6.5.3', '7.2.1', '7.2.10', '7.2.2', '7.2.3', '7.2.4', `
                '7.2.5', '7.2.6', '7.2.7', '7.2.9', '7.3.1', '7.3.2', '7.3.4', '8.1.1', `
                '8.1.2', '8.2.1', '8.5.1', '8.5.2', '8.5.3', '8.5.4', '8.5.5', '8.5.6', `
                '8.5.7', '8.6.1'
        )]
        [string[]]$IncludeRecommendation,

        # Exclusion of specific recommendation numbers
        [Parameter(ParameterSetName = 'SkipRecFilter')]
        [ValidateSet(
            '1.1.1','1.1.3', '1.2.1', '1.2.2', '1.3.1', '1.3.3', '1.3.6', '2.1.1', '2.1.2', `
                '2.1.3', '2.1.4', '2.1.5', '2.1.6', '2.1.7', '2.1.9', '3.1.1', '5.1.2.3', `
                '5.1.8.1', '6.1.1', '6.1.2', '6.1.3', '6.2.1', '6.2.2', '6.2.3', '6.3.1', `
                '6.5.1', '6.5.2', '6.5.3', '7.2.1', '7.2.10', '7.2.2', '7.2.3', '7.2.4', `
                '7.2.5', '7.2.6', '7.2.7', '7.2.9', '7.3.1', '7.3.2', '7.3.4', '8.1.1', `
                '8.1.2', '8.2.1', '8.5.1', '8.5.2', '8.5.3', '8.5.4', '8.5.5', '8.5.6', `
                '8.5.7', '8.6.1'
        )]
        [string[]]$SkipRecommendation,

        # Common parameters for all parameter sets
        [switch]$DoNotConnect,
        [switch]$DoNotDisconnect,
        [switch]$NoModuleCheck
    )



    Begin {
        if ($script:MaximumFunctionCount -lt 8192) {
            $script:MaximumFunctionCount = 8192
        }
        # Ensure required modules are installed
        # Define the required modules and versions in a hashtable
        if (!($NoModuleCheck)) {
            $requiredModules = @(
                @{ ModuleName = "ExchangeOnlineManagement"; RequiredVersion = "3.3.0" },
                @{ ModuleName = "AzureAD"; RequiredVersion = "2.0.2.182" },
                @{ ModuleName = "Microsoft.Graph"; RequiredVersion = "2.4.0"; SubModuleName = "Authentication" },
                @{ ModuleName = "Microsoft.Graph"; RequiredVersion = "2.4.0"; SubModuleName = "Users" },
                @{ ModuleName = "Microsoft.Graph"; RequiredVersion = "2.4.0"; SubModuleName = "Groups" },
                @{ ModuleName = "Microsoft.Graph"; RequiredVersion = "2.4.0"; SubModuleName = "DirectoryObjects" },
                @{ ModuleName = "Microsoft.Graph"; RequiredVersion = "2.4.0"; SubModuleName = "Domains" },
                @{ ModuleName = "Microsoft.Graph"; RequiredVersion = "2.4.0"; SubModuleName = "Reports" },
                @{ ModuleName = "Microsoft.Graph"; RequiredVersion = "2.4.0"; SubModuleName = "Mail" },
                @{ ModuleName = "Microsoft.Online.SharePoint.PowerShell"; RequiredVersion = "16.0.24009.12000" },
                @{ ModuleName = "MicrosoftTeams"; RequiredVersion = "5.5.0" }
            )
            foreach ($module in $requiredModules) {
                Assert-ModuleAvailability -ModuleName $module.ModuleName -RequiredVersion $module.RequiredVersion -SubModuleName $module.SubModuleName
            }
        }


        # Loop through each required module and assert its availability

        # Establishing connections
        #if (!($DoNotConnect -or $DoNotTest)) {
        # Establishing connections
        if (!($DoNotConnect)) {
            Connect-M365Suite -TenantAdminUrl $TenantAdminUrl
        }

        # Load test definitions from CSV
        $testDefinitionsPath = Join-Path -Path $PSScriptRoot -ChildPath "helper\TestDefinitions.csv"
        $testDefinitions = Import-Csv -Path $testDefinitionsPath
        # Load the Test Definitions into the script scope for use in other functions
        $script:TestDefinitionsObject = $testDefinitions
        # Apply filters based on parameter sets
        switch ($PSCmdlet.ParameterSetName) {
            'ELevelFilter' {
                if ($null -ne $ELevel -and $null -ne $ProfileLevel) {
                    $testDefinitions = $testDefinitions | Where-Object {
                        $_.ELevel -eq $ELevel -and $_.ProfileLevel -eq $ProfileLevel
                    }
                }
                elseif ($null -ne $ELevel) {
                    $testDefinitions = $testDefinitions | Where-Object {
                        $_.ELevel -eq $ELevel
                    }
                }
                elseif ($null -ne $ProfileLevel) {
                    $testDefinitions = $testDefinitions | Where-Object {
                        $_.ProfileLevel -eq $ProfileLevel
                    }
                }
            }
            'IG1Filter' {
                $testDefinitions = $testDefinitions | Where-Object { $_.IG1 -eq 'TRUE' }
            }
            'IG2Filter' {
                $testDefinitions = $testDefinitions | Where-Object { $_.IG2 -eq 'TRUE' }
            }
            'IG3Filter' {
                $testDefinitions = $testDefinitions | Where-Object { $_.IG3 -eq 'TRUE' }
            }
            'RecFilter' {
                $testDefinitions = $testDefinitions | Where-Object { $IncludeRecommendation -contains $_.Rec }
            }
            'SkipRecFilter' {
                $testDefinitions = $testDefinitions | Where-Object { $SkipRecommendation -notcontains $_.Rec }
            }
        }
        # End switch ($PSCmdlet.ParameterSetName)

        # Determine which test files to load based on filtering
        $testsToLoad = $testDefinitions.TestFileName | ForEach-Object { $_ -replace '.ps1$', '' }

        # Display the tests that would be loaded if the function is called with -WhatIf

        Write-Verbose "The $(($testsToLoad).count) test/s that would be loaded based on filter criteria:"
        $testsToLoad | ForEach-Object { Write-Verbose " $_" }
    } # End Begin

    Process {
        $allAuditResults = [System.Collections.ArrayList]::new() #@() # Initialize a collection to hold all results

        # Dynamically dot-source the test scripts
        $testsFolderPath = Join-Path -Path $PSScriptRoot -ChildPath "tests"
        $testFiles = Get-ChildItem -Path $testsFolderPath -Filter "Test-*.ps1" |
        Where-Object { $testsToLoad -contains $_.BaseName }

        # Import the test functions
        $testFiles | ForEach-Object {
            Try {
                . $_.FullName
            }
            Catch {
                Write-Error "Failed to load test function $($_.Name): $_"
            }
        }

        # Execute each test function from the prepared list
        foreach ($testFunction in $testFiles) {
            $functionName = $testFunction.BaseName
            $functionCmd = Get-Command -Name $functionName

            # Check if the test function needs DomainName parameter
            $paramList = @{}
            if ('DomainName' -in $functionCmd.Parameters.Keys) {
                $paramList.DomainName = $DomainName
            }

            # Use splatting to pass parameters
            if ($PSCmdlet.ShouldProcess($functionName, "Execute test")) {
                Write-Host "Running $functionName..."
                $result = & $functionName @paramList
                # Assuming each function returns an array of CISAuditResult or a single CISAuditResult
                [void]($allAuditResults.add($Result))
            }
        }
    }

    End {
        if (!($DoNotDisconnect)) {
            # Clean up sessions
            Disconnect-M365Suite
        }
        # Return all collected audit results
        return $allAuditResults.ToArray()
        # Check if the Disconnect switch is present
    }
}
#EndRegion '.\Public\Invoke-M365SecurityAudit.ps1' 261
#Region '.\Public\Sync-CISExcelAndCsvData.ps1' -1

<#
    .SYNOPSIS
    Synchronizes data between an Excel file and a CSV file and optionally updates the Excel worksheet.
    .DESCRIPTION
    The Sync-CISExcelAndCsvData function merges data from a specified Excel file and a CSV file based on a common key. It can also update the Excel worksheet with the merged data. This function is particularly useful for updating Excel records with additional data from a CSV file while preserving the original formatting and structure of the Excel worksheet.
    .PARAMETER ExcelPath
    The path to the Excel file that contains the original data. This parameter is mandatory.
    .PARAMETER WorksheetName
    The name of the worksheet within the Excel file that contains the data to be synchronized. This parameter is mandatory.
    .PARAMETER CsvPath
    The path to the CSV file containing data to be merged with the Excel data. This parameter is mandatory.
    .PARAMETER SkipUpdate
    If specified, the function will return the merged data object without updating the Excel worksheet. This is useful for previewing the merged data.
    .EXAMPLE
    PS> Sync-CISExcelAndCsvData -ExcelPath "path\to\excel.xlsx" -WorksheetName "DataSheet" -CsvPath "path\to\data.csv"
    Merges data from 'data.csv' into 'excel.xlsx' on the 'DataSheet' worksheet and updates the worksheet with the merged data.
    .EXAMPLE
    PS> $mergedData = Sync-CISExcelAndCsvData -ExcelPath "path\to\excel.xlsx" -WorksheetName "DataSheet" -CsvPath "path\to\data.csv" -SkipUpdate
    Retrieves the merged data object for preview without updating the Excel worksheet.
    .INPUTS
    None. You cannot pipe objects to Sync-CISExcelAndCsvData.
    .OUTPUTS
    Object[]
    If the SkipUpdate switch is used, the function returns an array of custom objects representing the merged data.
    .NOTES
    - Ensure that the 'ImportExcel' module is installed and up to date.
    - It is recommended to backup the Excel file before running this script to prevent accidental data loss.
    - This function is part of the CIS Excel and CSV Data Management Toolkit.
    .LINK
    https://criticalsolutionsnetwork.github.io/M365FoundationsCISReport/#Sync-CISExcelAndCsvData
#>

function Sync-CISExcelAndCsvData {
    [CmdletBinding()]
    param (
        [Parameter(Mandatory = $true)]
        [string]$ExcelPath,

        [Parameter(Mandatory = $true)]
        [string]$WorksheetName,

        [Parameter(Mandatory = $true)]
        [string]$CsvPath,

        [Parameter(Mandatory = $false)]
        [switch]$SkipUpdate
    )

    process {
        # Merge Excel and CSV data
        $mergedData = Merge-CISExcelAndCsvData -ExcelPath $ExcelPath -WorksheetName $WorksheetName -CsvPath $CsvPath

        # Output the merged data if the user chooses to skip the update
        if ($SkipUpdate) {
            return $mergedData
        } else {
            # Update the Excel worksheet with the merged data
            Update-CISExcelWorksheet -ExcelPath $ExcelPath -WorksheetName $WorksheetName -Data $mergedData
        }
    }
}
#EndRegion '.\Public\Sync-CISExcelAndCsvData.ps1' 62