PSRule

A cross-platform module to validate infrastructure as code (IaC) and objects using PowerShell rules. PSRule works great and integrates with popular continuous integration (CI) systems.

Summary

• Introduction
• Project Objectives
• Support
• Getting the module
• Getting extensions
• Getting started
  • Scenarios
• Language reference
  • Keywords
  • Commands
  • Concepts
  • Schemas
• Related projects
• Changes and versioning
• Contributing
• Code of conduct
• Maintainers
• License

Features of PSRule include

• DevOps - Built to support DevOps culture and tools.

• Extensible - Define tests using YAML, JSON, or PowerShell format.

• Reusable - Reuse and share rules across teams or organizations.

Project objectives

1. Extensible:
   • Provide an execution environment (tools and language) to validate infrastructure code.
   • Handling of common concerns such as input/ output/ reporting should be handled by the engine.
   • Language must be flexible enough to support a wide range of use cases.
2. DevOps:
   • Validation should support and enhance DevOps workflows by providing fast feedback in pull requests.
   • Allow quality gates to be implemented between environments such development, test, and production.
3. Cross-platform:
   • A wide range of platforms can be used to author and deploy infrastructure code. PSRule must support rule validation and authoring on Linux, MacOS, and Windows.
   • Runs in a Linux container. For continuous integration (CI) systems that do not support PowerShell, run in a container.
4. Reusable:
   • Validation should plug and play, reusable across teams and organizations.
   • Any reusable validation will have exceptions. Rules must be able to be disabled where they are not applicable.

Continue reading the PSRule design specification.

Back to the summary

Support

This project uses GitHub Issues to track bugs and feature requests. Please search the existing issues before filing new issues to avoid duplicates.

• For new issues, file your bug or feature request as a new issue.
• For help, discussion, and support questions about using this project, join or start a discussion.

Support for this project/ product is limited to the resources listed above.

Back to the summary

Getting the module

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

Module	Description	Downloads / instructions
PSRule	Validate infrastructure as code (IaC) and objects using PowerShell rules.	latest / instructions

For rule and integration modules see related projects.

Back to the summary

Getting extensions

Companion extensions are available for the following platforms.

Platform	Description	Downloads / instructions
Azure Pipelines	Validate infrastructure as code (IaC) and DevOps repositories using Azure Pipelines.	latest / instructions
GitHub Actions	Validate infrastructure as code (IaC) and DevOps repositories using GitHub Actions.	latest / instructions
Visual Studio Code	Visual Studio Code extension for PSRule.	latest / instructions

Back to the summary

Getting started

For an quickstart example of using PSRule see Create a standalone rule. For specific use cases see scenarios.

For frequently asked questions, see the FAQ.

Back to the summary

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

Back to the summary

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.

Back to the summary

Commands

The following commands exist in the PSRule module:

• Assert-PSRule - Evaluate objects against matching rules and assert any failures.
• Export-PSRuleBaseline - Exports a list of baselines to a file.
• 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.

Back to the summary

Concepts

The following conceptual topics exist in the PSRule module:

• Assert
  • APIVersion
  • Contains
  • Count
  • EndsWith
  • FileHeader
  • FilePath
  • Greater
  • GreaterOrEqual
  • HasDefaultValue
  • HasField
  • HasFields
  • HasFieldValue
  • HasJsonSchema
  • In
  • IsArray
  • IsBoolean
  • IsDateTime
  • IsInteger
  • IsLower
  • IsNumeric
  • IsString
  • IsUpper
  • JsonSchema
  • Less
  • LessOrEqual
  • Like
  • Match
  • NotContains
  • NotCount
  • NotEndsWith
  • NotHasField
  • NotIn
  • NotLike
  • NotMatch
  • NotNull
  • NotStartsWith
  • NotWithinPath
  • Null
  • NullOrEmpty
  • TypeOf
  • SetOf
  • StartsWith
  • Subset
  • Version
  • WithinPath
• Badges
• Baselines
  • Baseline specs
  • Baseline scopes
• Conventions
  • Using conventions
  • Defining conventions
  • Begin Process End blocks
  • Including with options
  • Using within modules
  • Execution order
• Docs
  • Getting documentation
  • Online help
  • Creating documentation
• Expressions
  • AllOf
  • AnyOf
  • APIVersion
  • Contains
  • Count
  • EndsWith
  • Exists
  • Equals
  • Field
  • Greater
  • GreaterOrEquals
  • HasDefault
  • HasSchema
  • HasValue
  • In
  • IsLower
  • IsString
  • IsArray
  • IsBoolean
  • IsDateTime
  • IsInteger
  • IsNumeric
  • IsUpper
  • Less
  • LessOrEquals
  • Like
  • Match
  • Name
  • Not
  • NotContains
  • NotCount
  • NotEndsWith
  • NotEquals
  • NotIn
  • NotLike
  • NotMatch
  • NotStartsWith
  • NotWithinPath
  • Scope
  • SetOf
  • Source
  • StartsWith
  • Subset
  • Type
  • WithinPath
  • Version
• Options
  • Baseline.Group
  • Binding.Field
  • Binding.IgnoreCase
  • Binding.NameSeparator
  • Binding.PreferTargetInfo
  • Binding.TargetName
  • Binding.TargetType
  • Binding.UseQualifiedName
  • Configuration
  • Convention.Include
  • Execution.AliasReference
  • Execution.DuplicateResourceId
  • Execution.HashAlgorithm
  • Execution.LanguageMode
  • Execution.InvariantCulture
  • Execution.InitialSessionState
  • Execution.RestrictScriptSource
  • Execution.RuleInconclusive
  • Execution.SuppressionGroupExpired
  • Execution.UnprocessedObject
  • Include.Module
  • Include.Path
  • Input.Format
  • Input.IgnoreGitPath
  • Input.IgnoreObjectSource
  • Input.IgnoreRepositoryCommon
  • Input.IgnoreUnchangedPath
  • Input.ObjectPath
  • Input.PathIgnore
  • Input.TargetType
  • Logging.LimitDebug
  • Logging.LimitVerbose
  • Logging.RuleFail
  • Logging.RulePass
  • Output.As
  • Output.Banner
  • Output.Culture
  • Output.Encoding
  • Output.Footer
  • Output.Format
  • Output.JobSummaryPath
  • Output.JsonIndent
  • Output.Outcome
  • Output.Path
  • Output.SarifProblemsOnly
  • Output.Style
  • Repository.BaseRef
  • Repository.Url
  • Requires
  • Rule.Baseline
  • Rule.Include
  • Rule.IncludeLocal
  • Rule.Exclude
  • Rule.Tag
  • Suppression
• Rules
• Selectors
• Suppression Groups
• Variables
  • $Assert
  • $Configuration
  • $LocalizedData
  • $PSRule
  • $Rule
  • $TargetObject

Back to the summary

Schemas

PSRule uses the following schemas:

• Options - Schema for PSRule YAML options file.
• Language - Schema for PSRule resources such as baselines.
• Resources - Schema for PSRule resources documents used with JSON.

Back to the summary

Related projects

For a list of projects and integrations see Related projects.

Changes and versioning

This repository uses semantic versioning to declare breaking changes. For details please see the changes and versioning.

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 opencode@microsoft.com with any additional questions or comments.

Maintainers

• Bernie White

License

This project is licensed under the MIT License.

Trademarks

This project may contain trademarks or logos for projects, products, or services. Authorized use of Microsoft trademarks or logos is subject to and must follow Microsoft's Trademark & Brand Guidelines. Use of Microsoft trademarks or logos in modified versions of this project must not cause confusion or imply Microsoft sponsorship. Any use of third-party trademarks or logos are subject to those third-party's policies.

Back to the summary