Add-MtAffectedObjectFact

Synopsis

Adds facts about an object, such as its last sign-in or its expired secrets, to the Affected objects page.

Syntax

Add-MtAffectedObjectFact [-Type] <String> [-Id] <String> [-Fact] <Object[]> [[-System] <String>]
 [-Source] <String> [[-AsOf] <DateTime>] [-ProgressAction <ActionPreference>] [<CommonParameters>]

Description

Call this from a test, an instance source or a pack that knows more about an object than the checks that name it: when the object was last used, which permissions it holds, whether its credentials have expired. The facts are shown with the object on the Affected objects page of the HTML report and kept in the AffectedObjects of the results, the JSON output and the objects files.

Add-MtTestResultDetail -GraphObjects says which objects a result is about, and adds them to the page with the check that named them. Add-MtAffectedObjectFact says what is known about an object, whichever check named it.

Facts only describe an object that the run already lists. They are merged into the record with the same System, Type and Id when the results are built, so adding facts about an object that no check names adds nothing to the report. Facts are collected only while Invoke-Maester collects affected objects; otherwise the call does nothing.

Each fact has a Name, a Value and a Tone: Risk for something to fix, Warning for something to review, Good for a sign that the object is in order, and Info (the default) for anything else.

A fact can also carry a Key and a Raw value, for code that reads the results: a summary, an insight or another report. The Key names what the fact is about, from the shared list of fact keys (user.mfaRegistered, signIn.daysSince, device.managed…), so the same fact from two sources means the same thing. Raw is its value as data: a boolean, a number, a string, a list of strings or a date, which is kept as an ISO 8601 UTC string. Value stays the text people read. Raw is kept only with a Key. A fact without a Key is shown the same way.

Adding a fact with the same Key, or without a Key the same Name, from the same Source again replaces the earlier one.

The value is shown as text. Name counts rather than other people where you can: the page shows facts to everyone who reads the report, and -RedactUserIdentity replaces only the names of users the run knows.

Examples

Example 1

Add-MtAffectedObjectFact -Type ServicePrincipal -Id $sp.id -Source 'Contoso inventory' -Fact @(
    @{ Name = 'Last sign-in'; Value = '2026-06-15 (143 days ago)'; Tone = 'Risk' }
    @{ Name = 'Publisher'; Value = 'Third party (Contoso Ltd)' }
)

Adds two facts to an enterprise application.

Example 2

Add-MtAffectedObjectFact -Type User -Id $user.id -Source 'Contoso HR' -Fact @(
    @{ Name = 'MFA'; Value = 'Not registered'; Tone = 'Risk'; Key = 'user.mfaRegistered'; Raw = $false }
    @{ Name = 'Last sign-in'; Value = '2026-06-15 (143 days ago)'; Tone = 'Warning'; Key = 'signIn.daysSince'; Raw = 143 }
)

Adds facts with keys, so code can read whether the user has MFA and how long since they signed in without parsing the text.

Example 3

$records | Add-MtAffectedObjectFact -Source 'Zero Trust Assessment' -AsOf $report.ExecutedAt

Adds facts to many objects at once. Each record has Type, Id and Fact properties, and optionally System.

Parameters

-Type

The object type, as the Affected objects page records it: User, Group, ServicePrincipal, AppRegistration (keyed by its appId), Device, ConditionalAccessPolicy, AgentIdentity, AgentIdentityBlueprint, ConfigurationPolicy…

Type: String
Parameter Sets: (All)
Aliases:

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

-Id

The object’s id, the same id the record uses (for an app registration, its appId).

Type: String
Parameter Sets: (All)
Aliases:

Required: True
Position: 2
Default value: None
Accept pipeline input: True (ByPropertyName)
Accept wildcard characters: False

-Fact

The facts: hashtables or objects with Name, Value, and optionally Tone (Risk, Warning, Good or Info), Key (a shared fact key such as user.mfaRegistered) and Raw (its value as data).

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

Required: True
Position: 3
Default value: None
Accept pipeline input: True (ByPropertyName)
Accept wildcard characters: False

-System

Where the object lives: EntraID (the default), Intune, ExchangeOnline, GitHub…

Type: String
Parameter Sets: (All)
Aliases:

Required: False
Position: 4
Default value: EntraID
Accept pipeline input: True (ByPropertyName)
Accept wildcard characters: False

-Source

What the facts come from, shown with them, for example ‘Zero Trust Assessment’.

Type: String
Parameter Sets: (All)
Aliases:

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

-AsOf

When the data behind the facts was read, when that is not now (a report written earlier).

Type: DateTime
Parameter Sets: (All)
Aliases:

Required: False
Position: 6
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.Void

Notes

Related links

https://maester.dev/docs/commands/Add-MtAffectedObjectFact

https://maester.dev/docs/writing-tests/formatting-test-results#adding-facts-about-an-object

https://maester.dev/docs/writing-tests/formatting-test-results#fact-keys