Writing a pack

Guided setup

To make a pack without writing the files by hand, use the guided setup at packs.maester.cloud/publish. It copies the demo pack into a repository of yours, or starts from an empty one, and fills in the manifest, the pack's Guide, its tests and its banner from a form. Then it releases the pack and publishes it. It writes the same files this page describes, so you can change any of them later by hand.

A pack is a folder with a maester-pack.json. Create one with New-MtPack:

New-MtPack -Path ./maester-google-workspace -Id contoso.google-workspace -Code CNT -Connector
Test-MtPack ./maester-google-workspace
Invoke-MtTest -Path ./maester-google-workspace

Invoke-MtTest -Path runs the pack from its folder, with its helpers and connector, and reloads it on every call. Test-MtPack runs every check Install-MtPack runs, without installing: use it in the pack's own CI.

maester-google-workspace/
  maester-pack.json
  README.md
  tests/
    suite.json
    Test.MP.CNT.1001.ps1
    Test.MP.CNT.1001.md
  helpers/
    Get-CntWorkspaceSetting.ps1
  connector/
    Connect-CntGoogleWorkspace.ps1

To share the pack, push the folder to a GitHub repository owned by the publisher and create a release. A release made immutable starts its cooldown when it is published; any other release starts it when each user first sees it. To have it listed where people look for packs, see Publishing your pack.

The manifest

{
  "$schema": "https://maester.dev/schemas/maester-pack-1.0.json",
  "Id": "contoso.google-workspace",
  "Name": "Google Workspace checks",
  "Description": "Checks the security settings of a Google Workspace tenant.",
  "Version": "1.2.0",
  "Publisher": "contoso",
  "License": "MIT",
  "RequiresMaester": ">=3.0",
  "Code": "CNT",
  "Suites": ["tests"],
  "Helpers": ["helpers"],
  "Connectors": [
    {
      "Service": "CNT.GoogleWorkspace",
      "DisplayName": "Google Workspace",
      "File": "connector/Connect-CntGoogleWorkspace.ps1",
      "Connect": "Connect-CntGoogleWorkspace",
      "Test": "Test-CntGoogleWorkspace",
      "Disconnect": "Disconnect-CntGoogleWorkspace"
    }
  ],
  "Uses": {
    "Services": ["CNT.GoogleWorkspace"],
    "GraphScopes": [],
    "TenantWrites": [],
    "Network": ["admin.googleapis.com", "oauth2.googleapis.com"],
    "Modules": [ { "Name": "GoogleWorkspaceTools", "Version": "1.4.2" } ]
  }
}

Key	Content
$schema	https://maester.dev/schemas/maester-pack-1.0.json, so editors such as VS Code check the manifest as you type. Maester checks it again when the pack is installed and loaded.
Id	<publisher>.<name> in lower case. The publisher is the GitHub user or organisation that owns the repository; a pack whose publisher is not the repository owner is refused.
Guid	Required. A GUID that identifies the pack for good, such as d1e2db80-6c27-4cb6-9389-2edf0a898d23; New-MtPack makes one. Keep it, and the code, for every version of the pack: Update-MtPack refuses a release whose Guid or code changed. A pack with a new code is a new pack, with a new Guid.
Version	A semantic version, such as 1.2.0.
RequiresMaester	The Maester versions the pack works with, such as >=3.0. Add an upper bound, such as >=3.0 <4.0, only if you know a later version breaks the pack. A pack that needs a newer Maester reports RequiresNewerMaester. New-MtPack fills in the version you made the pack with.
Code	The start of every test ID of the pack: CNT gives MP.CNT.1001. Two to ten letters or digits, starting with a letter. A publisher with several packs can group them with up to three parts separated by dots, such as CNT.GWS for MP.CNT.GWS.1001. No two installed packs may share a code, or have one code that starts with the other (CNT and CNT.GWS), so Install-MtPack refuses the second one. Any code is allowed, but pick one that the Maester Packs site does not list as claimed, so people can install your pack next to others.
Suites	Folders of native tests. Each needs a suite.json whose Id is the code or starts with it, such as CNT.GoogleWorkspace.
Helpers	Folders of .ps1 files that hold functions the tests call.
Connectors	Services the pack connects to (below).
Uses	What the pack reaches, shown when it is installed. An unknown key under Uses is an error, so a pack cannot hide what it reaches behind a key an older Maester does not show.
Uses.Modules	PowerShell Gallery modules, each pinned to one exact Version. Maester saves them into its own store and checks their files before every load. A module the user installs themselves can only be run in a separate process: { "Name": "X", "MinimumVersion": "2.0.0", "Install": "User", "Process": "Child" }.
Requires.Packs	Other packs this one needs: { "Id": "contoso.base", "Source": "contoso/maester-base", "Version": ">=1.0" }. They are installed first, with their own approval.
Exports	Functions of this pack that packs requiring it may call.
Pricing	Free (the default) or Paid, for a pack that needs a paid product or subscription to be useful. The pack index shows it; Maester does not act on it.
Banner	An image in the pack that the pack index shows when it features the pack. See Banner image.
Guide	A JSON file in the pack that says how to install, connect and run it, for its page on the pack index. See The pack page.
EnabledByDefault	For a pack that ships with Maester: false to leave it off until the config turns it on.

Banner image

A banner is optional. When the maintainers feature a pack on packs.maester.cloud, the card shows the banner beside the pack's description; without one, the card shows the pack's code and name on a dark background.

• File: .png, .jpg or .webp, at most 1 MB, inside the pack, for example "Banner": "assets/banner.png". The index reads the type from the file's contents, not its name, and SVG is refused. A banner that fails these checks is left out and the card falls back to the code and name.
• Size: 1200 × 630 pixels (the 1.91:1 shape of a social preview). Another size is cropped to fill that shape.
• Shown small: about 600 pixels wide on a desktop and 340 on a phone. Use at most eight words of text, set large, and keep it away from the edges.
• Your own brand. Use another company's logo only for a pack built on that company's product, and only with its permission. Don't add words such as "Official" or "Verified": the index shows its own badges, and a banner that suggests an endorsement it doesn't have can get the pack removed.
• No secrets or real data: a screenshot must not show a real tenant, user or key.

Making one with an AI image tool

Any image tool that takes a text prompt can make a banner. Image tools often misspell words, so check every letter, or ask for an image with no text and add the title yourself in an editor. Fill in the parts in angle brackets:

A wide banner image, 1200 x 630 pixels, for a software add-on called "<pack name>".
It checks the security settings of <service, for example Google Workspace> for IT administrators.
Style: clean, modern, flat illustration on a <dark navy / deep teal / near-black> gradient background,
with a simple abstract motif suggesting <what the pack checks, for example identity, email, devices>.
Text: the title "<pack name>" in large, bold, white sans-serif letters on the left,
and the line "<one short phrase, at most six words>" below it in smaller letters.
Leave a margin of at least 60 pixels on every side. No other text, no logos, no people,
no photos of screens, no badges or seals.

For an image without text, replace the Text: line with No text at all; leave the left half plain for a title.

The pack page

Every pack's page on packs.maester.cloud has the same sections: Install, Connect, Run, App-only, Tests, Security and Support. The index fills what it can from the manifest:

• the modules in Uses.Modules, with the line that installs each one;
• the Graph permissions in Uses.GraphScopes, which an app needs to run the pack app-only;
• the tests, with their products, from Suites (and Catalog for a family test that expands when it runs).

The rest comes from the Guide, a JSON file in the pack named by the manifest's Guide key, such as "Guide": "maester-pack.guide.json". Its schema is maester-pack-guide-1.0.json; add it as $schema so editors check the file as you type. Commands in it are shown as text and never run. A short example:

{
  "$schema": "https://maester.dev/schemas/maester-pack-guide-1.0.json",
  "Summary": "Checks the security settings of Google Workspace.",
  "Prerequisites": [{ "Text": "A Google Workspace super admin account." }],
  "Connect": { "Steps": [{ "Text": "Connect Maester, then sign in to Google when asked", "Command": "Connect-Maester" }] },
  "Run": {
    "Commands": [{ "Text": "Only this pack", "Command": "Invoke-Maester -Pack CNT -SkipBuiltIn" }],
    "Options": [{ "Name": "GoogleWorkspace.Customer", "Default": "my_customer", "Text": "The customer ID to read." }]
  },
  "AppOnly": { "Supported": true, "Methods": { "Certificate": true, "ClientSecret": true }, "Text": "Use a service account key." },
  "Screenshots": [{ "Path": "assets/report.png", "Caption": "The pack's results in the Maester report" }],
  "Support": { "Pack": "https://github.com/contoso/maester-google-workspace/issues" }
}

Maester checks that the Guide is a JSON object and that its screenshots (at most six) are .png, .jpg or .webp paths inside the pack. Like the banner, a screenshot that really is an image of at most 1 MB is not counted as binary content. Any section can end with "More": "<https link>" to your own documentation. The Zero Trust Assessment pack's guide is a full example.

Tests and helpers

A pack's tests are native tests with IDs MP.<Code>.<n>, or MP.<Code> for a family whose instances add their own part. (Packs that ship with Maester are part of it and drop the MP.: the Zero Trust Assessment pack's tests are ZTA.<n>.) Every .ps1 in a suite or helper folder holds only functions: code outside a function is refused, because it would run while the pack loads. A pack loads into a private module of its own, so its tests can call its helpers and Maester's exported commands. One pack does not see another pack's functions unless it requires that pack and the pack lists them in Exports. This keeps cooperating packs from colliding; it is not a security boundary, because code in the same PowerShell process can reach anything in it (see Pack security).

The scan flags, and raises the risk of, what a reviewer should look at: binary files, dynamic code (Invoke-Expression, [scriptblock]::Create), starting processes, requests to hosts that Uses.Network does not list, and module imports that Uses.Modules does not list.

Showing a long-running test's output and progress

A test that runs a tool for a long time, such as an assessment in another PowerShell process, can show the person running Maester what the tool is doing while it runs. In the full-screen dashboard both go into a box in the main column; in the compact layout, CI and redirected output they are written to the console, indented.

• Write-MtTestOutput shows the tool's log. -Title opens the box, each line scrolls into it, -Progress pins a changing line at the bottom, and -Complete closes it (Maester closes it when the test ends).
• Write-MtTestProgress shows where the tool is, as a header at the top of the box: the stage (-Stage, -StageNumber, -StageCount), a bar of the items done (-Completed, -Total, -Failed, -Running), what it is working on (-Current, -Status), and the errors it reported (-ErrorMessage), which the box also counts. With -Stages (the names of all the stages) the stages are drawn as a track, like the phases of a Maester run. With -Items (each with Id, and optionally Title, Status, Detail and Seconds) the box lists the items running and those that finished, with their result and time, the way the dashboard lists Maester's own tests; outside the dashboard each finished item is written once. Each call replaces the progress before it, so pass everything you know each time; a call with only -ErrorMessage keeps the progress.
• When the tool runs tests of its own, -Results (Passed, Failed, Error, Investigate, Skipped, Running, Total and optionally Name) and -Groups (the same counts with a Name each, such as the pillars of an assessment, with -GroupLabel 'Zero Trust Pillars') show them in the dashboard in place of Maester's own while the box is open: in the Results panel and the result blocks, and where the products are listed. The times of the items that finished go into the Pace graph next to the logo and the Slowest panel.

Write-MtTestOutput -Title 'Collecting the tenant data'
Write-MtTestProgress -Stage 'Exporting' -StageNumber 1 -StageCount 3 -Completed 12 -Total 40 -Running 2 -Current 'Users', 'Groups'
Write-MtTestProgress -ErrorMessage 'The export of Devices failed: Forbidden'

A tool in another process does not need to call Maester to report its progress. Pipe its output to Write-MtTestOutput, and have it write lines of this form to standard output, from any language:

##maester[progress] {"stages":["Export","Tests","Report"],"stageNumber":1,"stage":"Exporting","completed":12,"total":40,"failed":1,"items":[{"id":"Users","detail":"page 3","seconds":12},{"id":"Groups","status":"Passed","seconds":4.2}]}
##maester[progress] {"stage":"Running tests","results":{"passed":80,"failed":12,"running":4,"total":300},"groupLabel":"Zero Trust Pillars","groups":[{"name":"Identity","passed":50,"failed":8,"total":120}]}
##maester[error] The export of Devices failed: Forbidden

These lines set the header instead of showing in the log. The JSON object takes the names of the parameters of Write-MtTestProgress in any case (error for -ErrorMessage), and leaves out what it does not know. Write a progress line when something changes (at most a few times a second): each one is drawn. A line that cannot be read is dropped.

The Zero Trust Assessment pack is a worked example: its child process reads the progress the assessment keeps and the progress logs it writes, once a second, and writes these lines (see Invoke-MtZtaCollection in packs/zero-trust-assessment/tests/Test.ZTA.ps1).

Connectors

A connector adds a service to Maester. Its file holds a Connect and a Test function, and optionally Disconnect, Renew and Describe:

function Connect-CntGoogleWorkspace {
    [CmdletBinding()]
    param([string] $Domain, [string] $CredentialPath)

    $token = Get-CntAccessToken -Domain $Domain -CredentialPath $CredentialPath
    Set-MtConnectionState -Value @{ Token = $token.AccessToken; ExpiresOn = $token.ExpiresOn } -Tenant $Domain
}

function Test-CntGoogleWorkspace {
    [CmdletBinding()]
    [OutputType([bool])]
    param()
    [bool](Get-MtConnectionState)
}

• Connect-Maester -Service CNT.GoogleWorkspace calls Connect with the parameters it has from -ServiceSetting, MAESTER_CNT_GOOGLEWORKSPACE_<PARAMETER> and Connections.CNT.GoogleWorkspace in the config.
• Set-MtConnectionState keeps what the tests need for the PowerShell session only; Get-MtConnectionState reads it back in a test or helper. A pack can read its own connection and those of packs it requires, never another pack's.
• Test decides whether the tests that need the service run. With ExpiresOn in the state, Maester calls Renew shortly before it expires.
• The service name is <Code>.<Name>. Tests declare it like any service: Service = 'CNT.GoogleWorkspace'. "OptIn": true makes its tests not run, rather than skipped, while it is not connected.

Publishing your pack

Once the pack has a release, anyone can install it from its repository with Install-MtPack <owner>/<repo>. To help people find it, list it on a pack index: a site that collects packs, checks them and shows each one's page. An index only lists a pack. People still install it straight from your repository, and Maester runs the same checks at install whichever site they found it on.

Maester Packs

packs.maester.cloud is the index the Maester team runs. To list a pack there:

1. Go to packs.maester.cloud/publish and choose Yes, I have a pack repository.
2. Sign in with GitHub as an admin of the repository. The repository must be public; private and internal repositories are never listed.
3. Pick the repository, and the folder if the pack is not at its root, then press Check. It reads the latest release and its maester-pack.json, and says what to fix.
4. Press Publish. The site registers the pack's Guid and Code to the repository's owner, so nobody else can publish a pack with them, and queues the pack.

Within about ten minutes the index runs Test-MtPack's checks and its security scan on the release and lists the pack, with its page at /p/<code>. If the pack is not listed, its status page at /status/<owner>/<repo> says why and what to fix. Every later release is picked up on its own, so you publish only once. My Packs on the site shows your packs and how many tenants run them, and lets you hide one from the site for a while.