Commands

The Maester PowerShell module has commands to connect to your tenant, run the checks, build reports and alerts, manage Maester Packs and write your own tests. Each page below is generated from the command’s help in the source.

To write your own tests with these commands, see Write your own tests.

Step 1 · Sign inConnect-MaesterHelper method to connect to Microsoft Graph using Connect-MgGraph with the required permission scopes as well as other services such as Azure, Exchange Online, and GitHub.PS> Connect-MaesterStep 2 · Run the checksInvoke-MaesterThis is the main Maester command that runs the tests and generates a report of the results.PS> Invoke-Maester

Connect15Run and write tests15Reports and alerts9Maester Packs8Automation setup4Entra and Microsoft Graph12Exchange and email9Azure and SharePoint4Active Directory3

Connect

Sign in to Microsoft 365, Azure, Active Directory and GitHub, and manage the session and its caches.

• Clear-MtADCacheResets the local cache of Active Directory data.
• Clear-MtConnectionStateNew in 3.0Preview 3.0Forgets the connection of a Maester Pack connector.
• Clear-MtDnsCacheResets the local cache of DNS lookups.
• Clear-MtExoCacheResets the local cache of Exchange Online queries.
• Clear-MtGraphCacheResets the local cache of Graph API calls.
• Connect-MaesterHelper method to connect to Microsoft Graph using Connect-MgGraph with the required permission scopes as well as other services such as Azure, Exchange Online, and GitHub.
• Connect-MtGitHubEstablishes a GitHub Enterprise Cloud organization REST API session for Maester.
• Disconnect-MaesterDisconnects the services connected through Connect-Maester.
• Disconnect-MtGitHubClears the current GitHub REST session in Maester.
• Get-MtConnectionStateNew in 3.0Preview 3.0Returns what a Maester Pack connector kept with Set-MtConnectionState, or nothing when it is not connected.
• Get-MtGraphScopeReturns the list of Graph scopes required to run Maester.
• Get-MtSessionGets the current Maester session information which includes the current Graph base uri and other details.
• Get-MtTenantContextNew in 3.0Preview 3.0Returns the facts about the connected tenant that decide which Maester tests apply.
• Set-MtConnectionStateNew in 3.0Preview 3.0Keeps the connection of a Maester Pack connector for the session, so its tests and Connect-Maester can find it.
• Test-MtConnectionChecks if the current session is connected to the specified service.

Run and write tests

Run the checks, find and write tests, and record what a test found.

• Add-MtAffectedObjectFactNew in 3.0Preview 3.0Adds facts about an object, such as its last sign-in or its expired secrets, to the Affected objects page.
• Add-MtReportAttachmentNew in 3.0Preview 3.0Embeds an HTML report from another tool, or data for a built-in report view, in the Maester HTML report.
• Add-MtTestResultDetailAdd detailed information about a test so that it can be displayed in the test results report.
• Compare-MtJsonObjectCompares two PowerShell objects (typically JSON objects) and returns a list of differences.
• Convert-MtTestNew in 3.0Preview 3.0Converts custom Pester-format Maester tests to the native format (Test.<ID>.ps1 and Test.<ID>.md).
• Get-MtSettingNew in 3.0Preview 3.0Returns a setting from GlobalSettings in the Maester config.
• Get-MtTestNew in 3.0Preview 3.0Lists Maester native tests and their metadata without connecting to a tenant.
• Get-MtTestInventoryDiscover Pester test inventory and associated tags.
• Install-MaesterTestsNot needed from Maester 3.0.
• Invoke-MaesterThis is the main Maester command that runs the tests and generates a report of the results.
• Invoke-MtTestNew in 3.0Preview 3.0Runs one or more Maester native tests through the engine and returns their result rows.
• New-MtTestNew in 3.0Preview 3.0Creates a new Maester native test: Test.<ID>.ps1 and Test.<ID>.md.
• Update-MaesterTestsRemoves copies of the built-in Maester tests from a folder.
• Write-MtTestOutputNew in 3.0Preview 3.0Shows the lines a long-running test writes while it works, live in the Maester console.
• Write-MtTestProgressNew in 3.0Preview 3.0Shows where a long-running test is (its stage, the items done, what it is working on and its errors) in the

Reports and alerts

Build, merge and compare reports, and send the results by email or to Teams.

• Compare-MtTestResultCompares Maester test result JSON files
• Convert-MtResultsToFlatObjectConvert Maester test results to a flattened object that can be exported to CSV or Excel.
• Get-MtAdminPortalUrlGet the URL for the specific Microsoft admin portal based on the environment.
• Get-MtHtmlReportGenerates a formatted html report using the MaesterResults object created by ConvertTo-MtMaesterResult
• Get-MtSafeMarkdownEscapes text to be safe to use in markdown.
• Import-MtMaesterResultImports Maester test result JSON files from disk into PowerShell objects.
• Merge-MtMaesterResultMerges multiple MaesterResults objects into a single multi-tenant result for combined HTML reporting.
• Send-MtMailSend an email with the summary of the Maester test results
• Send-MtTeamsMessageSend an adaptive card in a teams channel with the summary of the Maester test results

Maester Packs

Install, update and build packs of extra checks.

• Get-MtConnectorNew in 3.0Preview 3.0Lists the services that installed Maester Packs connect to, and whether each is connected.
• Get-MtPackNew in 3.0Preview 3.0Lists the Maester Packs this folder runs: those that ship with Maester and those in maester-packs.lock.json, with whether each can run.
• Install-MtPackNew in 3.0Preview 3.0Installs a Maester Pack: tests, helpers and connectors that someone else publishes, checked and pinned before anything runs.
• New-MtPackNew in 3.0Preview 3.0Creates a new Maester Pack folder: maester-pack.json, a suite with a first test, and optionally a connector.
• Restore-MtPackNew in 3.0Preview 3.0Installs exactly the packs and modules that maester-packs.lock.json records, on a new computer or in a pipeline.
• Test-MtPackNew in 3.0Preview 3.0Checks a Maester Pack folder the way Install-MtPack does, without installing it or running any of its code.
• Uninstall-MtPackNew in 3.0Preview 3.0Removes a Maester Pack from maester-packs.lock.json and the Maester config.
• Update-MtPackNew in 3.0Preview 3.0Updates installed Maester Packs to their newest release that has met the cooldown, showing what changed.

Automation setup

Create and update the app registration that runs Maester in a pipeline.

• Add-MtMaesterAppFederatedCredentialAdds a federated credential to a Maester application for GitHub Actions authentication.
• Get-MtMaesterAppRetrieves Maester applications from Azure AD/Entra ID.
• New-MtMaesterAppCreates a new Maester application in Entra ID with required permissions.
• Update-MtMaesterAppUpdates an existing Maester application with the latest required permissions.

Entra and Microsoft Graph

Read users, roles, groups, licences and Conditional Access from Microsoft Graph, for your own tests.

• Get-MtAuthenticationMethodPolicyConfigGet details of authentication methods
• Get-MtConditionalAccessPolicyReturns all the Conditional Access policies in the tenant.
• Get-MtGroupMemberReturns all the members of the specific group ID.
• Get-MtLicenseInformationGet license information for a Microsoft 365 product.
• Get-MtRoleReturns all the role definitions in the tenant.
• Get-MtRoleMemberReturns all the members of a role.
• Get-MtUserGet a list of users from the tenant
• Get-MtUserAuthenticationMethodGet the authentication methods for the specified user
• Get-MtUserAuthenticationMethodInfoByTypeReturns DisplayName and IsMfa metadata about a specific user authentication method type
• Invoke-MtGraphRequestEnhanced version of Invoke-MgGraphRequest that supports paging, batching and caching.
• Invoke-MtGraphSecurityQueryExecute KQL query in Microsoft 365 Defender Advanced Hunting by using Graph API Security endpoint to get results programmatically.
• Test-MtConditionalAccessWhatIfTests Conditional Access evaluation with What If for a given scenario.

Exchange and email

Read Exchange Online settings and check a domain’s SPF, DKIM, DMARC and MX records.

• ConvertFrom-MailAuthenticationRecordDkimReturns structured RFC compliant object from DKIM record
• ConvertFrom-MailAuthenticationRecordDmarcReturns structured RFC compliant object for a DMARC record
• ConvertFrom-MailAuthenticationRecordMxA simple wrapper for Resolve-DnsName
• ConvertFrom-MailAuthenticationRecordSpfReturns a structured RFC compliant object for the supplied SPF record
• Get-MailAuthenticationRecordObtains and converts the mail authentication records of a domain
• Get-MtExoRetrieves cached response or requests from cmdlet
• Get-MtExoThreatPolicyMalwareRetrieves cached and extended (priority, enabled) of 'Get-MtExo -Request MalwareFilterPolicy'
• Get-MtRegistrableDomainGet the registrable domain for a given domain name.
• Resolve-SPFRecordReturns a list of all IP addresses from an SPF record.

Azure and SharePoint

Call Azure Resource Manager and Resource Graph, and read SharePoint Online settings.

• Get-MtAzureManagementGroupReturns all Azure Management Groups in the tenant
• Get-MtSpoRetrieves SharePoint Online tenant settings via PnP with session caching.
• Invoke-MtAzureRequestInvoke a REST API request to the Azure Management API.
• Invoke-MtAzureResourceGraphRequestInvoke a query request to the Azure Resource Graph.

Active Directory

Read on-premises Active Directory state for the AD checks.

• Get-MtADDaclsCollects Active Directory ACLs (Access Control Lists).
• Get-MtADDomainStateCollects Active Directory domain state information.
• Get-MtADGpoStateCollects Active Directory Group Policy state information.