Maester Documentation

Maester v1 introduced significant expansions to the testing framework, including:

• Expanded Test Suite: Increased from 96 to 194 tests, including CISA and CIS benchmark tests.
• Entra ID Security: Enhanced security configuration analysis for Entra ID (formerly Azure AD).
• Microsoft Teams Tests: New tests for Microsoft Teams meeting policies.
• Improved Reporting: Enhanced Pester test reports with support for filtering and tags.
• Improved Installation: A more robust test folder installation and update process.

The Maester PowerShell module provides a collection of commands designed to help you write Pester tests for validating Microsoft 365 tenant configurations. These commands abstract complex Graph API calls into simple PowerShell cmdlets.

To understand the underlying logic of a command, you can inspect the Graph API calls in the Maester GitHub repository's src folder. For specific command implementation details, use the Edit this page link within the individual command's documentation to view its source code.

The Maester repository is organized into several key top-level directories that separate the core framework, user-facing security suites, and supporting infrastructure:

• powershell/: Contains the core Maester module source code (e.g., Maester.psd1, Maester.psm1).
• tests/: Contains the Maester security check suites intended for end-users to run (not module unit tests).
• build/: Contains scripts for building, publishing, and generating suites.
• report/: The source for the Maester report application (Vite + React + Tailwind).
• website/: The Docusaurus 3 site for documentation.
• tools/: Contains user-facing utility scripts like Save-MaesterOffline.ps1.
• action/: (Deprecated) Legacy GitHub action files; the current action is located in maester365/maester-action.

Maester supports multi-tenant reporting, allowing you to run security tests across multiple Microsoft 365 tenants and consolidate the results into a single report.

Key capabilities include:

• Single Pipeline Run: Execute tests for multiple tenants in one pipeline execution.
• Tenant Selector: Switch between tenants using a sidebar within the single report (the selector only appears when multiple tenants are present).
• Full Feature Parity: Each tenant gets its own full dashboard, charts, and filters.
• Isolated Permissions: Each tenant uses its own service connection with read-only permissions.
• Tenant-Specific Configuration: You can provide unique configurations for each tenant using the maester-config.{TenantId}.json pattern.

The Test-MtEntitlementManagementDeletedGroups test identifies Microsoft Entra ID Governance access packages and catalogs that contain references to deleted Entra ID groups.

Deleted group references are problematic because they can cause:

• Access provisioning failures
• Broken approval workflows
• Compliance violations

What the test validates:

• Access Package Resources: Ensures groups assigned as resources in access packages still exist.
• Assignment Policy Approvers: Ensures groups configured as approvers in assignment policies are active.
• Catalog Registration: Ensures groups registered in catalogs have not been deleted.

When a deleted group is found, the test attempts to retrieve the group name from the Entra ID recycle bin (directory/deletedItems) to assist in identification.

The Maester project is organized as a PowerShell module. The core functionality is exposed through a public interface, while internal logic is encapsulated in a separate directory.

• Public Interface: End users interact with the module through scripts and functions located in the public/ directory, most notably the Invoke-Maester cmdlet.
• Module Files: The module is defined by two primary files at the root of the PowerShell directory:
  • Maester.psd1: The module manifest containing metadata (version, author, dependencies).
  • Maester.psm1: The module script containing the actual implementation of functions and cmdlets.

The recommended architectural pattern for generating multi-tenant reports is to follow this pipeline sequence:

1. Load: Import-MtMaesterResult (to load files) OR Invoke-Maester -PassThru (to get in-memory objects).
2. Process: Merge-MtMaesterResult (to combine results into a multi-tenant object).
3. Generate: Get-MtHtmlReport (to create the HTML content).
4. Save: Out-File (to write the report to disk).

While Merge-MtMaesterResult provides a -Path parameter as a convenience to skip the explicit Import-MtMaesterResult step, the full pipeline is more explicit for complex workflows.

To run security configuration checks, the Maester workload identity used by Azure DevOps requires specific Microsoft Graph permissions.

Required Permissions:

• Standard Graph permissions for tenant security checks.

Optional Permissions (for advanced tests):

• Privileged permissions for deeper inspection.

Entra Tenant Roles Required for Setup: To consent to these permissions, you must hold one of the following combinations in your Entra tenant:

• Global Administrator
• Privileged Role Administrator AND Application Administrator

The Maester website operates in two distinct environments to manage documentation updates:

• Production (https://maester.dev): The live site. It is updated only when a new version of the Maester module is released. It tracks the website-prod branch.
• Preview (https://preview.maester.dev): The development site. It is updated with every commit to the main branch, allowing you to see changes before they are officially released.