PSRule

A cross-platform PowerShell module (Windows, Linux, and MacOS) with commands to validate objects on the pipeline using PowerShell syntax.

Features of PSRule include:

• Extensible - Use PowerShell, a flexible scripting language.
• Cross-platform - Run on MacOS, Linux and Windows.
• Reusable - Share rules across teams or organizations.
• Recommendations - Include detailed instructions to remediate issues.

Disclaimer

This project is open source and not a supported product.

If you are experiencing problems, have a feature request, or a question, please check for an issue on GitHub. If you do not see your problem captured, please file a new issue, and follow the provided template.

Getting the module

You can download and install the PSRule module from the PowerShell Gallery.

For rule and integration modules see related projects.

Getting extensions

Companion extensions are available for the following platforms.

Getting started

The following example shows basic PSRule usage. For specific use cases see scenarios.

For frequently asked questions, see the FAQ.

Define a rule

To define a rule, use a Rule block saved to a file with the .Rule.ps1 extension.

Rule 'NameOfRule' {
    # Rule conditions
}

Within the body of the rule provide one or more conditions. A condition is valid PowerShell that results in $True or $False.

For example:

Rule 'isFruit' {
    # Condition to determine if the object is fruit
    $TargetObject.Name -in 'Apple', 'Orange', 'Pear'
}

An optional result message can be added to by using the Recommend keyword.

Rule 'isFruit' {
    # An recommendation to display in output
    Recommend 'Fruit is only Apple, Orange and Pear'

    # Condition to determine if the object is fruit
    $TargetObject.Name -in 'Apple', 'Orange', 'Pear'
}

The rule is saved to a file named isFruit.Rule.ps1 file. One or more rules can be defined within a single file.

Execute a rule

To execute the rule use Invoke-PSRule.

For example:

# Define objects to validate
$items = @();
$items += [PSCustomObject]@{ Name = 'Fridge' };
$items += [PSCustomObject]@{ Name = 'Apple' };

# Validate each item using rules saved in current working path
$items | Invoke-PSRule;

The output of this example is:

   TargetName: Fridge

RuleName                            Outcome    Recommendation
--------                            -------    --------------
isFruit                             Fail       Fruit is only Apple, Orange and Pear


   TargetName: Apple

RuleName                            Outcome    Recommendation
--------                            -------    --------------
isFruit                             Pass       Fruit is only Apple, Orange and Pear

Additional options

To filter results to only non-fruit results, use Invoke-PSRule -Outcome Fail. Passed, failed and error results are shown by default.

# Only show non-fruit results
$items | Invoke-PSRule -Outcome Fail;

For a summary of results for each rule use Invoke-PSRule -As Summary.

For example:

# Show rule summary
$items | Invoke-PSRule -As Summary;

The output of this example is:

RuleName                            Pass  Fail  Outcome
--------                            ----  ----  -------
isFruit                             1     1     Fail

An optional failure reason can be added to the rule block by using the Reason keyword.

Rule 'isFruit' {
    # An recommendation to display in output
    Recommend 'Fruit is only Apple, Orange and Pear'

    # An failure reason to display for non-fruit
    Reason "$($PSRule.TargetName) is not fruit."

    # Condition to determine if the object is fruit
    $TargetObject.Name -in 'Apple', 'Orange', 'Pear'
}

To include the reason with output use Invoke-PSRule -OutputFormat Wide.

For example:

# Show failure reason for failing results
$items | Invoke-PSRule -OutputFormat Wide;

The output of this example is:

   TargetName: Fridge

RuleName                            Outcome    Reason                              Recommendation
--------                            -------    ------                              --------------
isFruit                             Fail       Fridge is not fruit.                Fruit is only Apple, Orange and Pear


   TargetName: Apple

RuleName                            Outcome    Reason                              Recommendation
--------                            -------    ------                              --------------
isFruit                             Pass                                           Fruit is only Apple, Orange and Pear

The final rule is saved to isFruit.Rule.ps1.

Scenarios

For walk through examples of PSRule usage see:

• Validate Azure resource configuration
• Validate Azure resources tags
• Validate Kubernetes resources
• Using within continuous integration
• Packaging rules in a module
• Writing rule help

Language reference

PSRule extends PowerShell with domain specific language (DSL) keywords, cmdlets and automatic variables.

Keywords

The following language keywords are used by the PSRule module:

• Rule - A rule definition.
• Exists - Assert that a field or property must exist.
• Match - Assert that the field must match any of the regular expressions.
• AnyOf - Assert that any of the child expressions must be true.
• AllOf - Assert that all of the child expressions must be true.
• Within - Assert that the field must match any of the values.
• TypeOf - Assert that the object must be of a specific type.
• Reason - Return a reason for why the rule failed.
• Recommend - Return a recommendation to resolve the issue and pass the rule.

Commands

The following commands exist in the PSRule module:

• Assert-PSRule - Evaluate objects against matching rules and assert any failures.
• Get-PSRule - Get a list of rule definitions.
• Get-PSRuleBaseline - Get a list of baselines.
• Get-PSRuleHelp - Get documentation for a rule.
• Get-PSRuleTarget - Get a list of target objects.
• Invoke-PSRule - Evaluate objects against matching rules and output the results.
• New-PSRuleOption - Create options to configure PSRule execution.
• Set-PSRuleOption - Sets options that configure PSRule execution.
• Test-PSRuleTarget - Pass or fail objects against matching rules.

Concepts

The following conceptual topics exist in the PSRule module:

• Assert
  • Contains
  • EndsWith
  • FileHeader
  • FilePath
  • Greater
  • GreaterOrEqual
  • HasDefaultValue
  • HasField
  • HasFieldValue
  • HasJsonSchema
  • In
  • JsonSchema
  • Less
  • Match
  • NotIn
  • NotMatch
  • LessOrEqual
  • NullOrEmpty
  • StartsWith
  • Version
• Baselines
  • Baseline specs
  • Baseline scopes
• Docs
  • Getting documentation
  • Online help
  • Creating documentation
• Options
  • Binding.Field
  • Binding.IgnoreCase
  • Binding.NameSeparator
  • Binding.TargetName
  • Binding.TargetType
  • Binding.UseQualifiedName
  • Configuration
  • Execution.LanguageMode
  • Execution.InconclusiveWarning
  • Execution.NotProcessedWarning
  • Input.Format
  • Input.ObjectPath
  • Input.PathIgnore
  • Input.TargetType
  • Logging.LimitDebug
  • Logging.LimitVerbose
  • Logging.RuleFail
  • Logging.RulePass
  • Output.As
  • Output.Culture
  • Output.Encoding
  • Output.Format
  • Output.Path
  • Output.Style
  • Rule.Include
  • Rule.Exclude
  • Rule.Tag
  • Suppression
• Variables
  • $Assert
  • $Configuration
  • $LocalizedData
  • $PSRule
  • $Rule
  • $TargetObject

Schemas

PSRule uses the following schemas:

• Options - Schema for PSRule YAML options file.
• Resources - Schema for PSRule YAML resources such as baselines.

Related projects

The following projects use or integrate with PSRule.

Changes and versioning

Modules in this repository will use the semantic versioning model to declare breaking changes from v1.0.0. Prior to v1.0.0, breaking changes may be introduced in minor (0.x.0) version increments. For a list of module changes please see the change log.

Pre-release module versions are created on major commits and can be installed from the PowerShell Gallery. Pre-release versions should be considered experimental. Modules and change log details for pre-releases will be removed as standard releases are made available.

Contributing

This project welcomes contributions and suggestions. If you are ready to contribute, please visit the contribution guide.

Code of Conduct

This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact [email protected] with any additional questions or comments.

Maintainers

• Bernie White

License

This project is licensed under the MIT License.