Purpose

Further the state of Microsoft 365 security by authoring a PowerShell script that automates the security assessment of Microsoft 365 environments.

Soteria Inspect

Soteria Inspect is born from the 365Inspect project and is Soteria's SaaS solution to aid in assessing the security of a Microsoft 365 tenant with over 200 points of inspection across the full suite of Microsoft 365 services.

Soteria Inspect for Microsoft 365 allows customers to track changes to each finding's affected objects over time as well as remediation efforts, and now includes multi-tenancy for MSP's and parent organizations to keep a finger on the pulse of their child tenants.

Soteria Inspect for Microsoft 365 is available directly through Soteria or through the Azure Marketplace

See all of our Soteria Inspect for Microsoft 365 offers

Setup

365Inspect Community Edition requires the administrative PowerShell modules for Exchange administration, Microsoft Graph, Microsoft Teams, and the Sharepoint administration module.

365Inspect is now compatible with PowerShell Core (6+), and requires a Microsoft Windows operating system due to required module dependencies.

The 365Inspect.ps1 PowerShell script will validate the installed modules and minimum version of the modules necessary for the Inspectors to function.

If you do not have these modules installed, you will be prompted to install them, and with your approval, the script will attempt installation. Otherwise, you should be able to install them with the following commands in an administrative PowerShell prompt, or by following the instructions at the references below:

Install-Module -Name ExchangeOnlineManagement -AllowClobber -Force

Install-Module -Name PnP.PowerShell -AllowClobber -Force

Install-Module -Name Microsoft.Graph -AllowClobber -Force

Install-Module -Name MicrosoftTeams -AllowClobber -Force

Install Exchange Online PowerShell

Install SharePoint PnP PowerShell Module

Install Microsoft Graph SDK

Install Microsoft Teams

Once the above are installed, download the 365Inspect source code folder from Github using your browser or by using git clone.

As you will run 365Inspect with administrative privileges, you should place it in a logical location and make sure the contents of the folder are readable and writable only by the administrative user. This is especially important if you intend to install 365Inspect in a location where it will be executed frequently or used as part of an automated process. NOTE: 365Inspect does not need to be run in an administrative PowerShell window to function.

Usage

To run 365Inspect, open a PowerShell console and navigate to the folder you downloaded 365Inspect into:

cd 365Inspect

You will interact with 365Inspect by executing the main script file, 365Inspect.ps1, from within the PowerShell command prompt.

All 365Inspect requires to inspect your O365 tenant is access via an O365 account with proper permissions, so most of the command line parameters relate to the organization being assessed and the method of authentication.

Execution of 365Inspect looks like this:

.\365Inspect.ps1 -OutPath <value> -UserPrincipalName myuser@mytenant.onmicrosoft.com -Auth <MFA|DEVICE|ALREADY_AUTHED|APP>

As 365Inspect executes, it will steadily print status updates indicating which inspection task is running.

365Inspect may take some time to execute. This time scales with the size and complexity of the environment under test. For example, some inspection tasks involve scanning the account configuration of all users. This may occur near-instantly for an organization with 50 users, or could take entire minutes (!) for an organization with 10000.

Output

365Inspect creates the directory specified in the out_path parameter. This directory is the result of the entire 365Inspect inspection. It contains four items of note:

• Report.html: graphical report that describes the O365 security issues identified by 365Inspect, lists O365 objects that are misconfigured, and provides remediation advice.
• Various text files named [Inspector-Name]: these are raw output from inspector modules and contain a list (one item per line) of misconfigured O365 objects that contain the described security flaw. For example, if a module Inspect-FictionalMFASettings were to detect all users who do not have MFA set up, the file "Inspect-FictionalMFASettings" in the report ZIP would contain one user per line who does not have MFA set up. This information is only dumped to a file in cases where more than 15 affected objects are discovered. If less than 15 affected objects are discovered, the objects are listed directly in the main HTML report body.
• Report.zip: zipped version of this entire directory, for convenient distribution of the results in cases where some inspector modules generated a large amount of findings.
• Log directory: 365Inspect logs any errors encountered during the scripts execution to a timestamped log file found in the Log directory

CSV Output

Due to the nature of some of the returned items, the csv report is delimited on the carat (^) character. It is recommended to open the CSV report in a text editor rather than Excel, as Excel defaults to a comma (,) delimiter and will render the report incorrectly. Once opened in a text editor, the data may be pasted into Excel.

Coming Soon!

• You tell us!

Change Log

• Support for Device Authentication

Necessary Privileges

365Inspect can't run properly unless the O365 account you authenticate with has appropriate privileges. 365Inspect requires, at minimum, the following:

• Global Administrator
• SharePoint Administrator

We realize that these are extremely permissive roles, unfortunately due to the use of Microsoft Graph, we are restricted from using lesser privileges by Microsoft. Application and Cloud Application Administrator roles (used to grant delegated and application permissions) are restricted from granting permissions for Microsoft Graph or Azure AD PowerShell modules. Microsoft Docs - Application Administrator

If executing 365Inspect using the application auth parameter, additional roles must be granted to allow the application to perform all executed tasks. See Application Authentication requirements

Application Authentication Requirements

Before 365Inspect can be utilized all other requisite components must be in place.

See the following references:

• Tutorial: Register an app with Microsoft Entra ID
• App-only authentication for unattended scripts in Exchange Online PowerShell and Security & Compliance PowerShell
• Application and service principal objects in Microsoft Entra ID

Required Permissions

Developing Inspector Modules

365Inspect is designed to be easy to expand, with the hope that it enables individuals and organizations to either utilize their own 365Inspect modules internally, or publish those modules for the O365 community.

All of 365Inspect's inspector modules are stored in the .\inspectors folder.

It is simple to create an inspector module. Inspectors have two files:

• ModuleName.ps1: the PowerShell source code of the inspector module. Should return a list of all O365 objects affected by a specific issue, represented as strings.
• ModuleName.json: metadata about the inspector itself. For example, the finding name, description, remediation information, and references.

Templates are included in the Templates folder. Simply add your code and values in the respective locations. The PowerShell and JSON file names must be identical for 365Inspect to recognize that the two belong together. There are numerous examples in 365Inspect's built-in suite of modules, but we'll put an example here too.

Once you drop these two files in the .\inspectors folder, they are considered part of 365Inspect's module inventory and will run the next time you execute 365Inspect.

You have just created the BypassingSafeAttachments Inspector module. That's all!

365Inspect will throw a pretty loud and ugly error if something in your module doesn't work or doesn't follow 365Inspect conventions, so monitor the command line output.

Contributing

We encourage community involvement and contributions! Please check out our Contributing Guidelines

About Security

365Inspect is a script harness that runs other inspector script modules stored in the .\inspectors folder. As with any other script you may run with elevated privileges, you should observe certain security hygiene practices:

• No untrusted user should have write access to the 365Inspect folder/files, as that user could then overwrite scripts or templates therein and induce you to run malicious code.
• No script module should be placed in .\inspectors unless you trust the source of that script module.

About Soteria

Soteria offers a wide range of security and advisory solutions including Incident Response, Managed Detection and Response, Security Assessments, Penetration Testing, and more. Contact us for all your needs!