Failing a rule deliberately with custom statement

[ankur90Git]

I have 2 questions:

1. I was using $Assert command for pass, how can we give a custom fail statement if a condition fails and the rule also should be
   failed?
2. Is there any way to give custom statement or message along with pass statement in the results?

Rule 'ManagedIdentity3' -If { $TargetObject.RoleDefinitionName -eq $configuration.ServiceBusPermission }{
    
    $expectedQueues = $configuration.ServiceBusQueues.Split(',')
    $actualValue = $TargetObject.RoleAssignmentId
    $bFlag = $false
    Foreach($item in $expectedQueues){
        if($actualValue.Contains($item)){
            $bFlag = $true
            $Assert.Contains($TargetObject,'RoleAssignmentId',$item)
        }
    }

    if($bFlag -eq $false){
        **#Want to fail the rule with a message**
    }
}

[BernieWhite]

@ankur90Git Thanks for the questions.

1. PSRule provides two main options a recommendation and reason. A recommendation is designed to be a static message that describes what the user should do to make the rule pass, like a best practise. For example: "Consider using RBAC permissions to access service bus."

A reason is more dynamic, it's intended to report the specific thing that failed. An example might be: "A Contributor RBAC assignment was not found."

You can use both together.

Reasons are only shown if the rule failed. They are not shown for failure by default when using Invoke-PSRule but can be shown then using -OutputFormat Wide. They are always shown on failures when using Assert-PSRule.

Recommendations are more like metadata for the rule so they are always available on the result object. They are shown by default when using Invoke-PSRule and shown for failing rules when using Assert-PSRule.

In terms of your specific case I suggest using a reason. For example you could add the following:

Rule 'ManagedIdentity3' -If { $TargetObject.RoleDefinitionName -eq $configuration.ServiceBusPermission }{
    
    $expectedQueues = $configuration.ServiceBusQueues.Split(',')
    $actualValue = $TargetObject.RoleAssignmentId
    $bFlag = $false
    Foreach($item in $expectedQueues){
        if($actualValue.Contains($item)){
            $bFlag = $true
            $Assert.Contains($TargetObject,'RoleAssignmentId',$item)
        }
    }

    if($bFlag -eq $false){
        $Assert.Fail("Some reason why this failed.")
    }
}

Extending on this you could also write as:

Rule 'ManagedIdentity3' -If { $TargetObject.RoleDefinitionName -eq $configuration.ServiceBusPermission }{
    
    $expectedQueues = $configuration.ServiceBusQueues.Split(',')
    $actualValue = $TargetObject.RoleAssignmentId
    $bFlag = $false
    Foreach($item in $expectedQueues){
        if($actualValue.Contains($item)){
            $bFlag = $true
            $Assert.Contains($TargetObject,'RoleAssignmentId',$item)
        }
    }
    $Assert.Create($bFlag, "Some reason why this failed.")
}

Or use arguments in the reason like:

Rule 'ManagedIdentity3' -If { $TargetObject.RoleDefinitionName -eq $configuration.ServiceBusPermission }{
    
    $expectedQueues = $configuration.ServiceBusQueues.Split(',')
    $actualValue = $TargetObject.RoleAssignmentId
    $bFlag = $false
    Foreach($item in $expectedQueues){
        if($actualValue.Contains($item)){
            $bFlag = $true
            $Assert.Contains($TargetObject,'RoleAssignmentId',$item)
        }
    }
    $Assert.Create($bFlag, "Some reason why this failed for role assignment: {0}.", $TargetObject.RoleAssignmentId)
}

Some more options are here: Authoring assertion methods.

2. I think the rule recommendation would address this requirement. PSRule provides a static synopsis, description, and recommendation that can be set on a rule but not any other reason/ message that is provided if the rule passes.

A synopsis and recommendations can be added easily by setting the Synopsis: comment. Alternatively you can use markdown for extended information. When a recommendation is not set in markdown or via the Recommend keyword, the recommendation defaults to the synopsis.

To add a synopsis/ recommendation try:

# Synopsis: Some recommandations/ synopsis in a single line. Multi-lines are not supported via this comment.
Rule 'ManagedIdentity3' -If { $TargetObject.RoleDefinitionName -eq $configuration.ServiceBusPermission }{
    
    $expectedQueues = $configuration.ServiceBusQueues.Split(',')
    $actualValue = $TargetObject.RoleAssignmentId
    $bFlag = $false
    Foreach($item in $expectedQueues){
        if($actualValue.Contains($item)){
            $bFlag = $true
            $Assert.Contains($TargetObject,'RoleAssignmentId',$item)
        }
    }
    $Assert.Create($bFlag, "Some reason why this failed for role assignment: {0}.", $TargetObject.RoleAssignmentId)
}

• Defining script rules
• Define a rule
• Creating documentation for rules
• Recommend keyword

Alternatively, you could use Write-Verbose, Write-Information, Write-Error, and Write-Warning cmdlets to provide additional information for diagnostic purposes but these are not for rule results specifically.

---

I hope that helps.