Skip to main content
Version: 3.0.0-preview

Installation guide

Maester needs PowerShell 7.4 or later on Windows, Linux or macOS. Windows PowerShell 5.1 is not supported.

  • Install the Maester PowerShell module and prepare a folder for your configuration and custom tests.
Install-Module Maester -Scope CurrentUser

md maester-tests
cd maester-tests
Install-MaesterTests

The built-in tests ship inside the module, so Install-MaesterTests does not copy any tests. It creates a custom folder for your own tests and a starter maester-config.json.

  • Sign into your Microsoft 365 tenant and run the tests.
Connect-Maester
Invoke-Maester
Pester

Maester 3.0 does not need Pester. Install it only if you have custom tests written in the Pester format (*.Tests.ps1), see Pester-format tests:

Install-Module Pester -MinimumVersion 5.7.1 -SkipPublisherCheck -Force -Scope CurrentUser

Upgrading from Maester 2.x? See Upgrading from 2.x.

Invoke-Maester​

To learn more about the Invoke-Maester cmdlet including how to filter tests, see the Invoke-Maester documentation and the run configuration reference.

Optional modules and permissions​

Maester includes optional CISA tests that require additional permissions and modules to run. These optional tests are skipped if the modules are not installed or there is no active connection.

Also see Create-entra-app

Installing Azure, Exchange Online, Teams and PnP.PowerShell modules​

Install-Module Az.Accounts, ExchangeOnlineManagement, MicrosoftTeams, PnP.PowerShell -Scope CurrentUser

The Security & Compliance PowerShell module is dependent on the ExchangeOnlineManagement Connect-IPPSSession cmdlet.

Connecting to Azure, Exchange, and other services​

In order to run all the CISA tests, you need to connect to the Azure, Exchange Online, and other modules.

For a more detailed introduction to these concepts see the Connect-Maester documentation.

Run the following command to interactively connect to the Azure, Microsoft Graph, Exchange Online, and other modules. A sign-in window will appear for each module.

Connect-Maester -Service All

Connecting to GitHub​

GitHub is an optional connection for GitHub security tests and is not included in Connect-Maester -Service All. For interactive sessions, use the Maester GitHub App OAuth flow:

Connect-Maester -Service Graph,GitHub -GitHubOrganization '<github-organization>'

See Connect to GitHub (optional) for GitHub App install/approval details and token-based automation options.

Permissions​

Exchange Online implements a role-based access control model. The controls these cmdlets test require minimum roles of either of the following:

  • View-Only Configuration OR
  • O365SupportViewConfig

Installing Azure DevOps PowerShell module​

Install-Module ADOPS -Scope CurrentUser

Connecting to Azure DevOps​

In order to run all the Azure DevOps tests, you need to connect to Azure DevOps.

This is currently not included as part of Connect-Maester and must be called separately. Run the following command to interactively connect using the Azure DevOps modules. A sign-in window will appear.

Example with PowerShell variable

$AdoPSAllowInsecureAPIs = $true
Import-Module ADOPS
Connect-ADOPS -Organization <Name Of DevOps Organization>

Example with ArgumentList

Import-Module ADOPS -ArgumentList $true
Connect-ADOPS -Organization <Name Of DevOps Organization>

Note: Some of the API endpoints used for Azure DevOps tests use unsupported endpoints. To allow usage of unsupported endpoints, you must set $true in the argumentlist when importing the module, or set a PowerShell variable called "$AdoPSAllowInsecureAPIs" to $true before importing the module. Reference: https://github.com/AZDOPS/AZDOPS/issues/248

Permissions​

Azure DevOps implements a role-based access control model. The controls these cmdlets test require the minimum role of:

  • Project-Scoped Users at Organization level

Next Steps​