New-MtTest

Synopsis

Creates a new Maester native test: Test.<ID>.ps1 and Test.<ID>.md.

Syntax

New-MtTest [-Id] <String> -Title <String> [-Severity <String>] [-Service <String[]>] [-Product <String>]
 [-Feature <String>] [-Area <String>] [-ResourceType <String>] [-UserImpact <String>]
 [-ImplementationCost <String>] [-Mitre <String[]>] [-Path <String>] [-Force]
 [-ProgressAction <ActionPreference>] [-WhatIf] [-Confirm] [<CommonParameters>]

Description

Writes a test function with its [MaesterTest] attribute and a Markdown file with the description, remediation and result sections. Run it with Invoke-MtTest -Path, and validate it with Get-MtTest -Path.

A custom test needs only an ID and a title. -Product, -Feature, -Area, -ResourceType, -UserImpact, -ImplementationCost and -Mitre fill in the attributes that say what the test is about, what to fix first and which attack techniques it addresses; add or change them in the file later as you like.

Examples

Example 1

New-MtTest -Id CONTOSO.1001 -Title 'Guest invitations are restricted' -Service Graph -Severity High

Creates custom/Test.CONTOSO.1001.ps1 and custom/Test.CONTOSO.1001.md.

Example 2

New-MtTest -Id CONTOSO.1002 -Title 'Legacy authentication is blocked' -Product entra -Feature conditional-access -Area authentication -ResourceType Tenant -Severity High -UserImpact Medium -ImplementationCost Low -Mitre T1110.003

Creates a test with the classification, priority and ATT&CK attributes filled in. The attribute rubric at https://maester.dev/docs/writing-tests/attribute-rubric explains how to choose each value.

Parameters

-Id

The test ID. Use your own prefix, for example CONTOSO.1001.

Type: String
Parameter Sets: (All)
Aliases:

Required: True
Position: 1
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

-Title

The one-line title shown in the report.

Type: String
Parameter Sets: (All)
Aliases:

Required: True
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

-Severity

Critical, High, Medium, Low or Info.

Type: String
Parameter Sets: (All)
Aliases:

Required: False
Position: Named
Default value: Medium
Accept pipeline input: False
Accept wildcard characters: False

-Service

The services the test needs, for example Graph or ExchangeOnline.

Type: String[]
Parameter Sets: (All)
Aliases:

Required: False
Position: Named
Default value: @('Graph')
Accept pipeline input: False
Accept wildcard characters: False

-Product

The product where the fix is made: a key of the Maester taxonomy such as entra or exchange (an alias such as ‘Entra ID’ is written as the key), or any name of your own. Groups the console progress and the run summary.

Type: String
Parameter Sets: (All)
Aliases:

Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

-Feature

The part of the product the test is about, for example conditional-access. With a Maester product, one of its feature keys; otherwise any text.

Type: String
Parameter Sets: (All)
Aliases:

Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

-Area

The security theme, for example authentication or privileged-access.

Type: String
Parameter Sets: (All)
Aliases:

Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

-ResourceType

What a failing result points at, for example Tenant or User.

Type: String
Parameter Sets: (All)
Aliases:

Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

-UserImpact

How much the recommended fix disrupts end users: Low, Medium or High.

Type: String
Parameter Sets: (All)
Aliases:

Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

-ImplementationCost

How much administrator work the recommended fix takes: Low, Medium or High.

Type: String
Parameter Sets: (All)
Aliases:

Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

-Mitre

The MITRE ATT&CK technique IDs the checked control prevents or detects, for example T1110.003, or None.

Type: String[]
Parameter Sets: (All)
Aliases:

Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

-Path

The folder to create the files in. Defaults to ./custom (an existing ./Custom folder is reused).

Type: String
Parameter Sets: (All)
Aliases:

Required: False
Position: Named
Default value: ./custom
Accept pipeline input: False
Accept wildcard characters: False

-Force

Overwrites existing files.

Type: SwitchParameter
Parameter Sets: (All)
Aliases:

Required: False
Position: Named
Default value: False
Accept pipeline input: False
Accept wildcard characters: False

-WhatIf

Shows what would happen if the cmdlet runs. The cmdlet is not run.

Type: SwitchParameter
Parameter Sets: (All)
Aliases: wi

Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

-Confirm

Prompts you for confirmation before running the cmdlet.

Type: SwitchParameter
Parameter Sets: (All)
Aliases: cf

Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

-ProgressAction

Determines how PowerShell responds to progress updates generated by a script, cmdlet, or provider, such as the progress bars generated by Write-Progress.

Type: ActionPreference
Parameter Sets: (All)
Aliases: proga

Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

CommonParameters

This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters.

Inputs

Outputs

System.IO.FileInfo

Notes

Related links

https://maester.dev/docs/commands/New-MtTest