diff --git a/README copy.md b/README copy.md index 7055187..b0c6657 100644 --- a/README copy.md +++ b/README copy.md @@ -26,7 +26,7 @@ For full license details, please visit [Creative Commons Attribution-NonCommerci The `M365FoundationsCISReport` module relies on several other PowerShell modules to perform its operations. The default run ensures these modules are installed with the specified versions. Use -NoModuleCheck to skip this step if you have installed the required modules previously and would like to suppress any output for automated runs. -### Required Modules for Audit Functions +### Minimum Required Modules for Audit Functions Default modules used for audit functions: @@ -58,7 +58,7 @@ $auditResults = Invoke-M365SecurityAudit -TenantAdminUrl "https://contoso-admin. $auditResults = Invoke-M365SecurityAudit -TenantAdminUrl "https://contoso-admin.sharepoint.com" -NoModuleCheck -NoModuleCheck -DoNotConfirmConnections -Confirm:$false # Example 2: Exporting a security audit and it's nested tables to zipped CSV files -Export-M365SecurityAuditTable -AuditResults $auditResults -ExportPath "C:\temp" -ExportOriginalTests -ExportNestedTables +Export-M365SecurityAuditTable -AuditResults $auditResults -ExportPath "C:\temp" # Output Ex: 2024.07.07_14.55.55_M365FoundationsAudit_368B2E2F.zip # Example 3: Retrieving licenses for users in administrative roles diff --git a/README.md b/README.md index 20d18b0..cf025f8 100644 --- a/README.md +++ b/README.md @@ -26,7 +26,7 @@ For full license details, please visit [Creative Commons Attribution-NonCommerci The `M365FoundationsCISReport` module relies on several other PowerShell modules to perform its operations. The default run ensures these modules are installed with the specified versions. Use -NoModuleCheck to skip this step if you have installed the required modules previously and would like to suppress any output for automated runs. -### Required Modules for Audit Functions +### Minimum Required Modules for Audit Functions Default modules used for audit functions: @@ -58,7 +58,7 @@ $auditResults = Invoke-M365SecurityAudit -TenantAdminUrl "https://contoso-admin. $auditResults = Invoke-M365SecurityAudit -TenantAdminUrl "https://contoso-admin.sharepoint.com" -NoModuleCheck -NoModuleCheck -DoNotConfirmConnections -Confirm:$false # Example 2: Exporting a security audit and it's nested tables to zipped CSV files -Export-M365SecurityAuditTable -AuditResults $auditResults -ExportPath "C:\temp" -ExportOriginalTests -ExportNestedTables +Export-M365SecurityAuditTable -AuditResults $auditResults -ExportPath "C:\temp" # Output Ex: 2024.07.07_14.55.55_M365FoundationsAudit_368B2E2F.zip # Example 3: Retrieving licenses for users in administrative roles @@ -97,19 +97,19 @@ If you encounter any issues while using the cmdlets, ensure that your environmen - [Microsoft 365 Security Documentation](https://docs.microsoft.com/en-us/microsoft-365/security/) - [PowerShell Documentation](https://docs.microsoft.com/en-us/powershell/) + +# M365FoundationsCISReport Module ## Export-M365SecurityAuditTable ### Synopsis Exports Microsoft 365 security audit results to CSV or Excel files and supports outputting specific test results as objects. ### Syntax ```powershell -Export-M365SecurityAuditTable [-AuditResults] [-OutputTestNumber] [-WhatIf] [-Confirm] [] +Export-M365SecurityAuditTable -AuditResults -ExportPath [-ExportToExcel] [-Prefix ] [-WhatIf] [-Confirm] [] -Export-M365SecurityAuditTable [-AuditResults] [[-ExportNestedTables]] -ExportPath [-ExportOriginalTests] [-ExportToExcel] [-Prefix ] [-WhatIf] [-Confirm] [] +Export-M365SecurityAuditTable -AuditResults -OutputTestNumber [-WhatIf] [-Confirm] [] -Export-M365SecurityAuditTable [-CsvPath] [-OutputTestNumber] [-WhatIf] [-Confirm] [] - -Export-M365SecurityAuditTable [-CsvPath] [[-ExportNestedTables]] -ExportPath [-ExportOriginalTests] [-ExportToExcel] [-Prefix ] [-WhatIf] [-Confirm] [] +Export-M365SecurityAuditTable -AuditResults -ExportPath [-ExportToExcel] [-Prefix ] -OnlyExportNestedTables [-WhatIf] [-Confirm] [] @@ -119,20 +119,18 @@ Export-M365SecurityAuditTable [-CsvPath] [[-ExportNestedTables]] -Expor | Name | Alias | Description | Required? | Pipeline Input | Default Value | | - | - | - | - | - | - | | AuditResults | | An array of CISAuditResult objects containing the audit results. This parameter is mandatory when exporting from audit results. | true | false | | -| CsvPath | | The path to a CSV file containing the audit results. This parameter is mandatory when exporting from a CSV file. | true | false | | -| OutputTestNumber | | The test number to output as an object. Valid values are "1.1.1", "1.3.1", "6.1.2", "6.1.3", "7.3.4". This parameter is used to output a specific test result. | true | false | | -| ExportNestedTables | | Switch to export all test results. When specified, all test results are exported to the specified path. | false | false | False | | ExportPath | | The path where the CSV or Excel files will be exported. This parameter is mandatory when exporting all tests. | true | false | | -| ExportOriginalTests | | Switch to export the original audit results to a CSV file. When specified, the original test results are exported along with the processed results. | false | false | False | | ExportToExcel | | Switch to export the results to an Excel file. When specified, results are exported in Excel format. | false | false | False | -| Prefix | | Add Prefix to filename after date when outputting to excel or csv. Validate that the count of letters in the prefix is less than 5. | false | false | Corp | +| Prefix | | | false | false | Corp | +| OnlyExportNestedTables | | ─────────────────────────────────────────────────────────────────────────── 2\) OnlyExportNestedTables: nested tables only into ZIP -AuditResults, -ExportPath, -OnlyExportNestedTables ─────────────────────────────────────────────────────────────────────────── | true | false | False | +| OutputTestNumber | | The test number to output as an object. Valid values are "1.1.1", "1.3.1", "6.1.2", "6.1.3", "7.3.4". This parameter is used to output a specific test result. | true | false | | | WhatIf | wi | | false | false | | | Confirm | cf | | false | false | | ### Inputs - - \[CISAuditResult\[\\]\\] - An array of CISAuditResult objects. \[string\\] - A path to a CSV file. + - \[CISAuditResult\[\]\] - An array of CISAuditResult objects. \[string\] - A path to a CSV file. ### Outputs - - \[PSCustomObject\\] - A custom object containing the path to the zip file and its hash. + - \[PSCustomObject\] - A custom object containing the path to the zip file and its hash. ### Examples **EXAMPLE 1** @@ -228,9 +226,18 @@ This example retrieves all administrative role users along with their licenses w ### Links - [https://criticalsolutionsnetwork.github.io/M365FoundationsCISReport/#Get-AdminRoleUserLicense](https://criticalsolutionsnetwork.github.io/M365FoundationsCISReport/#Get-AdminRoleUserLicense) +## Get-M365SecurityAuditRecNumberList +### Syntax +```powershell +Get-M365SecurityAuditRecNumberList [[-Version] ] +``` +### Parameters +| Name | Alias | Description | Required? | Pipeline Input | Default Value | +| - | - | - | - | - | - | +| Version | None | | false | false | | ## Get-MFAStatus ### Synopsis -Retrieves the MFA \(Multi-Factor Authentication\) status for Azure Active Directory users. +Retrieves the MFA \\(Multi-Factor Authentication\) status for Azure Active Directory users. ### Syntax ```powershell @@ -243,7 +250,7 @@ Get-MFAStatus [[-UserId] ] [-SkipMSOLConnectionChecks] [UserId | | The User Principal Name \(UPN\) of a specific user to retrieve MFA status for. If not provided, the function retrieves MFA status for all users. | false | false | | +| UserId | | The User Principal Name \\(UPN\) of a specific user to retrieve MFA status for. If not provided, the function retrieves MFA status for all users. | false | false | | | SkipMSOLConnectionChecks | | | false | false | False | ### Outputs - System.Object Returns a sorted list of custom objects containing the following properties: - UserPrincipalName - DisplayName - MFAState - MFADefaultMethod - MFAPhoneNumber - PrimarySMTP - Aliases @@ -284,7 +291,7 @@ Grant-M365SecurityAuditConsent [-UserPrincipalNameForConsent] [-SkipGra ### Parameters | Name | Alias | Description | Required? | Pipeline Input | Default Value | | - | - | - | - | - | - | -| UserPrincipalNameForConsent | | The UPN or ID of the user to grant consent for. | true | true \(ByValue, ByPropertyName\) | | +| UserPrincipalNameForConsent | | The UPN or ID of the user to grant consent for. | true | true \\(ByValue, ByPropertyName\) | | | SkipGraphConnection | | If specified, skips connecting to Microsoft Graph. | false | false | False | | SkipModuleCheck | | If specified, skips the check for the Microsoft.Graph module. | false | false | False | | SuppressRevertOutput | | If specified, suppresses the output of the revert commands. | false | false | False | @@ -319,19 +326,19 @@ Invokes a security audit for Microsoft 365 environments. ### Syntax ```powershell -Invoke-M365SecurityAudit [-TenantAdminUrl ] [-DomainName ] [-ApprovedCloudStorageProviders ] [-ApprovedFederatedDomains ] [-DoNotConnect] [-DoNotDisconnect] [-NoModuleCheck] [-DoNotConfirmConnections] [-AuthParams ] [-WhatIf] [-Confirm] [] +Invoke-M365SecurityAudit [-TenantAdminUrl ] [-DomainName ] [-ApprovedCloudStorageProviders ] [-ApprovedFederatedDomains ] [-DoNotConnect] [-DoNotDisconnect] [-NoModuleCheck] [-DoNotConfirmConnections] [-AuthParams ] [-Version ] [-WhatIf] [-Confirm] [] -Invoke-M365SecurityAudit [-TenantAdminUrl ] [-DomainName ] -ELevel -ProfileLevel [-ApprovedCloudStorageProviders ] [-ApprovedFederatedDomains ] [-DoNotConnect] [-DoNotDisconnect] [-NoModuleCheck] [-DoNotConfirmConnections] [-AuthParams ] [-WhatIf] [-Confirm] [] +Invoke-M365SecurityAudit [-TenantAdminUrl ] [-DomainName ] -ELevel -ProfileLevel [-ApprovedCloudStorageProviders ] [-ApprovedFederatedDomains ] [-DoNotConnect] [-DoNotDisconnect] [-NoModuleCheck] [-DoNotConfirmConnections] [-AuthParams ] [-Version ] [-WhatIf] [-Confirm] [] -Invoke-M365SecurityAudit [-TenantAdminUrl ] [-DomainName ] -IncludeIG1 [-ApprovedCloudStorageProviders ] [-ApprovedFederatedDomains ] [-DoNotConnect] [-DoNotDisconnect] [-NoModuleCheck] [-DoNotConfirmConnections] [-AuthParams ] [-WhatIf] [-Confirm] [] +Invoke-M365SecurityAudit [-TenantAdminUrl ] [-DomainName ] -IncludeIG1 [-ApprovedCloudStorageProviders ] [-ApprovedFederatedDomains ] [-DoNotConnect] [-DoNotDisconnect] [-NoModuleCheck] [-DoNotConfirmConnections] [-AuthParams ] [-Version ] [-WhatIf] [-Confirm] [] -Invoke-M365SecurityAudit [-TenantAdminUrl ] [-DomainName ] -IncludeIG2 [-ApprovedCloudStorageProviders ] [-ApprovedFederatedDomains ] [-DoNotConnect] [-DoNotDisconnect] [-NoModuleCheck] [-DoNotConfirmConnections] [-AuthParams ] [-WhatIf] [-Confirm] [] +Invoke-M365SecurityAudit [-TenantAdminUrl ] [-DomainName ] -IncludeIG2 [-ApprovedCloudStorageProviders ] [-ApprovedFederatedDomains ] [-DoNotConnect] [-DoNotDisconnect] [-NoModuleCheck] [-DoNotConfirmConnections] [-AuthParams ] [-Version ] [-WhatIf] [-Confirm] [] -Invoke-M365SecurityAudit [-TenantAdminUrl ] [-DomainName ] -IncludeIG3 [-ApprovedCloudStorageProviders ] [-ApprovedFederatedDomains ] [-DoNotConnect] [-DoNotDisconnect] [-NoModuleCheck] [-DoNotConfirmConnections] [-AuthParams ] [-WhatIf] [-Confirm] [] +Invoke-M365SecurityAudit [-TenantAdminUrl ] [-DomainName ] -IncludeIG3 [-ApprovedCloudStorageProviders ] [-ApprovedFederatedDomains ] [-DoNotConnect] [-DoNotDisconnect] [-NoModuleCheck] [-DoNotConfirmConnections] [-AuthParams ] [-Version ] [-WhatIf] [-Confirm] [] -Invoke-M365SecurityAudit [-TenantAdminUrl ] [-DomainName ] -IncludeRecommendation [-ApprovedCloudStorageProviders ] [-ApprovedFederatedDomains ] [-DoNotConnect] [-DoNotDisconnect] [-NoModuleCheck] [-DoNotConfirmConnections] [-AuthParams ] [-WhatIf] [-Confirm] [] +Invoke-M365SecurityAudit [-TenantAdminUrl ] [-DomainName ] -IncludeRecommendation [-ApprovedCloudStorageProviders ] [-ApprovedFederatedDomains ] [-DoNotConnect] [-DoNotDisconnect] [-NoModuleCheck] [-DoNotConfirmConnections] [-AuthParams ] [-Version ] [-WhatIf] [-Confirm] [] -Invoke-M365SecurityAudit [-TenantAdminUrl ] [-DomainName ] -SkipRecommendation [-ApprovedCloudStorageProviders ] [-ApprovedFederatedDomains ] [-DoNotConnect] [-DoNotDisconnect] [-NoModuleCheck] [-DoNotConfirmConnections] [-AuthParams ] [-WhatIf] [-Confirm] [] +Invoke-M365SecurityAudit [-TenantAdminUrl ] [-DomainName ] -SkipRecommendation [-ApprovedCloudStorageProviders ] [-ApprovedFederatedDomains ] [-DoNotConnect] [-DoNotDisconnect] [-NoModuleCheck] [-DoNotConfirmConnections] [-AuthParams ] [-Version ] [-WhatIf] [-Confirm] [] @@ -342,27 +349,28 @@ Invoke-M365SecurityAudit [-TenantAdminUrl ] [-DomainName ] -Skip | - | - | - | - | - | - | | TenantAdminUrl | | The URL of the tenant admin. If not specified, none of the SharePoint Online tests will run. | false | false | | | DomainName | | The domain name of the Microsoft 365 environment to test. It is optional and will trigger various tests to run only for the specified domain. Tests Affected: 2.1.9/Test-EnableDKIM, 1.3.1/Test-PasswordNeverExpirePolicy, 2.1.4/Test-SafeAttachmentsPolicy | false | false | | -| ELevel | | Specifies the E-Level \(E3 or E5\) for the audit. This parameter is optional and can be combined with the ProfileLevel parameter. | true | false | | -| ProfileLevel | | Specifies the profile level \(L1 or L2\) for the audit. This parameter is mandatory, but only when ELevel is selected. Otherwise it is not required. | true | false | | +| ELevel | | Specifies the E-Level \\(E3 or E5\) for the audit. This parameter is optional and can be combined with the ProfileLevel parameter. | true | false | | +| ProfileLevel | | Specifies the profile level \\(L1 or L2\) for the audit. This parameter is mandatory, but only when ELevel is selected. Otherwise, it is not required. | true | false | | | IncludeIG1 | | If specified, includes tests where IG1 is true. | true | false | False | | IncludeIG2 | | If specified, includes tests where IG2 is true. | true | false | False | | IncludeIG3 | | If specified, includes tests where IG3 is true. | true | false | False | | IncludeRecommendation | | Specifies specific recommendations to include in the audit. Accepts an array of recommendation numbers. | true | false | | | SkipRecommendation | | Specifies specific recommendations to exclude from the audit. Accepts an array of recommendation numbers. | true | false | | -| ApprovedCloudStorageProviders | | Specifies the approved cloud storage providers for the audit. Accepts an array of cloud storage provider names for test 8.1.1/Test-TeamsExternalFileSharing. Acceptable values: 'GoogleDrive', 'ShareFile', 'Box', 'DropBox', 'Egnyte' | false | false | @\(\) | +| ApprovedCloudStorageProviders | | Specifies the approved cloud storage providers for the audit. Accepts an array of cloud storage provider names for test 8.1.1/Test-TeamsExternalFileSharing. Acceptable values: 'GoogleDrive', 'ShareFile', 'Box', 'DropBox', 'Egnyte' | false | false | @\\(\) | | ApprovedFederatedDomains | | Specifies the approved federated domains for the audit test 8.2.1/Test-TeamsExternalAccess. Accepts an array of allowed domain names. Additional Tests may include this parameter in the future. | false | false | | | DoNotConnect | | If specified, the cmdlet will not establish a connection to Microsoft 365 services. | false | false | False | | DoNotDisconnect | | If specified, the cmdlet will not disconnect from Microsoft 365 services after execution. | false | false | False | | NoModuleCheck | | If specified, the cmdlet will not check for the presence of required modules. | false | false | False | | DoNotConfirmConnections | | If specified, the cmdlet will not prompt for confirmation before proceeding with established connections and will disconnect from all of them. | false | false | False | | AuthParams | | Specifies an authentication object containing parameters for application-based authentication. If provided, this will be used for connecting to services. | false | false | | +| Version | | Specifies the CIS benchmark definitions version to use. Default is 4.0.0. Valid values are "3.0.0" or "4.0.0". | false | false | 4.0.0 | | WhatIf | wi | | false | false | | | Confirm | cf | | false | false | | ### 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. + - CISAuditResult\[\] The cmdlet returns an array of CISAuditResult objects representing the results of the security audit. ### Note - 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 @@ -398,12 +406,19 @@ Invoke-M365SecurityAudit -TenantAdminUrl "https://contoso-admin.sharepoint.com" **EXAMPLE 5** ```powershell +Invoke-M365SecurityAudit -TenantAdminUrl "https://contoso-admin.sharepoint.com" -DomainName "contoso.com" -Version "3.0.0" +# Performs a security audit using the CIS benchmark definitions version 3.0.0. +``` + + +**EXAMPLE 6** +```powershell $auditResults = Invoke-M365SecurityAudit -TenantAdminUrl "https://contoso-admin.sharepoint.com" -DomainName "contoso.com" PS> Export-M365SecurityAuditTable -AuditResults $auditResults -ExportPath "C:\temp" -ExportOriginalTests -ExportAllTests ``` -**EXAMPLE 6** +**EXAMPLE 7** ```powershell # (PowerShell 7.x Only) Creating a new authentication object for the security audit for app-based authentication. PS> $authParams = New-M365SecurityAuditAuthObject ` @@ -422,7 +437,7 @@ auditResults.csv ``` -**EXAMPLE 7** +**EXAMPLE 8** ```powershell Invoke-M365SecurityAudit -WhatIf Displays what would happen if the cmdlet is run without actually performing the audit. @@ -450,7 +465,7 @@ New-M365SecurityAuditAuthObject [-ClientCertThumbPrint] [-ClientId] ClientCertThumbPrint | | The thumbprint of the client certificate used for authentication. It must be a 40-character hexadecimal string. This certificate is used to authenticate the application in Azure AD. | true | false | | -| ClientId | | The Client ID \(Application ID\) of the Azure AD application. It must be a valid GUID format. | true | false | | +| ClientId | | The Client ID \\(Application ID\) of the Azure AD application. It must be a valid GUID format. | true | false | | | TenantId | | The Tenant ID of the Azure AD directory. It must be a valid GUID format representing your Microsoft 365 tenant. | true | false | | | OnMicrosoftUrl | | The URL of your onmicrosoft.com domain. It should be in the format 'example.onmicrosoft.com'. | true | false | | | SpAdminUrl | | The SharePoint admin URL, which should end with '-admin.sharepoint.com'. This URL is used for connecting to SharePoint Online. | true | false | | @@ -461,7 +476,7 @@ New-M365SecurityAuditAuthObject [-ClientCertThumbPrint] [-ClientId] - This code was generated by a tool. on: 08/04/2024 15:16:23 + This code was generated by a tool. on: 04/21/2025 11:26:56 If you'd like to regenerate the documentation, please open up powershell and run @@ -99,6 +99,7 @@