Home

Awesome

<img src="https://github.com/soteria-security/365Inspect/assets/88730003/af894eb2-7ed8-4082-a51c-dd2da0663ed3" align=right></br></br></br></br>

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

<details> <summary>See the feature comparison!</summary>

365Inspect Community Edition vs Soteria Inspect for Microsoft 365

</details>

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.

<details> <summary>Breaking Changes</summary>

PnP.PowerShell Module

As of September 9, 2024, PnP.PowerShell requires tenant admins to register their own application for use with the SharePoint/PnP service. See the following PnP.PowerShell documentation for required steps. Register an Entra ID Application to use with PnP PowerShell Determine Permissions Authentication

NOTE: If you are using PowerShell 5.1 PnP PowerShell is no longer compatible and all SharePoint Inspectors will be excluded at run time.

There is a command that can be run to automate this step.

Register-PnPEntraIDAppForInteractiveLogin -ApplicationName "PnP Rocks" -Tenant [yourtenant].onmicrosoft.com -Interactive

Remember the name or the Application/Client ID of the application that was created. This is now required to authenticate and you will be prompted for the AppID!

Module Compatibility

Currently the Microsoft.Graph and Microsoft.Graph.Beta Modules versions 2.23.0 are incompatible with ExchangeOnlineManagement version 3.5.1 The following versions are compatible:

The following commands may be used to install compatible versions:

Install-Module -Name Microsoft.Graph -Scope CurrentUser -RequiredVersion 2.21.1 -AllowClobber -Force
Install-Module -Name Microsoft.Graph.Beta -Scope CurrentUser -RequiredVersion 2.21.1 -AllowClobber -Force
Install-Module -Name ExchangeOnlineManagement -Scope CurrentUser -RequiredVersion 3.5.0 -AllowClobber -Force
</details>

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>
<details> <summary>Execution Examples</summary>

Script Execution

For example, to log in by entering your credentials in a browser with MFA support:

    .\365Inspect.ps1 -OutPath ..\365_report -UserPrincipalName myuser@mytenant.onmicrosoft.com -Auth MFA

To login to a Government or other National Cloud Deployment (China, Germany, etc.) the -Environment parameter should be specified as follows:

    .\365Inspect.ps1 -OutPath ..\365_report -UserPrincipalName myuser@mytenant.onmicrosoft.com -Auth MFA -Environment USGovGCCHigh

Valid arguments for the -Environment are:

Application Authentication can be achieved by executing the script with the following parameters:

    .\365Inspect.ps1 -OutPath ..\365_report -UserPrincipalName myuser@mytenant.onmicrosoft.com -Auth APP

To login to a Government or other National Cloud Deployment (China, Germany, etc.) the -Environment parameter should be specified as follows:

    .\365Inspect.ps1 -OutPath ..\365_report -UserPrincipalName myuser@mytenant.onmicrosoft.com -Auth APP -Environment USGovGCCHigh

Valid arguments for the -Environment are:

NOTE: There are prerequisites for execution of 365Inspect with application authentication. Go to Application Authentication Requirements

365Inspect now supports report output to HTML (default value), CSV, and XML formats.

For example, CSV reports can be generated by calling the -ReportType parameter:

    .\365Inspect.ps1 -OutPath ..\365_report -UserPrincipalName myuser@mytenant.onmicrosoft.com -Auth MFA -ReportType CSV

365Inspect can be run with only specified Inspector modules, or conversely, by excluding specified modules.

For example, to log in by entering your credentials in a browser with MFA support:

    .\365Inspect.ps1 -OutPath ..\365_report -UserPrincipalName myuser@mytenant.onmicrosoft.com -Auth MFA -SelectedInspectors inspector1, inspector2

or

    .\365Inspect.ps1 -OutPath ..\365_report -Auth MFA -ExcludedInspectors inspector1, inspector2, inspector3

To break down the parameters further:

When you execute 365Inspect with -Auth MFA, it may produce several graphical login prompts that you must sequentially log into. This is normal behavior as Exchange, SharePoint etc. have separate administration modules and each requires a different login session. If you simply log in the requested number of times, 365Inspect should begin to execute. This is the opposite of fun and we're seeking a workaround, but needless to say we feel the results are worth the minute spent looking at MFA codes.

</details>

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:

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!

Change Log

<details> <summary>Older Changes</summary>

Older Changes

</details>

Necessary Privileges

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

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.

<details> <summary>Prerequisite Preparation</summary>

For the most efficient use of time, it is recommended to perform the requisite functions in the following order:

  1. Prepare the client machine
    1. Client machine MUST be a Microsoft Windows OS
    2. Install required PowerShell modules listed in the Setup section above.
    3. Ensure proper access controls are in place
  2. Create the necessary certificate
    1. Create self-signed certificate for Azure Application authentication
  3. Create Azure Application
    1. Create the Service Principal
    2. Assign necessary rights to the application API permissions
    3. Assign the required roles to the application's Service Principal
      1. Global Administrator
      2. Exchange Administrator
      3. Teams Administrator
      4. SharePoint Administrator
    4. Upload certificate
    5. Document required information
  4. Acquire 365Inspect tool
    1. Download and extract the tool to the desired location on the client
</details>

See the following references:

Required Permissions

<details> <summary>Expand</summary>

Required Permissions

</details>

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:

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.

<details> <summary>Example .ps1 file, BypassingSafeAttachments.ps1:</summary> 
# Define a function that we will later invoke.
# 365Inspect's built-in modules all follow this pattern.
function Inspect-BypassingSafeAttachments {
	# Query some element of the O365 environment to inspect. Note that we did not have to authenticate to Exchange
	# to fetch these transport rules within this module; assume main 365Inspect harness has logged us in already.
	$safe_attachment_bypass_rules = (Get-TransportRule | Where { $_.SetHeaderName -eq "X-MS-Exchange-Organization-SkipSafeAttachmentProcessing" }).Identity
	
	# If some of the parsed O365 objects were found to have the security flaw this module is inspecting for,
	# return a list of strings representing those objects. This is what will end up as the "Affected Objects"
	# field in the report.
	If ($safe_attachment_bypass_rules.Count -ne 0) {
		return $safe_attachment_bypass_rules
	}
	
	# If none of the parsed O365 objects were found to have the security flaw this module is inspecting for,
	# returning $null indicates to 365Inspect that there were no findings for this module.
	return $null
}

# Return the results of invoking the inspector function.
return Inspect-BypassingSafeAttachments
</details> <details> <summary>Example .json file, BypassingSafeAttachments.json:</summary> 
{
    "FindingName": "Do Not Bypass the Safe Attachments Filter",
    "Description": "In Exchange, it is possible to create mail transport rules that bypass the Safe Attachments detection capability. The rules listed above bypass the Safe Attachments capability. Consider reviewing these rules, as bypassing the Safe Attachments capability even for a subset of senders could be considered insecure depending on the context or may be an indicator of compromise.",
    "Remediation": "Navigate to the Mail Flow &rarr; Rules screen in the Exchange Admin Center. Look for the offending rules and begin the process of assessing who created them and whether they are necessary to the continued function of the organization. If they are not, remove the rules.",
    "DefaultValue": "None",
    "ExpectedValue": "None",
    "Impact": "Critical",
    "AffectedObjects": "",
    "Service": "Exchange",  // Valid values are Exchange, SharePoint, Teams, Intune, AzureAD, SecurityandCompliance, Tenant //
    "PowerShell": "", // Any PowerShell remediation command examples should be placed here //
    "References": [
        {
            "Url": "https://docs.microsoft.com/en-us/exchange/security-and-compliance/mail-flow-rules/manage-mail-flow-rules",
            "Text": "Manage Mail Flow Rules in Exchange Online"
        },
        {
            "Url": "https://www.undocumented-features.com/2018/05/10/atp-safe-attachments-safe-links-and-anti-phishing-policies-or-all-the-policies-you-can-shake-a-stick-at/#Bypass_Safe_Attachments_Processing",
            "Text": "Undocumented Features: Safe Attachments, Safe Links, and Anti-Phishing Policies"
        }
    ]
}
</details>

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:

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!