Written in PowerShell 7 and 5.1
Current Version: v3.0 beta
Next Major Scheduled Release: Q1 (January 2025)
Next Release Version: v3.0
The Open-Source, Automated Microsoft 365 Security Assessment Tool
Nearly 50% of people worldwide rely on Microsoft 365 for their office work. Recognizing the growing security challenges, we have developed a unique technical solution tailored to address these concerns. Leveraging our expertise in Microsoft 365 security, we offer a comprehensive auditing solution that outperforms other security suites in assessing Microsoft 365 environments.
Introducing M365SAT, our newly released solution for Microsoft 365 and Azure environments. M365SAT safeguards your organization's Microsoft 365 tenant by identifying misconfigurations and mitigating potential risks.
Elevate your Microsoft 365 environment to unprecedented levels of security with our all-encompassing solution. Designed to protect your digital assets, M365SAT offers unmatched defense against evolving cyber threats, ensuring the security of your Microsoft 365 environment.
Our solution surpasses conventional security measures by meticulously analyzing approximately 300 distinct settings across the entire Microsoft 365 suite. From Teams to Exchange, SharePoint to Azure, every aspect of your ecosystem is thoroughly examined to identify and neutralize potential vulnerabilities. With this exhaustive approach, you can be confident that your digital infrastructure is comprehensively fortified.
M365SAT also examines your Microsoft 365 cloud settings, identifying deviations from the recommended CIS Benchmark configurations. This allows your organization to swiftly address potential security vulnerabilities and adhere to industry best practices. Beyond simply identifying issues, our solution provides remediation guidance through PowerShell scripts, simplifying the process and saving your IT team valuable time and effort.
M365SAT is the evolution of its predecessor, 365Inspect+, which was released in 2022. The goal of M365SAT is to enable Security and Compliance Administrators to easily measure their environment's security posture.
Our tool is completely free and open-source, utilizing PowerShell to assess Microsoft 365 and Azure security configurations. With approximately 300 inspection points, it helps administrators reduce risky configurations and enhance security.
The core features of M365SAT include:
- Automated Scanning: Allows administrators to easily initiate the scanning process multiple times with minimal interaction, simplifying the assessment of security configurations.
- Detailed Reporting: Generates comprehensive HTML reports that provide insights into risks and rationales, helping administrators understand and address potential vulnerabilities.
- Modularity: Supports the creation of new scan modules to extend auditing capabilities. Instructions for developing custom modules can be found in the Examples section.
M365SAT can be installed in the following ways:
- *Install-Module M365SAT: This option will be available in the next release.
- Downloading the latest release and using Import-Module: Download the latest release and use the Import-Module command on the .psd1 file.
- Downloading the latest release and using the M365SATTester.ps1 file: Download the latest release and run the M365SATTester.ps1 file.
The following modules need to be installed in order to make M365SAT work:
- Az
- ExchangeOnlineManagement
- Microsoft.Online.SharePoint.PowerShell
- Microsoft.Graph
- MicrosoftTeams
- PoShLog
PowerShell 7.x works with all the latest modules.
Install-Module -Name Az
Install-Module -Name ExchangeOnlineManagement
Install-Module -Name Microsoft.Online.SharePoint.PowerShell
Install-Module -Name Microsoft.Graph -AllowClobber -Force
Install-Module -Name Microsoft.Graph.Beta -AllowClobber -Force
Install-Module -Name MicrosoftTeams
Install-Module -Name PoShLog
Note: Microsoft PowerShell 5.1 does not work properly with Az.Accounts 3.x.x or later, due to the new mechanism of authentication it conflicts with the ExchangeOnlineManagement modules. 2.19.0 is the latest working version with PowerShell 5.1.
Install-Module -Name Az
Install-Module -Name ExchangeOnlineManagement -AllowClobber -Force
Install-Module -Name Microsoft.Online.SharePoint.PowerShell
Install-Module -Name Microsoft.Graph -AllowClobber -Force
Install-Module -Name Microsoft.Graph.Beta -AllowClobber -Force
Install-Module -Name MicrosoftTeams
Install-Module -Name PoShLog
- Remove from here the
3.x.xfolderC:\Program Files\WindowsPowerShell\Modules\Az.Accounts - Run
Install-Module -Name Az.Accounts -RequiredVersion 2.19.0to install the working PowerShell 5.1 version.
Note: This only works starting from v3.0!!! PowerShell 7 works with Linux, the only module that is not working straightforward is Microsoft Sharepoint. Thus will be replaced with PnP when using a Linux environment. For Linux you must follow the instructions below:
- Run
sudo pwsh - In the PowerShell SuperUser session run:
Install-Module -Name PSWSMan - After installation run the command:
Install-WSMan - You will be prompted to restart the PowerShell Session. Close the SuperUser session
- Install all the modules down below:
Install-Module -Name Az
Install-Module -Name ExchangeOnlineManagement -AllowClobber -Force
Install-Module -Name PnP.PowerShell
Install-Module -Name Microsoft.Graph -AllowClobber -Force
Install-Module -Name Microsoft.Graph.Beta -AllowClobber -Force
Install-Module -Name MicrosoftTeams
Install-Module -Name PoShLog
Please keep in mind that there might be things that are not working. Feel free to report any bugs if found.!
This method is coming in the next major release
M365SAT is very easy to use. There are two main ways of executing M365SAT:
- Using the M365SATTester.ps1 script
- Executing Get-M365SATReport after importing the M365SAT modules
M365SAT requires fewer permissions compared to its predecessor, 365Inspect+. The following permissions are sufficient to run a successful audit:
- Application Administrator
- SharePoint Administrator
- Exchange Administrator
- Global Reader
These permissions have been tested with the latest version of M365SAT and are confirmed to be working as of July 20, 2023.
While it is no longer necessary to use a Global Administrator account, we recommend using one for the most comprehensive results.
Why do we need SharePoint Administrator permissions instead of lesser permissions? Some settings can only be accessed when you have Administrator privileges. For more information, refer to the Microsoft documentation on permissions.
Make sure you RUN PowerShell as Administrator.
- Clone the github repository or download the latest release at the releases section
- cd C:\M365SAT; Get-ChildItem -Path .\ -Recurse | Unblock-File to unblock all files
- Edit the M365SATTester.ps1 and replace -Username value with the username containing at least Global Reader and SharePoint Admin permissions.
- Run M365SATTester.ps1 as Administrator the M365SAT.psm1 will be automatically imported and the assessment will be started!
Only use this method if you already installed all additional modules. Else step 5 will return a lot of errors! Use method 4 to install the required modules and return to this.
- Clone the github repository or download the latest release at the releases section
- cd C:\M365SAT; Get-ChildItem -Path .\ -Recurse | Unblock-File
- Import-Module .\M365SAT.psd1
- Wait until the process is finished, there might be some errors, because of not implemented solutions, you can safely ignore them.
- See 5.2 for the execution command
The execution of M365SAT can be done as followed:
Get-M365SATReport -OutPath <value> -reportType <HTML/CSV/XML> -Username <username> (-Password <password> -SkipChecks -SkipLogin -UseCustomModules -AllowLogging <Verbose/Debug/Info/Warning/Error/Fatal> -Modules <All/MicrosoftAzure/MicrosoftExchange/MicrosoftOffice365/MicrosoftSharepoint/MicrosoftTeams> )
-OutPath: Specifies the output path for the exported report.
-Username: Mandatory. Enter the administrator username.
-EnvironmentType: Mandatory. Choose the environment to audit. Options include:
- M365: Microsoft 365
- AZURE: Azure
- CUSTOM: Custom Scripts in the /CUSTOM folder
- ALL: All environments
-BenchmarkVersion: Choose the benchmark version. Options include:
- 3: Benchmark version 3
- 2: Benchmark version 2
- LATEST: Latest available benchmark version
-Modules: Choose the modules to audit. Options include:
- Azure: Azure
- Exchange: Exchange
- Office365: Office 365
- Sharepoint: SharePoint
- Teams: Teams
- All: All modules
-reportType: Choose the report format. Options include:
- HTML: HTML
- CSV: CSV
- XML: XML
- CSMS: CSMS
Note: Only HTML fully works at the moment!
-Environment: Specifies the environment type. Options include:
- Default: Standard environment
- USGovGCCHigh: U.S. Government Cloud Computing High
- USGovDoD: U.S. Government Department of Defense
- Germany: Germany region
- China: China region
-Password: Enter the administrator password. (Non-MFA Account)
-LicenseMode: Choose the benchmark license mode. Options include:
- E3: E3 license
- E5: E5 license
- All: All license modes
-LicenseLevel: Choose the benchmark level. Options include:
- L1: Level 1
- L2: Level 2
- All: All levels
-AllowLogging: Specifies the log message level. Options include:
- Verbose: Verbose logging
- Debug: Debug logging
- Info: Informational logging
- Warning: Warning logging
- Error: Error logging
- Fatal: Fatal logging
-SkipChecks: Skips module updates (experimental).
-ExpirimentalMode: Uses the experimental multi-threaded scanner (not recommended).
-LocalMode: Enables using the /inspectors folder instead of downloading the inspectors from GitHub.
-SkipLogin: Skips login if already authenticated (Not-Recommended).
When using the standard command to execute a security assessment, you will be prompted with graphical login screens where you must log in sequentially.
.\M365SATTester.ps1
You can add the desired parameters to this script and run it as needed.
The execution time for M365SAT varies depending on the size and complexity of your organization. For organizations with a small number of user accounts and minimal configuration, the assessment should take no longer than 30 minutes. However, for organizations with more than 100 user accounts and custom configurations, the process may take longer. The duration depends on the organization’s size, complexity, and the extent of configurations.
Unlike its predecessor, 365Inspect+, M365SAT is much more modular. It is designed to be easily expanded, allowing additional modules to be added or troubleshooted with ease when problems occur. We have organized multiple modules into directories, so when a user builds a new module, they can simply create a new directory and develop the module there.
All Inspector modules are stored in the .\inspectors folder. You can use any earlier created module as a template to create a new module. Most of the modules are called:
CSTM-[ProductFamily][ID].ps1
For ProductFamily we have the following options at the moment:
- Az (Microsoft Azure)
- Ex (Microsoft Exchange)
- O365 (Microsoft 365)
- Sp (Microsoft Sharepoint)
- Tms (Microsoft Teams)
ID Should be XXX-format e.g. 001, 002, 003, etc.
The following example is a Azure Inspector:
# Date: 25-1-2023
# Version: 1.0
# Benchmark: CIS Microsoft 365 v3.1.0
# Product Family: Microsoft Azure
# Purpose:
# Author:
# New Error Handler Will be Called here
Import-Module PoShLog
#Call the OutPath Variable here
$path = @($OutPath)
function Build-CISMAz5111($findings)
{
#Actual Inspector Object that will be returned. All object values are required to be filled in.
$inspectorobject = New-Object PSObject -Property @{
ID = "CISMAz5111"
FindingName = "CISMAz 5.1.1.1 - The Security Defaults are enabled on Azure Active Directory Tenant"
ProductFamily = "Microsoft Azure"
RiskScore = "4"
Description = "Security defaults in Azure Active Directory (Azure AD) make it easier to be secure and help protect your organization. Security defaults contain preconfigured security settings for common attacks."
Remediation = "Use the PowerShell Script to disable Security Defaults on Microsoft Azure Active Directory"
PowerShellScript = '$body = $body = (@{"isEnabled"="false"} | ConvertTo-Json) ;Invoke-MgGraphRequest -Method PATCH https://graph.microsoft.com/beta/policies/identitySecurityDefaultsEnforcementPolicy -Body $body'
DefaultValue = "True for tenants created later than 2019, False for tenants created before 2019"
ExpectedValue = "False"
ReturnedValue = "$findings"
Impact = "4"
Likelihood = "1"
RiskRating = "Low"
Priority = "Medium"
References = @(@{ 'Name' = 'Security defaults in Microsoft Entra ID'; 'URL' = 'https://learn.microsoft.com/en-us/entra/fundamentals/security-defaults' },
@{ 'Name' = 'Introducing security defaults'; 'URL' = 'https://techcommunity.microsoft.com/t5/microsoft-entra-azure-ad-blog/introducing-security-defaults/ba-p/1061414' })
}
return $inspectorobject
}
function Audit-CISMAz5111
{
try
{
# Actual Script
$SecureDefaultsState = Get-MgPolicyIdentitySecurityDefaultEnforcementPolicy
# Validation
if ($SecureDefaultsState.isEnabled -eq $true)
{
$SecureDefaultsState | Format-Table -AutoSize | Out-File "$path\CISMAz5111-SecureDefaultEnforcementPolicy.txt"
$finalobject = Build-CISMAz5111($SecureDefaultsState.isEnabled)
return $finalobject
}
return $null
}
catch
{
Write-WarningLog 'The Inspector: {inspector} was terminated!' -PropertyValues $_.InvocationInfo.ScriptName
Write-ErrorLog 'An error occured on line {line} char {char} : {error}' -ErrorRecord $_ -PropertyValues $_.InvocationInfo.ScriptLineNumber, $_.InvocationInfo.OffsetInLine, $_.InvocationInfo.Line
}
}
return Audit-CISMAz5111
Explanation of the Code Above:
- Description: This section includes metadata about the program, such as the author, purpose, and version.
- Error Handling: The script imports the PoShLog module to handle errors effectively.
- Log Exporting: The $path = @($OutPath) line is used to ensure logs are saved to the correct folder if the script outputs logs.
- Build Function: This function, Build-CISMAz5111, creates a custom PSObject to be returned if a violation is found by the inspector. It includes all necessary details for reporting.
- Audit Function: The Audit-CISMAz5111 function contains the actual script that checks for any violations. If a violation is found, it creates a final object using the build function and returns it. The $findings parameter is passed to populate the PSCustomObject with information that can be reported.
Coding Tips:
- Use Try & Catch: Always use try and catch blocks to handle errors. If an inspector encounters a problem, it will either return null or throw an exception. Error logs are saved in the same directory in a separate log folder.
- Keep Code Efficient: Write concise code to avoid performance delays and to shorten the security assessment duration.
- PowerShell Formatting: For well-formatted PowerShell scripts, consider using SAPIEN PowerShell Studio. It has a Format-Script function that helps format the script into readable sections, saving time in identifying issues.
You can develop additional modules and place them in different directories based on their purpose:
- Pre-check Modules: If you create a module for pre-check purposes, place it in the .\modules directory.
- Core Modules: If the module is an addition to the core functionality of the program, place it in the .\core directory.
- Output Parsers: If you develop a new method to output a report into a different file format, place the parser in the .\output directory.
As a Cyber Security Specialist, I take security very seriously. Please be aware that this program can execute various inspector modules, which means that potentially malicious scripts could be run if not properly managed. I am not responsible for any damage or loss of files that may occur in such cases.
To maintain a secure environment, please follow these best practices:
- Use Least Privilege: Audit with an account that has only the necessary privileges for the audit. Avoid using accounts with excessive permissions.
- Write-Protect the Inspector Folder: Ensure that the inspector folder is write-protected to prevent unauthorized access and to safeguard against malicious code being inserted.
- Avoid Untrusted Scripts: Do not place any PowerShell scripts in the inspector folder unless they are from a trusted source.
M365SAT is an open-source and free software released under the MIT License. All the additional plug-ins and frameworks are also accompanied by the same MIT Licence.
- Soteria-Security: For allowing me to create the fork on the predecessor!
- AsterICTNL: For allowing me to additionally develop this further
- CISSecurity: For providing the Azure and Microsoft 365 benchmarks to make the inspector modules
- cammurray: For the reporting structure
- OfficeDev: For the reporting structure
Donations are always welcome! Feel free to Donate to me through PayPal!