# Getting started

Your first Maester run, how to read the report, and how to go from a one-off check to continuous monitoring.

Source: https://maester.dev/docs/getting-started

# 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](connect-maester/readme.md#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:

<InstallCommand />

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

<Tabs syncKey="first-run">
<TabItem label="Quick check">

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

```powershell
Connect-Maester
Invoke-Maester
```

</TabItem>
<TabItem label="Comprehensive check">

Maester's built-in checks plus Microsoft's [Zero Trust Assessment](packs/zero-trust-assessment.md), 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.

```powershell
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](packs/zero-trust-assessment.md#run-it).

</TabItem>
</Tabs>

## 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](configuration/severity-levels.md)).
   To run only those tests:

   ```powershell
   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:

```json
{
  "GlobalSettings": {
    "EmergencyAccessAccounts": [
      { "Type": "User", "UserPrincipalName": "BreakGlass1@contoso.com" }
    ]
  }
}
```

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

```powershell
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:

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

See [Configure Maester](configuration/overview.md) and [Emergency access accounts](configuration/emergency-access-accounts.md).

## 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](choosing-a-baseline.md).

## 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](monitoring/readme.mdx).
2. Send the results to the people who act on them by email, Teams or Slack. See [Maester alerts](alerts/readme.mdx).
3. Export results for a ticketing system or a spreadsheet. See [Exporting results](export-results.md).

## 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](writing-tests/index.mdx) 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](making-the-case.mdx).
- Questions? See the [FAQ](faq.md).