Getting started

This page takes you from nothing to a first report in about fifteen minutes, then shows the steps most teams take over the following weeks. Each step links to the full guide.

Before you start

• PowerShell 7.4 or later on Windows, Linux or macOS.
• An account that can read your tenant’s configuration. Global Reader is the usual choice. The first time you connect, an admin may need to consent to the Microsoft Graph permissions Maester asks for (see Approval required when connecting).

By default Maester asks only for read permissions. It does not change anything in your tenant.

Step 1: Run your first report

Install Maester:

PS>Install-Module Maester -AllowPrereleaseInstall-Module MaesterCopy

Installs the 3.0 preview, which these docs describe. About the previewInstalls the stable release, 2.3.0. 2.x docs

Then pick one of these runs. Either way you get one report.

Quick check

Maester’s built-in checks, in a few minutes:

Connect-Maester
Invoke-Maester

Comprehensive check

Maester’s built-in checks plus Microsoft’s Zero Trust Assessment, for the most complete picture of your tenant. The assessment’s results appear in the same report, grouped by Zero Trust pillar and next to the Maester checks for the same product and area.

Install-Module ZeroTrustAssessment -Scope CurrentUser
Connect-Maester
Invoke-Maester -Pack ZTA

The assessment needs PowerShell 7.6 or later and asks you to sign in a second time, in the browser. It can take an hour or more on a large tenant. To include it in every run, see Run it.

Step 2: Read the report

When the run finishes, Maester writes an HTML report to the ./test-results folder and, in an interactive session, opens it. Every test appears with one of these results:

Result	What it means
Passed	The setting matches what the test expects.
Failed	The setting does not match. The test explains why and how to fix it.
Investigate	Maester found something a person should look at; it cannot decide on its own.
Skipped	The test did not run, for example because a service is not connected, a licence is missing or a permission was not granted.
Error	The test could not finish, for example because a service returned an unexpected error.
Not run	The test was left out of this run, for example because your configuration turned it off. The reason is shown.

Each failed test links to its own page on this site, with the background, the fix and the references.

Step 3: Fix what matters first

A first report usually has many failures. Do not try to fix them all at once.

1. Sort by severity. Start with Critical and High (see Severity levels). To run only those tests:

   Invoke-Maester -Severity Critical, High

2. Look for quick wins. Each test says how much its fix affects users and how much effort it takes. A failure with high severity, low user impact and low cost is the best place to start. In an interactive run, the Fix first panel lists these failures for you.

3. Record what you accept. Some failures are deliberate decisions. Turn those tests off in your configuration with a reason, so the report shows them as Not run with your reason instead of as failures (see the next step).

Step 4: Tell Maester about your tenant

Create a folder for your Maester settings and a maester-config.json in it. The most important setting is your emergency access (break glass) accounts, which many Conditional Access tests depend on:

{
  "GlobalSettings": {
    "EmergencyAccessAccounts": [
      { "Type": "User", "UserPrincipalName": "[email protected]" }
    ]
  }
}

Then run Maester from that folder, or pass it with -Path:

Invoke-Maester -Path ./maester

When you have decided to accept a failure, add a TestSettings row for that test with your reason. Add one only for a decision that has been made, because the test then stops checking that setting:

{
  "TestSettings": [
    { "Id": "<test ID>", "Enabled": false, "Reason": "<the decision and where it is recorded, for example RISK-042>" }
  ]
}

See Configure Maester and Emergency access accounts.

Step 5: Choose your baseline

Maester ships several suites: its own tests and the CIS, CISA, ASD Essential Eight, DISA STIG, EIDSCA and ORCA suites, plus the Zero Trust Assessment pack. Pick the ones that match the requirements your organisation has to meet. See Choosing a baseline.

Step 6: Monitor continuously

A single report shows where you stand today. The value of Maester comes from running it every day, so that a change that weakens your security is caught within a day instead of at the next audit.

1. Run Maester on a schedule from a pipeline or an Azure service. See Monitoring with Maester.
2. Send the results to the people who act on them by email, Teams or Slack. See Maester alerts.
3. Export results for a ticketing system or a spreadsheet. See Exporting results.

Step 7: Add your own tests

The built-in tests check widely recommended settings. Your organisation also has its own rules: a group that must always be in a policy, a named location that must exist, an app that must never get more permissions. Write those rules as custom tests and Maester checks them on every run alongside the built-in ones.

Next steps

• Need support from leadership to roll this out? See Making the case for Maester.
• Questions? See the FAQ.