M365FoundationsCISReport

Get-AdminRoleUserLicense

Retrieves user licenses and roles for administrative accounts from Microsoft 365 via the Graph API.

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.

Syntax 

Get-AdminRoleUserLicense [-SkipGraphConnection] [<CommonParameters>]

Parameters

Name Alias Description Required? Pipeline Input Default Value
-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.		 false false False

Inputs

The input type is the type of the objects that you can pipe to the cmdlet.

  • None. You cannot pipe objects to Get-AdminRoleUserLicense.

Outputs

The output type is the type of the objects that the cmdlet emits.

  • PSCustomObject Returns a custom object for each user with administrative roles that includes the following properties: RoleName, UserName, UserPrincipalName, UserId, HybridUser, and Licenses.

Note

Creation Date: 2024-04-15 Purpose/Change: Initial function development to support Microsoft 365 administrative role auditing.

Examples

EXAMPLE 1 
Get-AdminRoleUserLicense
This example retrieves all administrative role users along with their licenses by connecting to Microsoft Graph using the default scopes.
EXAMPLE 2 
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.

Top of page

Links

Get-MFAStatus

Retrieves the MFA (Multi-Factor Authentication) status for Azure Active Directory users.

The Get-MFAStatus function connects to Microsoft Online Service and retrieves the MFA status for all Azure Active Directory users, excluding guest accounts. Optionally, you can specify a single user by their User Principal Name
(UPN) to get their MFA status.

Syntax 

Get-MFAStatus [[-UserId] <String>] [<CommonParameters>]

Parameters

Name Alias Description Required? Pipeline Input Default Value
-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

Outputs

The output type is the type of the objects that the cmdlet emits.

  • System.Object Returns a sorted list of custom objects containing the following properties: - UserPrincipalName - DisplayName - MFAState - MFADefaultMethod - MFAPhoneNumber - PrimarySMTP - Aliases

Note

The function requires the MSOL module to be installed and connected to your tenant. Ensure that you have the necessary permissions to read user and MFA status information.

Examples

EXAMPLE 1 
Get-MFAStatus
Retrieves the MFA status for all Azure Active Directory users.
EXAMPLE 2 
Get-MFAStatus -UserId "example@domain.com"
Retrieves the MFA status for the specified user with the UPN "example@domain.com".

Top of page

Invoke-M365SecurityAudit

Invokes a security audit for Microsoft 365 environments.

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.

Syntax 

Invoke-M365SecurityAudit [-TenantAdminUrl <String>] [-M365DomainForPWPolicyTest <String>] [-DoNotConnect] [-DoNotDisconnect] [-NoModuleCheck] [-WhatIf] [-Confirm] [<CommonParameters>]

Invoke-M365SecurityAudit [-TenantAdminUrl <String>] [-M365DomainForPWPolicyTest <String>] -ELevel <String> -ProfileLevel <String> [-DoNotConnect] [-DoNotDisconnect] [-NoModuleCheck] [-WhatIf] [-Confirm] [<CommonParameters>]

Invoke-M365SecurityAudit [-TenantAdminUrl <String>] [-M365DomainForPWPolicyTest <String>] -IncludeIG1 [-DoNotConnect] [-DoNotDisconnect] [-NoModuleCheck] [-WhatIf] [-Confirm] [<CommonParameters>]

Invoke-M365SecurityAudit [-TenantAdminUrl <String>] [-M365DomainForPWPolicyTest <String>] -IncludeIG2 [-DoNotConnect] [-DoNotDisconnect] [-NoModuleCheck] [-WhatIf] [-Confirm] [<CommonParameters>]

Invoke-M365SecurityAudit [-TenantAdminUrl <String>] [-M365DomainForPWPolicyTest <String>] -IncludeIG3 [-DoNotConnect] [-DoNotDisconnect] [-NoModuleCheck] [-WhatIf] [-Confirm] [<CommonParameters>]

Invoke-M365SecurityAudit [-TenantAdminUrl <String>] [-M365DomainForPWPolicyTest <String>] -IncludeRecommendation <String[]> [-DoNotConnect] [-DoNotDisconnect] [-NoModuleCheck] [-WhatIf] [-Confirm] [<CommonParameters>]

Invoke-M365SecurityAudit [-TenantAdminUrl <String>] [-M365DomainForPWPolicyTest <String>] -SkipRecommendation <String[]> [-DoNotConnect] [-DoNotDisconnect] [-NoModuleCheck] [-WhatIf] [-Confirm] [<CommonParameters>]

Parameters

Name Alias Description Required? Pipeline Input Default Value
-TenantAdminUrl The URL of the tenant admin. If not specified, none of the SharePoint Online tests will run. false false
-M365DomainForPWPolicyTest The domain name of the Microsoft 365 environment to test. This parameter is not mandatory and by default it will pass/fail all found domains as a group if a specific domain is not specified. 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 optional and can be combined with the ELevel parameter. 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
-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
-WhatIf wi false false
-Confirm cf false false

Inputs

The input type is the type of the objects that you can pipe to the cmdlet.

  • None. You cannot pipe objects to Invoke-M365SecurityAudit.

Outputs

The output type is the type of the objects that the cmdlet emits.

  • 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

Examples

EXAMPLE 1 
Invoke-M365SecurityAudit
Performs a security audit using default parameters. Output: Status : Fail ELevel : E3 ProfileLevel: L1 Connection : Microsoft Graph Rec : 1.1.1 Result : False Details : Non-compliant accounts: Username | Roles | HybridStatus | Missing Licence user1@domain.com| Global Administrator | Cloud-Only | AAD_PREMIUM user2@domain.com| Global Administrator | Hybrid | AAD_PREMIUM, AAD_PREMIUM_P2 FailureReason: Non-Compliant Accounts: 2
EXAMPLE 2 
Invoke-M365SecurityAudit -TenantAdminUrl "https://contoso-admin.sharepoint.com" -M365DomainForPWPolicyTest "contoso.com" -ELevel "E5" -ProfileLevel "L1"
Performs a security audit for the E5 level and L1 profile in the specified Microsoft 365 environment. Output: Status : Fail ELevel : E5 ProfileLevel: L1 Connection : Microsoft Graph Rec : 1.1.1 Result : False Details : Non-compliant accounts: Username | Roles | HybridStatus | Missing Licence user1@domain.com| Global Administrator | Cloud-Only | AAD_PREMIUM user2@domain.com| Global Administrator | Hybrid | AAD_PREMIUM, AAD_PREMIUM_P2 FailureReason: Non-Compliant Accounts: 2
EXAMPLE 3 
Invoke-M365SecurityAudit -TenantAdminUrl "https://contoso-admin.sharepoint.com" -M365DomainForPWPolicyTest "contoso.com" -IncludeIG1
Performs an audit including all tests where IG1 is true. Output: Status : Fail ELevel : E3 ProfileLevel: L1 Connection : Microsoft Graph Rec : 1.1.1 Result : False Details : Non-compliant accounts: Username | Roles | HybridStatus | Missing Licence user1@domain.com| Global Administrator | Cloud-Only | AAD_PREMIUM user2@domain.com| Global Administrator | Hybrid | AAD_PREMIUM, AAD_PREMIUM_P2 FailureReason: Non-Compliant Accounts: 2
EXAMPLE 4 
Invoke-M365SecurityAudit -TenantAdminUrl "https://contoso-admin.sharepoint.com" -M365DomainForPWPolicyTest "contoso.com" -SkipRecommendation '1.1.3', '2.1.1'
Performs an audit while excluding specific recommendations 1.1.3 and 2.1.1. Output: Status : Fail ELevel : E3 ProfileLevel: L1 Connection : Microsoft Graph Rec : 1.1.1 Result : False Details : Non-compliant accounts: Username | Roles | HybridStatus | Missing Licence user1@domain.com| Global Administrator | Cloud-Only | AAD_PREMIUM user2@domain.com| Global Administrator | Hybrid | AAD_PREMIUM, AAD_PREMIUM_P2 FailureReason: Non-Compliant Accounts: 2
EXAMPLE 5 
$auditResults = Invoke-M365SecurityAudit -TenantAdminUrl "https://contoso-admin.sharepoint.com" -M365DomainForPWPolicyTest "contoso.com"
PS> $auditResults | Export-Csv -Path "auditResults.csv" -NoTypeInformation Captures the audit results into a variable and exports them to a CSV file. Output: CISAuditResult[] auditResults.csv
EXAMPLE 6 
Invoke-M365SecurityAudit -WhatIf
Displays what would happen if the cmdlet is run without actually performing the audit. Output: What if: Performing the operation "Invoke-M365SecurityAudit" on target "Microsoft 365 environment".

Top of page

Links

Sync-CISExcelAndCsvData

Synchronizes data between an Excel file and either a CSV file or an output object from Invoke-M365SecurityAudit, and optionally updates the Excel worksheet.

The Sync-CISExcelAndCsvData function merges data from a specified Excel file with data from either a CSV file or an output object from Invoke-M365SecurityAudit 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 or audit results while preserving the original formatting and structure of the Excel worksheet.

Syntax 

Sync-CISExcelAndCsvData -ExcelPath <String> -WorksheetName <String> -CsvPath <String> [-SkipUpdate] [<CommonParameters>]

Sync-CISExcelAndCsvData -ExcelPath <String> -WorksheetName <String> -AuditResults <CISAuditResult[]> [-SkipUpdate] [<CommonParameters>]

Parameters

Name Alias Description Required? Pipeline Input Default Value
-ExcelPath The path to the Excel file that contains the original data. This parameter is mandatory. true false
-WorksheetName The name of the worksheet within the Excel file that contains the data to be synchronized. This parameter is mandatory. true false
-CsvPath The path to the CSV file containing data to be merged with the Excel data. This parameter is mandatory when using the CsvInput parameter set. true false
-AuditResults An array of CISAuditResult objects from Invoke-M365SecurityAudit to be merged with the Excel data. This parameter is mandatory when using the ObjectInput parameter set. It can also accept pipeline input. true true (ByValue)
-SkipUpdate If specified, the function will return the merged data object without updating the Excel worksheet. This is useful for previewing the merged data. false false False

Inputs

The input type is the type of the objects that you can pipe to the cmdlet.

  • System.String, CISAuditResult[] You can pipe CISAuditResult objects to Sync-CISExcelAndCsvData.

Outputs

The output type is the type of the objects that the cmdlet emits.

  • Object[] If the SkipUpdate switch is used, the function returns an array of custom objects representing the merged data.

Note

- 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.

Examples

EXAMPLE 1 
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 2 
$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.
EXAMPLE 3 
$auditResults = Invoke-M365SecurityAudit -TenantAdminUrl "https://tenant-admin.url" -DomainName "example.com"
PS> Sync-CISExcelAndCsvData -ExcelPath "path\to\excel.xlsx" -WorksheetName "DataSheet" -AuditResults $auditResults Merges data from the audit results into 'excel.xlsx' on the 'DataSheet' worksheet and updates the worksheet with the merged data.
EXAMPLE 4 
$auditResults = Invoke-M365SecurityAudit -TenantAdminUrl "https://tenant-admin.url" -DomainName "example.com"
PS> $mergedData = Sync-CISExcelAndCsvData -ExcelPath "path\to\excel.xlsx" -WorksheetName "DataSheet" -AuditResults $auditResults -SkipUpdate Retrieves the merged data object for preview without updating the Excel worksheet.
EXAMPLE 5 
Invoke-M365SecurityAudit -TenantAdminUrl "https://tenant-admin.url" -DomainName "example.com" | Sync-CISExcelAndCsvData -ExcelPath "path\to\excel.xlsx" -WorksheetName "DataSheet"
Pipes the audit results into Sync-CISExcelAndCsvData to merge data into 'excel.xlsx' on the 'DataSheet' worksheet and updates the worksheet with the merged data.

Top of page

Links