365Inspect: automates the security assessment of Microsoft Office 365 environments

365Inspect

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

Use

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:

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

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:

or

To break down the parameters further:

• OrgName is the name of the core organization or “company” of your O365 instance, which will be inspected.
  • If you do not know your organization name, you can navigate to the list of all Exchange domains in O365. The topmost domain should be named domain_name.onmicrosoft.com. In that example, domain_name is your organization name and should be used when executing 365Inspect.
• OutPath is the path to a folder where the report generated by 365Inspect will be placed.
• Auth is a selector that should be one of the literal values “MFA”, “CMDLINE”, or “ALREADY_AUTHED”.
  • Auth controls how 365Inspect will authenticate to all of the Office 365 services.
  • Auth MFA will produce a graphical popup in which you can type your credentials and even enter an MFA code for MFA-enabled accounts.
  • Auth ALREADY_AUTHED instructs 365Inspect not to authenticate before scanning. This may be preferable if you are executing 365Inspect from a PowerShell prompt where you already have valid sessions for all of the described services, such as one where you have already executed 365Inspect.
• SelectedInspectors is the name or names of the inspector or inspectors you wish to run with 365Inspect. If multiple inspectors are selected they must be comma-separated. Only the named inspectors will be run.
• ExcludedInspectors is the name or names of the inspector or inspectors you wish to prevent from running with 365Inspect. If multiple inspectors are selected they must be comma-separated. All modules other included modules will be run.

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.

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 three items of note:

• Report.html: a 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.

Install

Copyright (c) 2021 Soteria