import React, { useCallback, useContext, useEffect, useMemo, useRef, useState } from "react";
import { createPortal } from "react-dom";
import Link from "@site/src/react/shims/Link.jsx";
import data from "@site/src/data/test-builder.json";
import Markdown, { firstTable } from "./Markdown";
import { NEW, emptyState, exampleState, functionNameFor, validate, buildPs1, buildMd, buildCommand, folderFor, addByHand, registryChanges, withPrefix, splitList, stateFromTest, parsePermission, PARAMETER_TYPES, emptyParameter, parameterForSetting, resolveParameter, settingOf, buildConfigExample, scaffoldedSettings } from "./generate";
import { AttributeIcon, Badge, Button, Checkbox, Combobox, DeleteIcon, Flag, HelpButton, LevelIcon, OptionIcon, PlusIcon, osGlyph, Input, RadioCards, RadioPills, Select, Sheet, Tabs, TabsContent } from "./ui";
import GitHubPeople from "./GitHubPeople";
import { fieldHelp } from "./help";
import LicenseExplorer, { indexCatalog, planLabel } from "./LicenseExplorer";
import styles from "./styles.module.css";
import { productIcon, productInitials, featureIcon } from "../../lib/report-icons.mjs";
const REPO = "https://github.com/maester365/maester/blob/main/";
const tacticName = Object.fromEntries(data.attack.tactics.map((t) => [t.id, t.name]));
const techniqueById = Object.fromEntries(data.attack.techniques.map((t) => [t.id, t]));
const PREFIX_KEY = "maester.testBuilder.customPrefix";
// Requirements of the frameworks in the repository, and the controls they relate to.
const requirementItems = data.frameworks.flatMap((f) =>
f.requirements.map((r) => {
const detail = [f.name, r.level, r.criticality, r.tests.length ? "implemented by " + r.tests.join(", ") : "no test yet"].filter(Boolean).join(" · ");
return { value: f.key + ":" + r.id, label: f.key + ":" + r.id, hint: detail, search: (f.key + ":" + r.id + " " + detail).toLowerCase() };
})
);
const relatedItems = [...new Set(data.frameworks.flatMap((f) => f.requirements.flatMap((r) => r.related || [])))].sort().map((c) => ({ value: c, label: c, hint: "Related to requirements in the repository" }));
const nistItems = data.nist.controls.map((c) => ({ value: data.nist.key + ":" + c.id, label: data.nist.key + ":" + c.id, hint: c.title, search: (data.nist.key + ":" + c.id + " " + c.title).toLowerCase() }));
const nistValues = new Set(nistItems.map((i) => i.value));
const controlItems = requirementItems.concat(nistItems, relatedItems.filter((i) => !nistValues.has(i.value)));
const knownLicenses = new Set(data.licenses);
const attackUrl = (id) => "https://attack.mitre.org/techniques/" + id.replace(".", "/") + "/";
function RepoFile({ path }) {
return (
{path}
);
}
// Only one help panel is open at a time; this holds the id of the field it belongs to.
const HelpContext = React.createContext({ openId: null, setOpenId: () => {} });
// With the form and the code side by side, the help panel covers the code column and leaves the form in view.
// In one column it slides in at the right edge of the window.
function useDock(open) {
const [place, setPlace] = useState(undefined);
useEffect(() => {
if (!open) return undefined;
const measure = () => {
const dock = document.querySelector("[data-help-dock]");
const form = dock && dock.previousElementSibling;
if (!dock || !form) return setPlace(undefined);
const side = dock.getBoundingClientRect().left > form.getBoundingClientRect().right;
setPlace(side ? { left: Math.max(0, dock.getBoundingClientRect().left - 12), width: "auto" } : undefined);
};
measure();
window.addEventListener("resize", measure);
return () => window.removeEventListener("resize", measure);
}, [open]);
return place;
}
// Links to the guides open in the help panel on this page, so the form stays in view while you read them: the
// sidebar's guides, links in the page and the builder, and links in a field's help. Links to other guides inside
// a guide open there too; anything else opens in a new tab.
const SIDEBAR_LINKS = "#starlight__sidebar ul.top-level a[href]";
const PAGE_LINKS = "main a[href]:not([target]), [data-help-sheet] a[href]:not([target])";
const isGuide = (url) => url.origin === window.location.origin && url.pathname.startsWith("/docs/");
const plainClick = (e) => e.button === 0 && !e.metaKey && !e.ctrlKey && !e.shiftKey && !e.altKey && !e.defaultPrevented;
function useGuides(setOpenId) {
const [guide, setGuide] = useState(null);
const latest = useRef(null);
const openGuide = useCallback(
(href) => {
const url = new URL(href, window.location.href);
latest.current = url.href;
setGuide((g) => ({ href: url.href, title: g && g.href === url.href ? g.title : "Loading…", html: null, error: false }));
setOpenId("guide");
fetch(url.pathname)
.then((r) => (r.ok ? r.text() : Promise.reject(new Error(r.status))))
.then((text) => {
if (latest.current !== url.href) return;
const page = new DOMParser().parseFromString(text, "text/html");
const content = page.querySelector(".sl-markdown-content");
if (!content) throw new Error("No content");
// The styles and scripts a guide's components bring (code blocks bring their own) load once into this page.
content.querySelectorAll('link[rel="stylesheet"], script[src]').forEach((el) => {
const isLink = el.tagName === "LINK";
const src = new URL(el.getAttribute(isLink ? "href" : "src"), url).pathname;
if (!document.head.querySelector(isLink ? 'link[href="' + src + '"]' : 'script[src="' + src + '"]')) {
const copy = document.createElement(isLink ? "link" : "script");
if (isLink) {
copy.rel = "stylesheet";
copy.href = src;
} else {
copy.type = "module";
copy.src = src;
}
document.head.appendChild(copy);
}
el.remove();
});
content.querySelectorAll("a[href], img[src]").forEach((el) => {
const attr = el.tagName === "A" ? "href" : "src";
const raw = el.getAttribute(attr);
if (raw.startsWith("#")) return;
const target = new URL(raw, url);
el.setAttribute(attr, target.origin === window.location.origin ? target.pathname + target.search + target.hash : target.href);
if (attr === "href" && !isGuide(target)) {
el.setAttribute("target", "_blank");
el.setAttribute("rel", "noreferrer");
}
});
const h1 = page.querySelector("h1");
setGuide({ href: url.href, title: h1 ? h1.textContent.trim() : url.pathname, html: content.innerHTML, error: false });
})
.catch(() => latest.current === url.href && setGuide((g) => ({ ...g, title: "Could not load the guide", error: true })));
},
[setOpenId]
);
// Sidebar links only while the sidebar is shown beside the page (Starlight's 50rem breakpoint); below that it is
// a menu over the page, and a guide opens as a page of its own.
useEffect(() => {
const onClick = (e) => {
if (!plainClick(e) || !e.target.closest) return;
const a = (window.matchMedia("(min-width: 50rem)").matches && e.target.closest(SIDEBAR_LINKS)) || e.target.closest(PAGE_LINKS);
if (!a) return;
const url = new URL(a.href, window.location.href);
if (!isGuide(url)) return;
e.preventDefault();
openGuide(url.href);
};
document.addEventListener("click", onClick);
return () => document.removeEventListener("click", onClick);
}, [openGuide]);
return [guide, openGuide];
}
function GuidePanel({ guide, open, onClose, openGuide }) {
const place = useDock(open);
const body = useRef(null);
useEffect(() => {
// A new guide starts at the top of the panel.
if (body.current && body.current.parentElement) body.current.parentElement.scrollTop = 0;
}, [guide]);
const onClick = (e) => {
const a = e.target.closest && e.target.closest("a[href]");
if (!a || !plainClick(e)) return;
const raw = a.getAttribute("href");
if (raw.startsWith("#")) {
e.preventDefault();
const target = body.current && body.current.querySelector("#" + CSS.escape(decodeURIComponent(raw.slice(1))));
if (target) target.scrollIntoView({ behavior: "smooth", block: "start" });
return;
}
const url = new URL(a.href, window.location.href);
if (isGuide(url) && url.pathname !== window.location.pathname) {
e.preventDefault();
openGuide(url.href);
}
};
return (
!o && onClose()}
title={guide ? guide.title : ""}
style={place}
actions={
guide && (
)
}
>
{guide && guide.error &&
The guide could not be loaded. Open it in a new tab instead.
}
{guide && !guide.error && !guide.html &&
Loading…
}
{guide && guide.html && }
);
}
// A help panel and the button that opens it. The panel is rendered by the field itself, so it follows the form's state.
function Help({ id, title, badge, label, children }) {
const { openId, setOpenId } = useContext(HelpContext);
const open = openId === id;
const place = useDock(open);
return (
<>
setOpenId(open ? null : id)}>
{label}
!o && setOpenId(null)} title={title} badge={badge} style={place}>
{children}
>
);
}
// A form field. The input and any problems are shown inline; what the attribute means, the rubric and how to
// add a missing value open in the help panel, so the form stays short.
function Field({ id, name, label, required, hint, guide, rubric, rubricTitle, notInList, problems, children }) {
const mine = problems.filter((p) => p.field === id);
const { builtin } = useContext(HelpContext);
const extra = fieldHelp(id, builtin);
const hasHelp = hint || guide || rubric || notInList || extra;
return (
Bound to the setting {setting.name}, which an administrator sets once in GlobalSettings. The settings registry gives it its type
{p.default ? ", its default (" + p.default + ")" : ""}
{p.allowedValues.length ? " and its allowed values (" + p.allowedValues.join(", ") + ")" : ""}.
) : (
<>
{raw.type === "switch" ? (
A switch is off by default. Name it after what turning it on does.
{used.tests} built-in {used.tests === 1 ? "test uses" : "tests use"} {used.name}. Reuse the name only if it means the same thing here.
)}
);
})}
);
}
// Permission: each box is one thing the test needs (all of them); the permissions inside a box are alternatives
// (any one of them), least privileged first.
function PermissionBuilder({ groups, services, onChange }) {
const registry = services.length ? data.services.filter((s) => services.includes(s.name)) : data.services;
const [draft, setDraft] = useState({});
const shown = groups.length ? groups : [[]];
const update = (index, values) => onChange(shown.map((g, i) => (i === index ? values : g)));
const filled = shown.filter((g) => g.length);
const draftFor = (index) => {
const d = draft[index] || {};
const service = registry.find((s) => s.name === d.service) || registry[0];
const kind = (service && service.permissionKinds.find((k) => k.kind === d.kind)) || (service && service.permissionKinds[0]);
return { service, kind, name: d.name || "" };
};
const setDraftFor = (index, patch) => setDraft((all) => ({ ...all, [index]: { ...(all[index] || {}), ...patch } }));
const describe = (text) => {
const p = parsePermission(text);
if (!p) return text;
const service = data.services.find((s) => s.name === p.service);
const kind = service && service.permissionKinds.find((k) => k.kind === p.kind);
return kind ? kind.description : null;
};
return (
Each box is one thing the test needs, and the test needs all of them. Permissions inside one box are alternatives: any one of them is enough. Put the least privileged one first.
The identity Maester signs in with needs {filled.map((g, i) => (
{i > 0 && and }
{filled.length > 1 && g.length > 1 && "("}
{g.map((text) => (parsePermission(text) || { name: text }).name).join(" or ")}
{filled.length > 1 && g.length > 1 && ")"}
))}
. Maester records this on the result; it does not skip the test on it yet.
)}
);
}
function LicenseBuilder({ groups, onChange }) {
const [catalog, setCatalog] = useState(null);
const [exploring, setExploring] = useState(null);
useEffect(() => {
let live = true;
import("@site/src/data/license-service-plans.json").then((m) => live && setCatalog(indexCatalog(m.default || m)));
return () => {
live = false;
};
}, []);
const items = useMemo(() => {
if (!catalog) return [];
return catalog.plans.map((plan) => ({
value: plan.name,
label: planLabel(plan),
plan,
hint: productSummary(plan.products),
primary: plan.search,
weight: plan.products.length,
search: plan.search + " " + plan.products.map((p) => p.search).join(" "),
}));
}, [catalog]);
// When the search text matched a product, not the plan itself, name that product first.
const hintFor = (item, q) => {
if (!q || item.primary.includes(q)) return item.hint;
const product = item.plan.products.find((p) => p.search.includes(q));
return product ? "In " + product.name + " (" + product.stringId + ")" + (item.plan.products.length > 1 ? " and " + (item.plan.products.length - 1) + " more" : "") : item.hint;
};
const shown = groups.length ? groups : [[]];
const update = (index, plans) => onChange(shown.map((g, i) => (i === index ? plans : g)));
const known = (name) => catalog && catalog.planByName[name];
const label = (name) => (known(name) ? planLabel(known(name)) : name);
const filled = shown.filter((g) => g.length);
return (
A test requires service plans, the building blocks inside a product such as Microsoft 365 E5. Plans inside one box are joined with and: the tenant needs all of them. Boxes are joined with or: any one box is enough.
{shown.map((group, index) => (
{index > 0 &&
or
}
{group.length > 0 && (
{group.map((name, n) => (
{n > 0 && and }
{label(name)}
{catalog && !known(name) && · not on Microsoft's list; matched as written}
{known(name) && · {productSummary(known(name).products)}}
{knownLicenses.has(name) && · Maester also counts its government and education variants}
);
}
// The icon beside each field's label and each step. An attribute the report shows has the report's icon.
const FIELD_ICONS = {
suite: "source", prefix: "tag", id: "id", title: "title", functionName: "code",
product: "product", feature: "feature", relatedProducts: "related", area: "area", resourceType: "resource",
severity: "severity", userImpact: "impact", implementationCost: "effort",
mitre: "attack", control: "framework",
services: "service", license: "licence", permission: "permission",
tenantType: "tenant", cloud: "cloud", platform: "platform",
parameters: "params",
lifecycle: "lifecycle", replacedBy: "related", flags: "duration", author: "person", contributor: "impact", tags: "tag",
};
const STEP_ICONS = { start: "person", name: "id", about: "product", priority: "severity", mapping: "framework", services: "service", licences: "licence", permissions: "permission", environment: "cloud", parameters: "params", lifecycle: "lifecycle" };
const LIFECYCLE_ICONS = { Preview: ["preview", "info"], Stable: ["stable", "ok"], Deprecated: ["deprecated", "low"] };
// Services show the icon of the product they connect to. Microsoft Graph has no icon of its own in the set, so it
// shows Microsoft 365's; Dataverse has none either and shows its initials.
const SERVICE_PRODUCT = { ActiveDirectory: "ad", Azure: "azure", AzureDevOps: "azure-devops", ExchangeOnline: "exchange", GitHub: "github", Graph: "microsoft-365", SecurityCompliance: "purview", SharePointOnline: "sharepoint", Teams: "teams" };
const serviceIconOf = (name) => (SERVICE_PRODUCT[name] && productIcon(SERVICE_PRODUCT[name]) ? { icon: productIcon(SERVICE_PRODUCT[name]) } : { initials: name.slice(0, 2) });
// Tenant types: the value written to the attribute stays Workforce or External; the label says what External
// means. Workforce shows the Entra ID icon the report uses. External shows Microsoft's External ID icon
// (public/img/icons/external-id.svg, from https://az-icons.com/icon/external-id-modified, unchanged).
const TENANT_TYPES = {
Workforce: { label: "Workforce", icon: productIcon("entra") },
External: { label: "External (Consumer)", icon: "/img/icons/external-id.svg" },
};
// Clouds: the country whose cloud it is, shown as a flag. Commercial is the worldwide cloud and shows a globe.
const CLOUDS = {
Commercial: { label: "Worldwide" },
GCC: { country: "us", label: "United States" },
GCCHigh: { country: "us", label: "United States" },
DoD: { country: "us", label: "United States" },
China: { country: "cn", label: "China" },
Bleu: { country: "fr", label: "France" },
Delos: { country: "de", label: "Germany" },
GovSG: { country: "sg", label: "Singapore" },
};
// The rating fields show a level icon on each choice, so the scale reads at a glance.
const SEVERITY_LEVEL = { Critical: 4, High: 3, Medium: 2, Low: 1, Info: 0 };
const SCALE_LEVEL = { Low: 1, Medium: 2, High: 3 };
const SCALE_TONE = { Low: "low", Medium: "medium", High: "high" };
const severityOptions = (options) => options.map((o) => ({ ...o, icon: }));
const scaleOptions = (options) => options.map((o) => ({ ...o, icon: }));
// The form is shown one step at a time. Each step lists the fields whose problems count against it.
const STEPS = [
{ key: "start", label: "Who it is for", fields: [] },
{ key: "name", label: "Name", fields: ["suite", "prefix", "id", "title", "functionName"] },
{ key: "about", label: "Subject", fields: ["product", "feature", "relatedProducts", "area", "resourceType"] },
{ key: "priority", label: "Priority", fields: ["severity", "userImpact", "implementationCost"] },
{ key: "mapping", label: "Mapping", fields: ["mitre", "control"] },
{ key: "services", label: "Service connections", fields: ["services"] },
{ key: "licences", label: "Licences", fields: ["license"] },
{ key: "permissions", label: "Permissions", fields: ["permission"] },
{ key: "environment", label: "Where it applies", fields: ["tenantType", "cloud", "platform"] },
{ key: "parameters", label: "Parameters", fields: ["parameters"] },
{ key: "lifecycle", label: "Lifecycle and credit", fields: ["lifecycle", "replacedBy", "flags", "author", "contributor", "tags"] },
];
const stepOfField = (field) => (STEPS.find((s) => s.fields.includes(field)) || STEPS[0]).key;
const stepOfHash = (hash) => {
const value = (hash || "").replace(/^#/, "");
if (value.startsWith("field-")) return stepOfField(value.slice(6));
return STEPS.some((s) => s.key === value) ? value : null;
};
// The list of steps: in the site's sidebar on a wide screen, a row above the form on a narrow one. A step shows
// a tick once it has been opened and has nothing to fix, or the number of things to fix.
function StepList({ steps, step, onStep, className }) {
return (
{steps.map((s, index) => (
))}
);
}
// Start from a test that ships with Maester: type its ID or part of its title. The list is fetched the first
// time the picker is used, so the page does not carry all the tests.
function ExistingTestPicker({ onLoad }) {
const [tests, setTests] = useState(null);
const [failed, setFailed] = useState(false);
const load = useCallback(() => {
if (tests || failed) return;
fetch("/data/builder-tests.json")
.then((response) => (response.ok ? response.json() : Promise.reject(new Error(String(response.status)))))
.then(setTests, () => setFailed(true));
}, [tests, failed]);
const items = useMemo(() => (tests || []).map((t) => ({ value: t.Id, label: t.Id + " " + t.Title, hint: t.Suite, ...productIconOf(t.Product) })), [tests]);
return (
{
const test = (tests || []).find((t) => t.Id === id);
if (test) onLoad(test);
}}
/>
);
}
export default function TestBuilder() {
const [state, setState] = useState(exampleState);
const [tab, setTab] = useState("ps1");
const [loaded, setLoaded] = useState(null);
const [step, setStepState] = useState("start");
const [seen, setSeen] = useState(["start"]);
const [railHost, setRailHost] = useState(null);
const formRef = useRef(null);
const jump = useRef(null);
const [jumps, setJumps] = useState(0);
const [helpId, setHelpId] = useState(null);
const helpContext = useMemo(() => ({ openId: helpId, setOpenId: setHelpId, builtin: state.mode === "builtin" }), [helpId, state.mode]);
const [guide, openGuide] = useGuides(setHelpId);
const set = (patch) => setState((s) => ({ ...s, ...patch }));
const builtin = state.mode === "builtin";
const P = data.properties;
const R = data.rubric;
const problems = useMemo(() => validate(state, data), [state]);
const errors = problems.filter((p) => p.level === "error");
const product = data.products.find((p) => p.key === state.product);
const features = product ? product.features : [];
const suite = data.suites.find((s) => s.id === state.suite);
const area = data.areas.find((a) => a.key === state.area);
const resourceType = data.resourceTypes.find((r) => r.key === state.resourceType);
const id = state.id.trim() || (builtin ? "MT.1234" : "CT.1001");
const folder = folderFor(state, data);
const changes = registryChanges(state, data);
const byHand = addByHand(state);
const firstFramework = state.controls.find((c) => data.frameworks.some((f) => c.startsWith(f.key + ":") && f.requirements.some((r) => f.key + ":" + r.id === c)));
const need = (name) => builtin && P[name].required !== "No";
// Steps. The address keeps the step, so a link or a reload opens it; a link to a field opens the field's step.
const setStep = useCallback((key, field) => {
setStepState(key);
setSeen((list) => (list.includes(key) ? list : [...list, key]));
setHelpId(null);
try {
window.history.replaceState(null, "", "#" + key);
} catch (e) {
// The address is not updated; the step still opens.
}
jump.current = { field };
setJumps((n) => n + 1);
}, []);
const goField = (field) => setStep(stepOfField(field), field);
// After the step is on the page: bring the field, or the top of the form, into view.
useEffect(() => {
if (!jump.current) return;
const { field } = jump.current;
jump.current = null;
const target = field ? document.getElementById("field-" + field) : formRef.current;
if (!target) return;
if (field) target.scrollIntoView({ block: "center" });
else if (target.getBoundingClientRect().top < 0) target.scrollIntoView({ block: "start" });
const input = field && document.getElementById("input-" + field);
if (input && input.focus) input.focus({ preventScroll: true });
}, [jumps]);
useEffect(() => {
setRailHost(document.getElementById("mt-builder-steps"));
const open = () => {
const hash = window.location.hash;
const key = stepOfHash(hash);
if (key) setStep(key, hash.startsWith("#field-") ? hash.slice(7) : undefined);
};
open();
window.addEventListener("hashchange", open);
return () => window.removeEventListener("hashchange", open);
}, [setStep]);
const steps = STEPS.map((s) => {
const count = errors.filter((p) => s.fields.includes(p.field)).length;
return { ...s, errors: count, done: seen.includes(s.key) && count === 0 && s.key !== step, optional: !builtin && !["start", "name"].includes(s.key) };
});
const stepIndex = STEPS.findIndex((s) => s.key === step);
// The prefix of custom tests is remembered in this browser.
useEffect(() => {
try {
const saved = window.localStorage.getItem(PREFIX_KEY);
if (saved && /^[A-Za-z][A-Za-z0-9]*$/.test(saved)) setState((s) => ({ ...s, customPrefix: saved, id: s.mode === "custom" ? withPrefix(s.id, saved) : s.id }));
} catch (e) {
// Storage is not available: the default prefix is used.
}
}, []);
const setPrefix = (value) => {
const prefix = value.trim();
const valid = /^[A-Za-z][A-Za-z0-9]*$/.test(prefix);
setState((s) => ({ ...s, customPrefix: value, id: valid ? withPrefix(s.id, prefix) : s.id }));
if (valid) {
try {
window.localStorage.setItem(PREFIX_KEY, prefix);
} catch (e) {
// Not saved; the prefix still applies to this visit.
}
}
};
const customId = (current) => withPrefix(current, /^[A-Za-z][A-Za-z0-9]*$/.test(state.customPrefix.trim()) ? state.customPrefix.trim() : "CT");
const setMode = (mode) => set(mode === "custom" ? { mode, id: customId(state.id) } : { mode, tags: "", id: withPrefix(state.id, "MT") });
const reset = (base) => setState({ ...base, mode: state.mode, customPrefix: state.customPrefix, id: builtin ? base.id : base.id ? customId(base.id) : "" });
const setProduct = (value) => {
const next = data.products.find((p) => p.key === value);
const keepFeature = state.feature === NEW || (next && next.features.some((f) => f.key === state.feature)) || !builtin;
set({ product: value, feature: keepFeature ? state.feature : "", relatedProducts: state.relatedProducts.filter((r) => r !== value) });
};
// Products show the icon the report and the test catalog use; features show theirs when they have one.
const iconOf = (field, key) =>
field === "product" ? productIconOf(key) : field === "feature" && state.product ? { icon: featureIcon(state.product, key) } : {};
const registrySelect = (field, options, placeholder) => {
const change = (value) => (field === "product" ? setProduct(value) : set({ [field]: value }));
const items = options.map((o) => ({ value: o.key, label: o.name ? o.name : o.key, hint: o.name ? o.key : undefined, ...iconOf(field, o.key) }));
return builtin ? (
) : (
);
};
const newEntry = (field, keys) =>
state[field] === NEW && (
A new value is added to the registry in the same pull request. The files to change are listed with the code.
);
const taxonomyHelp = (what, extra) => (
<>
Search the list first. {what} is a deliberate addition, because every key becomes a filter in the report. If nothing fits, choose Not in the list above, and add the entry to in the same pull request as the first test that needs it.
Every Maester test declares what it is about, how urgent a failure is and what it needs to run, in a [MaesterTest()] attribute. Pick the values step by step and the code updates as you go. The help button beside a field says what it means, what happens when you leave it empty, and the rule reviewers apply.
, label: "A test for Maester", text: "You will open a pull request. Values come from Maester's registries and every rubric attribute is required." },
{ value: "custom", icon: , label: "My own custom test", text: "It lives in your custom folder. Only the ID and title are required, and you may use your own values." },
]}
/>
Loaded {loaded.id}: its attributes and parameters are in the form. The code on the right is still the builder's template, not the test's own code, so copy the attribute and the param() block from it, not the body.
Set your prefix in the field above. The prefixes {data.reservedPrefixes.map((p) => {p} )} are reserved for the tests shipped with Maester and for Maester Packs.
A product entry has a Key, a Name, Aliases and its Features. If the test also needs a connection Maester does not have yet, that is a larger change to : open an issue first.
)}
>
{registrySelect("product", data.products, "Choose a product")}
{newEntry("product", [
["key", "Key, for example power-platform"],
["name", "Display name, for example Power Platform"],
])}
Add one line to the product's Features list. A feature that would hold one test only is usually too narrow, so prefer an existing one.)}>
{builtin && !state.product ?
Choose a product first. A feature belongs to one product.
: registrySelect("feature", state.product === NEW ? [] : features, "Choose a feature")}
{newEntry("feature", [
["key", "Key, for example access-reviews"],
["name", "Display name, for example Access reviews"],
])}
p.key !== state.product).map((p) => p.key)} describe={(k) => data.products.find((p) => p.key === k).name} iconFor={productIconOf} onChange={(v) => set({ relatedProducts: v })} />
The thirteen areas are meant to cover every product. When none fits, choose the closest and say so in the pull request, or propose a new one with its description and a row in the rubric's Area table.)}>
{registrySelect("area", data.areas, "Choose an area")}
{area &&
{area.description}
}
{newEntry("area", [
["key", "Key, for example physical-security"],
["name", "Display name"],
["description", "What the area is used for"],
])}
Add one line to ResourceTypes with a one-line description. For a one-off inventory with no matching type, the rubric says to use Tenant.)}>
{registrySelect("resourceType", data.resourceTypes, "Choose a resource type")}
{resourceType &&
{resourceType.description}
}
{newEntry("resourceType", [
["key", "Key in Pascal case, for example AccessPackage"],
["description", "One-line description"],
])}
What should be fixed first?
The five values are fixed. The report, the scores and the -Severity selector depend on them.}>
set({ severity: v })} />
{state.severity === "Info" ? (
An Info test makes no risk judgement, so it has no user impact or implementation cost and is left out of scores.
) : (
<>
set({ userImpact: v })} />
set({ implementationCost: v })} />
>
)}
What does it map to?
The list is the ATT&CK release Maester pins, in . A technique that is missing was retired, or is newer than the pinned release. Use its successor, or update the pinned release with ./build/attack/Update-MtAttackTechniques.ps1 in a pull request of its own.
}
>
set({ mitre: v })} onNone={(v) => set({ mitreNone: v })} />
What to list, in order
The requirement the test is written for. A CIS, CISA or ASD test lists its own requirement first, such as cis-m365:5.1.5.1 or essential-eight:ISM-1504.
A CIS, CISA or ASD requirement that asks for the same setting. Search for the setting or a test ID you know.
NIST SP 800-53 controls, at most three, when a passing result is direct evidence for them. Skip this when you already listed a cisa-scuba requirement: CISA publishes its NIST mapping and the result gets it from there.
>
}
notInList={
<>
The lookup lists the frameworks Maester ships a file for: {data.frameworks.map((f, i) => (
{i > 0 && ", "}
))}
. For any other framework, type the reference yourself with a lowercase key, for example nist-800-53-r5:IA-2(1) or iso-27001-2022:A.5.17, and use the same key every time.
The framework file is a catalogue. It holds what a key:id reference cannot: each requirement's level, profile or criticality, the controls it relates to, and the full list of requirements, so typos and gaps are found. A new CIS or CISA requirement is added to that file; the mapping itself is always this attribute.
>
}
>
{firstFramework && (
{firstFramework} is the first reference to a framework Maester has a file for, so it becomes the Benchmark of the result.
Services are registered in . A new service also needs a connection probe in the module, so open an issue before the pull request.
}
>
set({ serviceNone: v })}>
None: the test needs no connection
{!state.serviceNone && s.name)} iconFor={serviceIconOf} onChange={(v) => set({ services: v })} />}
Which licences does the tenant need?
The list is Microsoft's product names and service plan identifiers page, refreshed every day. You can also type a name that is not listed yet: it is matched as written against the tenant's service plan names.
For the plans in Maester also counts government, education and volume variants as the same licence. Add a plan there when its variants should count too.
>
}
>
set({ license: v })} />
Which permissions does it need?
The kinds of permission each service has are listed in . A test shipped with Maester names only the services it lists under Service connections.
}
>
set({ permission: v })} />
Where does it apply?
Leave these empty unless the test is only valid in some tenants, clouds or operating systems. Most tests leave them empty.
A parameter is a value of this test that an administrator can change in maester-config.json, such as a threshold or a list of exceptions.
A shared setting is one value that many tests use: a fact about the tenant, or a choice the organization makes once, such as its emergency access accounts or the domains that never send email. The administrator sets it once under GlobalSettings and every test that binds a parameter to it receives it. The help button explains how to add a new one.
What a shared setting is
Some values mean the same thing to every test that needs them: which accounts are the emergency access accounts, which domains are parked. Asking the administrator to repeat such a value on every test would be tedious and easy to get wrong. A shared setting holds it once, under GlobalSettings in maester-config.json.
A test does not read the setting itself. It declares a parameter bound to it, [MaesterParameter(Setting = 'ParkedDomains')], and the engine fills the parameter in. The result records the value and that it came from the setting, and a TestSettings row can still override it for one test.
Bind a parameter only when the organization sets the value once and it means the same to every test. A value a benchmark sets, such as a lockout threshold, is never a shared setting: it stays a parameter of that test, with the benchmark's value as the default.
Use a shared setting that exists
Choose it under Add a shared setting. The builder writes the parameter with the setting's type, default and allowed values, which must not be changed.
Add a new shared setting
{builtin ? (
Name it after what it holds, never after a test or a suite, in PascalCase and plural for a list: ParkedDomains, not Cis218Domains.
Register it in , in the same pull request, with its Type, Default, Sensitive and Description. Add AllowedValues for a fixed set of choices, Kind when a string holds something a picker can offer (a domain, a group), and Items for a list of objects.
Bind the parameter in the test with the same type, default and allowed values. The builder lists a setting only once it is registered, so write this one by hand:
Pass the value on. Give it to the helper functions that need it as an argument. A helper never reads a setting that tests bind, or it would ignore the value the test was given.
Document it in the GlobalSettings table of .
Regenerate and test. Run ./build/website/Update-MtTestBuilderData.ps1, so this page offers the setting, then ./powershell/tests/pester.ps1. The unit tests fail when a parameter's type or default differs from its setting.
) : (
Name it Namespace.Key, with your organization or pack as the namespace: Contoso.Regions. The dot keeps it apart from Maester's own settings, and Maester does not report it as a typo.
Add a parameter here and type that name under Shared setting of your own. Give it a default, so the test runs before anyone sets the value.
Set the value once under GlobalSettings in maester-config.json. Every test of yours that binds Contoso.Regions receives it. The example below the form shows the file.
In a Maester Pack, also declare the setting under Settings in maester-pack.json, with its type. Maester then checks the value in the config before a run.
How an administrator sets {(state.parameters || []).length === 1 ? "it" : "them"} in maester-config.json. A shared setting is set once under GlobalSettings, and the test's row under TestSettings can still override it for this test.
Step {stepIndex + 1} of {STEPS.length}
{stepIndex < STEPS.length - 1 ? (
) : (
{errors.length ? "Fix what is listed with the code, then copy it." : "Done. Copy the code."}
)}