M365FoundationsCISReport.psm1
|
#Region '.\Classes\CISAuditResult.ps1' -1 class CISAuditResult { [string]$Status [string]$ELevel [string]$ProfileLevel [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' 17 #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 '.\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 Online Version: https://github.com/CriticalSolutionsNetwork/M365FoundationsCISReport #> 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.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.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 # 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 = @() # 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 $allAuditResults += $result } } } End { # Return all collected audit results return $allAuditResults # Check if the Disconnect switch is present if (!($DoNotDisconnect)) { # Clean up sessions Disconnect-M365Suite } } } #EndRegion '.\Public\Invoke-M365SecurityAudit.ps1' 260 |