Change logUnreleased#
+v3.0.0-B0179 (pre-release)#
What's changed since pre-release v3.0.0-B0153:
- Engineering:
-
@@ -2962,7 +2981,7 @@
- Engine features:
- Added
HasFieldsassertion helper to check all fields exist. #578 - Updated
HasFieldto check if any of the specified fields exist. #578
- Added
- General improvements:
- Input format detection now includes
.jsoncand.markdownfile extensions. #575 - Improved support for cross module rule dependencies. #248
- Rule dependencies are now automatically imported.
- Input format detection now includes
- Bug fixes:
- Fixed handling for null or empty arrays with
StartsWith,Contains,EndsWith,In, andNotIn. #579
- Fixed handling for null or empty arrays with
- No additional changes.
- Engine features:
- Added
HasFieldsassertion helper to check all fields exist. #578 - Updated
HasFieldto check if any of the specified fields exist. #578
- Added
- General improvements:
- Input format detection now includes
.jsoncand.markdownfile extensions. #575 - Improved support for cross module rule dependencies. #248
- Rule dependencies are now automatically imported.
- Input format detection now includes
- Bug fixes:
- Fixed handling for null or empty arrays with
StartsWith,Contains,EndsWith,In, andNotIn. #579
- Fixed handling for null or empty arrays with
- Engine features:
- Added support for formatting results as markdown. #474
- Use
-OutputFormat Markdownor configureOutput.Formatto output markdown. - To format as either detail or summary, use the
-Asparameter or configureOutput.As.
- Use
- Added character case assertion helpers
IsLower, andIsUpper. #555IsLowerchecks that all letters in a field value are lowercase.IsUpperchecks that all letters in a field value are uppercase.
- Added support for formatting results as markdown. #474
- General improvements:
- Numerical strings can be converted with numeric assertion helpers. #550
- Added outcome
Output.Outcomeas a configurable option. #552 - Added help links and default snippets to schemas. #561
- Improved rule error reporting by including rule and source location. #565
- Engineering:
- Bump Manatee.Json from 13.0.2 to 13.0.3. #563
- Bug fixes:
- Fixed NUnit report reasons should be escaped in markdown. #471
- Fixed reporting of error when rule error is handled. #564
- Additionally rules can use
-ErrorAction Ignoreto ignore non-exception errors.
- Additionally rules can use
- Fixed first exception stops other rules from being processed. #566
- No additional changes.
- General improvements:
- Improved rule error reporting by including rule and source location. #565
- General improvements:
- Added help links and default snippets to schemas. #561
- Engineering:
- Bump Manatee.Json from 13.0.2 to 13.0.3. #563
- Bug fixes:
- Fixed reporting of error when rule error is handled. #564
- Additionally rules can use
-ErrorAction Ignoreto ignore non-exception errors.
- Additionally rules can use
- Fixed first exception stops other rules from being processed. #566
- Fixed reporting of error when rule error is handled. #564
- Engine features:
- Added character case assertion helpers
IsLower, andIsUpper. #555IsLowerchecks that all letters in a field value are lowercase.IsUpperchecks that all letters in a field value are uppercase.
- Added character case assertion helpers
- Bug fixes:
- Fixed NUnit report reasons should be escaped in markdown. #471
- Engine features:
- Added support for formatting results as markdown. #474
- Use
-OutputFormat Markdownor configureOutput.Formatto output markdown. - To format as either detail or summary, use the
-Asparameter or configureOutput.As.
- Use
- Added support for formatting results as markdown. #474
- General improvements:
- Numerical strings can be converted with numeric assertion helpers. #550
- Added outcome
Output.Outcomeas a configurable option. #552
- Engine features:
- Added support for scanning repository files. #524
- Added
Fileinput type (-InputType File) to scan for files without deserializing them. - Added
Input.PathIgnoreoption to ignore files. - When using the
Fileinput type path specs in.gitignoreare ignored.
- Added
- Added
Get-PSRuleTargetcmdlet to read input files and return raw objects. #525- This cmdlet can be used to troubleshoot PSRule input issues.
- Baselines can now be flagged as obsolete. #499
- Set the
metadata.annotations.obsoleteproperty totrueto flag a baseline as obsolete. - When an obsolete baseline is used, a warning will be generated.
- Set the
- Added file assertion helpers
FileHeader, andFilePath. #534FileHeaderchecks for a comment header in the file.FilePathchecks that a file path (optionally with suffixes) exist.
- Added support for scanning repository files. #524
- General improvements:
- Added automatic binding for Rule object. #542
- Engineering:
- Warn when deprecated
$Ruleproperties are used. #536 #545- First usage of deprecated property generates a warning.
- Rule using deprecated property is flagged in debug output.
- Bump YamlDotNet dependency to v8.1.2. #439
- Warn when deprecated
- Bug fixes:
- Fixed out of bounds exception when empty markdown documentation is used. #516
- Bug fixes:
- Fixed excessive obsolete property warnings. #545
- General improvements:
- Added automatic binding for Rule object. #542
- Bug fixes:
- Fixed
InputFileInfoTypeproperty causes downstream binding issues. #541
- Fixed
- Engine features:
- Added file assertion helpers
FileHeader, andFilePath. #534FileHeaderchecks for a comment header in the file.FilePathchecks that a file path (optionally with suffixes) exist.
- Added file assertion helpers
- Engineering:
- Warn when deprecated
$Ruleproperties are used. #536
- Warn when deprecated
- Bug fixes:
- Fixed out of bounds exception when empty markdown documentation is used. #516
- Fixed lines breaks in
RepositoryInfotarget name with git ref. #538
- Engine features:
- Baselines can now be flagged as obsolete. #499
- Set the
metadata.annotations.obsoleteproperty totrueto flag a baseline as obsolete. - When an obsolete baseline is used, a warning will be generated.
- Set the
- Baselines can now be flagged as obsolete. #499
- Engineering:
- Bump YamlDotNet dependency to v8.1.2. #439
- Engine features:
- Added support for scanning repository files. #524
- Added
Fileinput type (-InputType File) to scan for files without deserializing them. - Added
Input.PathIgnoreoption to ignore files. - When using the
Fileinput type path specs in.gitignoreare ignored.
- Added
- Added
Get-PSRuleTargetcmdlet to read input files and return raw objects. #525- This cmdlet can be used to troubleshoot PSRule input issues.
- Added support for scanning repository files. #524
- Engine features:
- Added
Reasonmethod to assertion results. #500- This new method, streamlines setting custom reasons particularly with formatted strings.
- The
Reasonmethod replaces any previously set reasons with a custom string. - Optional arguments can be provided to be included in string formatting.
- Improvements to assertion methods.
- Added regular expression assertion helpers
Match, andNotMatch. #502 - Added collection assertion helpers
In, andNotIn. #501
- Added regular expression assertion helpers
- Added module version constraints. #498
- The module versions that PSRule uses can be constrained.
- Added
- Bug fixes:
- Fixed styling for no rule files warning with
Assert-PSRule. #484 - Fixed actual value in reason for numeric comparison assertion method. #505
- Fixed styling for no rule files warning with
- No additional changes.
- Bug fixes:
- Fixed
Assert.Inunable to compare PSObject wrapped array items. #512
- Fixed
- Engine features:
- Added
Reasonmethod to assertion results. #500- This new method, streamlines setting custom reasons particularly with formatted strings.
- The
Reasonmethod replaces any previously set reasons with a custom string. - Optional arguments can be provided to be included in string formatting.
- Improvements to assertion methods.
- Added regular expression assertion helpers
Match, andNotMatch. #502 - Added collection assertion helpers
In, andNotIn. #501
- Added regular expression assertion helpers
- Added module version constraints. #498
- The module versions that PSRule uses can be constrained.
- Added
- Bug fixes:
- Fixed styling for no rule files warning with
Assert-PSRule. #484 - Fixed actual value in reason for numeric comparison assertion method. #505
- Fixed styling for no rule files warning with
- Bug fixes:
- Fixed unable to read properties for .NET
DynamicObject. #491 - Fixed read of JSON input format with null array item. #490
- Fixed
Csvoutput format with summary forInvoke-PSRule. #486
- Fixed unable to read properties for .NET
- Bug fixes:
- Fixed unable to read properties for .NET
DynamicObject. #491 - Fixed read of JSON input format with null array item. #490
- Fixed unable to read properties for .NET
- Bug fixes:
- Fixed
Csvoutput format with summary forInvoke-PSRule. #486
- Fixed
- General improvements:
- Improved
Assert-PSRuleoutput formatting. #472- Added recommendation and reasons for
AzurePipelinesandGitHubActionsstyles. - Summary line is has been updated to include synopsis instead of reasons.
- Added recommendation and reasons for
- Improved
- Bug fixes:
- Fixed binding with
ModuleConfig. #468 - Fixed recommendation output with client style. #467
- Fixed binding with
- No additional changes.
- General improvements:
- Improved
Assert-PSRuleoutput formatting. #472- Added recommendation and reasons for
AzurePipelinesandGitHubActionsstyles. - Summary line is has been updated to include synopsis instead of reasons.
- Added recommendation and reasons for
- Improved
- Bug fixes:
- Fixed binding with
ModuleConfig. #468 - Fixed recommendation output with client style. #467
- Fixed binding with
- General improvements:
- Improved
Assert-PSRuleoutput formatting.- Added recommendation and reasons for
ClientandPlainstyles. #456
- Added recommendation and reasons for
- Added support for configuration of default module options. #459
bindingandconfigurationoptions can be set to a default value.- Updated
New-PSRuleOptionparameter sets and help based on updates to module config.
- Added support for module fallback culture. #441
- Improved
- Bug fixes:
- Fixed resource schema to include
useQualifiedNameandnameSeparatoroption. #458
- Fixed resource schema to include
- No additional changes.
- General improvements:
- Improved
Assert-PSRuleoutput formatting.- Added recommendation and reasons for
ClientandPlainstyles. #456
- Added recommendation and reasons for
- Added support for configuration of default module options. #459
bindingandconfigurationoptions can be set to a default value.- Updated
New-PSRuleOptionparameter sets and help based on updates to module config.
- Added support for module fallback culture. #441
- Improved
- Bug fixes:
- Fixed resource schema to include
useQualifiedNameandnameSeparatoroption. #458
- Fixed resource schema to include
- General improvements:
- Added configuration option
Output.Culturefor setting culture. #442 - Improved handling of fields to allow the input object to be referenced with
.. #437
- Added configuration option
- Bug fixes:
- Fixed numeric comparison assertion with non-int types. #436
- Fixed output culture option ignored. #449
- No additional changes.
- Bug fixes:
- Fixed output culture option ignored. #449
- General improvements:
- Added configuration option
Output.Culturefor setting culture. #442 - Improved handling of fields to allow the input object to be referenced with
.. #437
- Added configuration option
- Bug fixes:
- Fixed numeric comparison assertion with non-int types. #436
- Engine features:
- Added
-ResultVariableto store results from Assert-PSRule into a variable. #412
- Added
- General improvements:
- Added recommendation to failure message of NUnit results. #421
- Bug fixes:
- Fixed handling of
vin field value with$Assert.Version. #429 - Fixed handling of warning action preference with
Assert-PSRule. #428 - Fixed parent culture unwind with POSIX. #414
- Fixed output of warning with
Assert-PSRule. #417 - Fixed NUnit report to include a failure element when reason is not specified. #420
- Fixed handling of
- No additional changes.
- Fixed handling of
vin field value with$Assert.Version. #429 - Fixed handling of warning action preference with
Assert-PSRule. #428 - Added
-ResultVariableto store results from Assert-PSRule into a variable. #412 - Fixed output of warning with
Assert-PSRule. #417 - Fixed NUnit report to include a failure element when reason is not specified. #420
- Added recommendation to failure message of NUnit results. #421
- Fixed parent culture unwind with POSIX. #414
- Engine features:
- Added support for qualified target names. #395
- Added options
Binding.UseQualifiedNameandBinding.NameSeparator. - See
about_PSRule_Optionsfor details.
- Added options
- Added assertion method
HasJsonSchemato check if a JSON schema is referenced. #398- See
about_PSRule_Assertfor usage details.
- See
- Added file content helper for reading objects from files. #399
- The method
GetContentof$PSRulecan be used to read files as objects. - See
about_PSRule_Variablesfor usage details.
- The method
- Added support for qualified target names. #395
- General improvements:
- Improved reporting on runtime errors in rule blocks. #239
- Improved NUnit results to include a failure message based on reported reasons. #404
- Bug fixes:
- Fixed wide formatting of rules with
Get-PSRule. #407 - Fixed TargetName hash serialization for base types. #406
- Fixed output not generated with Assert-PSRule and Stop. #405
- Fixed NUnit results incorrectly reporting that the test had not executed. #403
- Fixed wide formatting of rules with
- No additional changes
- Fixed wide formatting of rules with
Get-PSRule. #407 - Fixed TargetName hash serialization for base types. #406
- Fixed output not generated with Assert-PSRule and Stop. #405
- Fixed NUnit results incorrectly reporting that the test had not executed. #403
- Improved NUnit results to include a failure message based on reported reasons. #404
- Improved reporting on runtime errors in rule blocks. #239
- Added support for qualified target names. #395
- Added options
Binding.UseQualifiedNameandBinding.NameSeparator. - See
about_PSRule_Optionsfor details.
- Added options
- Added assertion method
HasJsonSchemato check if a JSON schema is referenced. #398- See
about_PSRule_Assertfor usage details.
- See
- Added file content helper for reading objects from files. #399
- The method
GetContentof$PSRulecan be used to read files as objects. - See
about_PSRule_Variablesfor usage details.
- The method
- Engine features:
- Improvements to rule help and documentation. #382 #316
- Added links and notes sections to help.
- Added
-Fullswitch toGet-PSRuleHelpto display links and notes sections. - Added support for using a parent culture in rule help.
- Rule help will use parent culture when a more specific culture is not available.
- Added input format for reading PowerShell data
.psd1files. #368PowerShellDatahas been added toInput.Format.- See
about_PSRule_Optionsfor details.
- Added custom rule data to results. #322
$PSRule.Datacan be used to set custom data during rule execution that is included in output.- See
about_PSRule_Variablesfor usage details.
- Improvements to assertion methods. #386 #374 #387 #344 #353 #357
- Added support for assertion methods to be used within script pre-conditions.
- Added numeric comparison assertion helpers
Greater,GreaterOrEqual,LessandLessOrEqual. - Added semantic version assertion helper
Version. - Added string affix assertion helpers
StartsWith,EndsWithandContains. - See
about_PSRule_Assertfor usage details.
- Improvements to output logging and formatting for
Assert-PSRule.- Formatting now includes errors and warnings using style.
- Added PSRule banner with module information.
- Added rule success summary.
- Improvements to rule help and documentation. #382 #316
- General improvements:
- Added aliases for
-OutputFormat(-o) and-Module(-m) parameters. #384 - Added
WithReasonto append/ replace reasons from assertion result. #354 - Added configuration helper for strings arrays. #363
- Added aliases for
- Bug fixes:
- Fixed JSON de-serialization fails with single object. #379
- Fixed stack overflow when parsing malformed JSON. #380
- No additional changes.
- Fixed JSON de-serialization fails with single object. #379
- Fixed stack overflow when parsing malformed JSON. #380
- Added rule documentation links and notes to help. #382
- Added
-Fullswitch toGet-PSRuleHelpto display links and notes sections.
- Added
- Added aliases for
-OutputFormat(-o) and-Module(-m) parameters. #384 - Improved numeric comparison assertion helpers to support strings. #387
- Methods
Greater,GreaterOrEqual,LessandLessOrEqualnow also check string length.
- Methods
- Added support for assertion methods to be used within script pre-conditions. #386
- Added input format for reading PowerShell data
.psd1files. #368PowerShellDatahas been added toInput.Format.- See
about_PSRule_Optionsfor details.
- Added numeric comparison assertion helpers. #374
- Added methods
Greater,GreaterOrEqual,LessandLessOrEqual. - See
about_PSRule_Assertfor usage details.
- Added methods
- Added configuration helper for strings arrays. #363
- Added support for using a parent culture in rule help. #316
- Rule help will use parent culture when a more specific culture is not available.
- Added custom rule data to results. #322
$PSRule.Datacan be used to set custom data during rule execution that is included in output.- See
about_PSRule_Variablesfor usage details.
- Improves output logging and formatting for Assert-PSRule. #357
- Formatting now includes errors and warnings using style.
- Added PSRule banner with module information.
- Added rule success summary.
- Added semantic version assertion helper
Version. #344 - Added string affix assertion helpers. #353
- Added methods
StartsWith,EndsWithandContains. Seeabout_PSRule_Assertfor usage details.
- Added methods
- Added
WithReasonto append/ replace reasons from assertion result. #354 - Engine features:
- Added
-Alloption toExistskeyword. #331 - Added custom field binding. #321
- Added new option
Binding.Fieldavailable in baselines to configure binding.
- Added new option
- Added
- General improvements:
- Added filtering for rules against a baseline with
Get-PSRule. #345 - Added parameter alias
-ffor-InputPath. #340-fwas added toInvoke-PSRule,Assert-PSRuleandTest-PSRuleTargetcmdlets.
- Added filtering for rules against a baseline with
- Important change: Added
$PSRulegeneric context variable. #341- Deprecated
TargetName,TargetTypeandTargetObjectproperties on$Rule. - Use
TargetName,TargetTypeandTargetObjecton$PSRuleinstead. - Properties
TargetName,TargetTypeandTargetObjecton$Rulewill be removed in the future. - Going forward
$Rulewill only contain properties that relate to the current rule context.
- Deprecated
- Bug fixes:
- Fixed key has already been added for default baseline. #349
- Fixed multiple value tag filtering. #346
- Fixed TargetType fall back to type name. #339
- Fixed NUnit serialization issue for unprocessed rules. #332
- Fixed key has already been added for default baseline. #349
- Fixed multiple value tag filtering. #346
- Added filtering for rules against a baseline with
Get-PSRule. #345 - Fixed TargetType fall back to type name. #339
- Added custom field binding. #321
- Added new option
Binding.Fieldavailable in baselines to configure binding.
- Added new option
- Added parameter alias
-ffor-InputPath. #340-fwas added toInvoke-PSRule,Assert-PSRuleandTest-PSRuleTargetcmdlets.
- Important change: Added
$PSRulegeneric context variable. #341- Deprecated
TargetName,TargetTypeandTargetObjectproperties on$Rule. - Use
TargetName,TargetTypeandTargetObjecton$PSRuleinstead. - Properties
TargetName,TargetTypeandTargetObjecton$Rulewill be removed in the future. - Going forward
$Rulewill only contain properties that relate to the current rule context.
- Deprecated
- Fixed NUnit serialization issue for unprocessed rules. #332
- Added
-Alloption toExistskeyword. #331 - General improvements:
- Added
-TargetTypeparameter to filter input objects by target type. #176- This parameter applies to
Invoke-PSRule,Assert-PSRuleandTest-PSRuleTarget.
- This parameter applies to
- Added
- Bug fixes:
- Fixed null reference exception when bound property is null. #323
- Fixed missing
Markdowninput format in options schema. #315
- Breaking change: Unprocessed object results are not returned from
Test-PSRuleTargetby default. #318- Previously unprocessed objects returned
$True, now unprocessed objects return no result. - Use
-Outcome Allto return$Truefor unprocessed objects the same as <= v0.10.0.
- Previously unprocessed objects returned
- No additional changes.
- Fixed null reference exception when bound property is null. #323
- Fixed missing
Markdowninput format in options schema. #315 - Added
-TargetTypeparameter to filter input objects by target type. #176- This parameter applies to
Invoke-PSRule,Assert-PSRuleandTest-PSRuleTarget.
- This parameter applies to
- Breaking change: Unprocessed object results are not returned from
Test-PSRuleTargetby default. #318- Previously unprocessed objects returned
$True, now unprocessed objects return no result. - Use
-Outcome Allto return$Truefor unprocessed objects the same as <= v0.10.0.
- Previously unprocessed objects returned
- General improvements:
- Added source note properties to input objects read from disk with
-InputPath. #302
- Added source note properties to input objects read from disk with
- Engine features:
- Added assertion helper for checking field default value. #289
- Added dependency
DependsOninformation to results fromGet-PSRule. #210- To include dependencies that would normally be filtered out use
-IncludeDependencies.
- To include dependencies that would normally be filtered out use
- Added input format for reading markdown front matter. #301
- Markdown front matter is deserialized and evaluated as an object.
- Added
Assert-PSRulecmdlet to improve integration into CI processes. #290- Added
Output.Styleoption to support output in the following styles:- Client/ Plain - Output returns easy to read log of rule pass/ fail.
- Azure Pipelines - Report rule failures as errors collected by Azure Pipelines.
- GitHub Actions - Reports rule failures as errors collected by GitHub Actions.
- Added
- Bug fixes:
- Fix
Get-PSRuleHelp-Online in constrained language mode. #296
- Fix
- Breaking change: Removed previously deprecated alias
HintforRecommend. #165- Use the
Recommendkeyword instead.
- Use the
- No additional changes.
- Added dependency
DependsOninformation to results fromGet-PSRule. #210- To include dependencies that would normally be filtered out use
-IncludeDependencies.
- To include dependencies that would normally be filtered out use
- Added input format for reading markdown front matter. #301
- Markdown front matter is deserialized and evaluated as an object.
- Added source note properties to input objects read from disk with
-InputPath. #302 - Breaking change: Removed previously deprecated alias
HintforRecommend. #165- Use the
Recommendkeyword instead.
- Use the
- Fix
Get-PSRuleHelp-Online in constrained language mode. #296 - Added
Assert-PSRulecmdlet to improve integration into CI processes. #290- Added
Output.Styleoption to support output in the following styles:- Client/ Plain - Output returns easy to read log of rule pass/ fail.
- Azure Pipelines - Report rule failures as errors collected by Azure Pipelines.
- GitHub Actions - Reports rule failures as errors collected by GitHub Actions.
- Added
- Added assertion helper for checking field default value. #289
- General improvements:
- Improve feedback of parsing errors. #185
- Updated
Get-PSRuleHelpto include help within the current path by default. #197
- Engine features:
- Added support for a wildcard match using the
Withinkeyword. #272 - Added rule info display name. #276
- Added support for matching an array of tag values. #282
- Added named baselines. Now baselines are a separate resource that can be individually used.
- Baselines can be packaged within module.
- Modules can specify a default baseline in module manifest.
- Target binding options (
Binding) are now part of baselines. - See about_PSRule_Baseline for more information.
- Added support for a wildcard match using the
- Bug fixes:
- Fix can not serialize nested System.IO.DirectoryInfo property. #281
- Fix ModuleName not displayed in Get-PSRuleHelp list. #275
- Fix outcome reported when error or exception is raised. #211
- Breaking change: Baseline improvements, fundamentally changes how baselines work. #274
- Previously, baselines were specified as workspace options.
- The previous
baselineoptions property has been renamed torule. - The previous
configurationproperty is now a top level option.
- No additional changes
- Added support for matching an array of tag values. #282
- Updated
Get-PSRuleHelpto include help within the current path by default. #197 - Fix can not serialize nested System.IO.DirectoryInfo property. #281
- Fix export of
Likeparameter forWithinkeyword. #279 - Breaking change: Added named baselines. This changes how baselines work. #274
- Previously, baselines were specified as workspace options.
- Now, baselines are a separate resource that can be individually used. Additionally:
- Baselines can be packaged within module.
- Modules can specify a default baseline in module manifest.
- Target binding options (
Binding) are now part of baselines.
- The previous
baselineoptions property has been renamed torule. - The previous
configurationproperty is now a top level option. - See about_PSRule_Baseline for more information.
- Added support for a wildcard match using the
Withinkeyword. #272 - Added rule info display name. #276
- Fix ModuleName not displayed in Get-PSRuleHelp list. #275
- Improve feedback of parsing errors. #185
- Fix outcome reported when error or exception is raised. #211
- General improvements:
- PSRule options are now displayed as YAML instead of a complex object. #233
- Add detection for improper keyword use. #203
- Automatically load rule modules. #218
- Added support for debug messages and
Write-Debugin rule definitions. #146 - Added
Logging.LimitDebugandLogging.LimitVerboseoptions to limit logging to named scopes. #235
- Engine features:
- Added per object reason for failing rules. #200
- Keywords
Exists,Match,WithinandTypeOfautomatically add a reason when they fail. - Custom reason can be set for keywords
Exists,Match,WithinandTypeOfwith-Reason. - Added
Reasonkeyword to add to reason for custom logic. - Added wide output display for
Invoke-PSRulewhich include the reason why rule failed.- To use wide output use the
-OutputFormat Wideparameter.
- To use wide output use the
- Renamed
-Messageparameter to-Texton theRecommendkeyword.- The
-Messageis an alias of-Textand will be deprecated in the future.
- The
- Keywords
- Added assertion helper
$Assertfor extensibility. #250- Add built-in assertions for
HasField,HasFieldValueandNullOrEmpty. - Add JSON schema assertion method
JsonSchema. #42
- Add built-in assertions for
- Added per object reason for failing rules. #200
- Bug fixes:
- Fix rule synopsis comment capture. #214
- Fix YAML options file discovery issue in dotted directory. #232
- Fix comparison of wrapped types and null with
Within. #237
- Breaking change: Use rule references consistent with cmdlet fully qualified syntax. #217
- Rule names have to be unique within the current execution path or within a module.
- Previously rule names only had to be unique within a single file.
- Previously the
filename.rule.ps1/RuleNamewas required to reference rules across files.- This is no longer required because rule names are unique.
- You can reference a rule from a loaded module by using the syntax
ModuleName\\RuleName.
- Rule names have to be unique within the current execution path or within a module.
- Fix export of assertion helper variable
$Assert. #262 - Fix module reloading with different versions. #254
- Fix not finding rules in current path by default. #256
- Fix rule synopsis comment capture. #214
- Fix inconsistent handling of
$PWD. #249 - Add detection for improper keyword use. #203
- Automatically load rule modules. #218
- Added assertion helper
$Assertfor extensibility. #250- Add built-in assertions for
HasField,HasFieldValueandNullOrEmpty. - Add JSON schema assertion method
JsonSchema. #42
- Add built-in assertions for
- Breaking change: Use rule references consistent with cmdlet fully qualified syntax. #217
- Rule names have to be unique within the current execution path or within a module.
- Previously rule names only had to be unique within a single file.
- Previously the
filename.rule.ps1/RuleNamewas required to reference rules across files.- This is no longer required because rule names are unique.
- You can reference a rule from a loaded module by using the syntax
ModuleName\\RuleName.
- Rule names have to be unique within the current execution path or within a module.
- Added per object reason for failing rules. #200
- The keywords
Exists,Match,WithinandTypeOfautomatically add a reason when they fail. - Added
-Reasonparameter toExists,Match,WithinandTypeOfkeywords to allow a custom reason to be set. - Added
Reasonkeyword to add to reason for custom logic. - Added wide output display for
Invoke-PSRulewhich include the reason why rule failed.- To use wide output use the
-OutputFormat Wideparameter.
- To use wide output use the
- Renamed
-Messageparameter to-Texton theRecommendkeyword.- The
-Messageis an alias of-Textand will be deprecated in the future.
- The
- The keywords
- Fix YAML options file discovery issue in dotted directory. #232
- Fix comparison of wrapped types and null with
Within. #237 - PSRule options are now displayed as YAML instead of a complex object. #233
- Added support for debug messages and
Write-Debugin rule definitions. #146 - Added
Logging.LimitDebugandLogging.LimitVerboseoptions to limit logging to named scopes. #235 - Fix reading nested arrays from JSON input. #223
- Fix comparison of non-string types with
Within. #226 - Fix circular rule dependency issue. #190
- Fix rule
DependsOnparameter allows null. #191 - Fix error message when attempting to use the rule keyword in a rule definition. #189
- Fix TargetName binding when TargetName or Name property is null. #202
- Fix handling of non-boolean results in rules. Rule is failed with more specific error message. #187 #224
- Include .ps1 files that are specified directly with
-Path, instead of only .Rule.ps1 files. #182- Improved warning message displayed when no Rule.ps1 files are founds.
- Added support for
Invoke-PSRuleto return CSV formatted results. #169- To generate CSV results use the
-OutputFormat Csvparameter. - Added
Output.Pathoption to allow output to be saved directly to file. - Added
Output.Encodingoption configure encoding used to write to file. - By default, UTF-8 encoding without BOM is used.
Invoke-PSRulecmdlet also provides a parameter-OutputPathto write results to file.
- To generate CSV results use the
- Reordered cmdlet parameters to improve usage of frequently used parameters. #175
-Moduleparameter will tab-complete with imported rule modules.
- Added culture support for PowerShell informational messages. #158
- A new
$LocalizedDatavariable can be used within rule definitions.
- A new
- Added
-Notswitch toWithinandMatchkeywords to allow negative comparison. #208 - Improve discovery of rule tags. #209
- Add wide format
-OutputFormat WidetoGet-PSRuleto allow output of rule tags.
- Add wide format
- Breaking change: Changed rule filtering by tag to be case-insensitive. #204
- Previously tag value was case-sensitive, however this is confusing since PowerShell is case-insensitive by default.
- Breaking change: Rule time is recorded in milliseconds instead of seconds. #192
- No additional changes.
- Fix reading nested arrays from JSON input. #223
- Fix comparison of non-string types with
Within. #226 - Improve handling of null rule result. #224
- Fix TargetName binding when TargetName or Name property is null. #202
- Add culture support for PowerShell informational messages. #158
- A new
$LocalizedDatavariable can be used within rule definitions.
- A new
- Add
-Notswitch toWithinandMatchkeywords to allow negative comparison. #208 - Improve discovery of rule tags. #209
- Add wide format
-OutputFormat WidetoGet-PSRuleto allow output of rule tags.
- Add wide format
- Breaking change: Change rule filtering by tag to be case-insensitive. #204
- Previously tag value was case-sensitive, however this is confusing since PowerShell is case-insensitive by default.
- Fix circular rule dependency issue. #190
- Fix rule
DependsOnparameter allows null. #191 - Fix error message when attempting to use the rule keyword in a rule definition. #189
- Breaking change: Rule time is recorded in milliseconds instead of seconds. #192
- Fix handling of non-boolean results in rules. Rule is failed with more specific error message. #187
- Include .ps1 files that are specified directly with
-Path, instead of only .rule.ps1 files. #182- Improved warning message displayed when no Rule.ps1 files are founds.
- Added support for
Invoke-PSRuleto return CSV formatted results. #169- To generate CSV results use the
-OutputFormat Csvparameter. - Added
Output.Pathoption to allow output to be saved directly to file. - Added
Output.Encodingoption configure encoding used to write to file. - By default, UTF-8 encoding without BOM is used.
Invoke-PSRulecmdlet also provides a parameter-OutputPathto write results to file.
- To generate CSV results use the
- Reordered cmdlet parameters to improve usage of frequently used parameters. #175
-Moduleparameter will tab-complete with imported rule modules.
- Fix operation is not supported on this platform failure. #152
- Fix FullName cannot be found on this object error. #149
- Fix discovery of rules within paths that contain spaces fails. #168
- Added rule documentation, which allows additional rule information to be stored in markdown files. #157
- Rule documentation also adds culture support. #18
- Rule documentation can be accessed like help with the
Get-PSRuleHelpcmdlet.
- Added annotations, which are non-indexed metadata stored in rule documentation. #148
- Annotations can contain a link to online version of the documentation. #147
- Important change: Changed
Hintkeyword toRecommendto align with rule documentation. #165- Use of
Hintkeyword is deprecated and will be removed in a future release. CurrentlyHintis aliased toRecommendfor compatibility.
- Use of
- Breaking change: Changed rule properties to align with rule documentation. #164
- Rule
Synopsis, is a brief summary of the rule andDescriptionis a detailed purpose of the rule. Description:metadata keyword used in comment help is nowSynopsis:, use ofDescription:will set synopsis. Description metadata keyword is deprecated and will be removed in a future update.- Output property
Messageon rule results is nowRecommendation.
- Rule
- Fix discovery of rules within paths that contain spaces fails. #168
- Fix exporting of
Recommendkeyword andHintalias. #171 - Important change: Changed
Hintkeyword toRecommendto align with rule documentation. #165- Use of
Hintkeyword is deprecated and will be removed in a future release. CurrentlyHintis aliased toRecommendfor compatibility.
- Use of
- Breaking change: Changed rule properties to align with rule documentation. #164
- Rule
Synopsis, is a brief summary of the rule andDescriptionis a detailed purpose of the rule. Description:metadata keyword used in comment help is nowSynopsis:, use ofDescription:will set synopsis. Description metadata keyword is deprecated and will be removed in a future update.- Output property
Messageon rule results is nowRecommendation.
- Rule
- Added rule documentation, which allows additional rule information to be stored in markdown files. #157
- Rule documentation also adds culture support. #18
- Rule documentation can be accessed like help with the
Get-PSRuleHelpcmdlet.
- Added annotations, which are non-indexed metadata stored in rule documentation. #148
- Annotations can contain a link to online version of the documentation. #147
- Fix operation is not supported on this platform failure. #152
- Fix FullName cannot be found on this object error. #149
- Fix PSRule options schema usage of additionalProperties. #136
- Fix null reference exception when traversing null field. #123
- Fix missing help topics for options and variables. #125
- Improved handling of default YAML options file. #137
- Added support for
Invoke-PSRuleto return NUnit3 formatted results. #129- To generate NUnit3 results use the
-OutputFormat NUnit3parameter.
- To generate NUnit3 results use the
- Added
Set-PSRuleOptioncmdlet to configure YAML options file. #135 - Added parameters to New-PSRuleOption to configure common options. #134
- Additional parameters are an alternative to using a
-Optionhashtable.
- Additional parameters are an alternative to using a
- Fix schema conformance of
-OutputFormat NUnit3to NUnit report schema. #141 - Fix PSRule options schema usage of additionalProperties. #136
- Added support for
Invoke-PSRuleto return NUnit3 formatted results. #129- To generate NUnit3 results use the
-OutputFormat NUnit3parameter.
- To generate NUnit3 results use the
- Added
Set-PSRuleOptioncmdlet to configure YAML options file. #135 - Added parameters to New-PSRuleOption to configure common options. #134
- Additional parameters are an alternative to using a
-Optionhashtable.
- Additional parameters are an alternative to using a
- Improved handling of default YAML options file. #137
- Fix null reference exception when traversing null field. #123
- Fix missing help topics for options and variables. #125
- Fix incorrect JSON de-serialization. #109 #111
- Added support for using
-InputPathinstead of using-InputObjectto handle serialized objects. #106-Formatis automatically detected for.yaml,.ymland.jsonfile extensions.
- Added
-OutputFormatparameter to serialize output fromInvoke-PSRuleas YAML or JSON. #29 - Added support for logging pass or fail outcomes to a data stream such as Error, Warning or Information. #97
- Breaking change: Deprecated usage of the
-TargetNameparameter on theHintkeyword has been removed. #81 - No additional changes.
- Fix summary is not correctly serialized with JSON or YAML output format. #116
- Fix missing properties on serialized YAML output. #115
- Fix incorrect property name case of YAML serialized results. #114
- Fix incorrect JSON de-serialization of nested arrays. #109
- Fix incorrect JSON de-serialization of non-object arrays. #111
- Added support for using
-InputPathinstead of using-InputObjectto handle serialized objects. #106-Formatis automatically detected for.yaml,.ymland.jsonfile extensions.
- Added
-OutputFormatparameter to serialize output fromInvoke-PSRule. #29 - Added support for logging pass or fail outcomes to a data stream such as Error, Warning or Information. #97
- Breaking change: Deprecated usage of the
-TargetNameparameter on theHintkeyword has been removed. #81 - Added support for pipelining with
Exists,Within,MatchandTypeOfkeywords #90 - Added support for packaging rules in modules #16
- Import objects from YAML or JSON format #75
- Added support for input de-serialization from FileInfo objects #95
- Support nested TargetObjects #77
- Export variables to improve authoring experience #83
- Binding improvements:
- Added object type binding and dynamic filtering for rules #82
- Added support for indexed and quoted field names #86
- Added support for case-sensitive binding operations #87
- Binding ignores case by default. Set option
Binding.CaseSensitivetotrueto enable case-sensitivity.
- Binding ignores case by default. Set option
- Support TargetName binding of nested properties #71
- Added online help links to keywords #72
- Added schema for PSRule options #74
- Important change: The
-TargetNameparameter of theHintkeyword has been deprecated #81-TargetNameparameter not longer sets the pipeline object TargetName and generates a warning instead.- The
-TargetNamewill be completely removed in v0.4.0, at which time using the parameter will generate an error.
- Breaking change: Changed parameter alias for
-Pathfrom-fto-p#99 - Added support for input de-serialization from FileInfo objects #95
- Breaking change: Changed parameter alias for
-Pathfrom-fto-p#99 - Added support for pipelining with
Exists,Within,MatchandTypeOfkeywords #90 - Fix empty YAML object causes format de-serialize to fail #92
- Export variables to improve authoring experience #83
- Added support for packaging rules in modules #16
- Added support for indexed and quoted field names #86
- Added object type binding and dynamic filtering for rules #82
- Added support for case-sensitive binding operations #87
- Binding ignores case by default. Set option
Binding.CaseSensitivetotrueto enable case-sensitivity.
- Binding ignores case by default. Set option
- Important change: The
-TargetNameparameter of theHintkeyword has been deprecated #81-TargetNameparameter not longer sets the pipeline object TargetName and generates a warning instead.- The
-TargetNamewill be completely removed in v0.4.0, at which time using the parameter will generate an error.
- Added online help links to keywords #72
- Added schema for PSRule options #74
- Import objects from YAML or JSON format #75
- Support TargetName binding of nested properties #71
- Support nested TargetObjects #77
- Added support for cross-platform environments (Windows, Linux and macOS) #49
- Added support for nested field names with
Exists,WithinandMatchkeywords #60 - Added support for rule configuration using baselines #17
- Use rule description when hint message not set #61
- Allow objects to be suppressed by TargetName for individual rules #13
- Allow binding of TargetName to custom property #44
- Custom functions can be used to bind TargetName #44
- Objects that are unable to bind a TargetName will use a SHA1 object hash for TargetName #44
- Added
Test-PSRuleTargetcommand to return an overall$Trueor$Falseafter evaluating rules for an object #30 - Improve reporting of inconclusive results and objects that are not processed by any rule #46
- Inconclusive results and objects not processed will return a warning by default.
- Fix propagation of informational messages to host from rule scripts and definitions #48
- Fix Get-PSRule generates exception when no .rule.ps1 scripts exist in path #53
- Fix LocalizedData.PathNotFound warning when no .rule.ps1 scripts exist in path #54
- No additional changes.
- Added support for nested field names with
Exists,WithinandMatchkeywords #60 - Added support for rule configuration using baselines #17
- Use rule description when hint message not set #61
- Fix Get-PSRule generates exception when no .rule.ps1 scripts exist in path #53
- Fix LocalizedData.PathNotFound warning when no .rule.ps1 scripts exist in path #54
- Breaking change: Renamed
Test-PSRulecmdlet toTest-PSRuleTargetwhich aligns more closely to the verb-noun naming standard #57 - Allow objects to be suppressed by TargetName for individual rules #13
- Allow binding of TargetName to custom property #44
- Custom functions can be used to bind TargetName #44
- Objects that are unable to bind a TargetName will use a SHA1 object hash for TargetName #44
- Added
Test-PSRulecommand to return an overall$Trueor$Falseafter evaluating rules for an object #30 - Improve reporting of inconclusive results and objects that are not processed by any rule #46
- Inconclusive results and objects not processed will return a warning by default.
- Fix propagation of informational messages to host from rule scripts and definitions #48
- Added support for cross-platform environments (Windows, Linux and macOS) #49
- Initial release
- Fix outcome filtering of summary results #33
- Fix target object counter in verbose logging #35
- Fix hashtable keys should be handled as fields #36
- RuleId and RuleName are now independent. Rules are created with a name, and the RuleId is generated based on rule name and file name
- Rules with the same name can exist and be cross linked with DependsOn, as long a the script file name is different
- Added
-NottoExistskeyword - Improved verbose logging of
Exists,AllOf,AnyOfkeywords and core engine - Breaking change: Renamed outcome filtering parameters to align to type name and increase clarity
Invoke-PSRulehas a-Outcomeparameter instead of-Status-Outcomesupports values ofPass,Fail,Error,None,ProcessedandAll
- Added rule tags to results to enable grouping and sorting #14
- Added support to check for rule tag existence. Use
*for tag value on-Tagparameter withInvoke-PSRuleandGet-PSRule - Added option to report rule summary using
-Asparameter ofInvoke-PSRule#12 - Initial pre-release.
- YAML resources will require an
apiVersionfrom PSRule v2. #648 - Setting the default module baseline requires a module configuration from PSRule v2. #809
- Resource names have naming restrictions introduced from PSRule v2. #1012
- Bug fixes:
- Fixed broken documentation links. #980
- General improvements:
- Added
versionexpression to check semantic version constraints. #861- See about_PSRule_Expressions for details.
- Added
hasDefaultexpression to check field default value. #870- See about_PSRule_Expressions for details.
- Added
- Bug fixes:
- Fixed
GetReason()not returning results for a failed assertion. #874
- Fixed
- No additional changes.
- General improvements:
- Added
versionexpression to check semantic version constraints. #861- See about_PSRule_Expressions for details.
- Added
hasDefaultexpression to check field default value. #870- See about_PSRule_Expressions for details.
- Added
- Bug fixes:
- Fixed
GetReason()not returning results for a failed assertion. #874
- Fixed
- General improvements:
- Added JSON support for reading rules and selectors from pipeline. #857
- Added
HasSchemaexpression to check the schema of an object. #860- See about_PSRule_Expressions for details.
- Engineering:
- Bump Microsoft.SourceLink.GitHub to 1.1.1. #856
- Bug fixes:
- Fixed
$Assert.HasJsonSchemaaccepts empty value. #859 - Fixed module configuration is not loaded when case does not match. #864
- Fixed
- No additional changes.
- Bug fixes:
- Fixed module configuration is not loaded when case does not match. #864
- General improvements:
- Added JSON support for reading rules and selectors from pipeline. #857
- Added
HasSchemaexpression to check the schema of an object. #860- See about_PSRule_Expressions for details.
- Engineering:
- Bump Microsoft.SourceLink.GitHub to 1.1.1. #856
- Bug fixes:
- Fixed
$Assert.HasJsonSchemaaccepts empty value. #859
- Fixed
- General improvements:
- Added improvements to YAML output for
Get-PSRuleBaseline. #829 - Added
-Initializeconvention block. #826- Use this block to perform any initialization that is required before any rules are run.
- This block is only run once instead of
-Beginwhich is run once per object. - See about_PSRule_Conventions for details.
- Allow lifetime services to be used. #827
- Use
$PSRule.AddServiceand$PSRule.GetServiceto add a service. - Services allows a singleton instance to be used and shared across multiple rules.
- PSRule will automatically dispose the service when all rules have run.
- See about_PSRule_Variables for details.
- Use
- Added
Export-PSRuleBaselinecmdlet to export baseline. #622 - Added JSON output format for Baseline cmdlets. #839
- Allow downstream issues to be consumed. #843
- Objects can be flagged with issues that have been generated externally.
- See about_PSRule_Assert for details.
- Migrated default baseline to module configuration. #809
- This enables configuration of the default baseline for a module with a module configuration.
- This depreciate configuring the default baseline within the module manifest.
- Modules using manifest configuration will start warning from v1.9.0.
- See about_PSRule_Options for details.
- Added JSON support to read baselines from pipeline. #845
- Added improvements to YAML output for
- Engineering:
- Bump System.Drawing.Common dependency to v6.0.0. #848
- Bug fixes:
- Fixed convention execution is out of order. #835
- Engineering:
- Bump Microsoft.CodeAnalysis.NetAnalyzers to v6.0.0. #851
- General improvements:
- Allow downstream issues to be consumed. #843
- Objects can be flagged with issues that have been generated externally.
- See about_PSRule_Assert for details.
- Migrated default baseline to module configuration. #809
- This enables configuration of the default baseline for a module with a module configuration.
- This depreciate configuring the default baseline within the module manifest.
- Modules using manifest configuration will start warning from v1.9.0.
- See about_PSRule_Options for details.
- Added JSON support to read baselines from pipeline. #845
- Allow downstream issues to be consumed. #843
- Engineering:
- Bump System.Drawing.Common dependency to v6.0.0. #848
- General improvements:
- Added JSON output format for Baseline cmdlets. #839
- Bug fixes:
- Fixed convention execution is out of order. #835
- General improvements:
- Added
Export-PSRuleBaselinecmdlet to export baseline. #622
- Added
- General improvements:
- Added improvements to YAML output for
Get-PSRuleBaseline. #829 - Added
-Initializeconvention block. #826- Use this block to perform any initialization that is required before any rules are run.
- This block is only run once instead of
-Beginwhich is run once per object. - See about_PSRule_Conventions for details.
- Allow lifetime services to be used. #827
- Use
$PSRule.AddServiceand$PSRule.GetServiceto add a service. - Services allows a singleton instance to be used and shared across multiple rules.
- PSRule will automatically dispose the service when all rules have run.
- See about_PSRule_Variables for details.
- Use
- Added improvements to YAML output for
- General improvements:
- Added YAML output format support for
Get-PSRuleBaseline. #326 - Added YAML/JSON output format support for
Get-PSRule. #128 - Added
Output.JsonIndentoption for JSON output format. #817 - Added assertion helpers and expressions for improving intersection checks. #795
- Added
Countto determine of the field has a specific number of elements. - Added
SetOfto determine if a collection is another collection. - Added
Subsetto determine if a collection is includes another collection. - See about_PSRule_Assert and about_PSRule_Expressions for details.
- Added
- Added support for conditional reason messages with
ReasonIf. #804- See about_PSRule_Assert for details.
- Added support for
typeandnameexpression properties. #810- Use
typeto compare the bound type of the current object. - Use
nameto compare the bound name of the current object. - See about_PSRule_Expressions for details.
- Use
- Added YAML output format support for
- Engineering:
- Migration of Pester v4 tests to Pester v5. #478
- No additional changes.
- General improvements:
- Added
Output.JsonIndentoption for JSON output format. #817
- Added
- General improvements:
- Added YAML/JSON output format support for
Get-PSRule. #128
- Added YAML/JSON output format support for
- Engineering:
- Migration of Pester v4 tests to Pester v5. #478
- General improvements:
- Added YAML output format support for
Get-PSRuleBaseline. #326
- Added YAML output format support for
- General improvements:
- Added support for conditional reason messages with
ReasonIf. #804- See about_PSRule_Assert for details.
- Added support for
typeandnameexpression properties. #810- Use
typeto compare the bound type of the current object. - Use
nameto compare the bound name of the current object. - See about_PSRule_Expressions for details.
- Use
- Added support for conditional reason messages with
- General improvements:
- Added assertion helpers and expressions for improving intersection checks. #795
- Added
Countto determine of the field has a specific number of elements. - Added
SetOfto determine if a collection is another collection. - Added
Subsetto determine if a collection is includes another collection. - See about_PSRule_Assert and about_PSRule_Expressions for details.
- Added
- Added assertion helpers and expressions for improving intersection checks. #795
- Bug fixes:
- Fixed
Get-PSRuleBaselinedoes not return any results from module. #801
- Fixed
- Bug fixes:
- Fixed ResourceTags does not contain a method named ToHashtable. #798
- Engine features:
- Added support for generating badges from rule results. #623
- Standard or custom badges can be generated using a convention and the badge API.
- See about_PSRule_Badges for details.
- Added support for generating badges from rule results. #623
- General improvements:
- Rule results now include a run ID or each run. #774
- Run ID is returned in
Assert-PSRuleoutput at the end of each run by default. - By default a unique
runIdis generated when the rule is run. - The
Output.Footeroption was added to configure the output footer. - See about_PSRule_Options for details.
- Run ID is returned in
- Automatically exclude common repository files from input files. #721
- Added
Input.IgnoreRepositoryCommonoption to change default behavior. - See about_PSRule_Options for details.
- Added
- Added aggregation assertion methods for
AnyOfandAllOf. #776- See about_PSRule_Assert for details.
- Allow baselines to include local rules. #756
- The
Rule.IncludeLocaloption was automatically include local/ standalone rules not in a module. - This option is useful when you want to include local rules not included in a baseline.
- See about_PSRule_Options for details.
- The
- Rule results now include a run ID or each run. #774
- Bug fixes:
- Fixed configuration array deserializes as dictionary from YAML options. #779
- No additional changes.
- General improvements:
- Allow baselines to include local rules. #756
- The
Rule.IncludeLocaloption was automatically include local/ standalone rules not in a module. - This option is useful when you want to include local rules not included in a baseline.
- See about_PSRule_Options for details.
- The
- Allow baselines to include local rules. #756
- Engine features:
- Added support for generating badges from rule results. #623
- Standard or custom badges can be generated using a convention and the badge API.
- See about_PSRule_Badges for details.
- Added support for generating badges from rule results. #623
- General improvements:
- Rule results now include a run ID or each run. #774
- Run ID is returned in
Assert-PSRuleoutput at the end of each run by default. - By default a unique
runIdis generated when the rule is run. - The
Output.Footeroption was added to configure the output footer. - See about_PSRule_Options for details.
- Run ID is returned in
- Rule results now include a run ID or each run. #774
- Bug fixes:
- Fixed configuration array deserializes as dictionary from YAML options. #779
- General improvements:
- Automatically exclude common repository files from input files. #721
- Added
Input.IgnoreRepositoryCommonoption to change default behavior. - See about_PSRule_Options for details.
- Added
- Added aggregation assertion methods for
AnyOfandAllOf. #776- See about_PSRule_Assert for details.
- Automatically exclude common repository files from input files. #721
- Bug fixes:
- Fixed configuration array deserializes as dictionary from YAML options. #779
- Engine features:
- Added support for YAML rules. #603
- YAML rules evaluate an expression tree and return a result for each object.
- YAML provides an additional option for defining rules in addition to PowerShell script rules.
- Type and selector pre-conditions are supported.
- See about_PSRule_Rules for details.
- Added support for YAML rules. #603
- General improvements:
- Added support for object source location in validation. #757
- Default rule source location
.ps-rule/is automatically included. #742- Added
Include.PathandInclude.Moduleoptions to automatically include rule sources. - See about_PSRule_Options for details.
- Added
- Bug fixes:
- Fixed target binding across multiple scopes. #762
- No additional changes.
- Engine features:
- Added support for YAML rules. #603
- YAML rules evaluate an expression tree and return a result for each object.
- YAML provides an additional option for defining rules in addition to PowerShell script rules.
- Type and selector pre-conditions are supported.
- See about_PSRule_Rules for details.
- Added support for YAML rules. #603
- Bug fixes:
- Fixed target binding across multiple scopes. #762
- General improvements:
- Added support for object source location in validation. #757
- Default rule source location
.ps-rule/is automatically included. #742- Added
Include.PathandInclude.Moduleoptions to automatically include rule sources. - See about_PSRule_Options for details.
- Added
- General improvements:
- Added string selector conditions. #747
- Use
startWith,contains, andendsWithto check for a sub-string. - Use
isString,isLower, andisUpperto check for string type and casing. - See about_PSRule_Selectors for details.
- Use
- Added string selector conditions. #747
- Engineering:
- Bump YamlDotNet dependency to 11.2.1. #740
- Bug fixes:
- Fixed options schema should allow spacing after
@pre. #743 - Fixed match selector expression passing on missing field. #745
- Fixed options schema should allow spacing after
- No additional changes.
- General improvements:
- Added string selector conditions. #747
- Use
startWith,contains, andendsWithto check for a sub-string. - Use
isString,isLower, andisUpperto check for string type and casing. - See about_PSRule_Selectors for details.
- Use
- Added string selector conditions. #747
- Engineering:
- Bump YamlDotNet dependency to 11.2.1. #740
- Bug fixes:
- Fixed options schema should allow spacing after
@pre. #743 - Fixed match selector expression passing on missing field. #745
- Fixed options schema should allow spacing after
- Engineering:
- Bump YamlDotNet dependency to 11.2.0. #736
- General improvements:
- PSRule banner can be configured in output when using
Assert-PSRule. #708 - Input source location of objects are included in results.
- Input source location of objects from JSON and YAML input files are read automatically. #624
- Input source location of objects from the pipeline are read from properties. #729
- Assert output improvements:
- Added support for Visual Studio Code with
VisualStudioCodestyle. #731- Updated output format provides support for problem matchers in task output.
- Automatically detect output style from environment variables. #732
- Assert-PSRule now defaults to
Detectinstead ofClient.
- Assert-PSRule now defaults to
- See about_PSRule_Options for details.
- Added support for Visual Studio Code with
- Improved support for version constraints by:
- Constraints can include prerelease versions of other matching versions. #714
- Constraints support using a
@prereleaseor@preto include prerelease versions. #717 - Constraint sets allow multiple constraints to be joined together. #715
- See about_PSRule_Assert for details.
- PSRule banner can be configured in output when using
- Bug fixes:
- Fixed prerelease constraint handling for prerelease versions. #712
- Fixed null reference in convention for nested exceptions. #725
- No additional changes.
- General improvements:
- Source location of objects from the pipeline are read from properties. #729
- Assert output improvements:
- Added support for Visual Studio Code with
VisualStudioCodestyle. #731- Updated output format provides support for problem matchers in task output.
- Automatically detect output style from environment variables. #732
- Assert-PSRule now defaults to
Detectinstead ofClient.
- Assert-PSRule now defaults to
- See about_PSRule_Options for details.
- Added support for Visual Studio Code with
- Bug fixes:
- Fixed null reference in convention for nested exceptions. #725
- General improvements:
- Source location of objects are included in results.
- Source location of objects from JSON and YAML input files are read automatically. #624
- Improved support for version constraints by:
- Constraints can include prerelease versions of other matching versions. #714
- Constraints support using a
@prereleaseor@preto include prerelease versions. #717 - Constraint sets allow multiple constraints to be joined together. #715
- See about_PSRule_Assert for details.
- Source location of objects are included in results.
- Bug fixes:
- Fixed prerelease constraint handling for prerelease versions. #712
- General improvements:
- PSRule banner can be configured in output when using
Assert-PSRule. #708
- PSRule banner can be configured in output when using
- Engine features:
- Options can be configured with environment variables. #691
- See about_PSRule_Options for details.
- Options can be configured with environment variables. #691
- General improvements:
- Exclude
.gitsub-directory by default for recursive scans. #697- Added
Input.IgnoreGitPathoption to configure inclusion of.gitpath. - See about_PSRule_Options for details.
- Added
- Added file path assertion helpers. #679
- Added
WithinPathto check the file path field is within a specified path. - Added
NotWithinPathto check the file path field is not within a specified path - See about_PSRule_Assert for details.
- Added
- Added DateTime type assertion helper. #680
- Added
IsDateTimeto check of object field is[DateTime]. - See about_PSRule_Assert for details.
- Added
- Improved numeric comparison assertion helpers to compare
[DateTime]fields. #685Less,LessOrEqual,Greater, andGreaterOrEqualcompare the number of days from the current time.- See about_PSRule_Assert for details.
- Improved handling of field names for objects implementing
IList,IEnumerable, and index properties. #692
- Exclude
- Engineering:
- Bump YamlDotNet dependency to 11.1.1. #690
- Bug fixes:
- Fixed expected DocumentEnd got SequenceEnd. #698
- No additional changes.
- Engine features:
- Options can be configured with environment variables. #691
- See about_PSRule_Options for details.
- Options can be configured with environment variables. #691
- General improvements:
- Exclude
.gitsub-directory by default for recursive scans. #697- Added
Input.IgnoreGitPathoption to configure inclusion of.gitpath. - See about_PSRule_Options for details.
- Added
- Exclude
- Bug fixes:
- Fixed expected DocumentEnd got SequenceEnd. #698
- General improvements:
- Improved handling of field names for objects implementing
IList,IEnumerable, and index properties. #692
- Improved handling of field names for objects implementing
- Engineering:
- Bump YamlDotNet dependency to 11.1.1. #690
- General improvements:
- Added file path assertion helpers. #679
- Added
WithinPathto check the file path field is within a specified path. - Added
NotWithinPathto check the file path field is not within a specified path - See about_PSRule_Assert for details.
- Added
- Added DateTime type assertion helper. #680
- Added
IsDateTimeto check of object field is[DateTime]. - See about_PSRule_Assert for details.
- Added
- Improved numeric comparison assertion helpers to compare
[DateTime]fields. #685Less,LessOrEqual,Greater, andGreaterOrEqualcompare the number of days from the current time.- See about_PSRule_Assert for details.
- Added file path assertion helpers. #679
- Engine features:
- Added support for extensibility with conventions. #650
- Conventions provide an extensibility point within PSRule to execute actions within the pipeline.
- A convention can expose
Begin,Process, andEndblocks. - In additional to within rules
$PSRule.Datacan be accessed fromBeginandProcessblocks. - See about_PSRule_Conventions for details.
- Added support for object expansion with conventions. #661
- Use the
$PSRule.Importmethod to import child source objects into the pipeline. - See about_PSRule_Variables for details.
- Use the
- Added support for complex pre-conditions with selectors. #649
- See about_PSRule_Selectors for details.
- Added support for extensibility with conventions. #650
- General improvements:
- Added support for preferring automatic binding over custom binding configurations. #670
- Added the
Binding.PreferTargetInfooption to prefer target info specified by the object. - See about_PSRule_Options for details.
- Added the
- Added strong apiVersion to resource types. #647
- Resource schemas now support an
apiVersionfield. - The
apiVersionfield is optional but recommended. - Resources without a
apiVersionfield will not be supported from PSRule v2. - Added warning to flag baseline without
apiVersionset.
- Resource schemas now support an
- Added support for detecting files headers from additional file extensions using
FileHeader. #664- Added
.bicep,.csx,.jsx,.groovy,.java,.json,.jsonc,.scala,.rb,.bat,.cmd. - Added support for
JenkinsfileandDockerfilewithout an extension. - See about_PSRule_Assert for details.
- Added
- Added support for automatic type binding with files that do not have a file extension. #665
- Added support for preferring automatic binding over custom binding configurations. #670
- Bug fixes:
- Fixed dependent rule execution is skipped for consequent input objects. #657
- No additional changes.
- Engine features:
- Added support for complex pre-conditions with selectors. #649
- General improvements:
- Added support for preferring automatic binding over custom binding configurations. #670
- Added the
Binding.PreferTargetInfooption to prefer target info specified by the object. - See about_PSRule_Options for details.
- Added the
- Added strong apiVersion to resource types. #647
- Resource schemas now support an
apiVersionfield. - The
apiVersionfield is optional but recommended. - Resources without a
apiVersionfield will not be supported from PSRule v2. - Added warning to flag baseline without
apiVersionset.
- Resource schemas now support an
- Added support for preferring automatic binding over custom binding configurations. #670
- General improvements:
- Added support for detecting files headers from additional file extensions. #664
- Added
.bicep,.csx,.jsx,.groovy,.java,.json,.jsonc,.scala,.rb,.bat,.cmd. - Added support for
JenkinsfileandDockerfilewithout an extension. - See about_PSRule_Assert for details.
- Added
- Added support for automatic type binding with files that do not have a file extension. #665
- Added support for detecting files headers from additional file extensions. #664
- Engine features:
- Added support for object expansion with conventions. #661
- Use the
$PSRule.Importmethod to import child source objects into the pipeline. - See about_PSRule_Variables for details.
- Use the
- Added support for object expansion with conventions. #661
- Bug fixes:
- Fixed dependent rule execution is skipped for consequent input objects. #657
- Engine features:
- Added support for extensibility with conventions. #650
- Conventions provide an extensibility point within PSRule to execute actions within the pipeline.
- A convention can expose
Begin,Process, andEndblocks. - In additional to within rules
$PSRule.Datacan be accessed fromBeginandProcessblocks. - See about_PSRule_Conventions for details.
- Added support for extensibility with conventions. #650
- Engine features:
- Added assertion helpers. #640
- Added
NotHasFieldto check object does not have any of the specified fields. - Added
Nullto check field value is null. - Added
NotNullto check field value is not null. - See about_PSRule_Assert for details.
- Added
- Added type assertion helpers. #635
- Added
IsNumericto check field value is a numeric types. - Added
IsIntegerto check field value is an integer types. - Added
IsBooleanto check field value is a boolean. - Added
IsArrayto check field value is an array. - Added
IsStringto check field value is a string. - Added
TypeOfto check field value is a specified type. - See about_PSRule_Assert for details.
- Added
- Added content helpers. #637
- Added
$PSRule.GetContentFirstOrDefaultto get content and return the first object. - Added
$PSRule.GetContentFieldto get the field from content objects. - See about_PSRule_Variables for details.
- Added
- Added assertion helpers. #640
- General improvements:
- Updated
HasJsonSchemaassertion helper. #636- The URI scheme can optionally be ignored for
http://orhttps://URIs. - The fragment
#is ignored. - See about_PSRule_Assert for details.
- The URI scheme can optionally be ignored for
- Added support for
-Outcomeand-Asto produce filtered output fromAssert-PSRule. #643- Configure
Output.AswithSummaryto produce summarized results per object. - Configure
Output.Outcometo limit output toFailorError. - See Assert-PSRule for details.
- Configure
- Updated
- No additional changes.
- General improvements:
- Added support for
-Outcomeand-Asto produce filtered output fromAssert-PSRule. #643- Configure
Output.AswithSummaryto produce summarized results per object. - Configure
Output.Outcometo limit output toFailorError. - See Assert-PSRule for details.
- Configure
- Added support for
- Engine features:
- Added assertion helpers. #640
- Added
NotHasFieldto check object does not have any of the specified fields. - Added
Nullto check field value is null. - Added
NotNullto check field value is not null. - See about_PSRule_Assert for details.
- Added
- Added assertion helpers. #640
- Engine features:
- Added type assertion helpers. #635
- Added
IsNumericto check field value is a numeric types. - Added
IsIntegerto check field value is an integer types. - Added
IsBooleanto check field value is a boolean. - Added
IsArrayto check field value is an array. - Added
IsStringto check field value is a string. - Added
TypeOfto check field value is a specified type. - See about_PSRule_Assert for details.
- Added
- Added content helpers. #637
- Added
$PSRule.GetContentFirstOrDefaultto get content and return the first object. - Added
$PSRule.GetContentFieldto get the field from content objects. - See about_PSRule_Variables for details.
- Added
- Added type assertion helpers. #635
- General improvements:
- Updated
HasJsonSchemaassertion helper. #636- The URI scheme can optionally be ignored for
http://orhttps://URIs. - The fragment
#is ignored. - See about_PSRule_Assert for details.
- The URI scheme can optionally be ignored for
- Updated
- Bug fixes:
- Fixed reason reported fields for
HasFieldandHasFieldsassertion helpers. #632
- Fixed reason reported fields for
- Engineering:
- Bump Manatee.Json dependency to 13.0.5. #619
- Bug fixes:
- Fixed
GetContentprocessing ofInputFileInfo. #625 - Fixed null reference of rule reason with wide output. #626
- Fixed markdown help handling of inline code blocks with
[. #627 - Fixed markdown help inclusion of fenced code blocks in notes and description. #628
- Fixed
- Bug fixes:
- Fixed module source key has already been added. #608
- General improvements:
- Added rule help link in failed
Assert-PSRuleoutput. #595
- Added rule help link in failed
- Engineering:
- Breaking change: Removed deprecated
$Ruleproperties. #495 - Bump Manatee.Json dependency to 13.0.4. #591
- Breaking change: Removed deprecated
- No additional changes.
- General improvements:
- Added rule help link in failed
Assert-PSRuleoutput. #595
- Added rule help link in failed
- Engineering:
- Breaking change: Removed deprecated
$Ruleproperties. #495 - Bump Manatee.Json dependency to 13.0.4. #591
- Breaking change: Removed deprecated
- Several options have been renamed and the old names will be removed in v3. See deprecations for details.
-
Several properties of rule and language block elements will be removed from v3. See deprecations for details.
- Baseline groups allow you to use a friendly name to reference baselines. See baselines for more information.
- Functions within YAML and JSON expressions can be used to perform manipulation prior to testing a condition. See functions for more information.
- Sub-selectors within YAML and JSON expressions can be used to filter rules and list properties. See sub-selectors for more information.
-
Processing of changes files only within a pipeline. See creating your pipeline for more information.
- New features:
- Added sub-selector quantifiers for
allOforanyOfoperators by @BernieWhite. #1423- Quantifiers allow you to specify the number of matches with
count,less,lessOrEqual,greater, orgreaterOrEqual. - See Sub-selectors for more information.
- Quantifiers allow you to specify the number of matches with
- Added support for new functions by @BernieWhite. #1422
- Added support for
padLeft, andpadRight.
- Added support for
- Experimental: Added support for baseline groups by @BernieWhite. #1541
- Baseline groups allow you to reference a baseline by a friendly name.
- Update the baseline group to point to a new baseline.
- Currently only a single baseline can be referenced by a baseline group.
- See baselines for more information.
- Added sub-selector quantifiers for
- General improvements:
- Added style and improved handling for restore command by @BernieWhite. #1152
- Important change: Rename of execution options by @BernieWhite. #1456
- Renamed options allow configuration of output level as
Ignore,Warn,Error, orDebug. Execution.AliasReferenceWarningis replaced withExecution.AliasReference.Execution.InconclusiveWarningis replaced withExecution.RuleInconclusive.Execution.InvariantCultureWarningis replaced withExecution.InvariantCulture.Execution.NotProcessedWarningis replaced withExecution.UnprocessedObject.- Deprecated
AliasReferenceWarningoption, which will be removed in v3. - Deprecated
InconclusiveWarningoption, which will be removed in v3. - Deprecated
InvariantCultureWarningoption, which will be removed in v3. - Deprecated
NotProcessedWarningoption, which will be removed in v3.
- Renamed options allow configuration of output level as
- Improved schema display names by @BernieWhite. #1488
- Engineering:
- Bump Pester to v5.4.1. #1510
- Bump Microsoft.NET.Test.Sdk to v17.6.2. #1544
- Bump Microsoft.CodeAnalysis.Common to v4.6.0. #1534
- Bug fixes:
- Fixed tool output on access denied to path by @BernieWhite. #1490
- Fixed tool exit code on error or failure by @BernieWhite. #1491
- Fixed include local not automatically being enabled for default module baseline by @BernieWhite. #1506
- No additional changes.
- New features:
- Experimental: Added support for baseline groups by @BernieWhite. #1541
- Baseline groups allow you to reference a baseline by a friendly name.
- Update the baseline group to point to a new baseline.
- Currently only a single baseline can be referenced by a baseline group.
- See baselines for more information.
- Experimental: Added support for baseline groups by @BernieWhite. #1541
- General improvements:
- Added style and improved handling for restore command by @BernieWhite. #1152
- Engineering:
- Bump Microsoft.NET.Test.Sdk to v17.6.2. #1544
- Bump Microsoft.CodeAnalysis.Common to v4.6.0. #1534
- Bug fixes:
- Fixed include local not automatically being enabled for default module baseline by @BernieWhite. #1506
- New features:
- Added sub-selector quantifiers for
allOforanyOfoperators by @BernieWhite. #1423- Quantifiers allow you to specify the number of matches with
count,less,lessOrEqual,greater, orgreaterOrEqual. - See Sub-selectors for more information.
- Quantifiers allow you to specify the number of matches with
- Added support for new functions by @BernieWhite. #1422
- Added support for
padLeft, andpadRight.
- Added support for
- Added sub-selector quantifiers for
- General improvements:
- Important change: Rename of execution options by @BernieWhite. #1456
- Renamed options allow configuration of output level as
Ignore,Warn,Error, orDebug. Execution.AliasReferenceWarningis replaced withExecution.AliasReference.Execution.InconclusiveWarningis replaced withExecution.RuleInconclusive.Execution.InvariantCultureWarningis replaced withExecution.InvariantCulture.Execution.NotProcessedWarningis replaced withExecution.UnprocessedObject.- Deprecated
AliasReferenceWarningoption, which will be removed in v3. - Deprecated
InconclusiveWarningoption, which will be removed in v3. - Deprecated
InvariantCultureWarningoption, which will be removed in v3. - Deprecated
NotProcessedWarningoption, which will be removed in v3.
- Renamed options allow configuration of output level as
- Improved schema display names by @BernieWhite. #1488
- Important change: Rename of execution options by @BernieWhite. #1456
- Engineering:
- Bump Pester to v5.4.1. #1510
- Bump Microsoft.CodeAnalysis.Common to v4.5.0. #1455
- Bug fixes:
- Fixed tool output on access denied to path by @BernieWhite. #1490
- Fixed tool exit code on error or failure by @BernieWhite. #1491
- Bug fixes:
- Fixed wrong message for excluded rules by @BernieWhite. #1493
- Fixed job summary reports completed time by @BernieWhite. #1492
- General improvements:
- Important change: Replaced
SuppressedRuleWarningexecution option withRuleSuppressedby @BernieWhite. #1456- Improved options for output of suppressed rules with
RuleSuppressedoption. - Deprecated
SuppressedRuleWarningoption, which will be removed in v3.
- Improved options for output of suppressed rules with
- Added support for logging excluded rules by @BernieWhite. #1432
- Configure
Execution.RuleExcludedto control output level of excluded rules asIgnore,Warn,Error, orDebug.
- Configure
- Added additional options to schema for PSRule for Azure by @BernieWhite. #1446
- Improved error message for failing to read options file by @BernieWhite. #1433
- Added support for import within initialize block by @BernieWhite. #1448
- Added support for direct typing on import by @BernieWhite. #1449
- Use the
$PSRule.ImportWithTypemethod to import an object with a specific type.
- Use the
- Added support for case sensitivity matching with
matchandnotMatchexpressions by @BernieWhite. #1480
- Important change: Replaced
- Engineering:
- Bump Pester to v5.4.0. #1414 Bump Microsoft.CodeAnalysis.Common to v4.4.0. #1341
- Bump BenchmarkDotNet to v0.13.5. #1413
- Bump BenchmarkDotNet.Diagnostics.Windows to v0.13.5. #1413
- Bump Microsoft.NET.Test.Sdk to v17.5.0. #1442
- Bump Newtonsoft.Json to v13.0.3. #1467
- Bump Microsoft.CodeAnalysis.NetAnalyzers to v7.0.1. #1468
- Bug fixes:
- Fixes handling of numerics in tests for that are impacted by regional format by @BernieWhite. #1405
- Fixed no output with using job summary with as summary by @BernieWhite. #1483
- Fixed output and added error for unsupported scenarios.
- Fixed LocalizedData is not exposed to if pre-conditions by @BernieWhite. #1083
- Fixed LocalizedData is not exposed to conventions by @BernieWhite. #1477
- Fixed problem binding when not set locally by @BernieWhite. #1473
- No additional changes.
- General improvements:
- Added support for case sensitivity matching with
matchandnotMatchexpressions by @BernieWhite. #1480
- Added support for case sensitivity matching with
- Bug fixes:
- Fixed no output with using job summary with as summary by @BernieWhite. #1483
- Fixed output and added error for unsupported scenarios.
- Fixed no output with using job summary with as summary by @BernieWhite. #1483
- Bug fixes:
- Fixed LocalizedData is not exposed to if pre-conditions by @BernieWhite. #1083
- Fixed LocalizedData is not exposed to conventions by @BernieWhite. #1477
- Engineering:
- Bump Newtonsoft.Json to v13.0.3. #1467
- Bump Microsoft.CodeAnalysis.NetAnalyzers to v7.0.1. #1468
- Bug fixes:
- Fixed problem binding when not set locally by @BernieWhite. #1473
- General improvements:
- Important change: Replaced
SuppressedRuleWarningexecution option withRuleSuppressedby @BernieWhite. #1456- Improved options for output of suppressed rules with
RuleSuppressedoption. - Deprecated
SuppressedRuleWarningoption, which will be removed in v3.
- Improved options for output of suppressed rules with
- Added support for logging excluded rules by @BernieWhite. #1432
- Added additional options to schema for PSRule for Azure by @BernieWhite. #1446
- Improved error message for failing to read options file by @BernieWhite. #1433
- Added support for import within initialize block by @BernieWhite. #1448
- Added support for direct typing on import by @BernieWhite. #1449
- Use the
$PSRule.ImportWithTypemethod to import an object with a specific type.
- Use the
- Important change: Replaced
- Engineering:
- Bump Pester to v5.4.0. #1414
- Bump Microsoft.CodeAnalysis.NetAnalyzers to v7.0.0. #1374 Bump Microsoft.CodeAnalysis.Common to v4.4.0. #1341
- Bump BenchmarkDotNet to v0.13.5. #1413
- Bump BenchmarkDotNet.Diagnostics.Windows to v0.13.5. #1413
- Bump Microsoft.NET.Test.Sdk to v17.5.0. #1442
- Bug fixes:
- Fixes handling of numerics in tests for that are impacted by regional format by @BernieWhite. #1405
- New features:
- Added API version date comparison assertion method and expression by @BernieWhite. #1356
- Added support for new functions by @BernieWhite. #1227
- Added support for
trim,replace,split,first, andlast.
- Added support for
- General improvements:
- Added support target scope by @BernieWhite. #1350
- Added support for
hasValueexpression withscopeby @BernieWhite. #1382 - Return target object scope as an array by @BernieWhite. #1383
- Improve support of string comparisons to support an array of strings by @BernieWhite. #1384
- Added help properties to rules from YAML/ JSON resources by @BernieWhite. #1386
- Engineering:
- Bump Newtonsoft.Json to v13.0.2. #1358
- Bump System.Drawing.Common to v7.0.0. #1332
- Bump Microsoft.NET.Test.Sdk to v17.4.1. #1389
- Bug fixes:
- Fixed exception with comments in JSON baselines by @BernieWhite. #1336
- Fixed handling of constrained language mode with PowerShell 7.3 by @BernieWhite. #1348
- Fixed exception calling
RuleSourcevalue cannot be null by @BernieWhite. #1343 - Fixed null reference for link property by @BernieWhite. #1393
- Fixed reason are emitted for pre-condition sub-selectors by @BernieWhite. #1394
- Fixed CLI failed to load required assemblies by @BernieWhite. #1361
- Fixed CLI ignores modules specified in
Include.Modulesby @BernieWhite. #1362 - Fixed job summary directory creation by @BernieWhite. #1353
- Fixed same key for ref and name by @BernieWhite #1354
- Fixed object path fails to iterate JSON object with wildcard selector by @BernieWhite. #1376
- Fixed rule annotations are not included from YAML/ JSON definition by @BernieWhite. #1378
- Fixed loop stuck parsing JSON
allOfnotrule condition by @BernieWhite. #1370 - Fixed handling of uint64 with
LessOrEqualassertion method by @BernieWhite. #1366
- No additional changes.
- Bug fixes:
- Fixed null reference for link property by @BernieWhite. #1393
- Fixed reason are emitted for pre-condition sub-selectors by @BernieWhite. #1394
- General improvements:
- Added support for
hasValueexpression withscopeby @BernieWhite. #1382 - Return target object scope as an array by @BernieWhite. #1383
- Improve support of string comparisons to support an array of strings by @BernieWhite. #1384
- Added help properties to rules from YAML/ JSON resources by @BernieWhite. #1386
- Added support for
- Engineering:
- Bump Newtonsoft.Json to v13.0.2. #1358
- Bump System.Drawing.Common to v7.0.0. #1332
- Bump Microsoft.NET.Test.Sdk to v17.4.1. #1389
- Bug fixes:
- Fixed object path fails to iterate JSON object with wildcard selector by @BernieWhite. #1376
- Fixed rule annotations are not included from YAML/ JSON definition by @BernieWhite. #1378
- Bug fixes:
- Fixed loop stuck parsing JSON
allOfnotrule condition by @BernieWhite. #1370 - Fixed handling of uint64 with
LessOrEqualassertion method by @BernieWhite. #1366
- Fixed loop stuck parsing JSON
- New features:
- Added API version date comparison assertion method and expression by @BernieWhite. #1356
- Added support for new functions by @BernieWhite. #1227
- Added support for
trim,replace,split,first, andlast.
- Added support for
- Bug fixes:
- Fixed CLI failed to load required assemblies by @BernieWhite. #1361
- Fixed CLI ignores modules specified in
Include.Modulesby @BernieWhite. #1362
- Bug fixes:
- Fixed job summary directory creation by @BernieWhite. #1353
- Fixed same key for ref and name by @BernieWhite #1354
- General improvements:
- Added support target scope by @BernieWhite. #1350
- Bug fixes:
- Fixed exception with comments in JSON baselines by @BernieWhite. #1336
- Fixed handling of constrained language mode with PowerShell 7.3 by @BernieWhite. #1348
- Bug fixes:
- Fixed exception calling
RuleSourcevalue cannot be null by @BernieWhite. #1343
- Fixed exception calling
- New features:
- Added support for generating job summaries by @BernieWhite. #1264
- Job summaries provide a markdown output for pipelines in addition to other supported output formats.
- To use, configure the
Output.JobSummaryPathoption.
- Added support for time bound suppression groups by @BernieWhite. #1335
- Suppression groups can be configured to expire after a specified time by setting the
spec.expiresOnproperty. - When a suppression group expires, the suppression group will generate a warning by default.
- Configure the
Execution.SuppressionGroupExpiredoption to ignore or error on expired suppression groups.
- Suppression groups can be configured to expire after a specified time by setting the
- Added support for generating job summaries by @BernieWhite. #1264
- Engineering:
- Bump Microsoft.NET.Test.Sdk to v17.4.0. #1331
- Bump PSScriptAnalyzer to v1.21.0. #1318
- Class clean up and documentation by @BernieWhite. #1186
- No additional changes.
- New features:
- Added support for generating job summaries by @BernieWhite. #1264
- Job summaries provide a markdown output for pipelines in addition to other supported output formats.
- To use, configure the
Output.JobSummaryPathoption.
- Added support for time bound suppression groups by @BernieWhite. #1335
- Suppression groups can be configured to expire after a specified time by setting the
spec.expiresOnproperty. - When a suppression group expires, the suppression group will generate a warning by default.
- Configure the
Execution.SuppressionGroupExpiredoption to ignore or error on expired suppression groups.
- Suppression groups can be configured to expire after a specified time by setting the
- Added support for generating job summaries by @BernieWhite. #1264
- Engineering:
- Bump Microsoft.NET.Test.Sdk to v17.4.0. #1331
- Engineering:
- Bump Microsoft.NET.Test.Sdk to v17.3.2. #1283
- Bump PSScriptAnalyzer to v1.21.0. #1318
- Class clean up and documentation by @BernieWhite. #1186
- Bug fixes:
- Fixed incorrect XML header for encoding by @BernieWhite. #1322
- Bug fixes:
- Fixed NUnit output does not escape characters in all result properties by @BernieWhite. #1316
- Bug fixes:
- Fixed
Inwith array source object and dot object path by @BernieWhite. #1314
- Fixed
- New features:
- Experimental: Added support for only processing changed files by @BernieWhite. #688
- To ignore unchanged files, set the
Input.IgnoreUnchangedPathoption totrue. - See creating your pipeline for more information.
- To ignore unchanged files, set the
- Experimental: Added support for only processing changed files by @BernieWhite. #688
- General improvements:
- Added labels metadata from grouping and filtering rules by @BernieWhite. #1272
- Labels are metadata that extends on tags to provide a more structured way to group rules.
- Rules can be classified by setting the
metadata.labelsproperty or-Labelsparameter.
- Provide unblock for command line tools by @BernieWhite. #1261
- Added labels metadata from grouping and filtering rules by @BernieWhite. #1272
- Engineering:
- Bump Microsoft.NET.Test.Sdk to v17.3.1. #1248
- Bug fixes:
- Fixed could not load Microsoft.Management.Infrastructure by @BernieWhite. #1249
- To use minimal initial session state set
Execution.InitialSessionStatetoMinimal.
- To use minimal initial session state set
- Fixed unhandled exception with GetRootedPath by @BernieWhite. #1251
- Fixed Dockerfile case sensitivity by @BernieWhite. #1269
- Fixed could not load Microsoft.Management.Infrastructure by @BernieWhite. #1249
- No additional changes.
- Bug fixes:
- Fixed exception with
PathExpressionBuilder.GetAllRecurseby @BernieWhite. #1301
- Fixed exception with
- New features:
- Experimental: Added support for only processing changed files by @BernieWhite. #688
- To ignore unchanged files, set the
Input.IgnoreUnchangedPathoption totrue. - See creating your pipeline for more information.
- To ignore unchanged files, set the
- Experimental: Added support for only processing changed files by @BernieWhite. #688
- General improvements:
- Added labels metadata from grouping and filtering rules by @BernieWhite. #1272
- Labels are metadata that extends on tags to provide a more structured way to group rules.
- Rules can be classified by setting the
metadata.labelsproperty or-Labelsparameter.
- Added labels metadata from grouping and filtering rules by @BernieWhite. #1272
- Bug fixes:
- Fixed Dockerfile case sensitivity by @BernieWhite. #1269
- Fixed markdown parsing of Spanish translated help fails by @BernieWhite @jonathanruiz. #1286 #1285
- General improvements:
- Provide unblock for command line tools by @BernieWhite. #1261
- Engineering:
- Bump Microsoft.NET.Test.Sdk to v17.3.1. #1248
- Bug fixes:
- Fixed could not load Microsoft.Management.Infrastructure by @BernieWhite. #1249
- To use minimal initial session state set
Execution.InitialSessionStatetoMinimal.
- To use minimal initial session state set
- Fixed unhandled exception with GetRootedPath by @BernieWhite. #1251
- Fixed could not load Microsoft.Management.Infrastructure by @BernieWhite. #1249
- Bug fixes:
- Fixed exception with
PathExpressionBuilder.GetAllRecurseby @BernieWhite. #1301
- Fixed exception with
- Bug fixes:
- Fixed markdown parsing of Spanish translated help fails by @BernieWhite @jonathanruiz. #1286 #1285
- New features:
- Experimental: Added support for functions within YAML and JSON expressions by @BernieWhite. #1227 #1016
- Added conversion functions
boolean,string, andinteger. - Added lookup functions
configuration, andpath. - Added string functions
concat,substring. - See functions for more information.
- Added conversion functions
- Experimental: Added support for sub-selector YAML and JSON expressions by @BernieWhite. #1024 #1045
- Sub-selector pre-conditions add an additional expression to determine if a rule is executed.
- Sub-selector object filters provide an way to filter items from list properties.
- See sub-selectors for more information.
- Experimental: Added support for functions within YAML and JSON expressions by @BernieWhite. #1227 #1016
- Engineering:
- Improvements to PSRule engine API documentation by @BernieWhite. #1186
- Updates to PSRule engine API by @BernieWhite. #1152
- Added tool support for baselines parameter.
- Added module path discovery.
- Added output for verbose and debug messages.
- Bump support projects to .NET 6 by @BernieWhite. #1209
- Bump Microsoft.NET.Test.Sdk to v17.3.0. #1213
- Bump BenchmarkDotNet to v0.13.2. #1241
- Bump BenchmarkDotNet.Diagnostics.Windows to v0.13.2. #1242
- Bug fixes:
- Fixed reporting of duplicate identifiers which were not generating an error for all cases by @BernieWhite. #1229
- Added
Execution.DuplicateResourceIdoption to configure PSRule behaviour. - By default, duplicate resource identifiers return an error.
- Added
- Fixed exception on JSON baseline without a synopsis by @BernieWhite. #1230
- Fixed repository information not in output by @BernieWhite. #1219
- Fixed reporting of duplicate identifiers which were not generating an error for all cases by @BernieWhite. #1229
- No additional changes.
- Engineering:
- Bump BenchmarkDotNet to v0.13.2. #1241
- Bump BenchmarkDotNet.Diagnostics.Windows to v0.13.2. #1242
- New features:
- Experimental: Added support for sub-selector YAML and JSON expressions by @BernieWhite. #1024 #1045
- Sub-selector pre-conditions add an additional expression to determine if a rule is executed.
- Sub-selector object filters provide an way to filter items from list properties.
- See sub-selectors for more information.
- Experimental: Added support for sub-selector YAML and JSON expressions by @BernieWhite. #1024 #1045
- Engineering:
- Improvements to PSRule engine API documentation by @BernieWhite. #1186
- New features:
- Experimental: Added support for functions within YAML and JSON expressions by @BernieWhite. #1227 #1016
- Added conversion functions
boolean,string, andinteger. - Added lookup functions
configuration, andpath. - Added string functions
concat,substring. - See functions for more information.
- Added conversion functions
- Experimental: Added support for functions within YAML and JSON expressions by @BernieWhite. #1227 #1016
- Bug fixes:
- Fixed reporting of duplicate identifiers which were not generating an error for all cases by @BernieWhite. #1229
- Added
Execution.DuplicateResourceIdoption to configure PSRule behaviour. - By default, duplicate resource identifiers return an error.
- Added
- Fixed exception on JSON baseline without a synopsis by @BernieWhite. #1230
- Fixed reporting of duplicate identifiers which were not generating an error for all cases by @BernieWhite. #1229
- Engineering:
- Updates to PSRule engine API by @BernieWhite. #1152
- Added tool support for baselines parameter.
- Added module path discovery.
- Added output for verbose and debug messages.
- Updates to PSRule engine API by @BernieWhite. #1152
- Engineering:
- Bump support projects to .NET 6 by @BernieWhite. #1209
- Bump Microsoft.NET.Test.Sdk to v17.3.0. #1213
- Bug fixes:
- Fixed repository information not in output by @BernieWhite. #1219
- Bug fixes:
- Fixes lost scope for rules by @BernieWhite. #1214
- Bug fixes:
- Fixed object path join handling of self path identifier by @BernieWhite. #1204
- General improvements:
- Added
PathPrefixmethod to add an object path prefix to assertion reasons by @BernieWhite. #1198 - Added support for binding with JSON objects by @BernieWhite. #1182
- Added support for full path from JSON objects by @BernieWhite. #1174
- Improved reporting of full object path from pre-processed results by @BernieWhite. #1169
- Added PSRule for Azure expansion configuration to options schema by @BernieWhite. #1149
- Added
- Engineering:
- Bump xunit to v2.4.2. #1200
- Expose online link extension method by @BernieWhite. #1195
- Added comment documentation to .NET classes and interfaces by @BernieWhite. #1186
- Added publishing support for NuGet symbol packages @BernieWhite. #1173
- Updated outcome option docs by @BernieWhite. #1166
- Bump Sarif.Sdk to v2.4.16. #1177
- Refactoring and updates to interfaces to allow use outside of PowerShell by @BernieWhite. #1152
- Bug fixes:
- Fixes JSON parsing of string array for single objects by @BernieWhite. #1193
- Fixed handling for JSON objects in rules by @BernieWhite. #1187
- Fixed null object reference for object equity comparison by @BernieWhite. #1157
- Fixed expression evaluation not logging debug output when using the
-Debugswitch by @BernieWhite. #1158 - Fixed startIndex cannot be larger than length of string by @BernieWhite. #1160
- Fixed path within SDK package causes
psd1to compile by @BernieWhite. #1146
- No additional changes.
- General improvements:
- Added
PathPrefixmethod to add an object path prefix to assertion reasons by @BernieWhite. #1198
- Added
- Engineering:
- Bump xunit to v2.4.2. #1200
- Engineering:
- Expose online link extension method by @BernieWhite. #1195
- Bug fixes:
- Fixes JSON parsing of string array for single objects by @BernieWhite. #1193
- Engineering:
- Added comment documentation to .NET classes and interfaces by @BernieWhite. #1186
- Bug fixes:
- Fixed handling for JSON objects in rules by @BernieWhite. #1187
- General improvements:
- Added support for binding with JSON objects by @BernieWhite. #1182
- General improvements:
- Added support for full path from JSON objects by @BernieWhite. #1174
- Engineering:
- Added publishing support for NuGet symbol packages @BernieWhite. #1173
- Updated outcome option docs by @BernieWhite. #1166
- Bump Sarif.Sdk to v2.4.16. #1177
- General improvements:
- Improved reporting of full object path from pre-processed results by @BernieWhite. #1169
- Bug fixes:
- Fixed null object reference for object equity comparison by @BernieWhite. #1157
- Fixed expression evaluation not logging debug output when using the
-Debugswitch by @BernieWhite. #1158 - Fixed startIndex cannot be larger than length of string by @BernieWhite. #1160
- General improvements:
- Added PSRule for Azure expansion configuration to options schema by @BernieWhite. #1149
- Engineering:
- Refactoring and updates to interfaces to allow use outside of PowerShell by @BernieWhite. #1152
- Bug fixes:
- Fixed path within SDK package causes
psd1to compile by @BernieWhite. #1146
- Fixed path within SDK package causes
- New features:
- Added
notCountexpression and assertion helper by @ArmaanMcleod. #1091
- Added
- General improvements:
- Improved reporting of the object path that caused rule failures by @BernieWhite. #1092
- Output include a new
Detailproperty with details of the reason and the object path. - Custom methods
ReasonFromandReasonIfaccept apathparameter to specify the object path.
- Output include a new
- Added informational message when output has been written to disk by @BernieWhite. #1074
- The
Output.Footeroption now supportsOutputFilewhich reports the output file path. This is enabled by default.
- The
- Added descendant selector to object path syntax by @BernieWhite. #1133
- Use
..to traverse into child objects, for example$..namefinds names for all nested objects.
- Use
- Improved reporting of the object path that caused rule failures by @BernieWhite. #1092
- Engineering:
- Bump Newtonsoft.Json to 13.0.1. #1137
- Added more object path tests by @ArmaanMcleod. #1110
- Bump xunit.runner.visualstudio to 2.4.5. #1084
- Bump Pester to 5.3.3. #1079
- Bump Microsoft.NET.Test.Sdk to 17.2.0. #1089
- Added NuGet packaging publishing by @BernieWhite. #1093
- Updated NuGet packaging metadata by @BernieWhite. #1093
- Bug fixes:
- Fixed output of reason with wide format by @BernieWhite. #1117
- Fixed piped input does not respect excluded paths by @BernieWhite. #1114
- By default, objects are not excluded by source.
- To exclude piped input based on source configure the
Input.IgnoreObjectSourceoption.
- Fixed issue building a PSRule project by removing PSRule.psd1 from compile target by @BernieWhite. #1140
- Fixed grouping of logical operators in object path by @BernieWhite. #1101
- No additional changes.
- Bug fixes:
- Fixed issue building a PSRule project by removing PSRule.psd1 from compile target by @BernieWhite. #1140
- General improvements:
- Added descendant selector to object path syntax by @BernieWhite. #1133
- Use
..to traverse into child objects, for example$..namefinds names for all nested objects.
- Use
- Added descendant selector to object path syntax by @BernieWhite. #1133
- Engineering:
- Bump Newtonsoft.Json to 13.0.1. #1137
- General improvements:
- Improved reporting of the object path that caused rule failures by @BernieWhite. #1092
- Output include a new
Detailproperty with details of the reason and the object path. - Custom methods
ReasonFromandReasonIfaccept apathparameter to specify the object path.
- Output include a new
- Improved reporting of the object path that caused rule failures by @BernieWhite. #1092
- General improvements:
- Added informational message when output has been written to disk by @BernieWhite. #1074
- The
Output.Footeroption now supportsOutputFilewhich reports the output file path. This is enabled by default.
- The
- Added informational message when output has been written to disk by @BernieWhite. #1074
- Engineering:
- Added more object path tests by @ArmaanMcleod. #1110
- Bug fixes:
- Fixed output of reason with wide format by @BernieWhite. #1117
- Fixed piped input does not respect excluded paths by @BernieWhite. #1114
- By default, objects are not excluded by source.
- To exclude piped input based on source configure the
Input.IgnoreObjectSourceoption.
- New features:
- Added
notCountexpression and assertion helper by @ArmaanMcleod. #1091
- Added
- Engineering:
- Bump xunit.runner.visualstudio to 2.4.5. #1084
- Bump Pester to 5.3.3. #1079
- Bump Microsoft.NET.Test.Sdk to 17.2.0. #1089
- Added NuGet packaging publishing by @BernieWhite. #1093
- Updated NuGet packaging metadata by @BernieWhite. #1093
- Bug fixes:
- Fixed grouping of logical operators in object path by @BernieWhite. #1101
- General improvements:
- Added
notStartsWith,notEndsWith, andnotContainsexpressions and assertion helpers. #1047 - Added
like,notLikeexpressions and assertion helpers. #1048 - Added additional repository paths to ignore by default. #1043
- Added custom suppression message during PSRule runs. #1046
- When a rule is suppressed using a suppression group the synopsis is shown in the suppression warning.
- Configure the suppression group synopsis to display a custom message.
- Suppression groups synopsis can be localized using markdown documentation.
- Use markdown to set a culture specific synopsis.
- Custom suppression messages are not supported when suppressing individual rules using
ps-rule.yaml. - See about_PSRule_SuppressionGroups for details.
- Added source support for string conditions. #1068
- Added
- Engineering:
- Added code signing of module. #1049
- Added SBOM manifests to module. #1050
- Bump Sarif.Sdk to 2.4.15. #1075
- Bump Pester to 5.3.2. #1062
- Bug fixes:
- Important change: Fixed source scope not updated in multi-module runs. #1053
- Several properties of rule and language block elements have been renamed to improve consistency.
- From v3 custom scripts may not work correctly until you update these names.
- For details on the updated property names see deprecations.
- Important change: Fixed source scope not updated in multi-module runs. #1053
- No additional changes.
- General improvements:
- Added
notStartsWith,notEndsWith, andnotContainsexpressions and assertion helpers. #1047 - Added
like,notLikeexpressions and assertion helpers. #1048 - Added additional repository paths to ignore by default. #1043
- Added
- Engineering:
- Bump Sarif.Sdk to 2.4.15. #1075
- General improvements:
- Added custom suppression message during PSRule runs. #1046
- When a rule is suppressed using a suppression group the synopsis is shown in the suppression warning.
- Configure the suppression group synopsis to display a custom message.
- Suppression groups synopsis can be localized using markdown documentation.
- Use markdown to set a culture specific synopsis.
- Custom suppression messages are not supported when suppressing individual rules using
ps-rule.yaml. - See about_PSRule_SuppressionGroups for details.
- Added source support for string conditions. #1068
- Added custom suppression message during PSRule runs. #1046
- Engineering:
- Bump Sarif.Sdk to 2.4.14. #1064
- Bump Pester to 5.3.2. #1062
- Bug fixes:
- Important change: Fixed source scope not updated in multi-module runs. #1053
- Several properties of rule and language block elements have been renamed to improve consistency.
- From v3 custom scripts may not work correctly until you update these names.
- For details on the updated property names see deprecations.
- Important change: Fixed source scope not updated in multi-module runs. #1053
- Engineering:
- Added code signing of module. #1049
- Added SBOM manifests to module. #1050
- Bug fixes:
- Fixed read JSON failed with comments. #1051
- Fixed null reference on elapsed time when required module check fails. #1054
- Fixed failed to read JSON objects with a empty property name. #1052
- New features:
- Add support for suppression groups. #793
- New
SuppressionGroupresource has been included. - See about_PSRule_SuppressionGroups for details.
- New
- Added source expression property. #933
- Included the following expressions:
sourcewithinPathnotWithinPath
- Included the following expressions:
- Added support for rule severity level. #880
- Rules can be configured to be
Error,Warning, orInformation. - Failing rules with the
Errorseverity level will cause the pipeline to fail. - Rules with the
Warningseverity level will be reported as warnings. - Rules with the
Informationseverity level will be reported as informational messages. - By default, the severity level for a rule is
Error.
- Rules can be configured to be
- Added expression support for type based assertions. #908
- Included the following expressions:
IsArrayIsBooleanIsDateTimeIsIntegerIsNumeric
- Included the following expressions:
- Added support for formatting results as SARIF. #878
- Set
Output.FormattoSarifto output results in the SARIF format. - See about_PSRule_Options for details.
- Set
- Add support for suppression groups. #793
- General improvements:
- Add option to disable invariant culture warning. #899
- Added
Execution.InvariantCultureWarningoption. - See about_PSRule_Options for details.
- Added
- Added support for object path expressions. #808 #693
- Inspired by JSONPath, object path expressions can be used to access nested objects.
- Array members can be filtered and enumerated using object path expressions.
- Object path expressions can be used in YAML, JSON, and PowerShell rules and selectors.
- See about_PSRule_Assert for details.
- Improve tracking of suppressed objects. #794
- Added
Execution.SuppressedRuleWarningoption to output warning for suppressed rules.
- Added
- Added support for rule aliases. #792
- Aliases allow rules to be references by an alternative name.
- When renaming rules, add a rule alias to avoid breaking references to the old rule name.
- To specify an alias use the
-Aliasparameter oraliasmetadata property in YAML or JSON.
- Added support for stable identifiers with rule refs. #881
- A rule ref may be optionally be used to reference a rule.
- Rule refs should be: stable, not changing between releases; opaque, as opposed to being a human-readable string. Stable and opaque refs ease web lookup and to help to avoid language difficulties.
- To specify a rule ref use the
-Refparameter orrefmetadata property in YAML or JSON.
- Added new properties for module lookup to SARIF results. #951
- Capture and output repository info in Assert-PSRule runs. #978
- Added
Repository.Urloption set repository URL reported in output. - Repository URL is detected automatically for GitHub Actions and Azure Pipelines.
- Added
RepositoryInfotoOutput.Banneroption. - Repository info is shown by default.
- Added
- Added
convertandcaseSensitiveto string comparison expressions. #1001- The following expressions support type conversion and case-sensitive comparison.
startsWith,contains, andendsWith.equalsandnotEquals.
- The following expressions support type conversion and case-sensitive comparison.
- Added
convertto numeric comparison expressions. #943- Type conversion is now supported for
less,lessOrEquals,greater, andgreaterOrEquals.
- Type conversion is now supported for
- Added
Extentproperty on rules reported byGet-PSRule. #990- Extent provides the line and position of the rule in the source code.
- Breaking change: Added validation of resource names. #1012
- Invalid rules names will now produce a specific error.
- See upgrade notes for more information.
- Add option to disable invariant culture warning. #899
- Engineering:
- Breaking change: Removal of deprecated default baseline from module manifest. #755
- Set the default module baseline using module configuration.
- See upgrade notes for details.
- Breaking change: Require
apiVersionon YAML and JSON to be specified. #648- Resources should use
github.com/microsoft/PSRule/v1as theapiVersion. - Resources that do not specify an
apiVersionwill be ignored. - See upgrade notes for details.
- Resources should use
- Breaking change: Prefer module sources over loose files. #610
- Module sources are discovered before loose files.
- Warning is shown for duplicate rule names, and exception is thrown for duplicate rule Ids.
- See upgrade notes for details.
- Breaking change: Require rule sources from current working directory to be explicitly included. #760
- From v2 onwards,
$PWDis not included by default unless-Path .or-Path $PWDis explicitly specified. - See upgrade notes for details.
- From v2 onwards,
- Added more tests for JSON resources. #929
- Bump Sarif.Sdk to 2.4.13. #1007
- Bump PowerShellStandard.Library to 5.1.1. #999
- Breaking change: Removal of deprecated default baseline from module manifest. #755
- Bug fixes:
- Fixed object path handling with dash. #902
- Fixed empty suppression group rules property applies to no rules. #931
- Fixed object reference for suppression group will rule not defined. #932
- Fixed rule source loading twice from
$PWDand.ps-rule/. #939 - Fixed rule references in SARIF format for extensions need a toolComponent reference. #949
- Fixed file objects processed with file input format have no source location. #950
- Fixed GitHub code scanning alerts treats pass as problems. #955
- By default, SARIF output will only include fail or error outcomes.
- Added
Output.SarifProblemsOnlyoption to include pass outcomes.
- Fixed SARIF output includes rule property for default tool component. #956
- Fixed Invoke-PSRule hanging if JSON rule file is empty. #969
- Fixed SARIF should report base branch. #964
- Fixed unclear error message on invalid rule names. #1012
- No additional changes.
- General improvements:
- Added
convertto numeric comparison expressions. #943- Type conversion is now supported for
less,lessOrEquals,greater, andgreaterOrEquals.
- Type conversion is now supported for
- Breaking change: Added validation of resource names. #1012
- Invalid rules names will now produce a specific error.
- See upgrade notes for more information.
- Added
- Bug fixes:
- Fixed unclear error message on invalid rule names. #1012
- General improvements:
- Added
Extentproperty on rules reported byGet-PSRule. #990- Extent provides the line and position of the rule in the source code.
- Added
- Engineering:
- Bump Sarif.Sdk to 2.4.13. #1007
- Bump PowerShellStandard.Library to 5.1.1. #999
- General improvements:
- Added
convertandcaseSensitiveto string comparison expressions. #1001- The following expressions support type conversion and case-sensitive comparison.
startsWith,contains, andendsWith.equalsandnotEquals.
- The following expressions support type conversion and case-sensitive comparison.
- Added
- General improvements:
- Capture and output repository info in Assert-PSRule runs. #978
- Added
Repository.Urloption set repository URL reported in output. - Repository URL is detected automatically for GitHub Actions and Azure Pipelines.
- Added
RepositoryInfotoOutput.Banneroption. - Repository info is shown by default.
- Added
- Capture and output repository info in Assert-PSRule runs. #978
- Bug fixes:
- Fixed SARIF should report base branch. #964
- Bug fixes:
- Fixed broken documentation links. #980
- Bug fixes:
- Fixed Invoke-PSRule hanging if JSON rule file is empty. #969
- New features:
- Added source expression property. #933
- Included the following expressions:
sourcewithinPathnotWithinPath
- Included the following expressions:
- Added source expression property. #933
- Bug fixes:
- Fixed GitHub code scanning alerts treats pass as problems. #955
- By default, SARIF output will only include fail or error outcomes.
- Added
Output.SarifProblemsOnlyoption to include pass outcomes.
- Fixed SARIF output includes rule property for default tool component. #956
- Fixed GitHub code scanning alerts treats pass as problems. #955
- General improvements:
- Added new properties for module lookup to SARIF results. #951
- Bug fixes:
- Fixed rule references in SARIF format for extensions need a toolComponent reference. #949
- Fixed file objects processed with file input format have no source location. #950
- New features:
- Added support for rule severity level. #880
- Rules can be configured to be
Error,Warning, orInformation. - Failing rules with the
Errorseverity level will cause the pipeline to fail. - Rules with the
Warningseverity level will be reported as warnings. - Rules with the
Informationseverity level will be reported as informational messages. - By default, the severity level for a rule is
Error.
- Rules can be configured to be
- Added expression support for type based assertions. #908
- Included the following expressions:
IsArrayIsBooleanIsDateTimeIsIntegerIsNumeric
- Included the following expressions:
- Added support for formatting results as SARIF. #878
- Set
Output.FormattoSarifto output results in the SARIF format. - See about_PSRule_Options for details.
- Set
- Added support for rule severity level. #880
- Engineering:
- Breaking change: Require rule sources from current working directory to be explicitly included. #760
- From v2 onwards,
$PWDis not included by default unless-Path .or-Path $PWDis explicitly specified. - See upgrade notes for details.
- From v2 onwards,
- Breaking change: Require rule sources from current working directory to be explicitly included. #760
- Bug fixes:
- Fixed rule source loading twice from
$PWDand.ps-rule/. #939
- Fixed rule source loading twice from
- Engineering:
- Breaking change: Prefer module sources over loose files. #610
- Module sources are discovered before loose files.
- Warning is shown for duplicate rule names, and exception is thrown for duplicate rule Ids.
- See upgrade notes for details.
- Added more tests for JSON resources. #929
- Breaking change: Prefer module sources over loose files. #610
- Bug fixes:
- Fixed empty suppression group rules property applies to no rules. #931
- Fixed object reference for suppression group will rule not defined. #932
- General improvements:
- Add option to disable invariant culture warning. #899
- Added
Execution.InvariantCultureWarningoption. - See about_PSRule_Options for details.
- Added
- Add option to disable invariant culture warning. #899
- New features:
- Add support for suppression groups. #793
- New
SuppressionGroupresource has been included. - See about_PSRule_SuppressionGroups for details.
- New
- Add support for suppression groups. #793
- General improvements:
- Added support for rule aliases. #792
- Aliases allow rules to be references by an alternative name.
- When renaming rules, add a rule alias to avoid breaking references to the old rule name.
- To specify an alias use the
-Aliasparameter oraliasmetadata property in YAML or JSON.
- Added support for stable identifiers with rule refs. #881
- A rule ref may be optionally be used to reference a rule.
- Rule refs should be: stable, not changing between releases; opaque, as opposed to being a human-readable string. Stable and opaque refs ease web lookup and to help to avoid language difficulties.
- To specify a rule ref use the
-Refparameter orrefmetadata property in YAML or JSON.
- Added support for rule aliases. #792
- Bug fixes:
- Fixed object path handling with dash. #902
- General improvements:
- Added support for object path expressions. #808 #693
- Inspired by JSONPath, object path expressions can be used to access nested objects.
- Array members can be filtered and enumerated using object path expressions.
- Object path expressions can be used in YAML, JSON, and PowerShell rules and selectors.
- See about_PSRule_Assert for details.
- Improve tracking of suppressed objects. #794
- Added
Execution.SuppressedRuleWarningoption to output warning for suppressed rules.
- Added
- Added support for object path expressions. #808 #693
- Engineering:
- Breaking change: Removal of deprecated default baseline from module manifest. #755
- Set the default module baseline using module configuration.
- See upgrade notes for details.
- Breaking change: Require
apiVersionon YAML and JSON to be specified. #648- Resources should use
github.com/microsoft/PSRule/v1as theapiVersion. - Resources that do not specify an
apiVersionwill be ignored. - See upgrade notes for details.
- Resources should use
- Breaking change: Removal of deprecated default baseline from module manifest. #755
- Baseline groups allow you to use a friendly name to reference baselines. See baselines for more information.
- Functions within YAML and JSON expressions can be used to perform manipulation prior to testing a condition. See functions for more information.
- Sub-selectors within YAML and JSON expressions can be used to filter rules and list properties. See sub-selectors for more information.
-
Processing of changes files only within a pipeline. See creating your pipeline for more information.
- Engineering:
- Bump System.Drawing.Common to v8.0.4. #1790
- Bump Bump xunit to v2.7.1. #1793
- Bump xunit.runner.visualstudio to v2.5.8. #1792
- Bump YamlDotNet to v15.1.2. #1771
- Bump Microsoft.CodeAnalysis.Common to v4.9.2. #1773
- Bug fixes:
- Fixed discovery of installed modules in CLI by @BernieWhite. #1779
- Bug fixes:
- Fixes null references for CLI module handling by @BernieWhite. #1746
- General improvements:
- Improved support for packaging with Visual Studio Code by @BernieWhite. #1755
- Engineering:
- Breaking change: Bump development tools to .NET 8.0 SDK by @BernieWhite. #1673
- Running PSRule from PowerShell 7.x is supported on 7.4 and above.
- Running PSRule from Windows PowerShell 5.1 is still supported but deprecated and will be removed in PSRule v4.
- Bump Microsoft.NET.Test.Sdk to v17.9.0. #1752
- Breaking change: Bump development tools to .NET 8.0 SDK by @BernieWhite. #1673
- Bug fixes:
- Fixed CLI null reference when include module is undefined by @BernieWhite. #1746
- General improvements:
- SARIF output has been improved to include effective configuration from a run by @BernieWhite. #1739
- SARIF output has been improved to include file hashes for source files from a run by @BernieWhite. #1740
- Added support to allow disabling PowerShell features that can be run from a repository by @BernieWhite. #1742
- Added the
Execution.RestrictScriptSourceoption to disable running scripts from a repository.
- Added the
- Engineering:
- Bump YamlDotNet to v15.1.0. #1737
- General improvements:
- Breaking change: Moved the
restorecommand to a sub-command ofmoduleby @BernieWhite. #1730- The functionality of the
restorecommand is now available asmodule restore.
- The functionality of the
- Added CLI commands to list and report status of locked modules by @BernieWhite. #1729
- Added
module initsub-command to initialize the lock file from configured options. - Added
module listsub-command to list locked and unlocked modules associated with the workspace. - Added
versionproperty to the lock file schema to support versioning of the lock file.
- Added
- Breaking change: Moved the
- Engineering:
- Bump BenchmarkDotNet to v0.13.12. #1725
- Bump BenchmarkDotNet.Diagnostics.Windows to v0.13.12. #1728
- Bump xunit to v2.6.6. #1732
- Bump xunit.runner.visualstudio to v2.5.6. #1717
- Bump System.Drawing.Common to v8.0.1. #1727
- General improvements:
- Breaking change: Renamed
analyzeCLI command torunby @BernieWhite. #1713 - Added
--outcomeargument for CLI to support filtering output by @bernieWhite. #1706
- Breaking change: Renamed
- Engineering:
- Bump xunit to v2.6.3. #1699
- Bump xunit.runner.visualstudio to v2.5.5. #1700
- Bump Microsoft.NET.Test.Sdk to v17.8.0. #1659
- Bump Microsoft.CodeAnalysis.NetAnalyzers to v8.0.0. #1674
- Bump Microsoft.CodeAnalysis.Common to v4.8.0. #1686
- Bump BenchmarkDotNet to v0.13.11. #1694
- Bump BenchmarkDotNet.Diagnostics.Windows to v0.13.11. #1697
- Engineering:
- Bump xunit to v2.6.1. #1656
- Bump System.Drawing.Common to v8.0.0. #1669
- Bug fixes:
- Fixed CLI IndexOutOfRangeException with lock file by @BernieWhite. #1676
- New features:
- Added lock file support when using CLI and related tools by @BernieWhite. #1660
- The lock file used used during analysis and when installing modules to select a specific version.
- Added lock file support when using CLI and related tools by @BernieWhite. #1660
- General improvements:
- Breaking change: Switch to use SHA-512 for generating unbound objects by @BernieWhite. #1155
- Objects that have no bound name will automatically be assigned a name based on the SHA-512 hash of the object.
- Previously a SHA-1 hash was used, however this is no longer considered secure.
- The name for unbound objects that are suppressed will change as a result.
- Additionally the hash can be changed by setting the
Execution.HashAlgorithmoption. - See upgrade notes for details.
- Breaking change: Removed deprecated execution options by @BernieWhite. #1457
- Breaking change: Removed deprecated object properties by @BernieWhite. #1601
- Expanded support for
FileHeaderassertion by @BernieWhite. #1521- Added support for
.bicepparam,.tsp,.tsx,.editorconfig,.ipynb, and.tomlfiles.
- Added support for
- Breaking change: Switch to use SHA-512 for generating unbound objects by @BernieWhite. #1155
- Engineering:
- Breaking change: Bump development tools to .NET 7.0 SDK by @BernieWhite. #1631
- Running PSRule from PowerShell 7.x is supported on 7.3 and above.
- Running PSRule from Windows PowerShell 5.1 is still supported but deprecated and will be removed in PSRule v4.
- Bump Microsoft.CodeAnalysis.NetAnalyzers to v7.0.4. #1602
- Bump Microsoft.CodeAnalysis.Common to v4.7.0. #1593
- Bump Microsoft.NET.Test.Sdk to v17.7.2. #1608
- Bump YamlDotNet to v13.7.1. #1647
- Bump xunit to v2.5.3. #1648
- Bump xunit.runner.visualstudio to v2.5.3. #1644
- Bump BenchmarkDotNet to v0.13.10. #1654
- Bump BenchmarkDotNet.Diagnostics.Windows to v0.13.10. #1654
- Breaking change: Bump development tools to .NET 7.0 SDK by @BernieWhite. #1631
- Reuse and share \u2014 existing pre-built rules, configure, or write your own.
- Incremental adoption \u2014 with baselines allows you to keep moving forward.
- Handle exceptions \u2014 and keep exceptions auditable in git history.
- Documentation \u2014 provides recommendations and examples instead of just pass or fail.
Yaml- Output is serialized as YAML.Json- Output is serialized as JSON.Markdown- Output is serialized as Markdown.NUnit3- Output is serialized as NUnit3 (XML).Csv- Output is serialized as a comma-separated values (CSV).Sarif- Output is serialized as SARIF.- Create a GitHub Actions workflow.
- Add a step using the
microsoft/ps-ruleaction.- Configure the
outputFormatandoutputPathparameters.
- Configure the
- Add a step using the
github/codeql-action/upload-sarifaction.- Configure the
sarif_fileparameter to the same file path specified inoutputPath.
- Configure the
- Exclude rules by name \u2014 The rule is not executed for any object.
- Suppress rules by name \u2014 The rule is not executed for a specific object by name.
- Suppress rules by condition \u2014 The rule is not executed for matching objects.
Ignore(1) - Continue to execute silently.Warn(2) - Continue to execute but log a warning. This is the default.Error(3) - Abort and throw an error.Debug(4) - Continue to execute but log a debug message.Execution.SuppressedRuleWarningis replaced withExecution.RuleSuppressed. SetExecution.RuleSuppressedtoWarnto log a warning from v2.8.0. If both options are set,Execution.SuppressedRuleWarningtakes precedence until v3.Execution.AliasReferenceWarningis replaced withExecution.AliasReference. SetExecution.AliasReferencetoWarnto log a warning from v2.9.0. If both options are set,Execution.AliasReferenceWarningtakes precedence until v3.Execution.InconclusiveWarningis replaced withExecution.RuleInconclusive. SetExecution.RuleInconclusivetoWarnto log a warning from v2.9.0. If both options are set,Execution.InconclusiveWarningtakes precedence until v3.Execution.InvariantCultureWarningis replaced withExecution.InvariantCulture. SetExecution.InvariantCulturetoWarnto log a warning from v2.9.0. If both options are set,Execution.InvariantCultureWarningtakes precedence until v3.Execution.NotProcessedWarningis replaced withExecution.UnprocessedObject. SetExecution.UnprocessedObjecttoWarnto log a warning from v2.9.0. If both options are set,Execution.NotProcessedWarningtakes precedence until v3.RuleIdRuleNameDescriptionModuleNameSourcePathIdinstead ofRuleId.Nameinstead ofRuleName.Synopsisinstead ofDescription.Source.Moduleinstead ofModuleName.Source.Pathinstead ofSourcePath.ModuleNameSourcePathSource.Moduleinstead ofModuleName.Source.Pathinstead ofSourcePath.- Objects - PowerShell objects can be validated on the pipeline or imported.
- Objects can be imported directly from
JSON,YAML, or.psd1. - Each object is automatically bound to a target type for use with pre-conditions.
- Rule results are orientated to validating an object.
- Built-in assertions, automatically traverse object properties.
- Objects can be imported directly from
- Pre-conditions - Rules understand which objects they apply to. Objects are bound to a type as they are processed using object properties. Dissimilar objects can be processed quickly.
- Objects that match no rules are flagged with a warning by default.
- Packaging - Rules can be reused between projects and optionally packaged into a module.
- Portable rules, configuration, baselines, and documentation allow greater reuse and distribution.
- Documentation with detailed guidance or next steps can be included.
- Standalone or rules from modules can be combined together with
-Moduleand-Path.
- Configuration - Configuration of rules is handled by PSRule.
- Rules can be configured at runtime, from YAML configuration, or environment variables.
- Baselines can be used to pair rules and configuration for a specific scenario.
- Exceptions - Exceptions to a rule can be ignored for a single object using suppression.
- Exclusion can be used additionally to ignore a rule entirely.
- Infrastructure as code, including:
- Kubernetes manifests.
- Azure Resource Manager (ARM) templates.
- Configuration files.
- Pipeline files.
- Deployments or configurations against a baseline.
- Parameter - PSRule can be configured at runtime by passing the
-Optionparameter to cmdlets. - Options file - Options stored in YAML are load configuration from file. The default
ps-rule.yamloption file is read automatically from the current working path by default. When checking into source control, store this file in the root directory of the repository. - Environment variables - Configuration can be specified using environment variables.
- Exclude the rule - The rule is not executed for any object.
- Suppress the rule - The rule is not executed for a specific object by name.
- Exclude files from analysis \u2014 Configure the Input.PathIgnore option.
-
Disable the warning entirely \u2014 Set the Execution.UnprocessedObject option to
Ignore. - Shift-left \u2014 Identify configuration issues and provide fast feedback in PRs.
- Quality gates \u2014 Implement quality gates between environments such as dev, test, and prod.
- Monitor continuously \u2014 Perform ongoing checks for configuration optimization opportunities.
- GitHub Actions \u2014 Trigger tests for GitHub repositories using workflows.
- Azure Pipelines \u2014 Use tasks to run tests in Azure DevOps YAML or Classic pipelines and releases.
- YAML \u2014 Use a popular, easy to read, and learn IaC format. With YAML, you can quickly build out common rules with minimal effort and no scripting experience.
- JSON \u2014 Is ubiquitous, used by many tools. While this format is typically harder to read then YAML it is easy to automate. You may prefer to use this format if you are generating rules with automation.
- PowerShell \u2014 Is a flexible scripting language. If you or your team already can write a basic PowerShell script, you can already define a rule. PowerShell allows you to tap into a large world-wide community of PowerShell users. Use existing cmdlets to help you build out rules quickly.
- Modular \u2014 Rules can be packages up into a standard PowerShell module then distributed.
- Private \u2014 Modules can be published privately on a network share or NuGet feed.
- Public \u2014 Distribute rules globally using the PowerShell Gallery.
- Configuration \u2014 PSRule and rules can be configured.
- Baselines \u2014 An artifact containing rules and configuration for a scenario.
- Suppression \u2014 Allows you to handle and keep exceptions auditable in git history.
- Approval \u2014 Use code owners and branch policy concepts to control changes.
-
Documentation \u2014 Provide guidance on how to resolve detected issues.
- Quick \u2014 Use a one liner to quickly add a hint or reference on rules you build.
- Detailed \u2014 Support for markdown allows you to provide detailed detailed guidance to resolve issues.
- Clone the GitHub repository.
- Run
./build.ps1from a PowerShell terminal in the cloned path. - PlatyPS
- Pester
- PSScriptAnalyzer
- PowerShellGet
- PackageManagement
- InvokeBuild
- Report issues.
- Up-vote existing issues that are important to you.
- Improve documentation.
-
Contribute code.
- 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.
- Check rule path \u2014 By default, PSRule will look for rules in the
.ps-rule/directory. This directory is the root for your repository or the current working path by default. On case-sensitive file systems such as Linux, this directory name is case-sensitive. See Storing and naming rules for more information. - Check file name suffix \u2014 PSRule only looks for files with the
.Rule.ps1,.Rule.yaml, or.Rule.jsoncsuffix. On case-sensitive file systems such as Linux, this file suffix is case-sensitive. See Storing and naming rules for more information. - Check binding configuration \u2014 PSRule uses binding to work out which property to use for a resource type. To be able to use the
-Typeparameter ortypeproperties in rules definitions, binding must be set. This is automatically configured for modules such as PSRule for Azure, however must be set inps-rule.yamlfor custom rules. - Check modules \u2014 Check if your custom rules have a dependency on another module such as
PSRule.Rules.Azure. If your rules have a dependency, be sure to add the module in your command-line. - Configure binding by setting the Binding.TargetName option to set an alternative property to use as the name. OR
-
Update any existing keys set with the Suppression option to use the new SHA-512 hash.
- Windows PowerShell 5.1 for running as a PowerShell module. OR
- PowerShell 7.3 or later for development, building locally, or running as a PowerShell module.
- To run rules, use
runinstead ofanalyze. i.e.ps-rule run. - To restore modules for a workspace, use
module restoreinstead ofrestore. i.e.ps-rule module restore. - The module lock file
ps-rule.lock.jsonif set. UsemoduleCLI commands to manage the lock file. AND -
Modules defined in the Include.Module option, if set. Additionally the Requires option is used to constrain the version of modules installed.
- Use between 3 and 128 characters \u2014 This is the minimum and maximum length of a resource name.
- Only use allowed characters \u2014 To preserve consistency between file systems, some characters are not permitted. Dots, hyphens, and underscores are not permitted at the start and end of the name. Additionally some characters are restricted for future use. The following characters are not permitted:
<(less than)>(greater than):(colon)/(forward slash)\\(backslash)|(vertical bar or pipe)?(question mark)*(asterisk)\"(double quote)'(single quote)`(backtick)+(plus)@(at sign)- Integer value zero, sometimes referred to as the ASCII NUL character.
- Characters whose integer representations are in the range from 1 through 31.
AzurePipelines- Output is written for integration Azure Pipelines.GitHubActions- Output is written for integration GitHub Actions.VisualStudioCode- Output is written for integration with Visual Studio Code.- If the
TF_BUILDenvironment variable is set totrue,AzurePipelineswill be used. - If the
GITHUB_ACTIONSenvironment variable is set totrue,GitHubActionswill be used. - If the
TERM_PROGRAMenvironment variable is set tovscode,VisualStudioCodewill be used. - Use
Client. TargetNameTargetTypeTargetObject- Enable or explicitly reference them.
- Version rules. PowerShell modules support semantic versioning (semver).
- Reuse rules across projects, pipelines or teams.
- Publish rules to external consumers via the PowerShell Gallery.
- Creating a module manifest
- Including rules and baselines
- Defining a module configuration
- Including documentation
- Enterprise.Rules/
- rules/
- Baseline.Rule.yaml
- Config.Rule.yaml
- Standards.Rule.ps1
- Enterprise.Rules.psd1
- rules/
Binding.FieldBinding.IgnoreCaseBinding.NameSeparatorBinding.PreferTargetInfoBinding.TargetNameBinding.TargetTypeBinding.UseQualifiedNameConfigurationOutput.CultureRule.Baseline- Enterprise.Rules/
- en/
- Org.Az.Storage.UseHttps.md
- Org.Az.Resource.Tagging.md
- en-US/
- Org.Az.Storage.UseHttps.md
- fr-FR/
- Org.Az.Storage.UseHttps.md
- rules/
- Baseline.Rule.yaml
- Config.Rule.yaml
- Standards.Rule.ps1
- Enterprise.Rules.psd1
- en/
- Enterprise.Rules.psd1 - An example module manifest.
- Baseline.Rule.yaml - An example baseline.
- Config.Rule.yaml - An example module configuration.
- Packaging rules in a module
- Use .ps-rule/ \u2014 Create a sub-directory called
.ps-rulein the root of your repository. Use all lower-case in the sub-directory name. Put any custom rules within this sub-directory. - Use files ending with .Rule.* \u2014 PSRule uses a file naming convention to discover rules. Use one of the following depending on the file format you are using:
- YAML -
.Rule.yaml. - JSON -
.Rule.jsoncor.Rule.json. - PowerShell -
.Rule.ps1.
- YAML -
Azure.AKS.VersionAzure.AKS.AuthorizedIPsAzure.SQL.MinTLS- Use between 3 and 128 characters \u2014 This is the minimum and maximum length of a resource name.
- Only use allowed characters \u2014 To preserve consistency between file systems, some characters are not permitted. Dots, hyphens, and underscores are not permitted at the start and end of the name. Additionally some characters are restricted for future use. The following characters are not permitted:
<(less than)>(greater than):(colon)/(forward slash)\\(backslash)|(vertical bar or pipe)?(question mark)*(asterisk)\"(double quote)'(single quote)`(backtick)+(plus)@(at sign)- Integer value zero, sometimes referred to as the ASCII NUL character.
- Characters whose integer representations are in the range from 1 through 31.
- Use a standard prefix \u2014 You can use the
Local.orOrg.prefix for standalone rules.- Alternatively choose a short prefix that identifies your organization.
- Use dotted notation \u2014 Use dots to separate rule name.
- Use a maximum length of 35 characters \u2014 The default view of
Invoke-PSRuletruncates longer names. PSRule supports longer rule names however ifInvoke-PSRuleis called directly consider usingFormat-List. -
Avoid using special characters and punctuation \u2014 Although these characters can be used in many cases, they may not be easy to use with all PSRule features.
- Enforce secure traffic by requiring
supportsHttpsTrafficOnlyto betrue. - Enforce use of TLS 1.2 as a minimum by requiring
minTLSVersionto be1.2. - Use a short
Synopsis:to describe your rule in a line comment above your rule. For this to be interpreted by PSRule, only a single line is allowed. - Name your rule with a unique name.
- The
conditionproperty determines the checks PSRule will use to testsettings.json. Specifically, the object pathconfigures.supportsHttpsTrafficOnlymust exist and be set totrue. - Use a short
Synopsis:to describe your rule in a line comment above your rule. For this to be interpreted by PSRule, only a single line is allowed. - Name your rule with a unique name.
- The
conditionproperty determines the checks PSRule will use to testsettings.json. Specifically, the object pathconfigures.supportsHttpsTrafficOnlymust exist and be set totrue. - Use a short
Synopsis:to describe your rule in a line comment above your rule. For this to be interpreted by PSRule, only a single line is allowed. - Name your rule with a unique name.
- The condition contained within the curly braces
{ }determines the checks PSRule will use to testsettings.json. - The
$Assert.HasFieldValuemethod checks the object pathconfigures.supportsHttpsTrafficOnlyexists and is set totrue. - Using the
allOfexpression requires that all conditions be true for the rule to pass. This expression allows an array of one or more conditions to be provided. UsinganyOfwould pass the rule if any single condition is true. - Using the
allOfexpression requires that all conditions be true for the rule to pass. This expression allows an array of one or more conditions to be provided. UsinganyOfwould pass the rule if any single condition is true. - An additional,
$Assert.HasFieldValueassertion helper method can be called. The rule will pass if all of the conditions return true. Error- A serious problem that must be addressed before going forward.Warning- A problem that should be addressed.Information- A minor problem or an opportunity to improve the code.- YAML \u2014 Start authoring quickly with minimal knowledge of PowerShell.
- JSON \u2014 Generate rules automatically using automation tools.
- PowerShell \u2014 Integrate with other tools using PowerShell cmdlets.
- Expressions \u2014 Schema-based conditions written in YAML or JSON. Expressions can be used in rules and selectors.
- Assertion methods \u2014 PowerShell-based condition helpers that make rules faster to author. Assertion methods can be used in combination with standard PowerShell code to build rules or conventions.
-
The
Equals,HasValueexpressions andHasFieldValueare similar.\u00a0\u21a9\u21a9\u21a9 - Using inline help
- Writing markdown documentation
- Localizing documentation files
- Synopsis resource comment.
metadata.displayNameproperty.metadata.descriptionproperty.metadata.linkproperty.spec.recommendproperty.- Synopsis script comment.
Recommendkeyword.Reasonkeyword.- Annotations are localized, and can have a different value for different languages; tags are not.
- Tags are indexed and can be used to filter rules; annotations have no affect on rule filtering.
online version- A URL to the online version of the document, used byGet-PSRuleHelp -Online.- If the rules are loose, PSRule will search for the culture directory in the same subdirectory as the
.Rule.ps1file. - When rules are included in a module, PSRule will search for the culture directory in the same subdirectory as the module manifest .psd1 file.
- .ps-rule/
- en/
- metadata.Name.md
- en-US/
- metadata.Name.md
- fr-FR/
- metadata.Name.md
- kubernetes.Rule.ps1
- en/
- Kubernetes.Rules/
- en/
- metadata.Name.md
- en-US/
- metadata.Name.md
- fr-FR/
- metadata.Name.md
- rules/
- kubernetes.Rule.ps1
- Kubernetes.Rules.psd1
- en/
- kubernetes.Rule.ps1 - An example rule for validating name label.
- metadata.Name - An example markdown documentation file.
- Environment
- BusinessUnit
- Department
- CostCode
- Use tags to organize your Azure resources and management hierarchy
- Require secure transfer in Azure Storage
- Sample policy for ensuring https traffic
app.kubernetes.io/nameapp.kubernetes.io/instanceapp.kubernetes.io/versionapp.kubernetes.io/componentapp.kubernetes.io/part-ofapp.kubernetes.io/managed-by- Recommended Labels
Invoke-PSRulewrites results as structured objectsAssert-PSRulewrites results as a formatted string.- None - Output is presented as an object using PowerShell defaults. This is the default.
- Yaml - Output is serialized as YAML.
- Json - Output is serialized as JSON.
- Markdown - Output is serialized as Markdown.
- NUnit3 - Output is serialized as NUnit3 (XML).
- Csv - Output is serialized as a comma separated values (CSV).
- Sarif - Output is serialized as SARIF.
- Client - Output is written to the host directly in green/ red to indicate outcome.
- Plain - Output is written as an unformatted string. This option can be redirected to a file.
- AzurePipelines - Output is written for integration Azure Pipelines.
- GitHubActions - Output is written for integration GitHub Actions.
- VisualStudioCode - Output is written for integration with Visual Studio Code.
- Detect - Output style will be detected by checking the environment variables. This is the default.
- If the
TF_BUILDenvironment variable is set totrue,AzurePipelineswill be used. - If the
GITHUB_ACTIONSenvironment variable is set totrue,GitHubActionswill be used. - If the
TERM_PROGRAMenvironment variable is set tovscode,VisualStudioCodewill be used. - Use
Client. Detail- Returns pass/ fail results for each rule per object.Summary- Failure or errors are shown but passing results are summarized.- Yaml - Output is serialized as YAML. This is the default.
- Json - Output is serialized as JSON.
- None - Output is presented as an object using PowerShell defaults. This is the default.
- Wide - Output is presented using the wide table format, which includes tags and wraps columns.
- Yaml - Output is serialized as YAML.
- Json - Output is serialized as JSON.
- None - Output is presented as an object using PowerShell defaults. This is the default.
- Yaml - Output is serialized as YAML.
- Json - Output is serialized as JSON.
Invoke-PSRulewrites results as structured objectsAssert-PSRulewrites results as a formatted string.Detail- Returns pass/ fail results for each rule per object.Summary- Returns summarized results for the rule and the worst outcome.- None - Output is presented as an object using PowerShell defaults. This is the default.
- Yaml - Output is serialized as YAML.
- Json - Output is serialized as JSON.
- Markdown - Output is serialized as Markdown.
- NUnit3 - Output is serialized as NUnit3 (XML).
- Csv - Output is serialized as a comma separated values (CSV).
- Wide - Output is presented using the wide table format, which includes reason and wraps columns.
- Sarif - Output is serialized as SARIF.
- The object fails if:
- Any rules fail or error.
- Any rules are inconclusive.
- The object passes if:
- No matching rules were found.
- All rules pass.
- Rules \u2014 PSRule supports running rules by name or tag. However, when working with a large number of rules it is often easier to group and run rules based on a name.
- Configuration \u2014 A baseline allows you to run any included rules with a predefined configuration by name.
- The
latestbaseline group is set toAzure.GA_2023_03within thePSRule.Rules.Azuremodule. - The
previewbaseline group is set toAzure.Preview_2023_03within thePSRule.Rules.Azuremodule. - The Azure Well-Architected Framework (WAF) defines pillars such as Security and Reliability.
- The CIS Benchmarks define a number of control IDs such as 3.12 and 13.4.
- Lock file is present - PSRule will use the module versions defined in the lock file.
- Lock file is not present - PSRule will use the latest version of each module installed locally.
- APIVersion - The field value must be a date version string.
- Contains - The field value must contain at least one of the strings.
- Count - The field value must contain the specified number of items.
- EndsWith - The field value must match at least one suffix.
- FileHeader - The file must contain a comment header.
- FilePath - The file path must exist.
- Greater - The field value must be greater.
- GreaterOrEqual - The field value must be greater or equal to.
- HasDefaultValue - The object should not have the field or the field value is set to the default value.
- HasField - The object must have any of the specified fields.
- HasFields - The object must have all of the specified fields.
- HasFieldValue - The object must have the specified field and that field is not empty.
- HasJsonSchema - The object must reference a JSON schema with the
$schemafield. - In - The field value must be included in the set.
- IsArray - The field value must be an array.
- IsBoolean - The field value must be a boolean.
- IsDateTime - The field value must be a DateTime.
- IsInteger - The field value must be an integer.
- IsLower - The field value must include only lowercase characters.
- IsNumeric - The field value must be a numeric type.
- IsString - The field value must be a string.
- IsUpper - The field value must include only uppercase characters.
- JsonSchema - The object must validate successfully against a JSON schema.
- Less - The field value must be less.
- LessOrEqual - The field value must be less or equal to.
- Like - The value must match any of the specified wildcard values.
- Match - The field value matches a regular expression pattern.
- NotContains - The value must not contain any of the specified strings.
- NotCount - The field value must not contain the specified number of items.
- NotEndsWith - The value must not end with any of the specified strings.
- NotHasField - The object must not have any of the specified fields.
- NotIn - The field value must not be included in the set.
- NotLike - The value must not match any of the specified wildcard values.
- NotMatch - The field value does not match a regular expression pattern.
- NotNull - The field value must not be null.
- NotStartsWith - The value must not start with any of the specified strings.
- NotWithinPath - The field must not be within the specified path.
- Null - The field value must not exist or be null.
- NullOrEmpty - The object must not have the specified field or it must be empty.
- TypeOf - The field value must be of the specified type.
- SetOf - The field value must match a set of specified values.
- StartsWith - The field value must match at least one prefix.
- Subset - The field value must include a set of specified values.
- Version - The field value must be a semantic version string.
- WithinPath - The field value must be within the specified path.
- The first parameter is always the input object of type
PSObject, additional parameters can be included based on the functionality required by the method.- In many cases the input object will be
$TargetObject, however assertion methods must not assume that$TargetObjectwill be used. - Assertion methods must accept a
$Nullinput object.
- In many cases the input object will be
- Assertion methods return the
AssertResultobject that is interpreted by the rule pipeline. - Property names for PSObjects or .NET objects.
- Keys for hash table or dictionaries.
- Indexes for arrays or collections.
- Queries that filter items from array or collection properties.
., or$refers to input object itself.Name,.Name, or$.Namerefers to the name member of the input object.Properties.enabledrefers to the enabled member under the Properties member. Alternatively this can also be written asProperties['enabled'].Tags.envrefers to the env member under a hash table property of the input object.Tags+envrefers to the env member using a case-sensitive match.Properties.securityRules[0].namereferences to the name member of the first security rule.Properties.securityRules[-1].namereferences to the name member of the last security rule.Properties.securityRules[?@direction == 'Inbound'].namereturns the name of any inbound rules. This will return an array of security rule names.- Member names (properties and keys) are case-insensitive by default. To perform a case-sensitive match of a member name use a plus selector
+in front of the member name. Some assertions such asHasFieldprovide an option to match case when matching member names. When this is used, the plus selector perform an case-insensitive match. - Quoted member names with single or double quotes are supported with dot selector. i.e.
Properties.'spaced name'is valid. - Member names with a dash
-are supported without being quoted. However member names can not start or end with a dash. i.e.Properties.dashed-nameandProperties.'-dashed-name'are valid. inputObject- The object being checked for the specified field.field- The name of the field to check. This is a case insensitive compare.constraint(optional) - A version constraint, see below for details of version constrain format.includePrerelease(optional) - Determines if prerelease versions are included. Unless specified this defaults to$False.version- Must match version exactly. This also accepts the prefix=.- e.g.
2015-10-01,=2015-10-01
- e.g.
>version- Must be greater than version.- e.g.
>2015-10-01
- e.g.
>=version- Must be greater than or equal to version.- e.g.
>=2015-10-01
- e.g.
<version- Must be less than version.- e.g.
<2022-03-01
- e.g.
<=version- Must be less than or equal to version.- e.g.
<=2022-03-01
- e.g.
- Use a space to separate multiple constraints, each must be true (logical AND).
- Separates constraint sets with the double pipe
||. Only one constraint set must be true (logical OR). 2014-01-01 || >=2015-10-01 <2022-03-01results in:- Pass:
2014-01-01,2015-10-01,2019-06-30,2022-02-01. - Fail:
2015-01-01,2022-09-01.
- Pass:
- Constraints and versions containing prerelease identifiers are supported. i.e.
>=2015-10-01-previewor2015-10-01-preview. - A version containing a prerelease identifer follows similar ordering to semantic versioning. i.e.
2015-10-01-preview<2015-10-01-preview.1<2015-10-01<2022-03-01-preview<2022-03-01. - A constraint without a prerelease identifer will only match a stable version by default. Set
includePrereleaseto$Trueto include prerelease versions. Alternatively use the@preor@prereleaseflag in a constraint. - The parameter 'inputObject' is null.
- The parameter 'field' is null or empty.
- The field '{0}' does not exist.
- The field value '{0}' is not a version string.
- The version '{0}' does not match the constraint '{1}'.
inputObject- The object being checked for the specified field.field- The name of the field to check. This is a case insensitive compare.text- A string or an array of strings to compare the field value with. Only one string must match. When an empty array of strings is specified or text is an empty string,Containsalways passes.caseSensitive(optional) - Use a case sensitive compare of the field value. Case is ignored by default.- The parameter 'inputObject' is null.
- The parameter 'field' is null or empty.
- The parameter 'text' is null.
- The field '{0}' does not exist.
- The field value '{0}' is not a string.
- The field '{0}' does not contain '{1}'.
inputObject- The object being checked for the specified field.field- The name of the field to check. This is a case insensitive compare.count- The number of items that the field value must contain.- The parameter 'inputObject' is null.
- The parameter 'field' is null or empty.
- The field '{0}' does not exist.
- The field '{0}' is not enumerable.
- The field '{0}' has '{1}' items instead of '{2}'.
inputObject- The object being checked for the specified field.field- The name of the field to check. This is a case insensitive compare.suffix- A suffix or an array of suffixes to compare the field value with. Only one suffix must match. When an empty array of suffixes is specified or suffix is an empty string,EndsWithalways passes.caseSensitive(optional) - Use a case sensitive compare of the field value. Case is ignored by default.- The parameter 'inputObject' is null.
- The parameter 'field' is null or empty.
- The parameter 'suffix' is null.
- The field '{0}' does not exist.
- The field value '{0}' is not a string.
- The field '{0}' does not end with '{1}'.
inputObject- The object being checked for the specified field.field- The name of the field containing a valid file path.header- One or more lines of a header to compare with file contents.prefix(optional) - An optional comment prefix for each line. By default a comment prefix will automatically detected based on file extension. When set, detection by file extension is skipped..bicep,.bicepparam,.cs,.csx,.ts,.tsp,.tsx,.js,.jsx,.fs,.go,.groovy,.php,.cpp,.h,.java,.json,.jsonc,.scala,Jenkinsfile- Use a prefix of (//)..editorconfig,.ipynb,.ps1,.psd1,.psm1,.yaml,.yml,.r,.py,.sh,.tf,.tfvars,.toml,.gitignore,.pl,.rb,Dockerfile- Use a prefix of (#)..sql,.lau- Use a prefix of (--)..bat,.cmd- Use a prefix of (::).- The parameter 'inputObject' is null.
- The parameter 'field' is null or empty.
- The field '{0}' does not exist.
- The field value '{0}' is not a string.
- The file '{0}' does not exist.
- The header was not set.
inputObject- The object being checked for the specified field.field- The name of the field containing a file path.suffix(optional) - Additional file path suffixes to append. When specified each suffix is combined with the file path. Only one full file path must be a valid file for the assertion method to pass.- The parameter 'inputObject' is null.
- The parameter 'field' is null or empty.
- The field '{0}' does not exist.
- The field value '{0}' is not a string.
- The file '{0}' does not exist.
- An integer or float, a numerical comparison is used.
- An array, the number of elements is compared.
- A string, the length of the string is compared.
- A DateTime, the number of days from the current time is compared.
inputObject- The object being checked for the specified field.field- The name of the field to check. This is a case insensitive compare.value- A integer to compare the field value against.convert(optional) - Convert numerical strings and use a numerical comparison instead of using string length. By default the string length is compared.- The parameter 'inputObject' is null.
- The parameter 'field' is null or empty.
- The field '{0}' does not exist.
- The value '{0}' was not > '{1}'.
- The field value '{0}' can not be compared with '{1}'.
- An integer or float, a numerical comparison is used.
- An array, the number of elements is compared.
- A string, the length of the string is compared.
- A DateTime, the number of days from the current time is compared.
inputObject- The object being checked for the specified field.field- The name of the field to check. This is a case insensitive compare.value- A integer to compare the field value against.convert(optional) - Convert numerical strings and use a numerical comparison instead of using string length. By default the string length is compared.- The parameter 'inputObject' is null.
- The parameter 'field' is null or empty.
- The field '{0}' does not exist.
- The value '{0}' was not >= '{1}'.
- The field value '{0}' can not be compared with '{1}'.
inputObject- The object being checked for the specified field.field- The name of the field to check. This is a case insensitive compare.defaultValue- The expected value if the field exists.- The field does not exist.
- The field value is set to
defaultValue. - The field value is set to a value different from
defaultValue. - The parameter 'inputObject' is null.
- The parameter 'field' is null or empty.
- The field '{0}' is set to '{1}'.
inputObject- The object being checked for the specified field.field- The name of one or more fields to check. By default, a case insensitive compare is used. If more than one field is specified, only one must exist.caseSensitive(optional) - Use a case sensitive compare of the field name.- The parameter 'inputObject' is null.
- The parameter 'field' is null or empty.
- Does not exist.
inputObject- The object being checked for the specified fields.field- The name of one or more fields to check. By default, a case insensitive compare is used. If more than one field is specified, all fields must exist.caseSensitive(optional) - Use a case sensitive compare of the field name.- The parameter 'inputObject' is null.
- The parameter 'field' is null or empty.
- The field '{0}' does not exist.
- The field does not exist.
- The field value is
$Null. - The field value is an empty array or collection.
- The field value is an empty string
''. inputObject- The object being checked for the specified field.field- The name of the field to check. This is a case insensitive compare.expectedValue(optional) - Check that the field value is set to a specific value. To check$NulluseNullOrEmptyinstead. IfexpectedValueis$Nullthe field value will not be compared.- The parameter 'inputObject' is null.
- The parameter 'field' is null or empty.
- Does not exist.
- Is null or empty.
- Is set to '{0}'.
inputObject- The object being compared.uri- Optional. When specified, the object being compared must have a$schemaproperty set to one of the specified schemas.ignoreScheme- Optional. By default,ignoreSchemeis$False. When$True, the schema will match ifhttporhttpsis specified.- The parameter 'inputObject' is null.
- The field '$schema' does not exist.
- The field value '$schema' is not a string.
- The value of '$schema' is null or empty.
- None of the specified schemas match '{0}'.
inputObject- The object being compared against the JSON schema.uri- A URL or file path to a JSON schema file formatted as UTF-8. Either a file path or URL can be used to specify the location of the schema file.- The parameter 'inputObject' is null.
- The parameter 'uri' is null or empty.
- The JSON schema '{0}' could not be found.
- Failed schema validation on {0}. {1}
inputObject- The object being checked for the specified field.field- The name of the field to check. This is a case insensitive compare.values- An array of values that the field value is compared against. When an empty array is specified,Inwill always fail.caseSensitive(optional) - Use a case sensitive compare of the field value. Case is ignored by default.- The parameter 'inputObject' is null.
- The parameter 'field' is null or empty.
- The parameter 'values' is null.
- The field '{0}' does not exist.
- The field value '{0}' was not included in the set.
inputObject- The object being checked for the specified field.field- The name of the field to check. This is a case insensitive compare.- The parameter 'inputObject' is null.
- The parameter 'field' is null or empty.
- The field '{0}' does not exist.
- The field value '{0}' is null.
- The field value '{1}' of type {0} is not [array].
inputObject- The object being checked for the specified field.field- The name of the field to check. This is a case insensitive compare.convert(optional) - Try to convert strings. By default strings are not converted.- The parameter 'inputObject' is null.
- The parameter 'field' is null or empty.
- The field '{0}' does not exist.
- The field value '{0}' is null.
- The value '{0}' is not a boolean.
inputObject- The object being checked for the specified field.field- The name of the field to check. This is a case insensitive compare.convert(optional) - Try to convert strings. By default strings are not converted.- The parameter 'inputObject' is null.
- The parameter 'field' is null or empty.
- The field '{0}' does not exist.
- The field value '{0}' is null.
- The value '{0}' is not a date.
inputObject- The object being checked for the specified field.field- The name of the field to check. This is a case insensitive compare.convert(optional) - Try to convert strings. By default strings are not converted.- The parameter 'inputObject' is null.
- The parameter 'field' is null or empty.
- The field '{0}' does not exist.
- The field value '{0}' is null.
- The value '{0}' is not an integer.
inputObject- The object being checked for the specified field.field- The name of the field to check. This is a case insensitive compare.requireLetters(optional) - Require each character to be lowercase letters only. Non-letter characters are ignored by default.- The parameter 'inputObject' is null.
- The parameter 'field' is null or empty.
- The field '{0}' does not exist.
- The field value '{0}' is not a string.
- The value '{0}' does not contain only lowercase characters.
- The value '{0}' does not contain only letters.
inputObject- The object being checked for the specified field.field- The name of the field to check. This is a case insensitive compare.convert(optional) - Try to convert numerical strings. By default strings are not converted.- The parameter 'inputObject' is null.
- The parameter 'field' is null or empty.
- The field '{0}' does not exist.
- The field value '{0}' is null.
- The value '{0}' is not numeric.
inputObject- The object being checked for the specified field.field- The name of the field to check. This is a case insensitive compare.- The parameter 'inputObject' is null.
- The parameter 'field' is null or empty.
- The field '{0}' does not exist.
- The field value '{0}' is null.
- The value '{0}' is not a string.
inputObject- The object being checked for the specified field.field- The name of the field to check. This is a case insensitive compare.requireLetters(optional) - Require each character to be uppercase letters only. Non-letter characters are ignored by default.- The parameter 'inputObject' is null.
- The parameter 'field' is null or empty.
- The field '{0}' does not exist.
- The field value '{0}' is not a string.
- The value '{0}' does not contain only uppercase characters.
- The value '{0}' does not contain only letters.
- An integer or float, a numerical comparison is used.
- An array, the number of elements is compared.
- A string, the length of the string is compared.
- A DateTime, the number of days from the current time is compared.
inputObject- The object being checked for the specified field.field- The name of the field to check. This is a case insensitive compare.value- A integer to compare the field value against.convert(optional) - Convert numerical strings and use a numerical comparison instead of using string length. By default the string length is compared.- The parameter 'inputObject' is null.
- The parameter 'field' is null or empty.
- The field '{0}' does not exist.
- The value '{0}' was not < '{1}'.
- The field value '{0}' can not be compared with '{1}'.
- An integer or float, a numerical comparison is used.
- An array, the number of elements is compared.
- A string, the length of the string is compared.
- A DateTime, the number of days from the current time is compared.
inputObject- The object being checked for the specified field.field- The name of the field to check. This is a case insensitive compare.value- A integer to compare the field value against.convert(optional) - Convert numerical strings and use a numerical comparison instead of using string length. By default the string length is compared.- The parameter 'inputObject' is null.
- The parameter 'field' is null or empty.
- The field '{0}' does not exist.
- The value '{0}' was not <= '{1}'.
- The field value '{0}' can not be compared with '{1}'.
inputObject- The object being checked for the specified field.field- The name of the field to check. This is a case insensitive compare.pattern- A pattern or an array of patterns to compare the field value with. Only one pattern must match. When an empty array of patterns is specified,Likealways passes.caseSensitive(optional) - Use a case sensitive compare of the field value. Case is ignored by default.- The parameter 'inputObject' is null.
- The parameter 'field' is null or empty.
- The parameter 'prefix' is null.
- The field '{0}' does not exist.
- The field value '{0}' is not a string.
- The value '{0}' is not like '{1}'.
inputObject- The object being checked for the specified field.field- The name of the field to check. This is a case insensitive compare.pattern- A regular expression pattern to match.caseSensitive(optional) - Use a case sensitive compare of the field value. Case is ignored by default.- The parameter 'inputObject' is null.
- The parameter 'field' is null or empty.
- The field '{0}' does not exist.
- The field value '{0}' is not a string.
- The field value '{0}' does not match the pattern '{1}'.
inputObject- The object being checked for the specified field.field- The name of the field to check. This is a case insensitive compare.text- A string or an array of strings to compare the field value with. When an empty array of strings is specified or text is an empty string,NotContainsalways passes.caseSensitive(optional) - Use a case sensitive compare of the field value. Case is ignored by default.- The parameter 'inputObject' is null.
- The parameter 'field' is null or empty.
- The parameter 'text' is null.
- The field '{0}' does not exist.
- The value '{0}' contains '{1}'.
inputObject- The object being checked for the specified field.field- The name of the field to check. This is a case insensitive compare.count- The number of items that the field value must contain.- The parameter 'inputObject' is null.
- The parameter 'field' is null or empty.
- The field '{0}' does not exist.
- The field '{0}' is not enumerable.
- The field '{0}' has '{1}' items instead of '{2}'.
inputObject- The object being checked for the specified field.field- The name of the field to check. This is a case insensitive compare.suffix- A suffix or an array of suffixes to compare the field value with. When an empty array of suffixes is specified or suffix is an empty string,NotEndsWithalways passes.caseSensitive(optional) - Use a case sensitive compare of the field value. Case is ignored by default.- The parameter 'inputObject' is null.
- The parameter 'field' is null or empty.
- The parameter 'suffix' is null.
- The field '{0}' does not exist.
- The value '{0}' ends with '{1}'.
inputObject- The object being checked for the specified field.field- The name of one or more fields to check. By default, a case insensitive compare is used. If more than one field is specified, all must not exist.caseSensitive(optional) - Use a case sensitive compare of the field name.- The parameter 'inputObject' is null.
- The parameter 'field' is null or empty.
- The field '{0}' exists.
inputObject- The object being checked for the specified field.field- The name of the field to check. This is a case insensitive compare.values- An array values that the field value is compared against. When an empty array is specified,NotInwill always pass.caseSensitive(optional) - Use a case sensitive compare of the field value. Case is ignored by default.- The parameter 'inputObject' is null.
- The parameter 'field' is null or empty.
- The parameter 'values' is null.
- The field value '{0}' was in the set.
inputObject- The object being checked for the specified field.field- The name of the field to check. This is a case insensitive compare.pattern- A pattern or an array of patterns to compare the field value with. When an empty array of pattens is specified,NotLikealways passes.caseSensitive(optional) - Use a case sensitive compare of the field value. Case is ignored by default.- The parameter 'inputObject' is null.
- The parameter 'field' is null or empty.
- The parameter 'prefix' is null.
- The field '{0}' does not exist.
- The value '{0}' is like '{1}'
inputObject- The object being checked for the specified field.field- The name of the field to check. This is a case insensitive compare.pattern- A regular expression pattern to match.caseSensitive(optional) - Use a case sensitive compare of the field value. Case is ignored by default.- The parameter 'inputObject' is null.
- The parameter 'field' is null or empty.
- The field value '{0}' is not a string.
- The field value '{0}' matches the pattern '{1}'.
inputObject- The object being checked for the specified field.field- The name of the field to check. This is a case insensitive compare.- The parameter 'inputObject' is null.
- The parameter 'field' is null or empty.
- The field '{0}' does not exist.
- The field value '{0}' is null.
inputObject- The object being checked for the specified field.field- The name of the field to check. This is a case insensitive compare.prefix- A prefix or an array of prefixes to compare the field value with. When an empty array of prefixes is specified or prefix is an empty string,NotStartsWithalways passes.caseSensitive(optional) - Use a case sensitive compare of the field value. Case is ignored by default.- The parameter 'inputObject' is null.
- The parameter 'field' is null or empty.
- The parameter 'prefix' is null.
- The field '{0}' does not exist.
- The value '{0}' starts with '{1}'.
inputObject- The object being checked for the specified field.field- The name of the field containing a file path. When the field isInputFileInfoorFileInfo, PSRule will automatically resolve the file path.path- An array of one or more directory paths to check. Only one path must match.caseSensitive(optional) - Determines if case-sensitive path matching is used. This can be set to$Trueor$False. When not set or$Null, the case-sensitivity rules of the working path file system will be used.- The parameter 'inputObject' is null.
- The parameter 'field' is null or empty.
- The parameter 'path' is null or empty.
- The field '{0}' does not exist.
- The file '{0}' is within the path '{1}'.
- The field does not exist.
- The field value is
$Null. inputObject- The object being checked for the specified field.field- The name of the field to check. This is a case insensitive compare.- The parameter 'inputObject' is null.
- The parameter 'field' is null or empty.
- The field value '{0}' is not null.
- The field does not exist.
- The field value is
$Null. - The field value is an empty array or collection.
- The field value is an empty string
''. inputObject- The object being checked for the specified field.field- The name of the field to check. This is a case insensitive compare.- The parameter 'inputObject' is null.
- The parameter 'field' is null or empty.
- The field '{0}' is not empty.
inputObject- The object being checked for the specified field.field- The name of the field to check. This is a case insensitive compare.type- One or more specified types to check. The field value only has to match a single type of more than one type is specified.- The parameter 'inputObject' is null.
- The parameter 'field' is null or empty.
- The parameter 'type' is null or empty.
- The field '{0}' does not exist.
- The field value '{0}' is null.
- The field value '{2}' of type {1} is not {0}.
inputObject- The object being checked for the specified field.field- The name of the field to check. This is a case insensitive compare.values- An array of values that the field value is compared against.caseSensitive(optional) - Use a case sensitive compare of the field value. Case is ignored by default.- The parameter 'inputObject' is null.
- The parameter 'field' is null or empty.
- The parameter 'values' is null.
- The field '{0}' does not exist.
- The field '{0}' is not enumerable.
- The field '{0}' did not contain '{1}'.
- The field '{0}' has '{1}' items instead of '{2}'.
inputObject- The object being checked for the specified field.field- The name of the field to check. This is a case insensitive compare.prefix- A prefix or an array of prefixes to compare the field value with. Only one prefix must match. When an empty array of prefixes is specified or prefix is an empty string,StartsWithalways passes.caseSensitive(optional) - Use a case sensitive compare of the field value. Case is ignored by default.- The parameter 'inputObject' is null.
- The parameter 'field' is null or empty.
- The parameter 'prefix' is null.
- The field '{0}' does not exist.
- The field value '{0}' is not a string.
- The field '{0}' does not start with '{1}'.
inputObject- The object being checked for the specified field.field- The name of the field to check. This is a case insensitive compare.values- An array of values that the field value is compared against. When an empty array is specified,Subsetwill always pass.caseSensitive(optional) - Use a case sensitive compare of the field value. Case is ignored by default.unique(optional) - A boolean value that indicates if the items must be unique. Whentruethe field value must not contain duplicate items.- The parameter 'inputObject' is null.
- The parameter 'field' is null or empty.
- The parameter 'values' is null.
- The field '{0}' does not exist.
- The field '{0}' is not enumerable.
- The field '{0}' did not contain '{1}'.
- The field '{0}' included multiple instances of '{1}'.
inputObject- The object being checked for the specified field.field- The name of the field to check. This is a case insensitive compare.constraint(optional) - A version constraint, see below for details of version constrain format.includePrerelease(optional) - Determines if prerelease versions are included. Unless specified this defaults to$False.version- Must match version exactly. This also accepts the following prefixes;=,v,V.- e.g.
1.2.3,=1.2.3
- e.g.
>version- Must be greater than version.- e.g.
>1.2.3
- e.g.
>=version- Must be greater than or equal to version.- e.g.
>=1.2.3
- e.g.
<version- Must be less than version.- e.g.
<1.2.3
- e.g.
<=version- Must be less than or equal to version.- e.g.
<=1.2.3
- e.g.
^version- Compatible with version.- e.g.
^1.2.3->=1.2.3,<2.0.0
- e.g.
~version- Approximately equivalent to version- e.g.
~1.2.3->=1.2.3,<1.3.0
- e.g.
- Use a space to separate multiple constraints, each must be true (logical AND).
- Separates constraint sets with the double pipe
||. Only one constraint set must be true (logical OR). 1.2.3 || >=3.4.5 <5.0.0results in:- Pass:
1.2.3,3.4.5,3.5.0,4.9.9. - Fail:
3.0.0,5.0.0.
- Pass:
- Constraints and versions containing prerelease identifiers are supported. i.e.
>=1.2.3-build.1or1.2.3-build.1. - A version containing a prerelease identifer follows semantic versioning rules. i.e.
1.2.3-alpha<1.2.3-alpha.1<1.2.3-alpha.beta<1.2.3-beta<1.2.3-beta.2<1.2.3-beta.11<1.2.3-rc.1<1.2.3. - A constraint without a prerelease identifer will only match a stable version by default. Set
includePrereleaseto$Trueto include prerelease versions. - Constraints with a prerelease identifer will only match:
- Matching prerelease versions of the same major.minor.patch version by default. Set
includePrereleaseto$Trueto include prerelease versions of all matching versions. Alternatively use the@preor@prereleaseflag in a constraint. - Matching stable versions.
- Matching prerelease versions of the same major.minor.patch version by default. Set
>=1.2.3results in:- Pass:
1.2.3,9.9.9. - Fail:
1.2.3-build.1,9.9.9-build.1.
- Pass:
>=1.2.3-0results in:- Pass:
1.2.3,1.2.3-build.1,9.9.9. - Fail:
9.9.9-build.1.
- Pass:
<1.2.3results in:- Pass:
1.2.2,1.0.0. - Fail:
1.0.0-build.1,1.2.3-build.1.
- Pass:
<1.2.3-0results in:- Pass:
1.2.2,1.0.0. - Fail:
1.0.0-build.1,1.2.3-build.1.
- Pass:
@pre >=1.2.3results in:- Pass:
1.2.3,9.9.9,9.9.9-build.1 - Fail:
1.2.3-build.1.
- Pass:
@pre >=1.2.3-0results in:- Pass:
1.2.3,1.2.3-build.1,9.9.9,9.9.9-build.1.
- Pass:
- The parameter 'inputObject' is null.
- The parameter 'field' is null or empty.
- The field '{0}' does not exist.
- The field value '{0}' is not a version string.
- The version '{0}' does not match the constraint '{1}'.
inputObject- The object being checked for the specified field.field- The name of the field containing a file path. When the field isInputFileInfoorFileInfo, PSRule will automatically resolve the file path.path- An array of one or more directory paths to check. Only one path must match.caseSensitive(optional) - Determines if case-sensitive path matching is used. This can be set to$Trueor$False. When not set or$Null, the case-sensitivity rules of the working path file system will be used.- The parameter 'inputObject' is null.
- The parameter 'field' is null or empty.
- The parameter 'path' is null or empty.
- The field '{0}' does not exist.
- The file '{0}' is not within the path '{1}'.
- Handles pass/ fail conditions and collection of reason information.
- Allows rules to implement their own handling or forward it up the stack to affect the rule outcome.
Result- Either$True(Pass) or$False(Fail).AddReason(<string> text)- Can be used to append additional reasons to the result. A reason can only be set if the assertion failed. Reason text should be localized before calling this method. Localization can be done using the$LocalizedDataautomatic variable.WithReason(<string> text, <bool> replace)- Can be used to append or replace reasons on the result. In addition,WithReasoncan be chained.Reason(<string> text, params <object[]> args)- Replaces the reason on the results with a formatted string. This method can be chained. For usage see examples below.ReasonFrom(<string> path, <string> text, params <object[]> args)- Replaces the reason on the results with a formatted string. Path specifies the object path that affected the reason. This method can be chained. For usage see examples below.ReasonIf(<bool> condition, <string> text, params <object[]> args)- Replaces the reason if the condition is true. This method can be chained, similar toReason.ReasonIf(<string> path, <bool> condition, <string> text, params <object[]> args)- Replaces the reason if the condition is true. This method can be chained, similar toReasonFrom.PathPrefix(<string> path)- Adds a path prefix to any reasons. This method can be chained. For usage see examples below.GetReason()- Gets any reasons currently associated with the failed result.Complete()- Returns$True(Pass) or$False(Fail) to the rule record. If the assertion failed, any reasons are automatically added to the rule record. To read the result without adding reason to the rule record use theResultproperty.Ignore()- Ignores the result. Nothing future is returned and any reasons are cleared. Use this method when implementing custom handling.type- The issue type. Issues are filtered by type.name- The name of a specific issue.message- The reason message for the issue.Create(<bool> condition, <string> reason, params <object[]> args)- Returns a result either pass or fail assertion result. Additional arguments can be provided to format the custom reason string.Create(<TargetIssueInfo[]>)- Returns a result based on reported downstream issues.Pass()- Returns a pass assertion result.Fail()- Results a fail assertion result.Fail(<string> reason, params <object[]> args)- Results a fail assertion result with a custom reason. Additional arguments can be provided to format the custom reason string.AnyOf(<AssertResult[]> results)- Results from assertion methods are aggregated into a single result. If any result is a pass, the result is a pass. If all results are fails, the result is a fail and any reasons are added to the result. If no results are provided, the result is a fail.AllOf(<AssertResult[]> results)- Results from assertion methods are aggregated into a single result. If all results are passes, the result is a pass. If any result is a fail, the result is a fail and any reasons are added to the result. If no results are provided, the result is a fail.- about_PSRule_Variables
- Invoke-PSRule
- Binding.Field
- Binding.IgnoreCase
- Binding.NameSeparator
- Binding.PreferTargetInfo
- Binding.TargetName
- Binding.TargetType
- Binding.UseQualifiedName
- Configuration
- Rule.Include
- Rule.IncludeLocal
- Rule.Exclude
- Rule.Tag
- Included as a baseline spec within a YAML or JSON file.
- When using this method, multiple baseline specs can be defined within the same YAML/JSON file.
- Each YAML baseline spec is separated using
---. - Each JSON baseline spec is separated by JSON objects in a JSON array.
- Set within a workspace options file like
ps-rule.yamlorps-rule.json.- Only a single baseline can be specified.
- See about_PSRule_Options for details on using this method.
- Parameter -
-Nameand-Tag. - Explicit - A named baseline specified with
-Baseline. - Workspace - Included in
ps-rule.yamlor specified on the command line with-Option. - Module - A baseline object included in a
.Rule.yamlor.Rule.jsonfile. obsolete- Marks the baseline as obsolete when set totrue. PSRule will generate a warning when an obsolete baseline is used.Initializeoccurs once at the beginning of the pipeline. UseInitializeto perform any initialization required by the convention.Beginoccurs once per object before the any rules are executed. UseBeginblocks to perform expansion, set data, or alter the object before rules are processed.Processoccurs once per object after all rules are executed. UseProcessblocks to perform per object tasks such as generate badges.Endoccurs only once after all objects have been processed. UseEndblocks to upload results to an external service.Initializecan not use automatic variables except$PSRule. Most methods and properties of$PSRuleare not available inInitialize.BeginandProcesscan not use rule specific variables such as$Rule. These blocks are executed outside of the context of a single rule.Endcan not use automatic variables except$PSRule. Most methods and properties of$PSRuleare not available inEnd.- Using
-Conventionparameter. - PSRule options.
- Module configuration.
- Invoke-PSRule
- Annotations - Additional metadata included in results.
- Synopsis - A brief description on the intended purpose of the rule.
- Description - A detailed description on the intended purpose of the rule.
- Recommendation - A detailed explanation of the requirements to pass the rule.
- Notes - Any additional information or configuration options.
- Links - Any links to external references.
- When resources are standalone, the culture subdirectory is relative to the
*.Rule.*file. - When packaged in a module, the culture subdirectory is relative to the module manifest
.psd1file. - Get-PSRuleHelp
- APIVersion
- Contains
- Count
- Equals
- EndsWith
- Exists
- Greater
- GreaterOrEquals
- HasDefault
- HasSchema
- HasValue
- In
- IsLower
- IsString
- IsArray
- IsBoolean
- IsDateTime
- IsInteger
- IsNumeric
- IsUpper
- Less
- LessOrEquals
- Like
- Match
- NotContains
- NotCount
- NotEndsWith
- NotEquals
- NotIn
- NotLike
- NotMatch
- NotStartsWith
- NotWithinPath
- SetOf
- StartsWith
- Subset
- WithinPath
- Version
- AllOf
- AnyOf
- Not
- Field
- Name
- Scope
- Source
- Type
caseSensitive- Optionally, a case sensitive-comparison can be performed. By default, case-insensitive comparison is performed.convert- Optionally, types can be converted to string type. By defaultconvertisfalse.- If the operand is a field, and the field does not exist, contains always returns
false. caseSensitive- Optionally, a case sensitive-comparison can be performed. This only applies to string comparisons. By default, case-insensitive comparison is performed.convert- Optionally, perform type conversion on operand type. By defaultconvertisfalse.caseSensitive- Optionally, a case sensitive-comparison can be performed. By default, case-insensitive comparison is performed.convert- Optionally, types can be converted to string type. By defaultconvertisfalse.- If the operand is a field, and the field does not exist, endsWith always returns
false. - When
exists: true, exists will returntrueif the field exists. - When
exists: false, exists will returntrueif the field does not exist. - A property name.
- A key within a hashtable or dictionary.
- An index in an array or collection.
- A nested path through an object.
convert- Optionally, perform type conversion on operand type. By defaultconvertisfalse.- An integer or float, a numerical comparison is used.
- An array, the number of elements is compared.
- A string, the length of the string is compared. If
convertistrue, the string is converted a number instead. - A DateTime, the number of days from the current time is compared.
convert- Optionally, perform type conversion on operand type. By defaultconvertisfalse.- An integer or float, a numerical comparison is used.
- An array, the number of elements is compared.
- A string, the length of the string is compared. If
convertistrue, the string is converted a number instead. - A DateTime, the number of days from the current time is compared.
caseSensitive- Optionally, a case-sensitive comparison can be performed for string values. By default, case-insensitive comparison is performed.caseSensitive- Optionally, a case-sensitive comparison can be performed. By default, case-insensitive comparison is performed.ignoreScheme- Optionally, the URI scheme is ignored in the comparison. By default, the scheme is compared. Whentrue, the schema will match if eitherhttp://orhttps://is specified.- When
hasSchema: [], hasSchema will returntrueif any non-empty$schemaproperty is defined. - When
hasValue: true, hasValue will returntrueif the field is not empty. - When
hasValue: false, hasValue will returntrueif the field is empty. - When
isLower: true, isLower will returntrueif the operand is a lowercase string. Non-letter characters are ignored. - When
isLower: false, isLower will returntrueif the operand is not a lowercase string. - If the operand is a field, and the field does not exist isLower always returns
false. - When
isString: true, isString will returntrueif the operand is a string. - When
isString: false, isString will returntrueif the operand is not a string or is null. - If the operand is a field, and the field does not exist isString always returns
false. - When
isArray: true, isArray will returntrueif the operand is an array. - When
isArray: false, isArray will returntrueif the operand is not an array or null. - If the operand is a field, and the field does not exist, isArray always returns
false. convert- Optionally, types can be converted to boolean type. E.g.'true'can be converted totrue. By defaultconvertisfalse.- When
isBoolean: true, isBoolean will returntrueif the operand is a boolean. - When
isBoolean: false, isBoolean will returnfalseif the operand is not a boolean or null. - When
convert: true, types will be converted to boolean before condition is evaluated. convert- Optionally, types can be converted to datetime type. E.g.'2021-04-03T15:00:00.00+10:00'can be converted to a datetime. By defaultconvertisfalse.- When
isDateTime: true, isDateTime will returntrueif the operand is a datetime. - When
isDateTime: false, isDateTime will returnfalseif the operand is not a datetime or null. - When
convert: true, types will be converted to datetime before condition is evaluated. convert- Optionally, types can be converted to integer type. E.g.'123'can be converted to123. By defaultconvertisfalse.- When
isInteger: true, isInteger will returntrueif the operand is an integer. - When
isInteger: false, isInteger will returnfalseif the operand is not an integer or null. - When
convert: true, types will be converted to integer before condition is evaluated. convert- Optionally, types can be converted to numeric type. E.g.'123'can be converted to123. By defaultconvertisfalse.- When
isNumeric: true, isNumeric will returntrueif the operand is a numeric. - When
isNumeric: false, isNumeric will returnfalseif the operand is not a numeric or null. - When
convert: true, types will be converted to numeric before condition is evaluated. - When
isUpper: true, isUpper will returntrueif the operand is an uppercase string. Non-letter characters are ignored. - When
isUpper: false, isUpper will returntrueif the operand is not an uppercase string. - If the operand is a field, and the field does not exist isUpper always returns
false. convert- Optionally, perform type conversion on operand type. By defaultconvertisfalse.- An integer or float, a numerical comparison is used.
- An array, the number of elements is compared.
- A string, the length of the string is compared. If
convertistrue, the string is converted a number instead. - A DateTime, the number of days from the current time is compared.
convert- Optionally, perform type conversion on operand type. By defaultconvertisfalse.- An integer or float, a numerical comparison is used.
- An array, the number of elements is compared.
- A string, the length of the string is compared. If
convertistrue, the string is converted a number instead. - A DateTime, the number of days from the current time is compared.
caseSensitive- Optionally, a case sensitive-comparison can be performed. By default, case-insensitive comparison is performed.convert- Optionally, types can be converted to string type. By defaultconvertisfalse.- If the operand is a field, and the field does not exist, like always returns
false. caseSensitive- Optionally, a case sensitive-comparison can be performed. By default, case-insensitive comparison is performed.caseSensitive- Optionally, a case sensitive-comparison can be performed. By default, case-insensitive comparison is performed.convert- Optionally, types can be converted to string type. By defaultconvertisfalse.- If the operand is a field, and the field does not exist, notContains always returns
false. caseSensitive- Optionally, a case sensitive-comparison can be performed. By default, case-insensitive comparison is performed.convert- Optionally, types can be converted to string type. By defaultconvertisfalse.- If the operand is a field, and the field does not exist, notEndsWith always returns
false. caseSensitive- Optionally, a case sensitive-comparison can be performed. This only applies to string comparisons. By default, case-insensitive comparison is performed.convert- Optionally, perform type conversion on operand type. By defaultconvertisfalse.caseSensitive- Optionally, a case sensitive-comparison can be performed. By default, case-insensitive comparison is performed.convert- Optionally, types can be converted to string type. By defaultconvertisfalse.- If the operand is a field, and the field does not exist, notLike always returns
false. caseSensitive- Optionally, a case sensitive-comparison can be performed. By default, case-insensitive comparison is performed.caseSensitive- Optionally, a case sensitive-comparison can be performed. By default, case-insensitive comparison is performed.convert- Optionally, types can be converted to string type. By defaultconvertisfalse.- If the operand is a field, and the field does not exist, notStartsWith always returns
false. caseSensitive- Optionally, a case-sensitive comparison can be performed for string values. By default, case-insensitive comparison is performed.caseSensitive- Optionally, a case sensitive-comparison can be performed. By default, case-insensitive comparison is performed.caseSensitive- Optionally, a case sensitive-comparison can be performed. By default, case-insensitive comparison is performed.convert- Optionally, types can be converted to string type. By defaultconvertisfalse.- If the operand is a field, and the field does not exist, startsWith always returns
false. caseSensitive- Optionally, a case-sensitive comparison can be performed. By default, case-insensitive comparison is performed.unique- Optionally, the operand must not contain duplicates. By default, duplicates are allowed.caseSensitive- Optionally, a case-sensitive comparison can be performed for string values. By default, case-insensitive comparison is performed.- Invoke-PSRule
- Baseline.Group
- 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
- Suppression
- Binding.Field
- Binding.IgnoreCase
- Binding.NameSeparator
- Binding.PreferTargetInfo
- Binding.TargetName
- Binding.TargetType
- Binding.UseQualifiedName
- Configuration
- Rule.Baseline
- Rule.Include
- Rule.IncludeLocal
- Rule.Exclude
- Rule.Tag
- Export-PSRuleBaseline
- Get-PSRule
- Get-PSRuleBaseline
- Get-PSRuleHelp
- Invoke-PSRule
- Test-PSRuleTarget
- Using the
-Optionparameter with an object created with theNew-PSRuleOptioncmdlet. See cmdlet help for syntax and examples. - Using the
-Optionparameter with a hashtable object. - Using the
-Optionparameter with a YAML file path. ps-rule.yamlps-rule.ymlpsrule.yamlpsrule.ymlExecution.InconclusiveWarningis configured byPSRULE_EXECUTION_INCONCLUSIVEWARNING.Input.TargetTypeis configured byPSRULE_INPUT_TARGETTYPE.Output.Formatis configured byPSRULE_OUTPUT_FORMAT.- Enum values are set by string. For example
PSRULE_OUTPUT_FORMATcould be set toYaml. Enum values are case-insensitive. - Boolean values are set by
true,false,1, or0. For examplePSRULE_EXECUTION_INCONCLUSIVEWARNINGcould be set tofalse. Boolean values are case-insensitive. - String array values can specify multiple items by using a semi-colon separator. For example
PSRULE_INPUT_TARGETTYPEcould be set tovirtualMachine;virtualNetwork. - By default PSRule will not extract any custom fields.
- If custom fields are configured, PSRule will attempt to bind the field.
- If none of the configured property names exist, the field will be skipped.
- If more then one property name is configured, the order they are specified in the configuration determines precedence.
- i.e. The first configured property name will take precedence over the second property name.
- By default the property name will be matched ignoring case sensitivity. To use a case sensitive match, configure the Binding.IgnoreCase option.
- By default, custom property binding finds the first matching property by name regardless of case. i.e.
Binding.IgnoreCaseistrue. - To make custom bindings case sensitive, set the
Binding.IgnoreCaseoption tofalse.- Changing this option will affect custom property bindings for both TargetName and TargetType.
- Setting this option has no affect on binding defaults or custom scripts.
- By default PSRule will:
- Use
TargetNameorNameproperties on the object. These property names are case insensitive. - If both
TargetNameandNameproperties exist,TargetNamewill take precedence overName. - If neither
TargetNameorNameproperties exist, a hash of the object will be used as TargetName. - The hash algorithm used can be set by the
Execution.HashAlgorithmoption.
- Use
- If custom TargetName binding properties are configured, the property names specified will override the defaults.
- If none of the configured property names exist, PSRule will revert back to
TargetNamethenName. - If more then one property name is configured, the order they are specified in the configuration determines precedence.
- i.e. The first configured property name will take precedence over the second property name.
- By default the property name will be matched ignoring case sensitivity. To use a case sensitive match, configure the Binding.IgnoreCase option.
- If none of the configured property names exist, PSRule will revert back to
- If a custom TargetName binding function is specified, the function will be evaluated first before any other option.
- If the function returns
$Nullthen custom properties,TargetNameandNameproperties will be used. - The custom binding function is executed outside the PSRule engine, so PSRule keywords and variables will not be available.
- Custom binding functions are blocked in constrained language mode is used. See language mode for more information.
- If the function returns
- By default PSRule will:
- Use the default type presented by PowerShell from
TypeNames. i.e..PSObject.TypeNames[0]
- Use the default type presented by PowerShell from
- If custom TargetType binding properties are configured, the property names specified will override the defaults.
- If none of the configured property names exist, PSRule will revert back to the type presented by PowerShell.
- If more then one property name is configured, the order they are specified in the configuration determines precedence.
- i.e. The first configured property name will take precedence over the second property name.
- By default the property name will be matched ignoring case sensitivity. To use a case sensitive match, configure the
Binding.IgnoreCaseoption.
- If a custom TargetType binding function is specified, the function will be evaluated first before any other option.
- If the function returns
$Nullthen custom properties, or the type presented by PowerShell will be used in order instead. - The custom binding function is executed outside the PSRule engine, so PSRule keywords and variables will not be available.
- Custom binding functions are blocked in constrained language mode is used. See language mode for more information.
- If the function returns
None(0) - No preference. Inherits the default ofWarn.Ignore(1) - Continue to execute silently.Warn(2) - Continue to execute but log a warning. This is the default.Error(3) - Abort and throw an error.Debug(4) - Continue to execute but log a debug message.None(0) - No preference. Inherits the default ofError.Ignore(1) - Continue to execute silently.Warn(2) - Continue to execute but log a warning.Error(3) - Abort and throw an error. This is the default.Debug(4) - Continue to execute but log a debug message.SHA512SHA384SHA256FullLanguage- Executes with all language features. This is the default.ConstrainedLanguage- Executes in constrained language mode that restricts the types and methods that can be used.None(0) - No preference. Inherits the default ofWarn.Ignore(1) - Continue to execute silently.Warn(2) - Continue to execute but log a warning. This is the default.Error(3) - Abort and throw an error.Debug(4) - Continue to execute but log a debug message.BuiltIn(0) - Create the initial session state with all built-in cmdlets loaded. This is the default.Minimal(1) - Create the initial session state with only a minimum set of cmdlets loaded.Unrestricted- PowerShell language features are allowed from workspace and modules. This is the default.ModuleOnly- PowerShell language features are allowed from loaded modules, but script files within the workspace are ignored.DisablePowerShell- No PowerShell language features are used during PSRule run. When this mode is used, rules and conventions written in PowerShell will not execute. Modules that use PowerShell rules and conventions may not work as expected.None(0) - No preference. Inherits the default ofWarn.Ignore(1) - Continue to execute silently.Warn(2) - Continue to execute but log a warning. This is the default.Error(3) - Abort and throw an error.Debug(4) - Continue to execute but log a debug message.None(0) - No preference. Inherits the default ofWarn.Ignore(1) - Continue to execute silently.Warn(2) - Continue to execute but log a warning. This is the default.Error(3) - Abort and throw an error.Debug(4) - Continue to execute but log a debug message.None(0) - No preference. Inherits the default ofIgnore.Ignore(1) - Continue to execute silently. This is the default.Warn(2) - Continue to execute but log a warning.Error(3) - Abort and throw an error.Debug(4) - Continue to execute but log a debug message.None(0) - No preference. Inherits the default ofWarn.Ignore(1) - Continue to execute silently.Warn(2) - Continue to execute but log a warning. This is the default.Error(3) - Abort and throw an error.Debug(4) - Continue to execute but log a debug message.None(0) - No preference. Inherits the default ofWarn.Ignore(1) - Continue to execute silently.Warn(2) - Continue to execute but log a warning. This is the default.Error(3) - Abort and throw an error.Debug(4) - Continue to execute but log a debug message.- Modules specified with
Include.Moduleare combined with-Module. Both sets of modules will be imported and used using execution. - Paths specified with
Include.Pathare combined with-Path. Both sets of paths will be imported and used using execution. - The
Include.Pathoption defaults to.ps-rule/. To override this default, specify one or more alternative paths or an empty array. - None - Treat strings as plain text and do not deserialize files.
- Yaml - Deserialize as one or more YAML objects.
- Json - Deserialize as one or more JSON objects.
- Markdown - Deserialize as a markdown object.
- PowerShellData - Deserialize as a PowerShell data object.
- File - Files are not deserialized.
- Detect - Detect format based on file extension. This is the default.
- Yaml -
.yamlor.yml - Json -
.jsonor.jsonc - Markdown -
.mdor.markdown - PowerShellData -
.psd1 README.md.DS_Store.gitignore.gitattributes.gitmodulesLICENSELICENSE.txtCODE_OF_CONDUCT.mdCONTRIBUTING.mdSECURITY.mdSUPPORT.md.vscode/*.json.vscode/*.code-snippets.github/**/*.md.github/CODEOWNERS.pipelines/**/*.yml.pipelines/**/*.yaml.azure-pipelines/**/*.yml.azure-pipelines/**/*.yaml.azuredevops/*.md[Discovery.Source]- Discovery messages for.Rule.ps1files and rule modules.[Discovery.Rule]- Discovery messages for individual rules within.Rule.ps1files.[Discovery.Source]- Discovery messages for.Rule.ps1files and rule modules.[Discovery.Rule]- Discovery messages for individual rules within.Rule.ps1files.- None
- Error
- Warning
- Information
- None
- Error
- Warning
- Information
- Detail - Return a record per rule per object.
- Summary - Return summary results.
Title(1) - Shows the PSRule title ASCII text.Source(2) - Shows rules module versions used in this run.SupportLinks(4) - Shows supporting links for PSRule and rules modules.RepositoryInfo(8) - Show information about the repository where PSRule is being run from.Default- ShowsTitle,Source,SupportLinks,RepositoryInfo. This is the default option.Minimal- ShowsSource.- Default
- UTF-8
- UTF-7
- Unicode
- UTF-32
- ASCII
RuleCount(1) - Shows a summary of rules processed.RunInfo(2) - Shows information about the run.OutputFile(4) - Shows information about the output file if an output path is set.Default- ShowsRuleCount,RunInfo, andOutputFile. This is the default option.- None - Output is presented as an object using PowerShell defaults. This is the default.
- Yaml - Output is serialized as YAML.
- Json - Output is serialized as JSON.
- Markdown - Output is serialized as Markdown.
- NUnit3 - Output is serialized as NUnit3 (XML).
- Csv - Output is serialized as a comma-separated values (CSV).
- The following columns are included for
Detailoutput: RuleName, TargetName, TargetType, Outcome, OutcomeReason, Synopsis, Recommendation - The following columns are included for
Summaryoutput: RuleName, Pass, Fail, Outcome, Synopsis, Recommendation
- The following columns are included for
- Wide - Output is presented using the wide table format, which includes reason and wraps columns.
- Sarif - Output is serialized as SARIF.
None(0) - Results for rules that did not get processed are returned. This include rules that have been suppressed or were not run against a target object.Fail(1) - Results for rules that failed are returned.Pass(2) - Results for rules that passed are returned.Error(4) - Results for rules that raised an error are returned.Processed- Results for rules with theFail,Pass, orErroroutcome. This is the default option.Problem- Results for rules with theFail, orErroroutcome.All- All results for rules are returned.Client- Output is written to the host directly in green/ red to indicate outcome.Plain- Output is written as an unformatted string. This option can be redirected to a file.AzurePipelines- Output is written for integration Azure Pipelines.GitHubActions- Output is written for integration GitHub Actions.VisualStudioCode- Output is written for integration with Visual Studio Code.Detect- Output style will be detected by checking the environment variables. This is the default.- If the
TF_BUILDenvironment variable is set totrue,AzurePipelineswill be used. - If the
GITHUB_ACTIONSenvironment variable is set totrue,GitHubActionswill be used. - If the
TERM_PROGRAMenvironment variable is set tovscode,VisualStudioCodewill be used. - Use
Client. - In GitHub Actions, the repository URL is detected from the
GITHUB_REPOSITORYenvironment variable. - In Azure Pipelines, the repository URL is detected from the
BUILD_REPOSITORY_URIenvironment variable. - A temporary exclusion for an object that is in a known failed state.
- An object should never be processed by any rule. Pre-filter the pipeline instead.
- The rule is not applicable because the object is the wrong type. Use pre-conditions on the rule instead.
- Invoke-PSRule
- New-PSRuleOption
- Set-PSRuleOption
- Each rule is defined PowerShell within a
.Rule.ps1file by using aRuleblock. - PowerShell variables, functions, and cmdlets can be used just like regular PowerShell scripts.
- Built-in assertion helpers can be used to quickly build out rules.
- Pre-conditions can be defined with using a script block, type binding, or YAML-based selector.
- Each rule is defined in a
.Rule.yamlfile by using theRuleresource. - YAML-based expressions can be used.
- Pre-conditions can be defined with using a type binding, or YAML-based selector.
- Script - A PowerShell script block that is executed and if true will cause the rule to be executed. Script block pre-conditions only work with script rules. To use a script block pre-condition, specify the
-Ifscript parameter on theRuleblock. - Type - A type string that is compared against the bound object type. When the type matches the rule will be executed. To use a type pre-conditions, specify the
-Typescript parameter ortypeYAML/JSON property. - Selector - A YAML/JSON based expression that is evaluated against the object. When the expression matches the rule will be executed. To use a selector pre-conditions, specify the
-Withscript parameter orwithYAML/JSON property. - Invoke-PSRule
- A selector is a YAML/JSON based expression that evaluates an object.
- Each selector is comprised of nested conditions, operators, and comparison properties.
- Selectors must use one or more available conditions with a comparison property to evaluate the object.
- Optionally a condition can be nested in an operator.
- Operators can be nested within other operators.
- Contains
- Count
- Equals
- EndsWith
- Exists
- Greater
- GreaterOrEquals
- HasDefault
- HasSchema
- HasValue
- In
- IsLower
- IsString
- IsArray
- IsBoolean
- IsDateTime
- IsInteger
- IsNumeric
- IsUpper
- Less
- LessOrEquals
- Match
- NotEquals
- NotIn
- NotMatch
- SetOf
- StartsWith
- Subset
- Version
- AllOf
- AnyOf
- Not
- Field
- Name
- Type
- Selectors can evaluate:
- Fields of the target object.
- Type and name binding of the target object by using
nameandtypecomparison properties.
- State variables such has
$PSRulecan not be evaluated. - Bound fields can not be evaluated.
- Invoke-PSRule
- Ignore test objects by name.
- Ignore test objects by type.
- Ignore objects with non-production tag.
- Invoke-PSRule
- $Assert
- $Configuration
- $LocalizedData
- $PSRule
- $Rule
- $TargetObject
Contains- The field value must contain at least one of the strings.EndsWith- The field value must match at least one suffix.FileHeader- The file must contain a comment header.FilePath- The file path must exist.Greater- The field value must be greater.GreaterOrEqual- The field value must be greater or equal to.HasDefaultValue- The object should not have the field or the field value is set to the default value.HasField- The object must have any of the specified fields.HasFields- The object must have all of the specified fields.HasFieldValue- The object must have the specified field and that field is not empty.HasJsonSchema- The object must reference a JSON schema with the$schemafield.In- The field value must be included in the set.IsArray- The field value must be an array.IsBoolean- The field value must be a boolean.IsInteger- The field value must be an integer.IsLower- The field value must include only lowercase characters.IsNumeric- The field value must be a numeric type.IsString- The field value must be a string.IsUpper- The field value must include only uppercase characters.JsonSchema- The object must validate successfully against a JSON schema.Less- The field value must be less.LessOrEqual- The field value must be less or equal to.Match- The field value matches a regular expression pattern.NotIn- The field value must not be included in the set.NotMatch- The field value does not match a regular expression pattern.NullOrEmpty- The object must not have the specified field or it must be empty.TypeOf- The field value must be of the specified type.StartsWith- The field value must match at least one prefix.Version- The field value must be a semantic version string.- Configuration keys are case sensitive.
- Configuration values are read only.
- Configuration values can be accessed through helper methods.
GetStringValues(string configurationKey)- Returns an array of strings, based onconfigurationKey.- If the rules are loose (not part of a module), PSRule will search for
PSRule-rules.psd1in the.\\<culture>\\subdirectory relative to where the rule script .ps1 file is located. - When the rules are shipped as part of a module, PSRule will search for
PSRule-rules.psd1in the.\\<culture>\\subdirectory relative to where the module manifest .psd1 file is located. - Message names are case sensitive.
- Message values are read only.
Badges- A helper to generate badges within PSRule. This property can only be called within the-Endblock of a convention.Field- A hashtable of custom bound fields. See optionBinding.Fieldfor more information.Input- Allows adding additional input paths to the pipeline.Repository- Provides access to information about the current repository.Scope- Any scopes assigned to the object currently being processed by the pipeline.Source- A collection of sources for the object currently being processed on the pipeline.TargetObject- The object currently being processed on the pipeline.TargetName- The name of the object currently being processed on the pipeline. This property will automatically default toTargetNameorNameproperties of the object if they exist.TargetType- The type of the object currently being processed on the pipeline. This property will automatically bind toPSObject.TypeNames[0]by default.Output- The output of all rules. This property can only be called within the-Endblock of a convention.Data- A hashtable of custom data. This property can be populated during rule or begin/ process convention execution. Custom data is not used by PSRule directly, and is intended to be used by downstream processes that need to interpret PSRule results.GetContent(PSObject sourceObject)- Returns the content of a file as one or more objects. The parametersourceObjectshould be aInputFileInfo,FileInfo, orUriobject.GetContentField(PSObject sourceObject, string field)- Returns the content of a file as one or more objects. The parametersourceObjectshould be aInputFileInfo,FileInfo, orUriobject. The parameterfieldis an field within each object to return. If the field does not exist on the object, an object is not returned.GetContentFirstOrDefault(PSObject sourceObject)- Returns the content of a file as on object. The parametersourceObjectshould be aInputFileInfo,FileInfo, orUriobject. If more than one object is contained in the file, only the first object is returned. When the source file contains no objects null is returned.Import(PSObject[] sourceObject)- Imports one or more source objects into the pipeline. This method can only be called within the-Initializeor-Beginblock of a convention. Use this method to expand an object into child objects that will be processed independently. Objects imported using this method will be excluded from theInput.ObjectPathoption if set.ImportWithType(string type, PSObject[] sourceObject)- Imports one or more source objects into the pipeline. This method can only be called within the-Initializeor-Beginblock of a convention. Use this method to expand an object into child objects that will be processed independently. Objects imported using this method will be excluded from theInput.ObjectPathoption if set. WhenBinding.PreferTargetInfois true, the type will be automatically used as theTargetTypefor the imported object.AddService(string id, object service)- Add a service to the current context. The service can be retrieved using$PSRule.GetService(id). The service object will be available to all rules and cleaned up after all rules are executed. Services should implement theIDisposableinterface to perform additional cleanup. This method can only be called within the-Initializeblock of a convention.GetService(string id)- Retrieves a service previously added by a convention.GetPath(object sourceObject, string path)- Evalute an object path expression and returns the resulting objects.RuleName- The name of the rule.RuleId- A unique identifier for the rule.- Invoke-PSRule
- run \u2014 Run rules against an input path and output the results.
- module \u2014 Manage or restore modules tracked by the module lock file and configured options.
- module init
- module list
- module add
- module remove
- module restore
- module upgrade
--force- Force the creation of a new lock file, even if one already exists.--version- Specifies a specific version of the module to add. By default, the latest stable version of the module is added. Any required version constraints set by theRequiresoption are taken into consideration.--force- Restore modules even when an existing version that meets constraints is already installed locally.Pass- Results for rules that passed.Fail- Results for rules that did not pass.Error- Results for rules that raised an error are returned.Processed- All results that were processed. This aggregated outcome includesPass,Fail, orErrorresults.Problem- Processed results that did not pass. This aggregated outcome includesFail, orErrorresults.- Transformation \u2014 you need to perform minor transformation before a condition.
- Configuration \u2014 you want to configure an input into a condition.
boolean- Convert a value to a boolean.concat- Concatenate multiple values.configuration- Get a configuration value.first- Return the first element in an array or the first character of a string.integer- Convert a value to an integer.last- Return the last element in an array or the last character of a string.padLeft- Pad a value with a character on the left to meet the specified length.padRight- Pad a value with a character on the right to meet the specified length.path- Get a value from an object path.replace- Replace an old string with a new string.split- Split a string into an array by a delimiter.string- Convert a value to a string.substring- Extract a substring from a string.trim- Remove whitespace from the start and end of a string.equalsnotEqualscountlesslessOrEqualsgreatergreaterOrEquals- Create a standalone rule
- Expressions
- Sub-selectors
- Pre-conditions \u2014 you want to filtering out objects before a rule is run.
- Object filtering \u2014 you want to limit a condition to specific elements in a list of items.
- The
whereproperty is the start of a sub-selector. - The sub-selector checks if the
kindproperty equalsapi. - The object does not have a
kindproperty. OR - The value of the
kindproperty is notapi. - If the array property
resourcesexists, any items with a type ofMicrosoft.Web/sites/configare evaluated.- Each item must have the
properties.detailedErrorLoggingEnabledproperty set totrueto pass. - Items without the
properties.detailedErrorLoggingEnabledproperty fail. - Items with the
properties.detailedErrorLoggingEnabledproperty set to a value other thentruefail.
- Each item must have the
- If the
resourcesproperty does not exist, the rule fails. - If the
resourcesproperty exists but has 0 items of typeMicrosoft.Web/sites/config, the rule fails. - If the
resourcesproperty exists and has any items of typeMicrosoft.Web/sites/configbut any fail, the rule fails. - If the
resourcesproperty exists and has any items of typeMicrosoft.Web/sites/configand all pass, the rule passes. - The
resourcesproperty doesn't exist. OR - The
resourcesproperty doesn't contain any items that match the sub-selector condition. - Use a pre-condition to avoid running the rule.
- Group the sub-selector into a
anyOf, and provide a secondary condition. - Use a quantifier to determine how many items must match sub-selector and match the
allOf/anyOfoperator. - If the array property
resourcesexists, any items with a type ofMicrosoft.Web/sites/configare evaluated.- Each item must have the
properties.detailedErrorLoggingEnabledproperty set totrueto pass. - Items without the
properties.detailedErrorLoggingEnabledproperty fail. - Items with the
properties.detailedErrorLoggingEnabledproperty set to a value other thentruefail.
- Each item must have the
- If the
resourcesproperty does not exist, the rule passes. - If the
resourcesproperty exists but has 0 items of typeMicrosoft.Web/sites/config, the rule fails. - If the
resourcesproperty exists and has any items of typeMicrosoft.Web/sites/configbut any fail, the rule fails. - If the
resourcesproperty exists and has any items of typeMicrosoft.Web/sites/configand all pass, the rule passes. - Selected by the sub-selector.
- Match the condition of the operator.
count\u2014 The number of items must equal then the specified value.less\u2014 The number of items must less then the specified value.lessOrEqual\u2014 The number of items must less or equal to the specified value.greater\u2014 The number of items must greater then the specified value.greaterOrEqual\u2014 The number of items must greater or equal to the specified value.- If the array property
resourcesexists, any items with a type ofMicrosoft.Web/sites/configare evaluated.- Each item must have the
properties.detailedErrorLoggingEnabledproperty set totrueto pass. - The number of items that pass must be greater or equal to
1.
- Each item must have the
- If the
resourcesproperty does not exist or is empty, the number of items is0which fails greater or equal to1. - Create a standalone rule
- Functions
- Expressions
- Rule - Creates a rule definition.
- AnyOf - Assert that any of the child expressions must be true.
- AllOf - Assert that all of the child expressions must be true.
- Exists - Assert that a field or property must exist.
- Match - Assert that the field must match any of the regular expressions.
- Reason - Return a reason for why the rule failed.
- Recommend - Return a recommendation to resolve the issue and pass the rule.
- TypeOf - Assert that the object must be of a specific type.
- Within - Assert that the field must match any of the values.
- Exists - Assert that a field or property must exist.
- Match - Assert that the field must match any of the regular expressions.
- TypeOf - Assert that the object must be of a specific type.
- Within - Assert that the field must match any of the values.
Name- The name of the rule definition. Each rule name must be unique. When packaging rules within a module, rule names must only be unique within the module.Ref- An optional stable and opaque identifier that can be used to reference the rule.Alias- A list of alternative names that can be used to reference the rule.Tag- A hashtable of key/ value metadata that can be used to filter and identify rules and rule results.When- A selector precondition that must evaluate true before the rule is executed.Type- A type precondition that must match the TargetType of the pipeline object before the rule is executed.If- A script precondition that must evaluate to$Truebefore the rule is executed.DependsOn- A list of rules this rule depends on. Rule dependencies must execute successfully before this rule is executed.Configure- A set of default configuration values. These values are only used when the baseline configuration does not contain the key.ErrorAction- The action to take when an error occur. Only a subset of preferences are supported, eitherStoporIgnore. When-ErrorActionis not specified the default preference isStop. When errors are ignored a rule will pass or fail based on the rule condition. Uncaught exceptions will still cause rule return an error outcome.Body- A script block that specifies one or more conditions that are required for the rule to Pass.- Rule conditions should only return
$Trueor$False. Other objects should be caught withOut-Nullor null assigned like$Null = SomeCommand. - The
Rulekeyword can not be nested in aRuledefinition. - Variables and functions defined within
.Rule.ps1files, but outside theRuledefinition block are not accessible unless theGlobalscope is applied. - Functions and variables within the caller's scope (the scope calling
Invoke-PSRule,Get-PSRule,Test-PSRuleTarget) are not accessible. - Cmdlets that require user interaction are not supported, i.e.
Read-Host. - Script preconditions can contain
Exists,Match,TypeOfandWithinkeywords. Field- One or more fields/ properties that must exist on the pipeline object.CaseSensitive- The field name must match exact case.Not- Instead of checking if the field names exists they should not exist.All- All fields must exist on the pipeline object, instead of only one.Reason- A custom reason provided if the condition fails.InputObject- Supports objects being piped directly.Field- The name of the field that will be evaluated on the pipeline object.Expression- One or more regular expressions that will be used to match the value of the field.CaseSensitive- The field value must match exact case.Not- Instead of checking the field value matches, the field value must not match any of the expressions.Reason- A custom reason provided if the condition fails.InputObject- Supports objects being piped directly.Field- The name of the field that will be evaluated on the pipeline object.Value- A list of values that the field value must match.CaseSensitive- The field value must match exact case. Only applies when the field value and allowed values are strings.Not- Instead of checking the field value matches, the field value must not match any of the supplied values.Like- Instead of using an exact match, a wildcard match is used. This switch can only be used whenValuea string type.Reason- A custom reason provided if the condition fails.InputObject- Supports objects being piped directly.Body- A script block definition of the containing one or more PSRule keywords and PowerShell expressions.Body- A script block definition of the containing one or more PSRule keywords and PowerShell expressions.TypeName- One or more type names which will be evaluated against the pipeline object.TypeNameis case sensitive.Reason- A custom reason provided if the condition fails.InputObject- Supports objects being piped directly.Text- A message that includes the reason for the failure.Text- A message that includes the process to resolve the issue and pass the rule.- [Invoke-PSRule]
- Use a short
Synopsis:to describe your rule in a line comment above your rule. This will be shown in output as the default recommendation. For this to be interpreted by PSRule, only a single line is allowed. - Name your rule with a unique name
Yaml.FileType. - The
typeproperty ensures the rule will only run for file info objects. Other objects that might be piped to PSRule will be skipped by theYaml.FileTyperule. - The
conditionproperty determines the checks PSRule will use to test each file returned withGet-ChildItem. Specifically, theExtensionproperty of eachFileInfoobject will be compared. The value ofExtensionshould not be either.jpgor.png. - Use a short
Synopsis:to describe your rule in a line comment above your rule. This will be shown in output as the default recommendation. For this to be interpreted by PSRule, only a single line is allowed. - Name your rule with a unique name
Json.FileType. - The
typeproperty ensures the rule will only run for file info objects. Other objects that might be piped to PSRule will be skipped by theJson.FileTyperule. - The
conditionproperty determines the checks PSRule will use to test each file returned withGet-ChildItem. Specifically, theExtensionproperty of eachFileInfoobject will be compared. The value ofExtensionshould not be either.jpgor.png. - Use a short
Synopsis:to describe your rule in a line comment above your rule. This will be shown in output as the default recommendation. For this to be interpreted by PSRule, only a single line is allowed. - Name your rule with a unique name
PS.FileType. - The
-Typeparameter ensures the rule will only run for file info objects. Other objects that might be piped to PSRule will be skipped by thePS.FileTyperule. - The condition contained within the curly braces
{ }determines the checks PSRule will use to test each file returned withGet-ChildItem. - The
$Assert.NotInmethod checks theExtensionproperty is not set to.jpgor.png. - If you didn't get any results with
Failtry creating or saving a.jpgfile in pathToSeach. -
If you have too many
Passresults you can filter the output to only fails by using-Outcome Fail. For example:$files | Invoke-PSRule -Path $rulePath -Outcome Fail\n - Find any services that are set to start automatically with
StartTypebeginning withAutomatic. - Fail for any service with a
Statusother thanRunning. - If the selector is
truethen the rule will be run and either pass or fail. - If the selector is
falsethen the rule will be skipped. - Use a short
Synopsis:to describe your selector in a line comment above your rule. - Name your selector with a unique name
Yaml.IsAutomaticService. - The
ifproperty determines if PSRule will evaluate the service rule. Specifically, theStartTypeproperty of each service object will be compared. The value ofStartTypemust start withAutomatic. - The
convertproperty automatically converts the enum type ofStartTypeto a string. - Use a short
Synopsis:to describe your selector in a line comment above your rule. - Name your selector with a unique name
Json.IsAutomaticService. - The
ifproperty determines if PSRule will evaluate the service rule. Specifically, theStartTypeproperty of each service object will be compared. The value ofStartTypemust start withAutomatic. - The
convertproperty automatically converts the enum type ofStartTypeto a string. - Use a short
Synopsis:to describe your rule in a line comment above your rule. This will be shown in output as the default recommendation. For this to be interpreted by PSRule, only a single line is allowed. - Name your rule with a unique name
Yaml.ServiceStarted. - The
withproperty indicates to only run this rule on selected service objects. TheYaml.IsAutomaticServiceselector must first returntrueotherwise this rule will be skipped. - The
conditionproperty determines the checks PSRule will use to test each service. Specifically, theStatusproperty will be compared. The value ofStatusmust beRunning. - The
convertproperty automatically converts the enum type ofStatusto a string. - Use a short
Synopsis:to describe your rule in a line comment above your rule. This will be shown in output as the default recommendation. For this to be interpreted by PSRule, only a single line is allowed. - Name your rule with a unique name
Json.ServiceStarted. - The
withproperty indicates to only run this rule on selected service objects. TheJson.IsAutomaticServiceselector must first returntrueotherwise this rule will be skipped. - The
conditionproperty determines the checks PSRule will use to test each service. Specifically, theStatusproperty will be compared. The value ofStatusmust beRunning. - The
convertproperty automatically converts the enum type ofStatusto a string. - Use a short
Synopsis:to describe your rule in a line comment above your rule. This will be shown in output as the default recommendation. For this to be interpreted by PSRule, only a single line is allowed. - Name your rule with a unique name
PS.ServiceStarted. - The
-Withparameter indicates to only run this rule on selected service objects. TheYaml.IsAutomaticServiceselector must first returntrueotherwise this rule will be skipped. - The condition contained within the curly braces
{ }determines the checks PSRule will use to test each service object. - The
Statusenum property is converted to a string. - The
$Assert.HasFieldValuemethod checks the convertedStatusproperty is set toRunning. - Validate Azure resource configuration
- Validate Azure resources tags
- Validate Kubernetes resources
- Using within continuous integration
- Packaging rules in a module
- Writing rule help
- PSRule.Rules.Azure
- PSRule.Rules.CAF
- Defining a basic rule.
- Adding a recommendation.
- Using script pre-conditions.
- Using helper functions.
resources.json- An export for the Azure resource properties saved for offline use.- We use
storageAccounts.UseHttpsdirectly after theRulekeyword to name the rule definition. Each rule must be named uniquely. - The
# Synopsis:comment is used to add additional metadata interpreted by PSRule. - One or more conditions are defined within the curly braces
{ }. - The rule definition is saved within a file named
storageAccounts.Rule.ps1. - We use the
$TargetObjectvariable to get the object on the pipeline and access it's properties. - The condition will return
$Trueor$Falseback to the pipeline, where:$True- the object passed the validation check$False- the object failed the validation check
- Directly after the
Recommendkeyword is a message to help understand why the rule failed or passed. - A check against
$TargetObject.ResourceTypeensured that our rule is only processed for Storage Accounts. - storageAccounts.Rule.ps1 - Example rules for validating Azure Storage.
- appService.Rule.ps1 - Example rules for validating Azure App Service.
- resources.json - Offline export of Azure resources.
- common.Rule.ps1 - ResourceType helper function.
- Defining a basic rule.
- Basic usage of
Exists,WithinandMatchkeywords. - Using configuration in a rule definition.
- Setting configuration in YAML.
- Running rules with configuration.
resources.json- An export of Azure resource properties saved for offline use.- Tag names should be easy to read and understand.
- Tag names will use lower-camel/ pascal casing.
- The following mandatory tags will be used:
- environment: An operational environment for systems and services. Valid environments are production, testing and development.
- costCentre: A allocation account within financial systems used for charging costs to a business unit. A cost centre is a number with 5 digits and can't start with a 0.
- businessUnit: The name of the organizational unit or team that owns the application/ solution.
- We use
environmentTagdirectly after theRulekeyword to name the rule definition. Each rule must be named uniquely. - The
# Synopsis:comment is used to add additional metadata interpreted by PSRule. - One or more conditions are defined within the curly braces
{ }. - The rule definition is saved within a file named
azureTags.Rule.ps1. - We use the
Existskeyword to check if the environment tag exists. - The
-CaseSensitiveswitch is also used to ensure that the tag name uses lowercase. - The condition will return
$Trueor$Falseback to the pipeline, where:$True- the environment tag exists.$False- the environment tag does not exist.
- We use the
Withinkeyword to check if the environment tag uses any of the allowed values. - The
-CaseSensitiveswitch is also used to ensure that the tag value is only a lowercase environment name. - The condition will return
$Trueor$Falseback to the pipeline, where:$True- an allowed environment is used.$False- the environment tag does not use one of the allowed values.
$TargetObjectautomatic variable is used to get the pipeline object being evaluated.- We use the
-cinoperator to check the environment tag only uses allowed values. - The
-cinoperator performs a cases sensitive match on production, test and development. - The condition will return
$Trueor$Falseback to the pipeline, where:$True- an allowed environment is used.$False- the environment tag does not use one of the allowed values.
- We use the
Matchkeyword to check if the costCentre tag uses a numeric only value with 5 digits, not starting with 0. - The condition will return
$Trueor$Falseback to the pipeline, where:$True- the costCentre tag value matches the regular expression.$False- the costCentre tag value does not use match the regular expression.
$TargetObjectautomatic variable is used to get the pipeline object being evaluated.- We use the
-matchoperator to check the costCentre tag value matches the regular expression. - The condition will return
$Trueor$Falseback to the pipeline, where:$True- the costCentre tag value matches the regular expression.$False- the costCentre tag value does not use match the regular expression.
- We use the
Withinkeyword to check if the businessUnit tag uses any of the allowed values. allowedBusinessUnitsconfiguration value can be referenced using the syntax$Configuration.allowedBusinessUnits.- The rule definition is defined in azureTags.Rule.ps1.
- YAML configuration is defined in ps-rule.yaml.
- azureTags.Rule.ps1 - Example rules for validating Azure resource tagging standard rules.
- resources.json - Offline export of Azure resources.
- ps-rule.yaml - A YAML configuration file for PSRule.
- PSRule.Rules.Kubernetes
- Defining a basic rule.
- Configuring custom binding.
- Using a type precondition.
- Running rules using YAML input.
resources.yaml- A Kubernetes manifest containing deployments and services.- The following recommended labels will be used on all services and deployments:
app.kubernetes.io/name- the name of the application/ service.app.kubernetes.io/version- the version of the service.app.kubernetes.io/component- identifies the type of component, valid options areweb,api,databaseandgateway
- For
weborapideployments, a minimum of two (2) replicas must be used. - Deployments must use container images with a specific version tag, and not
latest. - Deployments must declare minimum and maximum memory/ CPU resources.
- We use
metadata.Namedirectly after theRulekeyword to name the rule definition. Each rule must be named uniquely. - The
# Synopsis:comment is used to add additional metadata interpreted by PSRule. - One or more conditions are defined within the curly braces
{ }. - The rule definition is saved within a file named
kubernetes.Rule.ps1. - Any valid PowerShell that returns a true (pass) when the condition is met or false (fail) when the condition is not met.
- More than one condition can be defined, if any condition returns false then the whole rule fails.
- We use the
Existskeyword to check that the resource has theapp.kubernetes.io/namelabel set.- By default, PSRule will step through nested properties separated by a
.. i.e.labelsis a property ofmetadata. - Kubernetes supports and recommends label namespaces, which often use
.in their name. PSRule supports this by enclosing the field name (app.kubernetes.io/name) in apostrophes (') so thatapp.kubernetes.io/nameis checked instead ofapp.
- By default, PSRule will step through nested properties separated by a
- Double apostrophes (
'') are used to encloseapp.kubernetes.io/namebecause the field name uses'at the start and end of the string instead of\"in the previous example. - The
Withinkeyword is used to validate that theapp.kubernetes.io/componentonly uses one of four (4) allowed values. metadata.nameto store the name of a resource.kindto store the type of resource.- TargetName is bound to
metadata.name - TargetType is bound to
kind - Type preconditions are one or more type names that PSRule compares to the
TargetTypebinding, where:- One of the type names names equal
TargetTypethe rule will be processed. - None of the type names equal
TargetTypethe rule be skipped.
- One of the type names names equal
- Script block preconditions is a PowerShell script block that returns true or false, where:
- True - Continue processing the rule.
- False - Skip processing the rule.
- We update our
metadata.Namerule to use the-Typeparameter to specify a type precondition of either Deployment or Service. - In a previous step,
TypeNamewas bound to thekindproperty which will be Deployment or Service for these resource types. - The built-in variable
$TargetObjectis used to get the current pipeline object.- Built-in keywords like
Existsautomatically default to$TargetObject, but can be piped alternative input as shown in the rule definition nameddeployment.ResourcesSet.
- Built-in keywords like
- The
-InputPathparameter is used to load objects from disk as YAML. YAML is automatically detected based on the.yamlfile extension. Alternatively the-Foramt Yamlparameter can be used. - Binding parameters are read from
ps-rule.yamlin the current working path. Alternatively the-Optionparameter could be used to specify an alternative file path. kubectlis called with the-o yamlto output resources as YAML.kubectlis piped toOut-Stringto convert the multi-line output to a single string.- The
-Formatparameter informs PSRule that the string is YAML and it should convert the string into structured objects. - The
-ObjectPathparameter is used with the output fromkubectl. This is required because the output fromkubectlis a collection of resources instead of individual resources. Specifically-ObjectPath itemsgets the resources from theitemsproperty of the output. - kubernetes.Rule.ps1 - Example rules for validating Kubernetes resources.
- resources.yaml - An example Kubernetes manifest.
- ps-rule.yaml - PSRule options configuration file.
- Installing within a CI pipeline.
- Validating objects.
- Formatting output.
- Failing the pipeline.
- Generating NUnit output.
- Additional options.
- When installing modules on Windows, modules will be installed into Program Files by default, which requires administrator permissions. Depending on your environment, the CI worker process may not have administrative permissions. Instead we can install PSRule for the current context running the CI pipeline by using the
-Scope CurrentUserparameter. - By default, this cmdlet will install the module from the PowerShell Gallery which is not trusted by default. Since a CI pipeline is not interactive, use the
-Forceswitch to suppress the confirmation prompt. - Use the
-OutputFormat NUnit3parameter. - Use the
-OutputPathparameter to specify the path of the report file to write. - pipeline-deps.ps1 - Example script installing pipeline dependencies.
- file.Rule.ps1 - Example rules for validating script files.
- validate-files.ps1 - Example script for running files validation.
- azure-pipelines.yaml - An example Azure DevOps Pipeline.
- YAML (
.yamlor.yml). - JSON (
.json). - PowerShell Data Files (
.psd1). - Markdown front matter (
.mdor.markdown). - 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.
- 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.
- 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.
- 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.
- Reuses existing skills within Microsoft and customers who already know how to author PowerShell scripts.
- Builds on existing PowerShell community; allowing existing integrations and cmdlets to be used.
- PowerShell already has an established model for distributing packages (modules). This includes options for trust and hosting (publicly or privately).
- Rules can be written using standard PowerShell operators and conventions. Minimal knowledge of PSRule should be required to author rules.
- Rules validate an object graph. Whether an object originates from a YAML or JSON file should be abstract.
- Implements a test for one or more conditions against an object. When all conditions return true the rule passes, if not the rule fails.
- Is evaluated by executing the rule within a sandbox that provides context to each rule. Such as the deserialized object being processed and configuration.
- Can specify preconditions which determine if a rule should be evaluated based on the object being processed. Rules only run against the objects they are designed to test.
Baseline- A reusable group of rules and configuration defaults for a given scenario.Selector- A reusable filter to determine which objects a rule should be run against.- Separation of rules or features in development. For infrastructure code or rules early in their lifecycle, a recommend practice may not be fully ratified. Baselines allow rules to be distributed but not executed by default.
- Progressive adoption. If validation has been added for a new use case, it may not be possible to adopt all rules at once. Baselines act as checkpoints to allow validation of a subset of rules.
- Begin: TBA
- Process: TBA
- End: TBA
- Invoke: Returns output as pipeline objects so they can be natively processed by PowerShell code.
- Assert: Returns output as styled text to provide readable results within a CI pipeline.
- Test: Returns true or false based on pass or fail of each object. Use this option to use filter objects from a PowerShell pipeline.
- In the parent runspace where PSRule is called using
Invoke-PSRule,Assert-PSRule, orTest-PSRule. The parent runspace is responsible for all input and output. - The sandbox runspace is where rules execute. PSRule keywords and automatic variables are implemented in the sandbox. Flow control within the PSRule pipeline maintains context for each object as it is processed by rules.
- Configuring the default
ps-rule.yamlfile. - Setting at runtime by passing a
-Optionparameter to PSRule cmdlets. - Parameter
- Local options
- Baseline
- Module configuration
- Engine features:
- Added
HasFieldsassertion helper to check all fields exist. #578 - Updated
HasFieldto check if any of the specified fields exist. #578
- Added
- General improvements:
- Input format detection now includes
.jsoncand.markdownfile extensions. #575 - Improved support for cross module rule dependencies. #248
- Rule dependencies are now automatically imported.
- Input format detection now includes
- Bug fixes:
- Fixed handling for null or empty arrays with
StartsWith,Contains,EndsWith,In, andNotIn. #579
- Fixed handling for null or empty arrays with
- No additional changes.
- Engine features:
- Added
HasFieldsassertion helper to check all fields exist. #578 - Updated
HasFieldto check if any of the specified fields exist. #578
- Added
- General improvements:
- Input format detection now includes
.jsoncand.markdownfile extensions. #575 - Improved support for cross module rule dependencies. #248
- Rule dependencies are now automatically imported.
- Input format detection now includes
- Bug fixes:
- Fixed handling for null or empty arrays with
StartsWith,Contains,EndsWith,In, andNotIn. #579
- Fixed handling for null or empty arrays with
- Engine features:
- Added support for formatting results as markdown. #474
- Use
-OutputFormat Markdownor configureOutput.Formatto output markdown. - To format as either detail or summary, use the
-Asparameter or configureOutput.As.
- Use
- Added character case assertion helpers
IsLower, andIsUpper. #555IsLowerchecks that all letters in a field value are lowercase.IsUpperchecks that all letters in a field value are uppercase.
- Added support for formatting results as markdown. #474
- General improvements:
- Numerical strings can be converted with numeric assertion helpers. #550
- Added outcome
Output.Outcomeas a configurable option. #552 - Added help links and default snippets to schemas. #561
- Improved rule error reporting by including rule and source location. #565
- Engineering:
- Bump Manatee.Json from 13.0.2 to 13.0.3. #563
- Bug fixes:
- Fixed NUnit report reasons should be escaped in markdown. #471
- Fixed reporting of error when rule error is handled. #564
- Additionally rules can use
-ErrorAction Ignoreto ignore non-exception errors.
- Additionally rules can use
- Fixed first exception stops other rules from being processed. #566
- No additional changes.
- General improvements:
- Improved rule error reporting by including rule and source location. #565
- General improvements:
- Added help links and default snippets to schemas. #561
- Engineering:
- Bump Manatee.Json from 13.0.2 to 13.0.3. #563
- Bug fixes:
- Fixed reporting of error when rule error is handled. #564
- Additionally rules can use
-ErrorAction Ignoreto ignore non-exception errors.
- Additionally rules can use
- Fixed first exception stops other rules from being processed. #566
- Fixed reporting of error when rule error is handled. #564
- Engine features:
- Added character case assertion helpers
IsLower, andIsUpper. #555IsLowerchecks that all letters in a field value are lowercase.IsUpperchecks that all letters in a field value are uppercase.
- Added character case assertion helpers
- Bug fixes:
- Fixed NUnit report reasons should be escaped in markdown. #471
- Engine features:
- Added support for formatting results as markdown. #474
- Use
-OutputFormat Markdownor configureOutput.Formatto output markdown. - To format as either detail or summary, use the
-Asparameter or configureOutput.As.
- Use
- Added support for formatting results as markdown. #474
- General improvements:
- Numerical strings can be converted with numeric assertion helpers. #550
- Added outcome
Output.Outcomeas a configurable option. #552
- Engine features:
- Added support for scanning repository files. #524
- Added
Fileinput type (-InputType File) to scan for files without deserializing them. - Added
Input.PathIgnoreoption to ignore files. - When using the
Fileinput type path specs in.gitignoreare ignored.
- Added
- Added
Get-PSRuleTargetcmdlet to read input files and return raw objects. #525- This cmdlet can be used to troubleshoot PSRule input issues.
- Baselines can now be flagged as obsolete. #499
- Set the
metadata.annotations.obsoleteproperty totrueto flag a baseline as obsolete. - When an obsolete baseline is used, a warning will be generated.
- Set the
- Added file assertion helpers
FileHeader, andFilePath. #534FileHeaderchecks for a comment header in the file.FilePathchecks that a file path (optionally with suffixes) exist.
- Added support for scanning repository files. #524
- General improvements:
- Added automatic binding for Rule object. #542
- Engineering:
- Warn when deprecated
$Ruleproperties are used. #536 #545- First usage of deprecated property generates a warning.
- Rule using deprecated property is flagged in debug output.
- Bump YamlDotNet dependency to v8.1.2. #439
- Warn when deprecated
- Bug fixes:
- Fixed out of bounds exception when empty markdown documentation is used. #516
- Bug fixes:
- Fixed excessive obsolete property warnings. #545
- General improvements:
- Added automatic binding for Rule object. #542
- Bug fixes:
- Fixed
InputFileInfoTypeproperty causes downstream binding issues. #541
- Fixed
- Engine features:
- Added file assertion helpers
FileHeader, andFilePath. #534FileHeaderchecks for a comment header in the file.FilePathchecks that a file path (optionally with suffixes) exist.
- Added file assertion helpers
- Engineering:
- Warn when deprecated
$Ruleproperties are used. #536
- Warn when deprecated
- Bug fixes:
- Fixed out of bounds exception when empty markdown documentation is used. #516
- Fixed lines breaks in
RepositoryInfotarget name with git ref. #538
- Engine features:
- Baselines can now be flagged as obsolete. #499
- Set the
metadata.annotations.obsoleteproperty totrueto flag a baseline as obsolete. - When an obsolete baseline is used, a warning will be generated.
- Set the
- Baselines can now be flagged as obsolete. #499
- Engineering:
- Bump YamlDotNet dependency to v8.1.2. #439
- Engine features:
- Added support for scanning repository files. #524
- Added
Fileinput type (-InputType File) to scan for files without deserializing them. - Added
Input.PathIgnoreoption to ignore files. - When using the
Fileinput type path specs in.gitignoreare ignored.
- Added
- Added
Get-PSRuleTargetcmdlet to read input files and return raw objects. #525- This cmdlet can be used to troubleshoot PSRule input issues.
- Added support for scanning repository files. #524
- Engine features:
- Added
Reasonmethod to assertion results. #500- This new method, streamlines setting custom reasons particularly with formatted strings.
- The
Reasonmethod replaces any previously set reasons with a custom string. - Optional arguments can be provided to be included in string formatting.
- Improvements to assertion methods.
- Added regular expression assertion helpers
Match, andNotMatch. #502 - Added collection assertion helpers
In, andNotIn. #501
- Added regular expression assertion helpers
- Added module version constraints. #498
- The module versions that PSRule uses can be constrained.
- Added
- Bug fixes:
- Fixed styling for no rule files warning with
Assert-PSRule. #484 - Fixed actual value in reason for numeric comparison assertion method. #505
- Fixed styling for no rule files warning with
- No additional changes.
- Bug fixes:
- Fixed
Assert.Inunable to compare PSObject wrapped array items. #512
- Fixed
- Engine features:
- Added
Reasonmethod to assertion results. #500- This new method, streamlines setting custom reasons particularly with formatted strings.
- The
Reasonmethod replaces any previously set reasons with a custom string. - Optional arguments can be provided to be included in string formatting.
- Improvements to assertion methods.
- Added regular expression assertion helpers
Match, andNotMatch. #502 - Added collection assertion helpers
In, andNotIn. #501
- Added regular expression assertion helpers
- Added module version constraints. #498
- The module versions that PSRule uses can be constrained.
- Added
- Bug fixes:
- Fixed styling for no rule files warning with
Assert-PSRule. #484 - Fixed actual value in reason for numeric comparison assertion method. #505
- Fixed styling for no rule files warning with
- Bug fixes:
- Fixed unable to read properties for .NET
DynamicObject. #491 - Fixed read of JSON input format with null array item. #490
- Fixed
Csvoutput format with summary forInvoke-PSRule. #486
- Fixed unable to read properties for .NET
- Bug fixes:
- Fixed unable to read properties for .NET
DynamicObject. #491 - Fixed read of JSON input format with null array item. #490
- Fixed unable to read properties for .NET
- Bug fixes:
- Fixed
Csvoutput format with summary forInvoke-PSRule. #486
- Fixed
- General improvements:
- Improved
Assert-PSRuleoutput formatting. #472- Added recommendation and reasons for
AzurePipelinesandGitHubActionsstyles. - Summary line is has been updated to include synopsis instead of reasons.
- Added recommendation and reasons for
- Improved
- Bug fixes:
- Fixed binding with
ModuleConfig. #468 - Fixed recommendation output with client style. #467
- Fixed binding with
- No additional changes.
- General improvements:
- Improved
Assert-PSRuleoutput formatting. #472- Added recommendation and reasons for
AzurePipelinesandGitHubActionsstyles. - Summary line is has been updated to include synopsis instead of reasons.
- Added recommendation and reasons for
- Improved
- Bug fixes:
- Fixed binding with
ModuleConfig. #468 - Fixed recommendation output with client style. #467
- Fixed binding with
- General improvements:
- Improved
Assert-PSRuleoutput formatting.- Added recommendation and reasons for
ClientandPlainstyles. #456
- Added recommendation and reasons for
- Added support for configuration of default module options. #459
bindingandconfigurationoptions can be set to a default value.- Updated
New-PSRuleOptionparameter sets and help based on updates to module config.
- Added support for module fallback culture. #441
- Improved
- Bug fixes:
- Fixed resource schema to include
useQualifiedNameandnameSeparatoroption. #458
- Fixed resource schema to include
- No additional changes.
- General improvements:
- Improved
Assert-PSRuleoutput formatting.- Added recommendation and reasons for
ClientandPlainstyles. #456
- Added recommendation and reasons for
- Added support for configuration of default module options. #459
bindingandconfigurationoptions can be set to a default value.- Updated
New-PSRuleOptionparameter sets and help based on updates to module config.
- Added support for module fallback culture. #441
- Improved
- Bug fixes:
- Fixed resource schema to include
useQualifiedNameandnameSeparatoroption. #458
- Fixed resource schema to include
- General improvements:
- Added configuration option
Output.Culturefor setting culture. #442 - Improved handling of fields to allow the input object to be referenced with
.. #437
- Added configuration option
- Bug fixes:
- Fixed numeric comparison assertion with non-int types. #436
- Fixed output culture option ignored. #449
- No additional changes.
- Bug fixes:
- Fixed output culture option ignored. #449
- General improvements:
- Added configuration option
Output.Culturefor setting culture. #442 - Improved handling of fields to allow the input object to be referenced with
.. #437
- Added configuration option
- Bug fixes:
- Fixed numeric comparison assertion with non-int types. #436
- Engine features:
- Added
-ResultVariableto store results from Assert-PSRule into a variable. #412
- Added
- General improvements:
- Added recommendation to failure message of NUnit results. #421
- Bug fixes:
- Fixed handling of
vin field value with$Assert.Version. #429 - Fixed handling of warning action preference with
Assert-PSRule. #428 - Fixed parent culture unwind with POSIX. #414
- Fixed output of warning with
Assert-PSRule. #417 - Fixed NUnit report to include a failure element when reason is not specified. #420
- Fixed handling of
- No additional changes.
- Fixed handling of
vin field value with$Assert.Version. #429 - Fixed handling of warning action preference with
Assert-PSRule. #428 - Added
-ResultVariableto store results from Assert-PSRule into a variable. #412 - Fixed output of warning with
Assert-PSRule. #417 - Fixed NUnit report to include a failure element when reason is not specified. #420
- Added recommendation to failure message of NUnit results. #421
- Fixed parent culture unwind with POSIX. #414
- Engine features:
- Added support for qualified target names. #395
- Added options
Binding.UseQualifiedNameandBinding.NameSeparator. - See
about_PSRule_Optionsfor details.
- Added options
- Added assertion method
HasJsonSchemato check if a JSON schema is referenced. #398- See
about_PSRule_Assertfor usage details.
- See
- Added file content helper for reading objects from files. #399
- The method
GetContentof$PSRulecan be used to read files as objects. - See
about_PSRule_Variablesfor usage details.
- The method
- Added support for qualified target names. #395
- General improvements:
- Improved reporting on runtime errors in rule blocks. #239
- Improved NUnit results to include a failure message based on reported reasons. #404
- Bug fixes:
- Fixed wide formatting of rules with
Get-PSRule. #407 - Fixed TargetName hash serialization for base types. #406
- Fixed output not generated with Assert-PSRule and Stop. #405
- Fixed NUnit results incorrectly reporting that the test had not executed. #403
- Fixed wide formatting of rules with
- No additional changes
- Fixed wide formatting of rules with
Get-PSRule. #407 - Fixed TargetName hash serialization for base types. #406
- Fixed output not generated with Assert-PSRule and Stop. #405
- Fixed NUnit results incorrectly reporting that the test had not executed. #403
- Improved NUnit results to include a failure message based on reported reasons. #404
- Improved reporting on runtime errors in rule blocks. #239
- Added support for qualified target names. #395
- Added options
Binding.UseQualifiedNameandBinding.NameSeparator. - See
about_PSRule_Optionsfor details.
- Added options
- Added assertion method
HasJsonSchemato check if a JSON schema is referenced. #398- See
about_PSRule_Assertfor usage details.
- See
- Added file content helper for reading objects from files. #399
- The method
GetContentof$PSRulecan be used to read files as objects. - See
about_PSRule_Variablesfor usage details.
- The method
- Engine features:
- Improvements to rule help and documentation. #382 #316
- Added links and notes sections to help.
- Added
-Fullswitch toGet-PSRuleHelpto display links and notes sections. - Added support for using a parent culture in rule help.
- Rule help will use parent culture when a more specific culture is not available.
- Added input format for reading PowerShell data
.psd1files. #368PowerShellDatahas been added toInput.Format.- See
about_PSRule_Optionsfor details.
- Added custom rule data to results. #322
$PSRule.Datacan be used to set custom data during rule execution that is included in output.- See
about_PSRule_Variablesfor usage details.
- Improvements to assertion methods. #386 #374 #387 #344 #353 #357
- Added support for assertion methods to be used within script pre-conditions.
- Added numeric comparison assertion helpers
Greater,GreaterOrEqual,LessandLessOrEqual. - Added semantic version assertion helper
Version. - Added string affix assertion helpers
StartsWith,EndsWithandContains. - See
about_PSRule_Assertfor usage details.
- Improvements to output logging and formatting for
Assert-PSRule.- Formatting now includes errors and warnings using style.
- Added PSRule banner with module information.
- Added rule success summary.
- Improvements to rule help and documentation. #382 #316
- General improvements:
- Added aliases for
-OutputFormat(-o) and-Module(-m) parameters. #384 - Added
WithReasonto append/ replace reasons from assertion result. #354 - Added configuration helper for strings arrays. #363
- Added aliases for
- Bug fixes:
- Fixed JSON de-serialization fails with single object. #379
- Fixed stack overflow when parsing malformed JSON. #380
- No additional changes.
- Fixed JSON de-serialization fails with single object. #379
- Fixed stack overflow when parsing malformed JSON. #380
- Added rule documentation links and notes to help. #382
- Added
-Fullswitch toGet-PSRuleHelpto display links and notes sections.
- Added
- Added aliases for
-OutputFormat(-o) and-Module(-m) parameters. #384 - Improved numeric comparison assertion helpers to support strings. #387
- Methods
Greater,GreaterOrEqual,LessandLessOrEqualnow also check string length.
- Methods
- Added support for assertion methods to be used within script pre-conditions. #386
- Added input format for reading PowerShell data
.psd1files. #368PowerShellDatahas been added toInput.Format.- See
about_PSRule_Optionsfor details.
- Added numeric comparison assertion helpers. #374
- Added methods
Greater,GreaterOrEqual,LessandLessOrEqual. - See
about_PSRule_Assertfor usage details.
- Added methods
- Added configuration helper for strings arrays. #363
- Added support for using a parent culture in rule help. #316
- Rule help will use parent culture when a more specific culture is not available.
- Added custom rule data to results. #322
$PSRule.Datacan be used to set custom data during rule execution that is included in output.- See
about_PSRule_Variablesfor usage details.
- Improves output logging and formatting for Assert-PSRule. #357
- Formatting now includes errors and warnings using style.
- Added PSRule banner with module information.
- Added rule success summary.
- Added semantic version assertion helper
Version. #344 - Added string affix assertion helpers. #353
- Added methods
StartsWith,EndsWithandContains. Seeabout_PSRule_Assertfor usage details.
- Added methods
- Added
WithReasonto append/ replace reasons from assertion result. #354 - Engine features:
- Added
-Alloption toExistskeyword. #331 - Added custom field binding. #321
- Added new option
Binding.Fieldavailable in baselines to configure binding.
- Added new option
- Added
- General improvements:
- Added filtering for rules against a baseline with
Get-PSRule. #345 - Added parameter alias
-ffor-InputPath. #340-fwas added toInvoke-PSRule,Assert-PSRuleandTest-PSRuleTargetcmdlets.
- Added filtering for rules against a baseline with
- Important change: Added
$PSRulegeneric context variable. #341- Deprecated
TargetName,TargetTypeandTargetObjectproperties on$Rule. - Use
TargetName,TargetTypeandTargetObjecton$PSRuleinstead. - Properties
TargetName,TargetTypeandTargetObjecton$Rulewill be removed in the future. - Going forward
$Rulewill only contain properties that relate to the current rule context.
- Deprecated
- Bug fixes:
- Fixed key has already been added for default baseline. #349
- Fixed multiple value tag filtering. #346
- Fixed TargetType fall back to type name. #339
- Fixed NUnit serialization issue for unprocessed rules. #332
- Fixed key has already been added for default baseline. #349
- Fixed multiple value tag filtering. #346
- Added filtering for rules against a baseline with
Get-PSRule. #345 - Fixed TargetType fall back to type name. #339
- Added custom field binding. #321
- Added new option
Binding.Fieldavailable in baselines to configure binding.
- Added new option
- Added parameter alias
-ffor-InputPath. #340-fwas added toInvoke-PSRule,Assert-PSRuleandTest-PSRuleTargetcmdlets.
- Important change: Added
$PSRulegeneric context variable. #341- Deprecated
TargetName,TargetTypeandTargetObjectproperties on$Rule. - Use
TargetName,TargetTypeandTargetObjecton$PSRuleinstead. - Properties
TargetName,TargetTypeandTargetObjecton$Rulewill be removed in the future. - Going forward
$Rulewill only contain properties that relate to the current rule context.
- Deprecated
- Fixed NUnit serialization issue for unprocessed rules. #332
- Added
-Alloption toExistskeyword. #331 - General improvements:
- Added
-TargetTypeparameter to filter input objects by target type. #176- This parameter applies to
Invoke-PSRule,Assert-PSRuleandTest-PSRuleTarget.
- This parameter applies to
- Added
- Bug fixes:
- Fixed null reference exception when bound property is null. #323
- Fixed missing
Markdowninput format in options schema. #315
- Breaking change: Unprocessed object results are not returned from
Test-PSRuleTargetby default. #318- Previously unprocessed objects returned
$True, now unprocessed objects return no result. - Use
-Outcome Allto return$Truefor unprocessed objects the same as <= v0.10.0.
- Previously unprocessed objects returned
- No additional changes.
- Fixed null reference exception when bound property is null. #323
- Fixed missing
Markdowninput format in options schema. #315 - Added
-TargetTypeparameter to filter input objects by target type. #176- This parameter applies to
Invoke-PSRule,Assert-PSRuleandTest-PSRuleTarget.
- This parameter applies to
- Breaking change: Unprocessed object results are not returned from
Test-PSRuleTargetby default. #318- Previously unprocessed objects returned
$True, now unprocessed objects return no result. - Use
-Outcome Allto return$Truefor unprocessed objects the same as <= v0.10.0.
- Previously unprocessed objects returned
- General improvements:
- Added source note properties to input objects read from disk with
-InputPath. #302
- Added source note properties to input objects read from disk with
- Engine features:
- Added assertion helper for checking field default value. #289
- Added dependency
DependsOninformation to results fromGet-PSRule. #210- To include dependencies that would normally be filtered out use
-IncludeDependencies.
- To include dependencies that would normally be filtered out use
- Added input format for reading markdown front matter. #301
- Markdown front matter is deserialized and evaluated as an object.
- Added
Assert-PSRulecmdlet to improve integration into CI processes. #290- Added
Output.Styleoption to support output in the following styles:- Client/ Plain - Output returns easy to read log of rule pass/ fail.
- Azure Pipelines - Report rule failures as errors collected by Azure Pipelines.
- GitHub Actions - Reports rule failures as errors collected by GitHub Actions.
- Added
- Bug fixes:
- Fix
Get-PSRuleHelp-Online in constrained language mode. #296
- Fix
- Breaking change: Removed previously deprecated alias
HintforRecommend. #165- Use the
Recommendkeyword instead.
- Use the
- No additional changes.
- Added dependency
DependsOninformation to results fromGet-PSRule. #210- To include dependencies that would normally be filtered out use
-IncludeDependencies.
- To include dependencies that would normally be filtered out use
- Added input format for reading markdown front matter. #301
- Markdown front matter is deserialized and evaluated as an object.
- Added source note properties to input objects read from disk with
-InputPath. #302 - Breaking change: Removed previously deprecated alias
HintforRecommend. #165- Use the
Recommendkeyword instead.
- Use the
- Fix
Get-PSRuleHelp-Online in constrained language mode. #296 - Added
Assert-PSRulecmdlet to improve integration into CI processes. #290- Added
Output.Styleoption to support output in the following styles:- Client/ Plain - Output returns easy to read log of rule pass/ fail.
- Azure Pipelines - Report rule failures as errors collected by Azure Pipelines.
- GitHub Actions - Reports rule failures as errors collected by GitHub Actions.
- Added
- Added assertion helper for checking field default value. #289
- General improvements:
- Improve feedback of parsing errors. #185
- Updated
Get-PSRuleHelpto include help within the current path by default. #197
- Engine features:
- Added support for a wildcard match using the
Withinkeyword. #272 - Added rule info display name. #276
- Added support for matching an array of tag values. #282
- Added named baselines. Now baselines are a separate resource that can be individually used.
- Baselines can be packaged within module.
- Modules can specify a default baseline in module manifest.
- Target binding options (
Binding) are now part of baselines. - See about_PSRule_Baseline for more information.
- Added support for a wildcard match using the
- Bug fixes:
- Fix can not serialize nested System.IO.DirectoryInfo property. #281
- Fix ModuleName not displayed in Get-PSRuleHelp list. #275
- Fix outcome reported when error or exception is raised. #211
- Breaking change: Baseline improvements, fundamentally changes how baselines work. #274
- Previously, baselines were specified as workspace options.
- The previous
baselineoptions property has been renamed torule. - The previous
configurationproperty is now a top level option.
- No additional changes
- Added support for matching an array of tag values. #282
- Updated
Get-PSRuleHelpto include help within the current path by default. #197 - Fix can not serialize nested System.IO.DirectoryInfo property. #281
- Fix export of
Likeparameter forWithinkeyword. #279 - Breaking change: Added named baselines. This changes how baselines work. #274
- Previously, baselines were specified as workspace options.
- Now, baselines are a separate resource that can be individually used. Additionally:
- Baselines can be packaged within module.
- Modules can specify a default baseline in module manifest.
- Target binding options (
Binding) are now part of baselines.
- The previous
baselineoptions property has been renamed torule. - The previous
configurationproperty is now a top level option. - See about_PSRule_Baseline for more information.
- Added support for a wildcard match using the
Withinkeyword. #272 - Added rule info display name. #276
- Fix ModuleName not displayed in Get-PSRuleHelp list. #275
- Improve feedback of parsing errors. #185
- Fix outcome reported when error or exception is raised. #211
- General improvements:
- PSRule options are now displayed as YAML instead of a complex object. #233
- Add detection for improper keyword use. #203
- Automatically load rule modules. #218
- Added support for debug messages and
Write-Debugin rule definitions. #146 - Added
Logging.LimitDebugandLogging.LimitVerboseoptions to limit logging to named scopes. #235
- Engine features:
- Added per object reason for failing rules. #200
- Keywords
Exists,Match,WithinandTypeOfautomatically add a reason when they fail. - Custom reason can be set for keywords
Exists,Match,WithinandTypeOfwith-Reason. - Added
Reasonkeyword to add to reason for custom logic. - Added wide output display for
Invoke-PSRulewhich include the reason why rule failed.- To use wide output use the
-OutputFormat Wideparameter.
- To use wide output use the
- Renamed
-Messageparameter to-Texton theRecommendkeyword.- The
-Messageis an alias of-Textand will be deprecated in the future.
- The
- Keywords
- Added assertion helper
$Assertfor extensibility. #250- Add built-in assertions for
HasField,HasFieldValueandNullOrEmpty. - Add JSON schema assertion method
JsonSchema. #42
- Add built-in assertions for
- Added per object reason for failing rules. #200
- Bug fixes:
- Fix rule synopsis comment capture. #214
- Fix YAML options file discovery issue in dotted directory. #232
- Fix comparison of wrapped types and null with
Within. #237
- Breaking change: Use rule references consistent with cmdlet fully qualified syntax. #217
- Rule names have to be unique within the current execution path or within a module.
- Previously rule names only had to be unique within a single file.
- Previously the
filename.rule.ps1/RuleNamewas required to reference rules across files.- This is no longer required because rule names are unique.
- You can reference a rule from a loaded module by using the syntax
ModuleName\\RuleName.
- Rule names have to be unique within the current execution path or within a module.
- Fix export of assertion helper variable
$Assert. #262 - Fix module reloading with different versions. #254
- Fix not finding rules in current path by default. #256
- Fix rule synopsis comment capture. #214
- Fix inconsistent handling of
$PWD. #249 - Add detection for improper keyword use. #203
- Automatically load rule modules. #218
- Added assertion helper
$Assertfor extensibility. #250- Add built-in assertions for
HasField,HasFieldValueandNullOrEmpty. - Add JSON schema assertion method
JsonSchema. #42
- Add built-in assertions for
- Breaking change: Use rule references consistent with cmdlet fully qualified syntax. #217
- Rule names have to be unique within the current execution path or within a module.
- Previously rule names only had to be unique within a single file.
- Previously the
filename.rule.ps1/RuleNamewas required to reference rules across files.- This is no longer required because rule names are unique.
- You can reference a rule from a loaded module by using the syntax
ModuleName\\RuleName.
- Rule names have to be unique within the current execution path or within a module.
- Added per object reason for failing rules. #200
- The keywords
Exists,Match,WithinandTypeOfautomatically add a reason when they fail. - Added
-Reasonparameter toExists,Match,WithinandTypeOfkeywords to allow a custom reason to be set. - Added
Reasonkeyword to add to reason for custom logic. - Added wide output display for
Invoke-PSRulewhich include the reason why rule failed.- To use wide output use the
-OutputFormat Wideparameter.
- To use wide output use the
- Renamed
-Messageparameter to-Texton theRecommendkeyword.- The
-Messageis an alias of-Textand will be deprecated in the future.
- The
- The keywords
- Fix YAML options file discovery issue in dotted directory. #232
- Fix comparison of wrapped types and null with
Within. #237 - PSRule options are now displayed as YAML instead of a complex object. #233
- Added support for debug messages and
Write-Debugin rule definitions. #146 - Added
Logging.LimitDebugandLogging.LimitVerboseoptions to limit logging to named scopes. #235 - Fix reading nested arrays from JSON input. #223
- Fix comparison of non-string types with
Within. #226 - Fix circular rule dependency issue. #190
- Fix rule
DependsOnparameter allows null. #191 - Fix error message when attempting to use the rule keyword in a rule definition. #189
- Fix TargetName binding when TargetName or Name property is null. #202
- Fix handling of non-boolean results in rules. Rule is failed with more specific error message. #187 #224
- Include .ps1 files that are specified directly with
-Path, instead of only .Rule.ps1 files. #182- Improved warning message displayed when no Rule.ps1 files are founds.
- Added support for
Invoke-PSRuleto return CSV formatted results. #169- To generate CSV results use the
-OutputFormat Csvparameter. - Added
Output.Pathoption to allow output to be saved directly to file. - Added
Output.Encodingoption configure encoding used to write to file. - By default, UTF-8 encoding without BOM is used.
Invoke-PSRulecmdlet also provides a parameter-OutputPathto write results to file.
- To generate CSV results use the
- Reordered cmdlet parameters to improve usage of frequently used parameters. #175
-Moduleparameter will tab-complete with imported rule modules.
- Added culture support for PowerShell informational messages. #158
- A new
$LocalizedDatavariable can be used within rule definitions.
- A new
- Added
-Notswitch toWithinandMatchkeywords to allow negative comparison. #208 - Improve discovery of rule tags. #209
- Add wide format
-OutputFormat WidetoGet-PSRuleto allow output of rule tags.
- Add wide format
- Breaking change: Changed rule filtering by tag to be case-insensitive. #204
- Previously tag value was case-sensitive, however this is confusing since PowerShell is case-insensitive by default.
- Breaking change: Rule time is recorded in milliseconds instead of seconds. #192
- No additional changes.
- Fix reading nested arrays from JSON input. #223
- Fix comparison of non-string types with
Within. #226 - Improve handling of null rule result. #224
- Fix TargetName binding when TargetName or Name property is null. #202
- Add culture support for PowerShell informational messages. #158
- A new
$LocalizedDatavariable can be used within rule definitions.
- A new
- Add
-Notswitch toWithinandMatchkeywords to allow negative comparison. #208 - Improve discovery of rule tags. #209
- Add wide format
-OutputFormat WidetoGet-PSRuleto allow output of rule tags.
- Add wide format
- Breaking change: Change rule filtering by tag to be case-insensitive. #204
- Previously tag value was case-sensitive, however this is confusing since PowerShell is case-insensitive by default.
- Fix circular rule dependency issue. #190
- Fix rule
DependsOnparameter allows null. #191 - Fix error message when attempting to use the rule keyword in a rule definition. #189
- Breaking change: Rule time is recorded in milliseconds instead of seconds. #192
- Fix handling of non-boolean results in rules. Rule is failed with more specific error message. #187
- Include .ps1 files that are specified directly with
-Path, instead of only .rule.ps1 files. #182- Improved warning message displayed when no Rule.ps1 files are founds.
- Added support for
Invoke-PSRuleto return CSV formatted results. #169- To generate CSV results use the
-OutputFormat Csvparameter. - Added
Output.Pathoption to allow output to be saved directly to file. - Added
Output.Encodingoption configure encoding used to write to file. - By default, UTF-8 encoding without BOM is used.
Invoke-PSRulecmdlet also provides a parameter-OutputPathto write results to file.
- To generate CSV results use the
- Reordered cmdlet parameters to improve usage of frequently used parameters. #175
-Moduleparameter will tab-complete with imported rule modules.
- Fix operation is not supported on this platform failure. #152
- Fix FullName cannot be found on this object error. #149
- Fix discovery of rules within paths that contain spaces fails. #168
- Added rule documentation, which allows additional rule information to be stored in markdown files. #157
- Rule documentation also adds culture support. #18
- Rule documentation can be accessed like help with the
Get-PSRuleHelpcmdlet.
- Added annotations, which are non-indexed metadata stored in rule documentation. #148
- Annotations can contain a link to online version of the documentation. #147
- Important change: Changed
Hintkeyword toRecommendto align with rule documentation. #165- Use of
Hintkeyword is deprecated and will be removed in a future release. CurrentlyHintis aliased toRecommendfor compatibility.
- Use of
- Breaking change: Changed rule properties to align with rule documentation. #164
- Rule
Synopsis, is a brief summary of the rule andDescriptionis a detailed purpose of the rule. Description:metadata keyword used in comment help is nowSynopsis:, use ofDescription:will set synopsis. Description metadata keyword is deprecated and will be removed in a future update.- Output property
Messageon rule results is nowRecommendation.
- Rule
- Fix discovery of rules within paths that contain spaces fails. #168
- Fix exporting of
Recommendkeyword andHintalias. #171 - Important change: Changed
Hintkeyword toRecommendto align with rule documentation. #165- Use of
Hintkeyword is deprecated and will be removed in a future release. CurrentlyHintis aliased toRecommendfor compatibility.
- Use of
- Breaking change: Changed rule properties to align with rule documentation. #164
- Rule
Synopsis, is a brief summary of the rule andDescriptionis a detailed purpose of the rule. Description:metadata keyword used in comment help is nowSynopsis:, use ofDescription:will set synopsis. Description metadata keyword is deprecated and will be removed in a future update.- Output property
Messageon rule results is nowRecommendation.
- Rule
- Added rule documentation, which allows additional rule information to be stored in markdown files. #157
- Rule documentation also adds culture support. #18
- Rule documentation can be accessed like help with the
Get-PSRuleHelpcmdlet.
- Added annotations, which are non-indexed metadata stored in rule documentation. #148
- Annotations can contain a link to online version of the documentation. #147
- Fix operation is not supported on this platform failure. #152
- Fix FullName cannot be found on this object error. #149
- Fix PSRule options schema usage of additionalProperties. #136
- Fix null reference exception when traversing null field. #123
- Fix missing help topics for options and variables. #125
- Improved handling of default YAML options file. #137
- Added support for
Invoke-PSRuleto return NUnit3 formatted results. #129- To generate NUnit3 results use the
-OutputFormat NUnit3parameter.
- To generate NUnit3 results use the
- Added
Set-PSRuleOptioncmdlet to configure YAML options file. #135 - Added parameters to New-PSRuleOption to configure common options. #134
- Additional parameters are an alternative to using a
-Optionhashtable.
- Additional parameters are an alternative to using a
- Fix schema conformance of
-OutputFormat NUnit3to NUnit report schema. #141 - Fix PSRule options schema usage of additionalProperties. #136
- Added support for
Invoke-PSRuleto return NUnit3 formatted results. #129- To generate NUnit3 results use the
-OutputFormat NUnit3parameter.
- To generate NUnit3 results use the
- Added
Set-PSRuleOptioncmdlet to configure YAML options file. #135 - Added parameters to New-PSRuleOption to configure common options. #134
- Additional parameters are an alternative to using a
-Optionhashtable.
- Additional parameters are an alternative to using a
- Improved handling of default YAML options file. #137
- Fix null reference exception when traversing null field. #123
- Fix missing help topics for options and variables. #125
- Fix incorrect JSON de-serialization. #109 #111
- Added support for using
-InputPathinstead of using-InputObjectto handle serialized objects. #106-Formatis automatically detected for.yaml,.ymland.jsonfile extensions.
- Added
-OutputFormatparameter to serialize output fromInvoke-PSRuleas YAML or JSON. #29 - Added support for logging pass or fail outcomes to a data stream such as Error, Warning or Information. #97
- Breaking change: Deprecated usage of the
-TargetNameparameter on theHintkeyword has been removed. #81 - No additional changes.
- Fix summary is not correctly serialized with JSON or YAML output format. #116
- Fix missing properties on serialized YAML output. #115
- Fix incorrect property name case of YAML serialized results. #114
- Fix incorrect JSON de-serialization of nested arrays. #109
- Fix incorrect JSON de-serialization of non-object arrays. #111
- Added support for using
-InputPathinstead of using-InputObjectto handle serialized objects. #106-Formatis automatically detected for.yaml,.ymland.jsonfile extensions.
- Added
-OutputFormatparameter to serialize output fromInvoke-PSRule. #29 - Added support for logging pass or fail outcomes to a data stream such as Error, Warning or Information. #97
- Breaking change: Deprecated usage of the
-TargetNameparameter on theHintkeyword has been removed. #81 - Added support for pipelining with
Exists,Within,MatchandTypeOfkeywords #90 - Added support for packaging rules in modules #16
- Import objects from YAML or JSON format #75
- Added support for input de-serialization from FileInfo objects #95
- Support nested TargetObjects #77
- Export variables to improve authoring experience #83
- Binding improvements:
- Added object type binding and dynamic filtering for rules #82
- Added support for indexed and quoted field names #86
- Added support for case-sensitive binding operations #87
- Binding ignores case by default. Set option
Binding.CaseSensitivetotrueto enable case-sensitivity.
- Binding ignores case by default. Set option
- Support TargetName binding of nested properties #71
- Added online help links to keywords #72
- Added schema for PSRule options #74
- Important change: The
-TargetNameparameter of theHintkeyword has been deprecated #81-TargetNameparameter not longer sets the pipeline object TargetName and generates a warning instead.- The
-TargetNamewill be completely removed in v0.4.0, at which time using the parameter will generate an error.
- Breaking change: Changed parameter alias for
-Pathfrom-fto-p#99 - Added support for input de-serialization from FileInfo objects #95
- Breaking change: Changed parameter alias for
-Pathfrom-fto-p#99 - Added support for pipelining with
Exists,Within,MatchandTypeOfkeywords #90 - Fix empty YAML object causes format de-serialize to fail #92
- Export variables to improve authoring experience #83
- Added support for packaging rules in modules #16
- Added support for indexed and quoted field names #86
- Added object type binding and dynamic filtering for rules #82
- Added support for case-sensitive binding operations #87
- Binding ignores case by default. Set option
Binding.CaseSensitivetotrueto enable case-sensitivity.
- Binding ignores case by default. Set option
- Important change: The
-TargetNameparameter of theHintkeyword has been deprecated #81-TargetNameparameter not longer sets the pipeline object TargetName and generates a warning instead.- The
-TargetNamewill be completely removed in v0.4.0, at which time using the parameter will generate an error.
- Added online help links to keywords #72
- Added schema for PSRule options #74
- Import objects from YAML or JSON format #75
- Support TargetName binding of nested properties #71
- Support nested TargetObjects #77
- Added support for cross-platform environments (Windows, Linux and macOS) #49
- Added support for nested field names with
Exists,WithinandMatchkeywords #60 - Added support for rule configuration using baselines #17
- Use rule description when hint message not set #61
- Allow objects to be suppressed by TargetName for individual rules #13
- Allow binding of TargetName to custom property #44
- Custom functions can be used to bind TargetName #44
- Objects that are unable to bind a TargetName will use a SHA1 object hash for TargetName #44
- Added
Test-PSRuleTargetcommand to return an overall$Trueor$Falseafter evaluating rules for an object #30 - Improve reporting of inconclusive results and objects that are not processed by any rule #46
- Inconclusive results and objects not processed will return a warning by default.
- Fix propagation of informational messages to host from rule scripts and definitions #48
- Fix Get-PSRule generates exception when no .rule.ps1 scripts exist in path #53
- Fix LocalizedData.PathNotFound warning when no .rule.ps1 scripts exist in path #54
- No additional changes.
- Added support for nested field names with
Exists,WithinandMatchkeywords #60 - Added support for rule configuration using baselines #17
- Use rule description when hint message not set #61
- Fix Get-PSRule generates exception when no .rule.ps1 scripts exist in path #53
- Fix LocalizedData.PathNotFound warning when no .rule.ps1 scripts exist in path #54
- Breaking change: Renamed
Test-PSRulecmdlet toTest-PSRuleTargetwhich aligns more closely to the verb-noun naming standard #57 - Allow objects to be suppressed by TargetName for individual rules #13
- Allow binding of TargetName to custom property #44
- Custom functions can be used to bind TargetName #44
- Objects that are unable to bind a TargetName will use a SHA1 object hash for TargetName #44
- Added
Test-PSRulecommand to return an overall$Trueor$Falseafter evaluating rules for an object #30 - Improve reporting of inconclusive results and objects that are not processed by any rule #46
- Inconclusive results and objects not processed will return a warning by default.
- Fix propagation of informational messages to host from rule scripts and definitions #48
- Added support for cross-platform environments (Windows, Linux and macOS) #49
- Initial release
- Fix outcome filtering of summary results #33
- Fix target object counter in verbose logging #35
- Fix hashtable keys should be handled as fields #36
- RuleId and RuleName are now independent. Rules are created with a name, and the RuleId is generated based on rule name and file name
- Rules with the same name can exist and be cross linked with DependsOn, as long a the script file name is different
- Added
-NottoExistskeyword - Improved verbose logging of
Exists,AllOf,AnyOfkeywords and core engine - Breaking change: Renamed outcome filtering parameters to align to type name and increase clarity
Invoke-PSRulehas a-Outcomeparameter instead of-Status-Outcomesupports values ofPass,Fail,Error,None,ProcessedandAll
- Added rule tags to results to enable grouping and sorting #14
- Added support to check for rule tag existence. Use
*for tag value on-Tagparameter withInvoke-PSRuleandGet-PSRule - Added option to report rule summary using
-Asparameter ofInvoke-PSRule#12 - Initial pre-release.
- YAML resources will require an
apiVersionfrom PSRule v2. #648 - Setting the default module baseline requires a module configuration from PSRule v2. #809
- Resource names have naming restrictions introduced from PSRule v2. #1012
- Bug fixes:
- Fixed broken documentation links. #980
- General improvements:
- Added
versionexpression to check semantic version constraints. #861- See about_PSRule_Expressions for details.
- Added
hasDefaultexpression to check field default value. #870- See about_PSRule_Expressions for details.
- Added
- Bug fixes:
- Fixed
GetReason()not returning results for a failed assertion. #874
- Fixed
- No additional changes.
- General improvements:
- Added
versionexpression to check semantic version constraints. #861- See about_PSRule_Expressions for details.
- Added
hasDefaultexpression to check field default value. #870- See about_PSRule_Expressions for details.
- Added
- Bug fixes:
- Fixed
GetReason()not returning results for a failed assertion. #874
- Fixed
- General improvements:
- Added JSON support for reading rules and selectors from pipeline. #857
- Added
HasSchemaexpression to check the schema of an object. #860- See about_PSRule_Expressions for details.
- Engineering:
- Bump Microsoft.SourceLink.GitHub to 1.1.1. #856
- Bug fixes:
- Fixed
$Assert.HasJsonSchemaaccepts empty value. #859 - Fixed module configuration is not loaded when case does not match. #864
- Fixed
- No additional changes.
- Bug fixes:
- Fixed module configuration is not loaded when case does not match. #864
- General improvements:
- Added JSON support for reading rules and selectors from pipeline. #857
- Added
HasSchemaexpression to check the schema of an object. #860- See about_PSRule_Expressions for details.
- Engineering:
- Bump Microsoft.SourceLink.GitHub to 1.1.1. #856
- Bug fixes:
- Fixed
$Assert.HasJsonSchemaaccepts empty value. #859
- Fixed
- General improvements:
- Added improvements to YAML output for
Get-PSRuleBaseline. #829 - Added
-Initializeconvention block. #826- Use this block to perform any initialization that is required before any rules are run.
- This block is only run once instead of
-Beginwhich is run once per object. - See about_PSRule_Conventions for details.
- Allow lifetime services to be used. #827
- Use
$PSRule.AddServiceand$PSRule.GetServiceto add a service. - Services allows a singleton instance to be used and shared across multiple rules.
- PSRule will automatically dispose the service when all rules have run.
- See about_PSRule_Variables for details.
- Use
- Added
Export-PSRuleBaselinecmdlet to export baseline. #622 - Added JSON output format for Baseline cmdlets. #839
- Allow downstream issues to be consumed. #843
- Objects can be flagged with issues that have been generated externally.
- See about_PSRule_Assert for details.
- Migrated default baseline to module configuration. #809
- This enables configuration of the default baseline for a module with a module configuration.
- This depreciate configuring the default baseline within the module manifest.
- Modules using manifest configuration will start warning from v1.9.0.
- See about_PSRule_Options for details.
- Added JSON support to read baselines from pipeline. #845
- Added improvements to YAML output for
- Engineering:
- Bump System.Drawing.Common dependency to v6.0.0. #848
- Bug fixes:
- Fixed convention execution is out of order. #835
- Engineering:
- Bump Microsoft.CodeAnalysis.NetAnalyzers to v6.0.0. #851
- General improvements:
- Allow downstream issues to be consumed. #843
- Objects can be flagged with issues that have been generated externally.
- See about_PSRule_Assert for details.
- Migrated default baseline to module configuration. #809
- This enables configuration of the default baseline for a module with a module configuration.
- This depreciate configuring the default baseline within the module manifest.
- Modules using manifest configuration will start warning from v1.9.0.
- See about_PSRule_Options for details.
- Added JSON support to read baselines from pipeline. #845
- Allow downstream issues to be consumed. #843
- Engineering:
- Bump System.Drawing.Common dependency to v6.0.0. #848
- General improvements:
- Added JSON output format for Baseline cmdlets. #839
- Bug fixes:
- Fixed convention execution is out of order. #835
- General improvements:
- Added
Export-PSRuleBaselinecmdlet to export baseline. #622
- Added
- General improvements:
- Added improvements to YAML output for
Get-PSRuleBaseline. #829 - Added
-Initializeconvention block. #826- Use this block to perform any initialization that is required before any rules are run.
- This block is only run once instead of
-Beginwhich is run once per object. - See about_PSRule_Conventions for details.
- Allow lifetime services to be used. #827
- Use
$PSRule.AddServiceand$PSRule.GetServiceto add a service. - Services allows a singleton instance to be used and shared across multiple rules.
- PSRule will automatically dispose the service when all rules have run.
- See about_PSRule_Variables for details.
- Use
- Added improvements to YAML output for
- General improvements:
- Added YAML output format support for
Get-PSRuleBaseline. #326 - Added YAML/JSON output format support for
Get-PSRule. #128 - Added
Output.JsonIndentoption for JSON output format. #817 - Added assertion helpers and expressions for improving intersection checks. #795
- Added
Countto determine of the field has a specific number of elements. - Added
SetOfto determine if a collection is another collection. - Added
Subsetto determine if a collection is includes another collection. - See about_PSRule_Assert and about_PSRule_Expressions for details.
- Added
- Added support for conditional reason messages with
ReasonIf. #804- See about_PSRule_Assert for details.
- Added support for
typeandnameexpression properties. #810- Use
typeto compare the bound type of the current object. - Use
nameto compare the bound name of the current object. - See about_PSRule_Expressions for details.
- Use
- Added YAML output format support for
- Engineering:
- Migration of Pester v4 tests to Pester v5. #478
- No additional changes.
- General improvements:
- Added
Output.JsonIndentoption for JSON output format. #817
- Added
- General improvements:
- Added YAML/JSON output format support for
Get-PSRule. #128
- Added YAML/JSON output format support for
- Engineering:
- Migration of Pester v4 tests to Pester v5. #478
- General improvements:
- Added YAML output format support for
Get-PSRuleBaseline. #326
- Added YAML output format support for
- General improvements:
- Added support for conditional reason messages with
ReasonIf. #804- See about_PSRule_Assert for details.
- Added support for
typeandnameexpression properties. #810- Use
typeto compare the bound type of the current object. - Use
nameto compare the bound name of the current object. - See about_PSRule_Expressions for details.
- Use
- Added support for conditional reason messages with
- General improvements:
- Added assertion helpers and expressions for improving intersection checks. #795
- Added
Countto determine of the field has a specific number of elements. - Added
SetOfto determine if a collection is another collection. - Added
Subsetto determine if a collection is includes another collection. - See about_PSRule_Assert and about_PSRule_Expressions for details.
- Added
- Added assertion helpers and expressions for improving intersection checks. #795
- Bug fixes:
- Fixed
Get-PSRuleBaselinedoes not return any results from module. #801
- Fixed
- Bug fixes:
- Fixed ResourceTags does not contain a method named ToHashtable. #798
- Engine features:
- Added support for generating badges from rule results. #623
- Standard or custom badges can be generated using a convention and the badge API.
- See about_PSRule_Badges for details.
- Added support for generating badges from rule results. #623
- General improvements:
- Rule results now include a run ID or each run. #774
- Run ID is returned in
Assert-PSRuleoutput at the end of each run by default. - By default a unique
runIdis generated when the rule is run. - The
Output.Footeroption was added to configure the output footer. - See about_PSRule_Options for details.
- Run ID is returned in
- Automatically exclude common repository files from input files. #721
- Added
Input.IgnoreRepositoryCommonoption to change default behavior. - See about_PSRule_Options for details.
- Added
- Added aggregation assertion methods for
AnyOfandAllOf. #776- See about_PSRule_Assert for details.
- Allow baselines to include local rules. #756
- The
Rule.IncludeLocaloption was automatically include local/ standalone rules not in a module. - This option is useful when you want to include local rules not included in a baseline.
- See about_PSRule_Options for details.
- The
- Rule results now include a run ID or each run. #774
- Bug fixes:
- Fixed configuration array deserializes as dictionary from YAML options. #779
- No additional changes.
- General improvements:
- Allow baselines to include local rules. #756
- The
Rule.IncludeLocaloption was automatically include local/ standalone rules not in a module. - This option is useful when you want to include local rules not included in a baseline.
- See about_PSRule_Options for details.
- The
- Allow baselines to include local rules. #756
- Engine features:
- Added support for generating badges from rule results. #623
- Standard or custom badges can be generated using a convention and the badge API.
- See about_PSRule_Badges for details.
- Added support for generating badges from rule results. #623
- General improvements:
- Rule results now include a run ID or each run. #774
- Run ID is returned in
Assert-PSRuleoutput at the end of each run by default. - By default a unique
runIdis generated when the rule is run. - The
Output.Footeroption was added to configure the output footer. - See about_PSRule_Options for details.
- Run ID is returned in
- Rule results now include a run ID or each run. #774
- Bug fixes:
- Fixed configuration array deserializes as dictionary from YAML options. #779
- General improvements:
- Automatically exclude common repository files from input files. #721
- Added
Input.IgnoreRepositoryCommonoption to change default behavior. - See about_PSRule_Options for details.
- Added
- Added aggregation assertion methods for
AnyOfandAllOf. #776- See about_PSRule_Assert for details.
- Automatically exclude common repository files from input files. #721
- Bug fixes:
- Fixed configuration array deserializes as dictionary from YAML options. #779
- Engine features:
- Added support for YAML rules. #603
- YAML rules evaluate an expression tree and return a result for each object.
- YAML provides an additional option for defining rules in addition to PowerShell script rules.
- Type and selector pre-conditions are supported.
- See about_PSRule_Rules for details.
- Added support for YAML rules. #603
- General improvements:
- Added support for object source location in validation. #757
- Default rule source location
.ps-rule/is automatically included. #742- Added
Include.PathandInclude.Moduleoptions to automatically include rule sources. - See about_PSRule_Options for details.
- Added
- Bug fixes:
- Fixed target binding across multiple scopes. #762
- No additional changes.
- Engine features:
- Added support for YAML rules. #603
- YAML rules evaluate an expression tree and return a result for each object.
- YAML provides an additional option for defining rules in addition to PowerShell script rules.
- Type and selector pre-conditions are supported.
- See about_PSRule_Rules for details.
- Added support for YAML rules. #603
- Bug fixes:
- Fixed target binding across multiple scopes. #762
- General improvements:
- Added support for object source location in validation. #757
- Default rule source location
.ps-rule/is automatically included. #742- Added
Include.PathandInclude.Moduleoptions to automatically include rule sources. - See about_PSRule_Options for details.
- Added
- General improvements:
- Added string selector conditions. #747
- Use
startWith,contains, andendsWithto check for a sub-string. - Use
isString,isLower, andisUpperto check for string type and casing. - See about_PSRule_Selectors for details.
- Use
- Added string selector conditions. #747
- Engineering:
- Bump YamlDotNet dependency to 11.2.1. #740
- Bug fixes:
- Fixed options schema should allow spacing after
@pre. #743 - Fixed match selector expression passing on missing field. #745
- Fixed options schema should allow spacing after
- No additional changes.
- General improvements:
- Added string selector conditions. #747
- Use
startWith,contains, andendsWithto check for a sub-string. - Use
isString,isLower, andisUpperto check for string type and casing. - See about_PSRule_Selectors for details.
- Use
- Added string selector conditions. #747
- Engineering:
- Bump YamlDotNet dependency to 11.2.1. #740
- Bug fixes:
- Fixed options schema should allow spacing after
@pre. #743 - Fixed match selector expression passing on missing field. #745
- Fixed options schema should allow spacing after
- Engineering:
- Bump YamlDotNet dependency to 11.2.0. #736
- General improvements:
- PSRule banner can be configured in output when using
Assert-PSRule. #708 - Input source location of objects are included in results.
- Input source location of objects from JSON and YAML input files are read automatically. #624
- Input source location of objects from the pipeline are read from properties. #729
- Assert output improvements:
- Added support for Visual Studio Code with
VisualStudioCodestyle. #731- Updated output format provides support for problem matchers in task output.
- Automatically detect output style from environment variables. #732
- Assert-PSRule now defaults to
Detectinstead ofClient.
- Assert-PSRule now defaults to
- See about_PSRule_Options for details.
- Added support for Visual Studio Code with
- Improved support for version constraints by:
- Constraints can include prerelease versions of other matching versions. #714
- Constraints support using a
@prereleaseor@preto include prerelease versions. #717 - Constraint sets allow multiple constraints to be joined together. #715
- See about_PSRule_Assert for details.
- PSRule banner can be configured in output when using
- Bug fixes:
- Fixed prerelease constraint handling for prerelease versions. #712
- Fixed null reference in convention for nested exceptions. #725
- No additional changes.
- General improvements:
- Source location of objects from the pipeline are read from properties. #729
- Assert output improvements:
- Added support for Visual Studio Code with
VisualStudioCodestyle. #731- Updated output format provides support for problem matchers in task output.
- Automatically detect output style from environment variables. #732
- Assert-PSRule now defaults to
Detectinstead ofClient.
- Assert-PSRule now defaults to
- See about_PSRule_Options for details.
- Added support for Visual Studio Code with
- Bug fixes:
- Fixed null reference in convention for nested exceptions. #725
- General improvements:
- Source location of objects are included in results.
- Source location of objects from JSON and YAML input files are read automatically. #624
- Improved support for version constraints by:
- Constraints can include prerelease versions of other matching versions. #714
- Constraints support using a
@prereleaseor@preto include prerelease versions. #717 - Constraint sets allow multiple constraints to be joined together. #715
- See about_PSRule_Assert for details.
- Source location of objects are included in results.
- Bug fixes:
- Fixed prerelease constraint handling for prerelease versions. #712
- General improvements:
- PSRule banner can be configured in output when using
Assert-PSRule. #708
- PSRule banner can be configured in output when using
- Engine features:
- Options can be configured with environment variables. #691
- See about_PSRule_Options for details.
- Options can be configured with environment variables. #691
- General improvements:
- Exclude
.gitsub-directory by default for recursive scans. #697- Added
Input.IgnoreGitPathoption to configure inclusion of.gitpath. - See about_PSRule_Options for details.
- Added
- Added file path assertion helpers. #679
- Added
WithinPathto check the file path field is within a specified path. - Added
NotWithinPathto check the file path field is not within a specified path - See about_PSRule_Assert for details.
- Added
- Added DateTime type assertion helper. #680
- Added
IsDateTimeto check of object field is[DateTime]. - See about_PSRule_Assert for details.
- Added
- Improved numeric comparison assertion helpers to compare
[DateTime]fields. #685Less,LessOrEqual,Greater, andGreaterOrEqualcompare the number of days from the current time.- See about_PSRule_Assert for details.
- Improved handling of field names for objects implementing
IList,IEnumerable, and index properties. #692
- Exclude
- Engineering:
- Bump YamlDotNet dependency to 11.1.1. #690
- Bug fixes:
- Fixed expected DocumentEnd got SequenceEnd. #698
- No additional changes.
- Engine features:
- Options can be configured with environment variables. #691
- See about_PSRule_Options for details.
- Options can be configured with environment variables. #691
- General improvements:
- Exclude
.gitsub-directory by default for recursive scans. #697- Added
Input.IgnoreGitPathoption to configure inclusion of.gitpath. - See about_PSRule_Options for details.
- Added
- Exclude
- Bug fixes:
- Fixed expected DocumentEnd got SequenceEnd. #698
- General improvements:
- Improved handling of field names for objects implementing
IList,IEnumerable, and index properties. #692
- Improved handling of field names for objects implementing
- Engineering:
- Bump YamlDotNet dependency to 11.1.1. #690
- General improvements:
- Added file path assertion helpers. #679
- Added
WithinPathto check the file path field is within a specified path. - Added
NotWithinPathto check the file path field is not within a specified path - See about_PSRule_Assert for details.
- Added
- Added DateTime type assertion helper. #680
- Added
IsDateTimeto check of object field is[DateTime]. - See about_PSRule_Assert for details.
- Added
- Improved numeric comparison assertion helpers to compare
[DateTime]fields. #685Less,LessOrEqual,Greater, andGreaterOrEqualcompare the number of days from the current time.- See about_PSRule_Assert for details.
- Added file path assertion helpers. #679
- Engine features:
- Added support for extensibility with conventions. #650
- Conventions provide an extensibility point within PSRule to execute actions within the pipeline.
- A convention can expose
Begin,Process, andEndblocks. - In additional to within rules
$PSRule.Datacan be accessed fromBeginandProcessblocks. - See about_PSRule_Conventions for details.
- Added support for object expansion with conventions. #661
- Use the
$PSRule.Importmethod to import child source objects into the pipeline. - See about_PSRule_Variables for details.
- Use the
- Added support for complex pre-conditions with selectors. #649
- See about_PSRule_Selectors for details.
- Added support for extensibility with conventions. #650
- General improvements:
- Added support for preferring automatic binding over custom binding configurations. #670
- Added the
Binding.PreferTargetInfooption to prefer target info specified by the object. - See about_PSRule_Options for details.
- Added the
- Added strong apiVersion to resource types. #647
- Resource schemas now support an
apiVersionfield. - The
apiVersionfield is optional but recommended. - Resources without a
apiVersionfield will not be supported from PSRule v2. - Added warning to flag baseline without
apiVersionset.
- Resource schemas now support an
- Added support for detecting files headers from additional file extensions using
FileHeader. #664- Added
.bicep,.csx,.jsx,.groovy,.java,.json,.jsonc,.scala,.rb,.bat,.cmd. - Added support for
JenkinsfileandDockerfilewithout an extension. - See about_PSRule_Assert for details.
- Added
- Added support for automatic type binding with files that do not have a file extension. #665
- Added support for preferring automatic binding over custom binding configurations. #670
- Bug fixes:
- Fixed dependent rule execution is skipped for consequent input objects. #657
- No additional changes.
- Engine features:
- Added support for complex pre-conditions with selectors. #649
- General improvements:
- Added support for preferring automatic binding over custom binding configurations. #670
- Added the
Binding.PreferTargetInfooption to prefer target info specified by the object. - See about_PSRule_Options for details.
- Added the
- Added strong apiVersion to resource types. #647
- Resource schemas now support an
apiVersionfield. - The
apiVersionfield is optional but recommended. - Resources without a
apiVersionfield will not be supported from PSRule v2. - Added warning to flag baseline without
apiVersionset.
- Resource schemas now support an
- Added support for preferring automatic binding over custom binding configurations. #670
- General improvements:
- Added support for detecting files headers from additional file extensions. #664
- Added
.bicep,.csx,.jsx,.groovy,.java,.json,.jsonc,.scala,.rb,.bat,.cmd. - Added support for
JenkinsfileandDockerfilewithout an extension. - See about_PSRule_Assert for details.
- Added
- Added support for automatic type binding with files that do not have a file extension. #665
- Added support for detecting files headers from additional file extensions. #664
- Engine features:
- Added support for object expansion with conventions. #661
- Use the
$PSRule.Importmethod to import child source objects into the pipeline. - See about_PSRule_Variables for details.
- Use the
- Added support for object expansion with conventions. #661
- Bug fixes:
- Fixed dependent rule execution is skipped for consequent input objects. #657
- Engine features:
- Added support for extensibility with conventions. #650
- Conventions provide an extensibility point within PSRule to execute actions within the pipeline.
- A convention can expose
Begin,Process, andEndblocks. - In additional to within rules
$PSRule.Datacan be accessed fromBeginandProcessblocks. - See about_PSRule_Conventions for details.
- Added support for extensibility with conventions. #650
- Engine features:
- Added assertion helpers. #640
- Added
NotHasFieldto check object does not have any of the specified fields. - Added
Nullto check field value is null. - Added
NotNullto check field value is not null. - See about_PSRule_Assert for details.
- Added
- Added type assertion helpers. #635
- Added
IsNumericto check field value is a numeric types. - Added
IsIntegerto check field value is an integer types. - Added
IsBooleanto check field value is a boolean. - Added
IsArrayto check field value is an array. - Added
IsStringto check field value is a string. - Added
TypeOfto check field value is a specified type. - See about_PSRule_Assert for details.
- Added
- Added content helpers. #637
- Added
$PSRule.GetContentFirstOrDefaultto get content and return the first object. - Added
$PSRule.GetContentFieldto get the field from content objects. - See about_PSRule_Variables for details.
- Added
- Added assertion helpers. #640
- General improvements:
- Updated
HasJsonSchemaassertion helper. #636- The URI scheme can optionally be ignored for
http://orhttps://URIs. - The fragment
#is ignored. - See about_PSRule_Assert for details.
- The URI scheme can optionally be ignored for
- Added support for
-Outcomeand-Asto produce filtered output fromAssert-PSRule. #643- Configure
Output.AswithSummaryto produce summarized results per object. - Configure
Output.Outcometo limit output toFailorError. - See Assert-PSRule for details.
- Configure
- Updated
- No additional changes.
- General improvements:
- Added support for
-Outcomeand-Asto produce filtered output fromAssert-PSRule. #643- Configure
Output.AswithSummaryto produce summarized results per object. - Configure
Output.Outcometo limit output toFailorError. - See Assert-PSRule for details.
- Configure
- Added support for
- Engine features:
- Added assertion helpers. #640
- Added
NotHasFieldto check object does not have any of the specified fields. - Added
Nullto check field value is null. - Added
NotNullto check field value is not null. - See about_PSRule_Assert for details.
- Added
- Added assertion helpers. #640
- Engine features:
- Added type assertion helpers. #635
- Added
IsNumericto check field value is a numeric types. - Added
IsIntegerto check field value is an integer types. - Added
IsBooleanto check field value is a boolean. - Added
IsArrayto check field value is an array. - Added
IsStringto check field value is a string. - Added
TypeOfto check field value is a specified type. - See about_PSRule_Assert for details.
- Added
- Added content helpers. #637
- Added
$PSRule.GetContentFirstOrDefaultto get content and return the first object. - Added
$PSRule.GetContentFieldto get the field from content objects. - See about_PSRule_Variables for details.
- Added
- Added type assertion helpers. #635
- General improvements:
- Updated
HasJsonSchemaassertion helper. #636- The URI scheme can optionally be ignored for
http://orhttps://URIs. - The fragment
#is ignored. - See about_PSRule_Assert for details.
- The URI scheme can optionally be ignored for
- Updated
- Bug fixes:
- Fixed reason reported fields for
HasFieldandHasFieldsassertion helpers. #632
- Fixed reason reported fields for
- Engineering:
- Bump Manatee.Json dependency to 13.0.5. #619
- Bug fixes:
- Fixed
GetContentprocessing ofInputFileInfo. #625 - Fixed null reference of rule reason with wide output. #626
- Fixed markdown help handling of inline code blocks with
[. #627 - Fixed markdown help inclusion of fenced code blocks in notes and description. #628
- Fixed
- Bug fixes:
- Fixed module source key has already been added. #608
- General improvements:
- Added rule help link in failed
Assert-PSRuleoutput. #595
- Added rule help link in failed
- Engineering:
- Breaking change: Removed deprecated
$Ruleproperties. #495 - Bump Manatee.Json dependency to 13.0.4. #591
- Breaking change: Removed deprecated
- No additional changes.
- General improvements:
- Added rule help link in failed
Assert-PSRuleoutput. #595
- Added rule help link in failed
- Engineering:
- Breaking change: Removed deprecated
$Ruleproperties. #495 - Bump Manatee.Json dependency to 13.0.4. #591
- Breaking change: Removed deprecated
- Several options have been renamed and the old names will be removed in v3. See deprecations for details.
-
Several properties of rule and language block elements will be removed from v3. See deprecations for details.
- Baseline groups allow you to use a friendly name to reference baselines. See baselines for more information.
- Functions within YAML and JSON expressions can be used to perform manipulation prior to testing a condition. See functions for more information.
- Sub-selectors within YAML and JSON expressions can be used to filter rules and list properties. See sub-selectors for more information.
-
Processing of changes files only within a pipeline. See creating your pipeline for more information.
- New features:
- Added sub-selector quantifiers for
allOforanyOfoperators by @BernieWhite. #1423- Quantifiers allow you to specify the number of matches with
count,less,lessOrEqual,greater, orgreaterOrEqual. - See Sub-selectors for more information.
- Quantifiers allow you to specify the number of matches with
- Added support for new functions by @BernieWhite. #1422
- Added support for
padLeft, andpadRight.
- Added support for
- Experimental: Added support for baseline groups by @BernieWhite. #1541
- Baseline groups allow you to reference a baseline by a friendly name.
- Update the baseline group to point to a new baseline.
- Currently only a single baseline can be referenced by a baseline group.
- See baselines for more information.
- Added sub-selector quantifiers for
- General improvements:
- Added style and improved handling for restore command by @BernieWhite. #1152
- Important change: Rename of execution options by @BernieWhite. #1456
- Renamed options allow configuration of output level as
Ignore,Warn,Error, orDebug. Execution.AliasReferenceWarningis replaced withExecution.AliasReference.Execution.InconclusiveWarningis replaced withExecution.RuleInconclusive.Execution.InvariantCultureWarningis replaced withExecution.InvariantCulture.Execution.NotProcessedWarningis replaced withExecution.UnprocessedObject.- Deprecated
AliasReferenceWarningoption, which will be removed in v3. - Deprecated
InconclusiveWarningoption, which will be removed in v3. - Deprecated
InvariantCultureWarningoption, which will be removed in v3. - Deprecated
NotProcessedWarningoption, which will be removed in v3.
- Renamed options allow configuration of output level as
- Improved schema display names by @BernieWhite. #1488
- Engineering:
- Bump Pester to v5.4.1. #1510
- Bump Microsoft.NET.Test.Sdk to v17.6.2. #1544
- Bump Microsoft.CodeAnalysis.Common to v4.6.0. #1534
- Bug fixes:
- Fixed tool output on access denied to path by @BernieWhite. #1490
- Fixed tool exit code on error or failure by @BernieWhite. #1491
- Fixed include local not automatically being enabled for default module baseline by @BernieWhite. #1506
- No additional changes.
- New features:
- Experimental: Added support for baseline groups by @BernieWhite. #1541
- Baseline groups allow you to reference a baseline by a friendly name.
- Update the baseline group to point to a new baseline.
- Currently only a single baseline can be referenced by a baseline group.
- See baselines for more information.
- Experimental: Added support for baseline groups by @BernieWhite. #1541
- General improvements:
- Added style and improved handling for restore command by @BernieWhite. #1152
- Engineering:
- Bump Microsoft.NET.Test.Sdk to v17.6.2. #1544
- Bump Microsoft.CodeAnalysis.Common to v4.6.0. #1534
- Bug fixes:
- Fixed include local not automatically being enabled for default module baseline by @BernieWhite. #1506
- New features:
- Added sub-selector quantifiers for
allOforanyOfoperators by @BernieWhite. #1423- Quantifiers allow you to specify the number of matches with
count,less,lessOrEqual,greater, orgreaterOrEqual. - See Sub-selectors for more information.
- Quantifiers allow you to specify the number of matches with
- Added support for new functions by @BernieWhite. #1422
- Added support for
padLeft, andpadRight.
- Added support for
- Added sub-selector quantifiers for
- General improvements:
- Important change: Rename of execution options by @BernieWhite. #1456
- Renamed options allow configuration of output level as
Ignore,Warn,Error, orDebug. Execution.AliasReferenceWarningis replaced withExecution.AliasReference.Execution.InconclusiveWarningis replaced withExecution.RuleInconclusive.Execution.InvariantCultureWarningis replaced withExecution.InvariantCulture.Execution.NotProcessedWarningis replaced withExecution.UnprocessedObject.- Deprecated
AliasReferenceWarningoption, which will be removed in v3. - Deprecated
InconclusiveWarningoption, which will be removed in v3. - Deprecated
InvariantCultureWarningoption, which will be removed in v3. - Deprecated
NotProcessedWarningoption, which will be removed in v3.
- Renamed options allow configuration of output level as
- Improved schema display names by @BernieWhite. #1488
- Important change: Rename of execution options by @BernieWhite. #1456
- Engineering:
- Bump Pester to v5.4.1. #1510
- Bump Microsoft.CodeAnalysis.Common to v4.5.0. #1455
- Bug fixes:
- Fixed tool output on access denied to path by @BernieWhite. #1490
- Fixed tool exit code on error or failure by @BernieWhite. #1491
- Bug fixes:
- Fixed wrong message for excluded rules by @BernieWhite. #1493
- Fixed job summary reports completed time by @BernieWhite. #1492
- General improvements:
- Important change: Replaced
SuppressedRuleWarningexecution option withRuleSuppressedby @BernieWhite. #1456- Improved options for output of suppressed rules with
RuleSuppressedoption. - Deprecated
SuppressedRuleWarningoption, which will be removed in v3.
- Improved options for output of suppressed rules with
- Added support for logging excluded rules by @BernieWhite. #1432
- Configure
Execution.RuleExcludedto control output level of excluded rules asIgnore,Warn,Error, orDebug.
- Configure
- Added additional options to schema for PSRule for Azure by @BernieWhite. #1446
- Improved error message for failing to read options file by @BernieWhite. #1433
- Added support for import within initialize block by @BernieWhite. #1448
- Added support for direct typing on import by @BernieWhite. #1449
- Use the
$PSRule.ImportWithTypemethod to import an object with a specific type.
- Use the
- Added support for case sensitivity matching with
matchandnotMatchexpressions by @BernieWhite. #1480
- Important change: Replaced
- Engineering:
- Bump Pester to v5.4.0. #1414 Bump Microsoft.CodeAnalysis.Common to v4.4.0. #1341
- Bump BenchmarkDotNet to v0.13.5. #1413
- Bump BenchmarkDotNet.Diagnostics.Windows to v0.13.5. #1413
- Bump Microsoft.NET.Test.Sdk to v17.5.0. #1442
- Bump Newtonsoft.Json to v13.0.3. #1467
- Bump Microsoft.CodeAnalysis.NetAnalyzers to v7.0.1. #1468
- Bug fixes:
- Fixes handling of numerics in tests for that are impacted by regional format by @BernieWhite. #1405
- Fixed no output with using job summary with as summary by @BernieWhite. #1483
- Fixed output and added error for unsupported scenarios.
- Fixed LocalizedData is not exposed to if pre-conditions by @BernieWhite. #1083
- Fixed LocalizedData is not exposed to conventions by @BernieWhite. #1477
- Fixed problem binding when not set locally by @BernieWhite. #1473
- No additional changes.
- General improvements:
- Added support for case sensitivity matching with
matchandnotMatchexpressions by @BernieWhite. #1480
- Added support for case sensitivity matching with
- Bug fixes:
- Fixed no output with using job summary with as summary by @BernieWhite. #1483
- Fixed output and added error for unsupported scenarios.
- Fixed no output with using job summary with as summary by @BernieWhite. #1483
- Bug fixes:
- Fixed LocalizedData is not exposed to if pre-conditions by @BernieWhite. #1083
- Fixed LocalizedData is not exposed to conventions by @BernieWhite. #1477
- Engineering:
- Bump Newtonsoft.Json to v13.0.3. #1467
- Bump Microsoft.CodeAnalysis.NetAnalyzers to v7.0.1. #1468
- Bug fixes:
- Fixed problem binding when not set locally by @BernieWhite. #1473
- General improvements:
- Important change: Replaced
SuppressedRuleWarningexecution option withRuleSuppressedby @BernieWhite. #1456- Improved options for output of suppressed rules with
RuleSuppressedoption. - Deprecated
SuppressedRuleWarningoption, which will be removed in v3.
- Improved options for output of suppressed rules with
- Added support for logging excluded rules by @BernieWhite. #1432
- Added additional options to schema for PSRule for Azure by @BernieWhite. #1446
- Improved error message for failing to read options file by @BernieWhite. #1433
- Added support for import within initialize block by @BernieWhite. #1448
- Added support for direct typing on import by @BernieWhite. #1449
- Use the
$PSRule.ImportWithTypemethod to import an object with a specific type.
- Use the
- Important change: Replaced
- Engineering:
- Bump Pester to v5.4.0. #1414
- Bump Microsoft.CodeAnalysis.NetAnalyzers to v7.0.0. #1374 Bump Microsoft.CodeAnalysis.Common to v4.4.0. #1341
- Bump BenchmarkDotNet to v0.13.5. #1413
- Bump BenchmarkDotNet.Diagnostics.Windows to v0.13.5. #1413
- Bump Microsoft.NET.Test.Sdk to v17.5.0. #1442
- Bug fixes:
- Fixes handling of numerics in tests for that are impacted by regional format by @BernieWhite. #1405
- New features:
- Added API version date comparison assertion method and expression by @BernieWhite. #1356
- Added support for new functions by @BernieWhite. #1227
- Added support for
trim,replace,split,first, andlast.
- Added support for
- General improvements:
- Added support target scope by @BernieWhite. #1350
- Added support for
hasValueexpression withscopeby @BernieWhite. #1382 - Return target object scope as an array by @BernieWhite. #1383
- Improve support of string comparisons to support an array of strings by @BernieWhite. #1384
- Added help properties to rules from YAML/ JSON resources by @BernieWhite. #1386
- Engineering:
- Bump Newtonsoft.Json to v13.0.2. #1358
- Bump System.Drawing.Common to v7.0.0. #1332
- Bump Microsoft.NET.Test.Sdk to v17.4.1. #1389
- Bug fixes:
- Fixed exception with comments in JSON baselines by @BernieWhite. #1336
- Fixed handling of constrained language mode with PowerShell 7.3 by @BernieWhite. #1348
- Fixed exception calling
RuleSourcevalue cannot be null by @BernieWhite. #1343 - Fixed null reference for link property by @BernieWhite. #1393
- Fixed reason are emitted for pre-condition sub-selectors by @BernieWhite. #1394
- Fixed CLI failed to load required assemblies by @BernieWhite. #1361
- Fixed CLI ignores modules specified in
Include.Modulesby @BernieWhite. #1362 - Fixed job summary directory creation by @BernieWhite. #1353
- Fixed same key for ref and name by @BernieWhite #1354
- Fixed object path fails to iterate JSON object with wildcard selector by @BernieWhite. #1376
- Fixed rule annotations are not included from YAML/ JSON definition by @BernieWhite. #1378
- Fixed loop stuck parsing JSON
allOfnotrule condition by @BernieWhite. #1370 - Fixed handling of uint64 with
LessOrEqualassertion method by @BernieWhite. #1366
- No additional changes.
- Bug fixes:
- Fixed null reference for link property by @BernieWhite. #1393
- Fixed reason are emitted for pre-condition sub-selectors by @BernieWhite. #1394
- General improvements:
- Added support for
hasValueexpression withscopeby @BernieWhite. #1382 - Return target object scope as an array by @BernieWhite. #1383
- Improve support of string comparisons to support an array of strings by @BernieWhite. #1384
- Added help properties to rules from YAML/ JSON resources by @BernieWhite. #1386
- Added support for
- Engineering:
- Bump Newtonsoft.Json to v13.0.2. #1358
- Bump System.Drawing.Common to v7.0.0. #1332
- Bump Microsoft.NET.Test.Sdk to v17.4.1. #1389
- Bug fixes:
- Fixed object path fails to iterate JSON object with wildcard selector by @BernieWhite. #1376
- Fixed rule annotations are not included from YAML/ JSON definition by @BernieWhite. #1378
- Bug fixes:
- Fixed loop stuck parsing JSON
allOfnotrule condition by @BernieWhite. #1370 - Fixed handling of uint64 with
LessOrEqualassertion method by @BernieWhite. #1366
- Fixed loop stuck parsing JSON
- New features:
- Added API version date comparison assertion method and expression by @BernieWhite. #1356
- Added support for new functions by @BernieWhite. #1227
- Added support for
trim,replace,split,first, andlast.
- Added support for
- Bug fixes:
- Fixed CLI failed to load required assemblies by @BernieWhite. #1361
- Fixed CLI ignores modules specified in
Include.Modulesby @BernieWhite. #1362
- Bug fixes:
- Fixed job summary directory creation by @BernieWhite. #1353
- Fixed same key for ref and name by @BernieWhite #1354
- General improvements:
- Added support target scope by @BernieWhite. #1350
- Bug fixes:
- Fixed exception with comments in JSON baselines by @BernieWhite. #1336
- Fixed handling of constrained language mode with PowerShell 7.3 by @BernieWhite. #1348
- Bug fixes:
- Fixed exception calling
RuleSourcevalue cannot be null by @BernieWhite. #1343
- Fixed exception calling
- New features:
- Added support for generating job summaries by @BernieWhite. #1264
- Job summaries provide a markdown output for pipelines in addition to other supported output formats.
- To use, configure the
Output.JobSummaryPathoption.
- Added support for time bound suppression groups by @BernieWhite. #1335
- Suppression groups can be configured to expire after a specified time by setting the
spec.expiresOnproperty. - When a suppression group expires, the suppression group will generate a warning by default.
- Configure the
Execution.SuppressionGroupExpiredoption to ignore or error on expired suppression groups.
- Suppression groups can be configured to expire after a specified time by setting the
- Added support for generating job summaries by @BernieWhite. #1264
- Engineering:
- Bump Microsoft.NET.Test.Sdk to v17.4.0. #1331
- Bump PSScriptAnalyzer to v1.21.0. #1318
- Class clean up and documentation by @BernieWhite. #1186
- No additional changes.
- New features:
- Added support for generating job summaries by @BernieWhite. #1264
- Job summaries provide a markdown output for pipelines in addition to other supported output formats.
- To use, configure the
Output.JobSummaryPathoption.
- Added support for time bound suppression groups by @BernieWhite. #1335
- Suppression groups can be configured to expire after a specified time by setting the
spec.expiresOnproperty. - When a suppression group expires, the suppression group will generate a warning by default.
- Configure the
Execution.SuppressionGroupExpiredoption to ignore or error on expired suppression groups.
- Suppression groups can be configured to expire after a specified time by setting the
- Added support for generating job summaries by @BernieWhite. #1264
- Engineering:
- Bump Microsoft.NET.Test.Sdk to v17.4.0. #1331
- Engineering:
- Bump Microsoft.NET.Test.Sdk to v17.3.2. #1283
- Bump PSScriptAnalyzer to v1.21.0. #1318
- Class clean up and documentation by @BernieWhite. #1186
- Bug fixes:
- Fixed incorrect XML header for encoding by @BernieWhite. #1322
- Bug fixes:
- Fixed NUnit output does not escape characters in all result properties by @BernieWhite. #1316
- Bug fixes:
- Fixed
Inwith array source object and dot object path by @BernieWhite. #1314
- Fixed
- New features:
- Experimental: Added support for only processing changed files by @BernieWhite. #688
- To ignore unchanged files, set the
Input.IgnoreUnchangedPathoption totrue. - See creating your pipeline for more information.
- To ignore unchanged files, set the
- Experimental: Added support for only processing changed files by @BernieWhite. #688
- General improvements:
- Added labels metadata from grouping and filtering rules by @BernieWhite. #1272
- Labels are metadata that extends on tags to provide a more structured way to group rules.
- Rules can be classified by setting the
metadata.labelsproperty or-Labelsparameter.
- Provide unblock for command line tools by @BernieWhite. #1261
- Added labels metadata from grouping and filtering rules by @BernieWhite. #1272
- Engineering:
- Bump Microsoft.NET.Test.Sdk to v17.3.1. #1248
- Bug fixes:
- Fixed could not load Microsoft.Management.Infrastructure by @BernieWhite. #1249
- To use minimal initial session state set
Execution.InitialSessionStatetoMinimal.
- To use minimal initial session state set
- Fixed unhandled exception with GetRootedPath by @BernieWhite. #1251
- Fixed Dockerfile case sensitivity by @BernieWhite. #1269
- Fixed could not load Microsoft.Management.Infrastructure by @BernieWhite. #1249
- No additional changes.
- Bug fixes:
- Fixed exception with
PathExpressionBuilder.GetAllRecurseby @BernieWhite. #1301
- Fixed exception with
- New features:
- Experimental: Added support for only processing changed files by @BernieWhite. #688
- To ignore unchanged files, set the
Input.IgnoreUnchangedPathoption totrue. - See creating your pipeline for more information.
- To ignore unchanged files, set the
- Experimental: Added support for only processing changed files by @BernieWhite. #688
- General improvements:
- Added labels metadata from grouping and filtering rules by @BernieWhite. #1272
- Labels are metadata that extends on tags to provide a more structured way to group rules.
- Rules can be classified by setting the
metadata.labelsproperty or-Labelsparameter.
- Added labels metadata from grouping and filtering rules by @BernieWhite. #1272
- Bug fixes:
- Fixed Dockerfile case sensitivity by @BernieWhite. #1269
- Fixed markdown parsing of Spanish translated help fails by @BernieWhite @jonathanruiz. #1286 #1285
- General improvements:
- Provide unblock for command line tools by @BernieWhite. #1261
- Engineering:
- Bump Microsoft.NET.Test.Sdk to v17.3.1. #1248
- Bug fixes:
- Fixed could not load Microsoft.Management.Infrastructure by @BernieWhite. #1249
- To use minimal initial session state set
Execution.InitialSessionStatetoMinimal.
- To use minimal initial session state set
- Fixed unhandled exception with GetRootedPath by @BernieWhite. #1251
- Fixed could not load Microsoft.Management.Infrastructure by @BernieWhite. #1249
- Bug fixes:
- Fixed exception with
PathExpressionBuilder.GetAllRecurseby @BernieWhite. #1301
- Fixed exception with
- Bug fixes:
- Fixed markdown parsing of Spanish translated help fails by @BernieWhite @jonathanruiz. #1286 #1285
- New features:
- Experimental: Added support for functions within YAML and JSON expressions by @BernieWhite. #1227 #1016
- Added conversion functions
boolean,string, andinteger. - Added lookup functions
configuration, andpath. - Added string functions
concat,substring. - See functions for more information.
- Added conversion functions
- Experimental: Added support for sub-selector YAML and JSON expressions by @BernieWhite. #1024 #1045
- Sub-selector pre-conditions add an additional expression to determine if a rule is executed.
- Sub-selector object filters provide an way to filter items from list properties.
- See sub-selectors for more information.
- Experimental: Added support for functions within YAML and JSON expressions by @BernieWhite. #1227 #1016
- Engineering:
- Improvements to PSRule engine API documentation by @BernieWhite. #1186
- Updates to PSRule engine API by @BernieWhite. #1152
- Added tool support for baselines parameter.
- Added module path discovery.
- Added output for verbose and debug messages.
- Bump support projects to .NET 6 by @BernieWhite. #1209
- Bump Microsoft.NET.Test.Sdk to v17.3.0. #1213
- Bump BenchmarkDotNet to v0.13.2. #1241
- Bump BenchmarkDotNet.Diagnostics.Windows to v0.13.2. #1242
- Bug fixes:
- Fixed reporting of duplicate identifiers which were not generating an error for all cases by @BernieWhite. #1229
- Added
Execution.DuplicateResourceIdoption to configure PSRule behaviour. - By default, duplicate resource identifiers return an error.
- Added
- Fixed exception on JSON baseline without a synopsis by @BernieWhite. #1230
- Fixed repository information not in output by @BernieWhite. #1219
- Fixed reporting of duplicate identifiers which were not generating an error for all cases by @BernieWhite. #1229
- No additional changes.
- Engineering:
- Bump BenchmarkDotNet to v0.13.2. #1241
- Bump BenchmarkDotNet.Diagnostics.Windows to v0.13.2. #1242
- New features:
- Experimental: Added support for sub-selector YAML and JSON expressions by @BernieWhite. #1024 #1045
- Sub-selector pre-conditions add an additional expression to determine if a rule is executed.
- Sub-selector object filters provide an way to filter items from list properties.
- See sub-selectors for more information.
- Experimental: Added support for sub-selector YAML and JSON expressions by @BernieWhite. #1024 #1045
- Engineering:
- Improvements to PSRule engine API documentation by @BernieWhite. #1186
- New features:
- Experimental: Added support for functions within YAML and JSON expressions by @BernieWhite. #1227 #1016
- Added conversion functions
boolean,string, andinteger. - Added lookup functions
configuration, andpath. - Added string functions
concat,substring. - See functions for more information.
- Added conversion functions
- Experimental: Added support for functions within YAML and JSON expressions by @BernieWhite. #1227 #1016
- Bug fixes:
- Fixed reporting of duplicate identifiers which were not generating an error for all cases by @BernieWhite. #1229
- Added
Execution.DuplicateResourceIdoption to configure PSRule behaviour. - By default, duplicate resource identifiers return an error.
- Added
- Fixed exception on JSON baseline without a synopsis by @BernieWhite. #1230
- Fixed reporting of duplicate identifiers which were not generating an error for all cases by @BernieWhite. #1229
- Engineering:
- Updates to PSRule engine API by @BernieWhite. #1152
- Added tool support for baselines parameter.
- Added module path discovery.
- Added output for verbose and debug messages.
- Updates to PSRule engine API by @BernieWhite. #1152
- Engineering:
- Bump support projects to .NET 6 by @BernieWhite. #1209
- Bump Microsoft.NET.Test.Sdk to v17.3.0. #1213
- Bug fixes:
- Fixed repository information not in output by @BernieWhite. #1219
- Bug fixes:
- Fixes lost scope for rules by @BernieWhite. #1214
- Bug fixes:
- Fixed object path join handling of self path identifier by @BernieWhite. #1204
- General improvements:
- Added
PathPrefixmethod to add an object path prefix to assertion reasons by @BernieWhite. #1198 - Added support for binding with JSON objects by @BernieWhite. #1182
- Added support for full path from JSON objects by @BernieWhite. #1174
- Improved reporting of full object path from pre-processed results by @BernieWhite. #1169
- Added PSRule for Azure expansion configuration to options schema by @BernieWhite. #1149
- Added
- Engineering:
- Bump xunit to v2.4.2. #1200
- Expose online link extension method by @BernieWhite. #1195
- Added comment documentation to .NET classes and interfaces by @BernieWhite. #1186
- Added publishing support for NuGet symbol packages @BernieWhite. #1173
- Updated outcome option docs by @BernieWhite. #1166
- Bump Sarif.Sdk to v2.4.16. #1177
- Refactoring and updates to interfaces to allow use outside of PowerShell by @BernieWhite. #1152
- Bug fixes:
- Fixes JSON parsing of string array for single objects by @BernieWhite. #1193
- Fixed handling for JSON objects in rules by @BernieWhite. #1187
- Fixed null object reference for object equity comparison by @BernieWhite. #1157
- Fixed expression evaluation not logging debug output when using the
-Debugswitch by @BernieWhite. #1158 - Fixed startIndex cannot be larger than length of string by @BernieWhite. #1160
- Fixed path within SDK package causes
psd1to compile by @BernieWhite. #1146
- No additional changes.
- General improvements:
- Added
PathPrefixmethod to add an object path prefix to assertion reasons by @BernieWhite. #1198
- Added
- Engineering:
- Bump xunit to v2.4.2. #1200
- Engineering:
- Expose online link extension method by @BernieWhite. #1195
- Bug fixes:
- Fixes JSON parsing of string array for single objects by @BernieWhite. #1193
- Engineering:
- Added comment documentation to .NET classes and interfaces by @BernieWhite. #1186
- Bug fixes:
- Fixed handling for JSON objects in rules by @BernieWhite. #1187
- General improvements:
- Added support for binding with JSON objects by @BernieWhite. #1182
- General improvements:
- Added support for full path from JSON objects by @BernieWhite. #1174
- Engineering:
- Added publishing support for NuGet symbol packages @BernieWhite. #1173
- Updated outcome option docs by @BernieWhite. #1166
- Bump Sarif.Sdk to v2.4.16. #1177
- General improvements:
- Improved reporting of full object path from pre-processed results by @BernieWhite. #1169
- Bug fixes:
- Fixed null object reference for object equity comparison by @BernieWhite. #1157
- Fixed expression evaluation not logging debug output when using the
-Debugswitch by @BernieWhite. #1158 - Fixed startIndex cannot be larger than length of string by @BernieWhite. #1160
- General improvements:
- Added PSRule for Azure expansion configuration to options schema by @BernieWhite. #1149
- Engineering:
- Refactoring and updates to interfaces to allow use outside of PowerShell by @BernieWhite. #1152
- Bug fixes:
- Fixed path within SDK package causes
psd1to compile by @BernieWhite. #1146
- Fixed path within SDK package causes
- New features:
- Added
notCountexpression and assertion helper by @ArmaanMcleod. #1091
- Added
- General improvements:
- Improved reporting of the object path that caused rule failures by @BernieWhite. #1092
- Output include a new
Detailproperty with details of the reason and the object path. - Custom methods
ReasonFromandReasonIfaccept apathparameter to specify the object path.
- Output include a new
- Added informational message when output has been written to disk by @BernieWhite. #1074
- The
Output.Footeroption now supportsOutputFilewhich reports the output file path. This is enabled by default.
- The
- Added descendant selector to object path syntax by @BernieWhite. #1133
- Use
..to traverse into child objects, for example$..namefinds names for all nested objects.
- Use
- Improved reporting of the object path that caused rule failures by @BernieWhite. #1092
- Engineering:
- Bump Newtonsoft.Json to 13.0.1. #1137
- Added more object path tests by @ArmaanMcleod. #1110
- Bump xunit.runner.visualstudio to 2.4.5. #1084
- Bump Pester to 5.3.3. #1079
- Bump Microsoft.NET.Test.Sdk to 17.2.0. #1089
- Added NuGet packaging publishing by @BernieWhite. #1093
- Updated NuGet packaging metadata by @BernieWhite. #1093
- Bug fixes:
- Fixed output of reason with wide format by @BernieWhite. #1117
- Fixed piped input does not respect excluded paths by @BernieWhite. #1114
- By default, objects are not excluded by source.
- To exclude piped input based on source configure the
Input.IgnoreObjectSourceoption.
- Fixed issue building a PSRule project by removing PSRule.psd1 from compile target by @BernieWhite. #1140
- Fixed grouping of logical operators in object path by @BernieWhite. #1101
- No additional changes.
- Bug fixes:
- Fixed issue building a PSRule project by removing PSRule.psd1 from compile target by @BernieWhite. #1140
- General improvements:
- Added descendant selector to object path syntax by @BernieWhite. #1133
- Use
..to traverse into child objects, for example$..namefinds names for all nested objects.
- Use
- Added descendant selector to object path syntax by @BernieWhite. #1133
- Engineering:
- Bump Newtonsoft.Json to 13.0.1. #1137
- General improvements:
- Improved reporting of the object path that caused rule failures by @BernieWhite. #1092
- Output include a new
Detailproperty with details of the reason and the object path. - Custom methods
ReasonFromandReasonIfaccept apathparameter to specify the object path.
- Output include a new
- Improved reporting of the object path that caused rule failures by @BernieWhite. #1092
- General improvements:
- Added informational message when output has been written to disk by @BernieWhite. #1074
- The
Output.Footeroption now supportsOutputFilewhich reports the output file path. This is enabled by default.
- The
- Added informational message when output has been written to disk by @BernieWhite. #1074
- Engineering:
- Added more object path tests by @ArmaanMcleod. #1110
- Bug fixes:
- Fixed output of reason with wide format by @BernieWhite. #1117
- Fixed piped input does not respect excluded paths by @BernieWhite. #1114
- By default, objects are not excluded by source.
- To exclude piped input based on source configure the
Input.IgnoreObjectSourceoption.
- New features:
- Added
notCountexpression and assertion helper by @ArmaanMcleod. #1091
- Added
- Engineering:
- Bump xunit.runner.visualstudio to 2.4.5. #1084
- Bump Pester to 5.3.3. #1079
- Bump Microsoft.NET.Test.Sdk to 17.2.0. #1089
- Added NuGet packaging publishing by @BernieWhite. #1093
- Updated NuGet packaging metadata by @BernieWhite. #1093
- Bug fixes:
- Fixed grouping of logical operators in object path by @BernieWhite. #1101
- General improvements:
- Added
notStartsWith,notEndsWith, andnotContainsexpressions and assertion helpers. #1047 - Added
like,notLikeexpressions and assertion helpers. #1048 - Added additional repository paths to ignore by default. #1043
- Added custom suppression message during PSRule runs. #1046
- When a rule is suppressed using a suppression group the synopsis is shown in the suppression warning.
- Configure the suppression group synopsis to display a custom message.
- Suppression groups synopsis can be localized using markdown documentation.
- Use markdown to set a culture specific synopsis.
- Custom suppression messages are not supported when suppressing individual rules using
ps-rule.yaml. - See about_PSRule_SuppressionGroups for details.
- Added source support for string conditions. #1068
- Added
- Engineering:
- Added code signing of module. #1049
- Added SBOM manifests to module. #1050
- Bump Sarif.Sdk to 2.4.15. #1075
- Bump Pester to 5.3.2. #1062
- Bug fixes:
- Important change: Fixed source scope not updated in multi-module runs. #1053
- Several properties of rule and language block elements have been renamed to improve consistency.
- From v3 custom scripts may not work correctly until you update these names.
- For details on the updated property names see deprecations.
- Important change: Fixed source scope not updated in multi-module runs. #1053
- No additional changes.
- General improvements:
- Added
notStartsWith,notEndsWith, andnotContainsexpressions and assertion helpers. #1047 - Added
like,notLikeexpressions and assertion helpers. #1048 - Added additional repository paths to ignore by default. #1043
- Added
- Engineering:
- Bump Sarif.Sdk to 2.4.15. #1075
- General improvements:
- Added custom suppression message during PSRule runs. #1046
- When a rule is suppressed using a suppression group the synopsis is shown in the suppression warning.
- Configure the suppression group synopsis to display a custom message.
- Suppression groups synopsis can be localized using markdown documentation.
- Use markdown to set a culture specific synopsis.
- Custom suppression messages are not supported when suppressing individual rules using
ps-rule.yaml. - See about_PSRule_SuppressionGroups for details.
- Added source support for string conditions. #1068
- Added custom suppression message during PSRule runs. #1046
- Engineering:
- Bump Sarif.Sdk to 2.4.14. #1064
- Bump Pester to 5.3.2. #1062
- Bug fixes:
- Important change: Fixed source scope not updated in multi-module runs. #1053
- Several properties of rule and language block elements have been renamed to improve consistency.
- From v3 custom scripts may not work correctly until you update these names.
- For details on the updated property names see deprecations.
- Important change: Fixed source scope not updated in multi-module runs. #1053
- Engineering:
- Added code signing of module. #1049
- Added SBOM manifests to module. #1050
- Bug fixes:
- Fixed read JSON failed with comments. #1051
- Fixed null reference on elapsed time when required module check fails. #1054
- Fixed failed to read JSON objects with a empty property name. #1052
- New features:
- Add support for suppression groups. #793
- New
SuppressionGroupresource has been included. - See about_PSRule_SuppressionGroups for details.
- New
- Added source expression property. #933
- Included the following expressions:
sourcewithinPathnotWithinPath
- Included the following expressions:
- Added support for rule severity level. #880
- Rules can be configured to be
Error,Warning, orInformation. - Failing rules with the
Errorseverity level will cause the pipeline to fail. - Rules with the
Warningseverity level will be reported as warnings. - Rules with the
Informationseverity level will be reported as informational messages. - By default, the severity level for a rule is
Error.
- Rules can be configured to be
- Added expression support for type based assertions. #908
- Included the following expressions:
IsArrayIsBooleanIsDateTimeIsIntegerIsNumeric
- Included the following expressions:
- Added support for formatting results as SARIF. #878
- Set
Output.FormattoSarifto output results in the SARIF format. - See about_PSRule_Options for details.
- Set
- Add support for suppression groups. #793
- General improvements:
- Add option to disable invariant culture warning. #899
- Added
Execution.InvariantCultureWarningoption. - See about_PSRule_Options for details.
- Added
- Added support for object path expressions. #808 #693
- Inspired by JSONPath, object path expressions can be used to access nested objects.
- Array members can be filtered and enumerated using object path expressions.
- Object path expressions can be used in YAML, JSON, and PowerShell rules and selectors.
- See about_PSRule_Assert for details.
- Improve tracking of suppressed objects. #794
- Added
Execution.SuppressedRuleWarningoption to output warning for suppressed rules.
- Added
- Added support for rule aliases. #792
- Aliases allow rules to be references by an alternative name.
- When renaming rules, add a rule alias to avoid breaking references to the old rule name.
- To specify an alias use the
-Aliasparameter oraliasmetadata property in YAML or JSON.
- Added support for stable identifiers with rule refs. #881
- A rule ref may be optionally be used to reference a rule.
- Rule refs should be: stable, not changing between releases; opaque, as opposed to being a human-readable string. Stable and opaque refs ease web lookup and to help to avoid language difficulties.
- To specify a rule ref use the
-Refparameter orrefmetadata property in YAML or JSON.
- Added new properties for module lookup to SARIF results. #951
- Capture and output repository info in Assert-PSRule runs. #978
- Added
Repository.Urloption set repository URL reported in output. - Repository URL is detected automatically for GitHub Actions and Azure Pipelines.
- Added
RepositoryInfotoOutput.Banneroption. - Repository info is shown by default.
- Added
- Added
convertandcaseSensitiveto string comparison expressions. #1001- The following expressions support type conversion and case-sensitive comparison.
startsWith,contains, andendsWith.equalsandnotEquals.
- The following expressions support type conversion and case-sensitive comparison.
- Added
convertto numeric comparison expressions. #943- Type conversion is now supported for
less,lessOrEquals,greater, andgreaterOrEquals.
- Type conversion is now supported for
- Added
Extentproperty on rules reported byGet-PSRule. #990- Extent provides the line and position of the rule in the source code.
- Breaking change: Added validation of resource names. #1012
- Invalid rules names will now produce a specific error.
- See upgrade notes for more information.
- Add option to disable invariant culture warning. #899
- Engineering:
- Breaking change: Removal of deprecated default baseline from module manifest. #755
- Set the default module baseline using module configuration.
- See upgrade notes for details.
- Breaking change: Require
apiVersionon YAML and JSON to be specified. #648- Resources should use
github.com/microsoft/PSRule/v1as theapiVersion. - Resources that do not specify an
apiVersionwill be ignored. - See upgrade notes for details.
- Resources should use
- Breaking change: Prefer module sources over loose files. #610
- Module sources are discovered before loose files.
- Warning is shown for duplicate rule names, and exception is thrown for duplicate rule Ids.
- See upgrade notes for details.
- Breaking change: Require rule sources from current working directory to be explicitly included. #760
- From v2 onwards,
$PWDis not included by default unless-Path .or-Path $PWDis explicitly specified. - See upgrade notes for details.
- From v2 onwards,
- Added more tests for JSON resources. #929
- Bump Sarif.Sdk to 2.4.13. #1007
- Bump PowerShellStandard.Library to 5.1.1. #999
- Breaking change: Removal of deprecated default baseline from module manifest. #755
- Bug fixes:
- Fixed object path handling with dash. #902
- Fixed empty suppression group rules property applies to no rules. #931
- Fixed object reference for suppression group will rule not defined. #932
- Fixed rule source loading twice from
$PWDand.ps-rule/. #939 - Fixed rule references in SARIF format for extensions need a toolComponent reference. #949
- Fixed file objects processed with file input format have no source location. #950
- Fixed GitHub code scanning alerts treats pass as problems. #955
- By default, SARIF output will only include fail or error outcomes.
- Added
Output.SarifProblemsOnlyoption to include pass outcomes.
- Fixed SARIF output includes rule property for default tool component. #956
- Fixed Invoke-PSRule hanging if JSON rule file is empty. #969
- Fixed SARIF should report base branch. #964
- Fixed unclear error message on invalid rule names. #1012
- No additional changes.
- General improvements:
- Added
convertto numeric comparison expressions. #943- Type conversion is now supported for
less,lessOrEquals,greater, andgreaterOrEquals.
- Type conversion is now supported for
- Breaking change: Added validation of resource names. #1012
- Invalid rules names will now produce a specific error.
- See upgrade notes for more information.
- Added
- Bug fixes:
- Fixed unclear error message on invalid rule names. #1012
- General improvements:
- Added
Extentproperty on rules reported byGet-PSRule. #990- Extent provides the line and position of the rule in the source code.
- Added
- Engineering:
- Bump Sarif.Sdk to 2.4.13. #1007
- Bump PowerShellStandard.Library to 5.1.1. #999
- General improvements:
- Added
convertandcaseSensitiveto string comparison expressions. #1001- The following expressions support type conversion and case-sensitive comparison.
startsWith,contains, andendsWith.equalsandnotEquals.
- The following expressions support type conversion and case-sensitive comparison.
- Added
- General improvements:
- Capture and output repository info in Assert-PSRule runs. #978
- Added
Repository.Urloption set repository URL reported in output. - Repository URL is detected automatically for GitHub Actions and Azure Pipelines.
- Added
RepositoryInfotoOutput.Banneroption. - Repository info is shown by default.
- Added
- Capture and output repository info in Assert-PSRule runs. #978
- Bug fixes:
- Fixed SARIF should report base branch. #964
- Bug fixes:
- Fixed broken documentation links. #980
- Bug fixes:
- Fixed Invoke-PSRule hanging if JSON rule file is empty. #969
- New features:
- Added source expression property. #933
- Included the following expressions:
sourcewithinPathnotWithinPath
- Included the following expressions:
- Added source expression property. #933
- Bug fixes:
- Fixed GitHub code scanning alerts treats pass as problems. #955
- By default, SARIF output will only include fail or error outcomes.
- Added
Output.SarifProblemsOnlyoption to include pass outcomes.
- Fixed SARIF output includes rule property for default tool component. #956
- Fixed GitHub code scanning alerts treats pass as problems. #955
- General improvements:
- Added new properties for module lookup to SARIF results. #951
- Bug fixes:
- Fixed rule references in SARIF format for extensions need a toolComponent reference. #949
- Fixed file objects processed with file input format have no source location. #950
- New features:
- Added support for rule severity level. #880
- Rules can be configured to be
Error,Warning, orInformation. - Failing rules with the
Errorseverity level will cause the pipeline to fail. - Rules with the
Warningseverity level will be reported as warnings. - Rules with the
Informationseverity level will be reported as informational messages. - By default, the severity level for a rule is
Error.
- Rules can be configured to be
- Added expression support for type based assertions. #908
- Included the following expressions:
IsArrayIsBooleanIsDateTimeIsIntegerIsNumeric
- Included the following expressions:
- Added support for formatting results as SARIF. #878
- Set
Output.FormattoSarifto output results in the SARIF format. - See about_PSRule_Options for details.
- Set
- Added support for rule severity level. #880
- Engineering:
- Breaking change: Require rule sources from current working directory to be explicitly included. #760
- From v2 onwards,
$PWDis not included by default unless-Path .or-Path $PWDis explicitly specified. - See upgrade notes for details.
- From v2 onwards,
- Breaking change: Require rule sources from current working directory to be explicitly included. #760
- Bug fixes:
- Fixed rule source loading twice from
$PWDand.ps-rule/. #939
- Fixed rule source loading twice from
- Engineering:
- Breaking change: Prefer module sources over loose files. #610
- Module sources are discovered before loose files.
- Warning is shown for duplicate rule names, and exception is thrown for duplicate rule Ids.
- See upgrade notes for details.
- Added more tests for JSON resources. #929
- Breaking change: Prefer module sources over loose files. #610
- Bug fixes:
- Fixed empty suppression group rules property applies to no rules. #931
- Fixed object reference for suppression group will rule not defined. #932
- General improvements:
- Add option to disable invariant culture warning. #899
- Added
Execution.InvariantCultureWarningoption. - See about_PSRule_Options for details.
- Added
- Add option to disable invariant culture warning. #899
- New features:
- Add support for suppression groups. #793
- New
SuppressionGroupresource has been included. - See about_PSRule_SuppressionGroups for details.
- New
- Add support for suppression groups. #793
- General improvements:
- Added support for rule aliases. #792
- Aliases allow rules to be references by an alternative name.
- When renaming rules, add a rule alias to avoid breaking references to the old rule name.
- To specify an alias use the
-Aliasparameter oraliasmetadata property in YAML or JSON.
- Added support for stable identifiers with rule refs. #881
- A rule ref may be optionally be used to reference a rule.
- Rule refs should be: stable, not changing between releases; opaque, as opposed to being a human-readable string. Stable and opaque refs ease web lookup and to help to avoid language difficulties.
- To specify a rule ref use the
-Refparameter orrefmetadata property in YAML or JSON.
- Added support for rule aliases. #792
- Bug fixes:
- Fixed object path handling with dash. #902
- General improvements:
- Added support for object path expressions. #808 #693
- Inspired by JSONPath, object path expressions can be used to access nested objects.
- Array members can be filtered and enumerated using object path expressions.
- Object path expressions can be used in YAML, JSON, and PowerShell rules and selectors.
- See about_PSRule_Assert for details.
- Improve tracking of suppressed objects. #794
- Added
Execution.SuppressedRuleWarningoption to output warning for suppressed rules.
- Added
- Added support for object path expressions. #808 #693
- Engineering:
- Breaking change: Removal of deprecated default baseline from module manifest. #755
- Set the default module baseline using module configuration.
- See upgrade notes for details.
- Breaking change: Require
apiVersionon YAML and JSON to be specified. #648- Resources should use
github.com/microsoft/PSRule/v1as theapiVersion. - Resources that do not specify an
apiVersionwill be ignored. - See upgrade notes for details.
- Resources should use
- Breaking change: Removal of deprecated default baseline from module manifest. #755
- Baseline groups allow you to use a friendly name to reference baselines. See baselines for more information.
- Functions within YAML and JSON expressions can be used to perform manipulation prior to testing a condition. See functions for more information.
- Sub-selectors within YAML and JSON expressions can be used to filter rules and list properties. See sub-selectors for more information.
-
Processing of changes files only within a pipeline. See creating your pipeline for more information.
- Engineering:
- Bump System.Drawing.Common to v8.0.4. #1790
- Bump Bump xunit to v2.7.1. #1793
- Bump xunit.runner.visualstudio to v2.5.8. #1792
- Bump YamlDotNet to v15.1.2. #1771
- Bump Microsoft.CodeAnalysis.Common to v4.9.2. #1773
- Bug fixes:
- Fixed discovery of installed modules in CLI by @BernieWhite. #1779
- Bug fixes:
- Fixes null references for CLI module handling by @BernieWhite. #1746
- General improvements:
- Improved support for packaging with Visual Studio Code by @BernieWhite. #1755
- Engineering:
- Breaking change: Bump development tools to .NET 8.0 SDK by @BernieWhite. #1673
- Running PSRule from PowerShell 7.x is supported on 7.4 and above.
- Running PSRule from Windows PowerShell 5.1 is still supported but deprecated and will be removed in PSRule v4.
- Bump Microsoft.NET.Test.Sdk to v17.9.0. #1752
- Breaking change: Bump development tools to .NET 8.0 SDK by @BernieWhite. #1673
- Bug fixes:
- Fixed CLI null reference when include module is undefined by @BernieWhite. #1746
- General improvements:
- SARIF output has been improved to include effective configuration from a run by @BernieWhite. #1739
- SARIF output has been improved to include file hashes for source files from a run by @BernieWhite. #1740
- Added support to allow disabling PowerShell features that can be run from a repository by @BernieWhite. #1742
- Added the
Execution.RestrictScriptSourceoption to disable running scripts from a repository.
- Added the
- Engineering:
- Bump YamlDotNet to v15.1.0. #1737
- General improvements:
- Breaking change: Moved the
restorecommand to a sub-command ofmoduleby @BernieWhite. #1730- The functionality of the
restorecommand is now available asmodule restore.
- The functionality of the
- Added CLI commands to list and report status of locked modules by @BernieWhite. #1729
- Added
module initsub-command to initialize the lock file from configured options. - Added
module listsub-command to list locked and unlocked modules associated with the workspace. - Added
versionproperty to the lock file schema to support versioning of the lock file.
- Added
- Breaking change: Moved the
- Engineering:
- Bump BenchmarkDotNet to v0.13.12. #1725
- Bump BenchmarkDotNet.Diagnostics.Windows to v0.13.12. #1728
- Bump xunit to v2.6.6. #1732
- Bump xunit.runner.visualstudio to v2.5.6. #1717
- Bump System.Drawing.Common to v8.0.1. #1727
- General improvements:
- Breaking change: Renamed
analyzeCLI command torunby @BernieWhite. #1713 - Added
--outcomeargument for CLI to support filtering output by @bernieWhite. #1706
- Breaking change: Renamed
- Engineering:
- Bump xunit to v2.6.3. #1699
- Bump xunit.runner.visualstudio to v2.5.5. #1700
- Bump Microsoft.NET.Test.Sdk to v17.8.0. #1659
- Bump Microsoft.CodeAnalysis.NetAnalyzers to v8.0.0. #1674
- Bump Microsoft.CodeAnalysis.Common to v4.8.0. #1686
- Bump BenchmarkDotNet to v0.13.11. #1694
- Bump BenchmarkDotNet.Diagnostics.Windows to v0.13.11. #1697
- Engineering:
- Bump xunit to v2.6.1. #1656
- Bump System.Drawing.Common to v8.0.0. #1669
- Bug fixes:
- Fixed CLI IndexOutOfRangeException with lock file by @BernieWhite. #1676
- New features:
- Added lock file support when using CLI and related tools by @BernieWhite. #1660
- The lock file used used during analysis and when installing modules to select a specific version.
- Added lock file support when using CLI and related tools by @BernieWhite. #1660
- General improvements:
- Breaking change: Switch to use SHA-512 for generating unbound objects by @BernieWhite. #1155
- Objects that have no bound name will automatically be assigned a name based on the SHA-512 hash of the object.
- Previously a SHA-1 hash was used, however this is no longer considered secure.
- The name for unbound objects that are suppressed will change as a result.
- Additionally the hash can be changed by setting the
Execution.HashAlgorithmoption. - See upgrade notes for details.
- Breaking change: Removed deprecated execution options by @BernieWhite. #1457
- Breaking change: Removed deprecated object properties by @BernieWhite. #1601
- Expanded support for
FileHeaderassertion by @BernieWhite. #1521- Added support for
.bicepparam,.tsp,.tsx,.editorconfig,.ipynb, and.tomlfiles.
- Added support for
- Breaking change: Switch to use SHA-512 for generating unbound objects by @BernieWhite. #1155
- Engineering:
- Breaking change: Bump development tools to .NET 7.0 SDK by @BernieWhite. #1631
- Running PSRule from PowerShell 7.x is supported on 7.3 and above.
- Running PSRule from Windows PowerShell 5.1 is still supported but deprecated and will be removed in PSRule v4.
- Bump Microsoft.CodeAnalysis.NetAnalyzers to v7.0.4. #1602
- Bump Microsoft.CodeAnalysis.Common to v4.7.0. #1593
- Bump Microsoft.NET.Test.Sdk to v17.7.2. #1608
- Bump YamlDotNet to v13.7.1. #1647
- Bump xunit to v2.5.3. #1648
- Bump xunit.runner.visualstudio to v2.5.3. #1644
- Bump BenchmarkDotNet to v0.13.10. #1654
- Bump BenchmarkDotNet.Diagnostics.Windows to v0.13.10. #1654
- Breaking change: Bump development tools to .NET 7.0 SDK by @BernieWhite. #1631
- Reuse and share \u2014 existing pre-built rules, configure, or write your own.
- Incremental adoption \u2014 with baselines allows you to keep moving forward.
- Handle exceptions \u2014 and keep exceptions auditable in git history.
- Documentation \u2014 provides recommendations and examples instead of just pass or fail.
Yaml- Output is serialized as YAML.Json- Output is serialized as JSON.Markdown- Output is serialized as Markdown.NUnit3- Output is serialized as NUnit3 (XML).Csv- Output is serialized as a comma-separated values (CSV).Sarif- Output is serialized as SARIF.- Create a GitHub Actions workflow.
- Add a step using the
microsoft/ps-ruleaction.- Configure the
outputFormatandoutputPathparameters.
- Configure the
- Add a step using the
github/codeql-action/upload-sarifaction.- Configure the
sarif_fileparameter to the same file path specified inoutputPath.
- Configure the
- Exclude rules by name \u2014 The rule is not executed for any object.
- Suppress rules by name \u2014 The rule is not executed for a specific object by name.
- Suppress rules by condition \u2014 The rule is not executed for matching objects.
Ignore(1) - Continue to execute silently.Warn(2) - Continue to execute but log a warning. This is the default.Error(3) - Abort and throw an error.Debug(4) - Continue to execute but log a debug message.Execution.SuppressedRuleWarningis replaced withExecution.RuleSuppressed. SetExecution.RuleSuppressedtoWarnto log a warning from v2.8.0. If both options are set,Execution.SuppressedRuleWarningtakes precedence until v3.Execution.AliasReferenceWarningis replaced withExecution.AliasReference. SetExecution.AliasReferencetoWarnto log a warning from v2.9.0. If both options are set,Execution.AliasReferenceWarningtakes precedence until v3.Execution.InconclusiveWarningis replaced withExecution.RuleInconclusive. SetExecution.RuleInconclusivetoWarnto log a warning from v2.9.0. If both options are set,Execution.InconclusiveWarningtakes precedence until v3.Execution.InvariantCultureWarningis replaced withExecution.InvariantCulture. SetExecution.InvariantCulturetoWarnto log a warning from v2.9.0. If both options are set,Execution.InvariantCultureWarningtakes precedence until v3.Execution.NotProcessedWarningis replaced withExecution.UnprocessedObject. SetExecution.UnprocessedObjecttoWarnto log a warning from v2.9.0. If both options are set,Execution.NotProcessedWarningtakes precedence until v3.RuleIdRuleNameDescriptionModuleNameSourcePathIdinstead ofRuleId.Nameinstead ofRuleName.Synopsisinstead ofDescription.Source.Moduleinstead ofModuleName.Source.Pathinstead ofSourcePath.ModuleNameSourcePathSource.Moduleinstead ofModuleName.Source.Pathinstead ofSourcePath.- Objects - PowerShell objects can be validated on the pipeline or imported.
- Objects can be imported directly from
JSON,YAML, or.psd1. - Each object is automatically bound to a target type for use with pre-conditions.
- Rule results are orientated to validating an object.
- Built-in assertions, automatically traverse object properties.
- Objects can be imported directly from
- Pre-conditions - Rules understand which objects they apply to. Objects are bound to a type as they are processed using object properties. Dissimilar objects can be processed quickly.
- Objects that match no rules are flagged with a warning by default.
- Packaging - Rules can be reused between projects and optionally packaged into a module.
- Portable rules, configuration, baselines, and documentation allow greater reuse and distribution.
- Documentation with detailed guidance or next steps can be included.
- Standalone or rules from modules can be combined together with
-Moduleand-Path.
- Configuration - Configuration of rules is handled by PSRule.
- Rules can be configured at runtime, from YAML configuration, or environment variables.
- Baselines can be used to pair rules and configuration for a specific scenario.
- Exceptions - Exceptions to a rule can be ignored for a single object using suppression.
- Exclusion can be used additionally to ignore a rule entirely.
- Infrastructure as code, including:
- Kubernetes manifests.
- Azure Resource Manager (ARM) templates.
- Configuration files.
- Pipeline files.
- Deployments or configurations against a baseline.
- Parameter - PSRule can be configured at runtime by passing the
-Optionparameter to cmdlets. - Options file - Options stored in YAML are load configuration from file. The default
ps-rule.yamloption file is read automatically from the current working path by default. When checking into source control, store this file in the root directory of the repository. - Environment variables - Configuration can be specified using environment variables.
- Exclude the rule - The rule is not executed for any object.
- Suppress the rule - The rule is not executed for a specific object by name.
- Exclude files from analysis \u2014 Configure the Input.PathIgnore option.
-
Disable the warning entirely \u2014 Set the Execution.UnprocessedObject option to
Ignore. - Shift-left \u2014 Identify configuration issues and provide fast feedback in PRs.
- Quality gates \u2014 Implement quality gates between environments such as dev, test, and prod.
- Monitor continuously \u2014 Perform ongoing checks for configuration optimization opportunities.
- GitHub Actions \u2014 Trigger tests for GitHub repositories using workflows.
- Azure Pipelines \u2014 Use tasks to run tests in Azure DevOps YAML or Classic pipelines and releases.
- YAML \u2014 Use a popular, easy to read, and learn IaC format. With YAML, you can quickly build out common rules with minimal effort and no scripting experience.
- JSON \u2014 Is ubiquitous, used by many tools. While this format is typically harder to read then YAML it is easy to automate. You may prefer to use this format if you are generating rules with automation.
- PowerShell \u2014 Is a flexible scripting language. If you or your team already can write a basic PowerShell script, you can already define a rule. PowerShell allows you to tap into a large world-wide community of PowerShell users. Use existing cmdlets to help you build out rules quickly.
- Modular \u2014 Rules can be packages up into a standard PowerShell module then distributed.
- Private \u2014 Modules can be published privately on a network share or NuGet feed.
- Public \u2014 Distribute rules globally using the PowerShell Gallery.
- Configuration \u2014 PSRule and rules can be configured.
- Baselines \u2014 An artifact containing rules and configuration for a scenario.
- Suppression \u2014 Allows you to handle and keep exceptions auditable in git history.
- Approval \u2014 Use code owners and branch policy concepts to control changes.
-
Documentation \u2014 Provide guidance on how to resolve detected issues.
- Quick \u2014 Use a one liner to quickly add a hint or reference on rules you build.
- Detailed \u2014 Support for markdown allows you to provide detailed detailed guidance to resolve issues.
- Clone the GitHub repository.
- Run
./build.ps1from a PowerShell terminal in the cloned path. - PlatyPS
- Pester
- PSScriptAnalyzer
- PowerShellGet
- PackageManagement
- InvokeBuild
- Report issues.
- Up-vote existing issues that are important to you.
- Improve documentation.
-
Contribute code.
- 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.
- Check rule path \u2014 By default, PSRule will look for rules in the
.ps-rule/directory. This directory is the root for your repository or the current working path by default. On case-sensitive file systems such as Linux, this directory name is case-sensitive. See Storing and naming rules for more information. - Check file name suffix \u2014 PSRule only looks for files with the
.Rule.ps1,.Rule.yaml, or.Rule.jsoncsuffix. On case-sensitive file systems such as Linux, this file suffix is case-sensitive. See Storing and naming rules for more information. - Check binding configuration \u2014 PSRule uses binding to work out which property to use for a resource type. To be able to use the
-Typeparameter ortypeproperties in rules definitions, binding must be set. This is automatically configured for modules such as PSRule for Azure, however must be set inps-rule.yamlfor custom rules. - Check modules \u2014 Check if your custom rules have a dependency on another module such as
PSRule.Rules.Azure. If your rules have a dependency, be sure to add the module in your command-line. - Configure binding by setting the Binding.TargetName option to set an alternative property to use as the name. OR
-
Update any existing keys set with the Suppression option to use the new SHA-512 hash.
- Windows PowerShell 5.1 for running as a PowerShell module. OR
- PowerShell 7.3 or later for development, building locally, or running as a PowerShell module.
- To run rules, use
runinstead ofanalyze. i.e.ps-rule run. - To restore modules for a workspace, use
module restoreinstead ofrestore. i.e.ps-rule module restore. - The module lock file
ps-rule.lock.jsonif set. UsemoduleCLI commands to manage the lock file. AND -
Modules defined in the Include.Module option, if set. Additionally the Requires option is used to constrain the version of modules installed.
- Use between 3 and 128 characters \u2014 This is the minimum and maximum length of a resource name.
- Only use allowed characters \u2014 To preserve consistency between file systems, some characters are not permitted. Dots, hyphens, and underscores are not permitted at the start and end of the name. Additionally some characters are restricted for future use. The following characters are not permitted:
<(less than)>(greater than):(colon)/(forward slash)\\(backslash)|(vertical bar or pipe)?(question mark)*(asterisk)\"(double quote)'(single quote)`(backtick)+(plus)@(at sign)- Integer value zero, sometimes referred to as the ASCII NUL character.
- Characters whose integer representations are in the range from 1 through 31.
AzurePipelines- Output is written for integration Azure Pipelines.GitHubActions- Output is written for integration GitHub Actions.VisualStudioCode- Output is written for integration with Visual Studio Code.- If the
TF_BUILDenvironment variable is set totrue,AzurePipelineswill be used. - If the
GITHUB_ACTIONSenvironment variable is set totrue,GitHubActionswill be used. - If the
TERM_PROGRAMenvironment variable is set tovscode,VisualStudioCodewill be used. - Use
Client. TargetNameTargetTypeTargetObject- Enable or explicitly reference them.
- Version rules. PowerShell modules support semantic versioning (semver).
- Reuse rules across projects, pipelines or teams.
- Publish rules to external consumers via the PowerShell Gallery.
- Creating a module manifest
- Including rules and baselines
- Defining a module configuration
- Including documentation
- Enterprise.Rules/
- rules/
- Baseline.Rule.yaml
- Config.Rule.yaml
- Standards.Rule.ps1
- Enterprise.Rules.psd1
- rules/
Binding.FieldBinding.IgnoreCaseBinding.NameSeparatorBinding.PreferTargetInfoBinding.TargetNameBinding.TargetTypeBinding.UseQualifiedNameConfigurationOutput.CultureRule.Baseline- Enterprise.Rules/
- en/
- Org.Az.Storage.UseHttps.md
- Org.Az.Resource.Tagging.md
- en-US/
- Org.Az.Storage.UseHttps.md
- fr-FR/
- Org.Az.Storage.UseHttps.md
- rules/
- Baseline.Rule.yaml
- Config.Rule.yaml
- Standards.Rule.ps1
- Enterprise.Rules.psd1
- en/
- Enterprise.Rules.psd1 - An example module manifest.
- Baseline.Rule.yaml - An example baseline.
- Config.Rule.yaml - An example module configuration.
- Packaging rules in a module
- Use .ps-rule/ \u2014 Create a sub-directory called
.ps-rulein the root of your repository. Use all lower-case in the sub-directory name. Put any custom rules within this sub-directory. - Use files ending with .Rule.* \u2014 PSRule uses a file naming convention to discover rules. Use one of the following depending on the file format you are using:
- YAML -
.Rule.yaml. - JSON -
.Rule.jsoncor.Rule.json. - PowerShell -
.Rule.ps1.
- YAML -
Azure.AKS.VersionAzure.AKS.AuthorizedIPsAzure.SQL.MinTLS- Use between 3 and 128 characters \u2014 This is the minimum and maximum length of a resource name.
- Only use allowed characters \u2014 To preserve consistency between file systems, some characters are not permitted. Dots, hyphens, and underscores are not permitted at the start and end of the name. Additionally some characters are restricted for future use. The following characters are not permitted:
<(less than)>(greater than):(colon)/(forward slash)\\(backslash)|(vertical bar or pipe)?(question mark)*(asterisk)\"(double quote)'(single quote)`(backtick)+(plus)@(at sign)- Integer value zero, sometimes referred to as the ASCII NUL character.
- Characters whose integer representations are in the range from 1 through 31.
- Use a standard prefix \u2014 You can use the
Local.orOrg.prefix for standalone rules.- Alternatively choose a short prefix that identifies your organization.
- Use dotted notation \u2014 Use dots to separate rule name.
- Use a maximum length of 35 characters \u2014 The default view of
Invoke-PSRuletruncates longer names. PSRule supports longer rule names however ifInvoke-PSRuleis called directly consider usingFormat-List. -
Avoid using special characters and punctuation \u2014 Although these characters can be used in many cases, they may not be easy to use with all PSRule features.
- Enforce secure traffic by requiring
supportsHttpsTrafficOnlyto betrue. - Enforce use of TLS 1.2 as a minimum by requiring
minTLSVersionto be1.2. - Use a short
Synopsis:to describe your rule in a line comment above your rule. For this to be interpreted by PSRule, only a single line is allowed. - Name your rule with a unique name.
- The
conditionproperty determines the checks PSRule will use to testsettings.json. Specifically, the object pathconfigures.supportsHttpsTrafficOnlymust exist and be set totrue. - Use a short
Synopsis:to describe your rule in a line comment above your rule. For this to be interpreted by PSRule, only a single line is allowed. - Name your rule with a unique name.
- The
conditionproperty determines the checks PSRule will use to testsettings.json. Specifically, the object pathconfigures.supportsHttpsTrafficOnlymust exist and be set totrue. - Use a short
Synopsis:to describe your rule in a line comment above your rule. For this to be interpreted by PSRule, only a single line is allowed. - Name your rule with a unique name.
- The condition contained within the curly braces
{ }determines the checks PSRule will use to testsettings.json. - The
$Assert.HasFieldValuemethod checks the object pathconfigures.supportsHttpsTrafficOnlyexists and is set totrue. - Using the
allOfexpression requires that all conditions be true for the rule to pass. This expression allows an array of one or more conditions to be provided. UsinganyOfwould pass the rule if any single condition is true. - Using the
allOfexpression requires that all conditions be true for the rule to pass. This expression allows an array of one or more conditions to be provided. UsinganyOfwould pass the rule if any single condition is true. - An additional,
$Assert.HasFieldValueassertion helper method can be called. The rule will pass if all of the conditions return true. Error- A serious problem that must be addressed before going forward.Warning- A problem that should be addressed.Information- A minor problem or an opportunity to improve the code.- YAML \u2014 Start authoring quickly with minimal knowledge of PowerShell.
- JSON \u2014 Generate rules automatically using automation tools.
- PowerShell \u2014 Integrate with other tools using PowerShell cmdlets.
- Expressions \u2014 Schema-based conditions written in YAML or JSON. Expressions can be used in rules and selectors.
- Assertion methods \u2014 PowerShell-based condition helpers that make rules faster to author. Assertion methods can be used in combination with standard PowerShell code to build rules or conventions.
-
The
Equals,HasValueexpressions andHasFieldValueare similar.\u00a0\u21a9\u21a9\u21a9 - Using inline help
- Writing markdown documentation
- Localizing documentation files
- Synopsis resource comment.
metadata.displayNameproperty.metadata.descriptionproperty.metadata.linkproperty.spec.recommendproperty.- Synopsis script comment.
Recommendkeyword.Reasonkeyword.- Annotations are localized, and can have a different value for different languages; tags are not.
- Tags are indexed and can be used to filter rules; annotations have no affect on rule filtering.
online version- A URL to the online version of the document, used byGet-PSRuleHelp -Online.- If the rules are loose, PSRule will search for the culture directory in the same subdirectory as the
.Rule.ps1file. - When rules are included in a module, PSRule will search for the culture directory in the same subdirectory as the module manifest .psd1 file.
- .ps-rule/
- en/
- metadata.Name.md
- en-US/
- metadata.Name.md
- fr-FR/
- metadata.Name.md
- kubernetes.Rule.ps1
- en/
- Kubernetes.Rules/
- en/
- metadata.Name.md
- en-US/
- metadata.Name.md
- fr-FR/
- metadata.Name.md
- rules/
- kubernetes.Rule.ps1
- Kubernetes.Rules.psd1
- en/
- kubernetes.Rule.ps1 - An example rule for validating name label.
- metadata.Name - An example markdown documentation file.
- Environment
- BusinessUnit
- Department
- CostCode
- Use tags to organize your Azure resources and management hierarchy
- Require secure transfer in Azure Storage
- Sample policy for ensuring https traffic
app.kubernetes.io/nameapp.kubernetes.io/instanceapp.kubernetes.io/versionapp.kubernetes.io/componentapp.kubernetes.io/part-ofapp.kubernetes.io/managed-by- Recommended Labels
Invoke-PSRulewrites results as structured objectsAssert-PSRulewrites results as a formatted string.- None - Output is presented as an object using PowerShell defaults. This is the default.
- Yaml - Output is serialized as YAML.
- Json - Output is serialized as JSON.
- Markdown - Output is serialized as Markdown.
- NUnit3 - Output is serialized as NUnit3 (XML).
- Csv - Output is serialized as a comma separated values (CSV).
- Sarif - Output is serialized as SARIF.
- Client - Output is written to the host directly in green/ red to indicate outcome.
- Plain - Output is written as an unformatted string. This option can be redirected to a file.
- AzurePipelines - Output is written for integration Azure Pipelines.
- GitHubActions - Output is written for integration GitHub Actions.
- VisualStudioCode - Output is written for integration with Visual Studio Code.
- Detect - Output style will be detected by checking the environment variables. This is the default.
- If the
TF_BUILDenvironment variable is set totrue,AzurePipelineswill be used. - If the
GITHUB_ACTIONSenvironment variable is set totrue,GitHubActionswill be used. - If the
TERM_PROGRAMenvironment variable is set tovscode,VisualStudioCodewill be used. - Use
Client. Detail- Returns pass/ fail results for each rule per object.Summary- Failure or errors are shown but passing results are summarized.- Yaml - Output is serialized as YAML. This is the default.
- Json - Output is serialized as JSON.
- None - Output is presented as an object using PowerShell defaults. This is the default.
- Wide - Output is presented using the wide table format, which includes tags and wraps columns.
- Yaml - Output is serialized as YAML.
- Json - Output is serialized as JSON.
- None - Output is presented as an object using PowerShell defaults. This is the default.
- Yaml - Output is serialized as YAML.
- Json - Output is serialized as JSON.
Invoke-PSRulewrites results as structured objectsAssert-PSRulewrites results as a formatted string.Detail- Returns pass/ fail results for each rule per object.Summary- Returns summarized results for the rule and the worst outcome.- None - Output is presented as an object using PowerShell defaults. This is the default.
- Yaml - Output is serialized as YAML.
- Json - Output is serialized as JSON.
- Markdown - Output is serialized as Markdown.
- NUnit3 - Output is serialized as NUnit3 (XML).
- Csv - Output is serialized as a comma separated values (CSV).
- Wide - Output is presented using the wide table format, which includes reason and wraps columns.
- Sarif - Output is serialized as SARIF.
- The object fails if:
- Any rules fail or error.
- Any rules are inconclusive.
- The object passes if:
- No matching rules were found.
- All rules pass.
- Rules \u2014 PSRule supports running rules by name or tag. However, when working with a large number of rules it is often easier to group and run rules based on a name.
- Configuration \u2014 A baseline allows you to run any included rules with a predefined configuration by name.
- The
latestbaseline group is set toAzure.GA_2023_03within thePSRule.Rules.Azuremodule. - The
previewbaseline group is set toAzure.Preview_2023_03within thePSRule.Rules.Azuremodule. - The Azure Well-Architected Framework (WAF) defines pillars such as Security and Reliability.
- The CIS Benchmarks define a number of control IDs such as 3.12 and 13.4.
- Lock file is present - PSRule will use the module versions defined in the lock file.
- Lock file is not present - PSRule will use the latest version of each module installed locally.
- APIVersion - The field value must be a date version string.
- Contains - The field value must contain at least one of the strings.
- Count - The field value must contain the specified number of items.
- EndsWith - The field value must match at least one suffix.
- FileHeader - The file must contain a comment header.
- FilePath - The file path must exist.
- Greater - The field value must be greater.
- GreaterOrEqual - The field value must be greater or equal to.
- HasDefaultValue - The object should not have the field or the field value is set to the default value.
- HasField - The object must have any of the specified fields.
- HasFields - The object must have all of the specified fields.
- HasFieldValue - The object must have the specified field and that field is not empty.
- HasJsonSchema - The object must reference a JSON schema with the
$schemafield. - In - The field value must be included in the set.
- IsArray - The field value must be an array.
- IsBoolean - The field value must be a boolean.
- IsDateTime - The field value must be a DateTime.
- IsInteger - The field value must be an integer.
- IsLower - The field value must include only lowercase characters.
- IsNumeric - The field value must be a numeric type.
- IsString - The field value must be a string.
- IsUpper - The field value must include only uppercase characters.
- JsonSchema - The object must validate successfully against a JSON schema.
- Less - The field value must be less.
- LessOrEqual - The field value must be less or equal to.
- Like - The value must match any of the specified wildcard values.
- Match - The field value matches a regular expression pattern.
- NotContains - The value must not contain any of the specified strings.
- NotCount - The field value must not contain the specified number of items.
- NotEndsWith - The value must not end with any of the specified strings.
- NotHasField - The object must not have any of the specified fields.
- NotIn - The field value must not be included in the set.
- NotLike - The value must not match any of the specified wildcard values.
- NotMatch - The field value does not match a regular expression pattern.
- NotNull - The field value must not be null.
- NotStartsWith - The value must not start with any of the specified strings.
- NotWithinPath - The field must not be within the specified path.
- Null - The field value must not exist or be null.
- NullOrEmpty - The object must not have the specified field or it must be empty.
- TypeOf - The field value must be of the specified type.
- SetOf - The field value must match a set of specified values.
- StartsWith - The field value must match at least one prefix.
- Subset - The field value must include a set of specified values.
- Version - The field value must be a semantic version string.
- WithinPath - The field value must be within the specified path.
- The first parameter is always the input object of type
PSObject, additional parameters can be included based on the functionality required by the method.- In many cases the input object will be
$TargetObject, however assertion methods must not assume that$TargetObjectwill be used. - Assertion methods must accept a
$Nullinput object.
- In many cases the input object will be
- Assertion methods return the
AssertResultobject that is interpreted by the rule pipeline. - Property names for PSObjects or .NET objects.
- Keys for hash table or dictionaries.
- Indexes for arrays or collections.
- Queries that filter items from array or collection properties.
., or$refers to input object itself.Name,.Name, or$.Namerefers to the name member of the input object.Properties.enabledrefers to the enabled member under the Properties member. Alternatively this can also be written asProperties['enabled'].Tags.envrefers to the env member under a hash table property of the input object.Tags+envrefers to the env member using a case-sensitive match.Properties.securityRules[0].namereferences to the name member of the first security rule.Properties.securityRules[-1].namereferences to the name member of the last security rule.Properties.securityRules[?@direction == 'Inbound'].namereturns the name of any inbound rules. This will return an array of security rule names.- Member names (properties and keys) are case-insensitive by default. To perform a case-sensitive match of a member name use a plus selector
+in front of the member name. Some assertions such asHasFieldprovide an option to match case when matching member names. When this is used, the plus selector perform an case-insensitive match. - Quoted member names with single or double quotes are supported with dot selector. i.e.
Properties.'spaced name'is valid. - Member names with a dash
-are supported without being quoted. However member names can not start or end with a dash. i.e.Properties.dashed-nameandProperties.'-dashed-name'are valid. inputObject- The object being checked for the specified field.field- The name of the field to check. This is a case insensitive compare.constraint(optional) - A version constraint, see below for details of version constrain format.includePrerelease(optional) - Determines if prerelease versions are included. Unless specified this defaults to$False.version- Must match version exactly. This also accepts the prefix=.- e.g.
2015-10-01,=2015-10-01
- e.g.
>version- Must be greater than version.- e.g.
>2015-10-01
- e.g.
>=version- Must be greater than or equal to version.- e.g.
>=2015-10-01
- e.g.
<version- Must be less than version.- e.g.
<2022-03-01
- e.g.
<=version- Must be less than or equal to version.- e.g.
<=2022-03-01
- e.g.
- Use a space to separate multiple constraints, each must be true (logical AND).
- Separates constraint sets with the double pipe
||. Only one constraint set must be true (logical OR). 2014-01-01 || >=2015-10-01 <2022-03-01results in:- Pass:
2014-01-01,2015-10-01,2019-06-30,2022-02-01. - Fail:
2015-01-01,2022-09-01.
- Pass:
- Constraints and versions containing prerelease identifiers are supported. i.e.
>=2015-10-01-previewor2015-10-01-preview. - A version containing a prerelease identifer follows similar ordering to semantic versioning. i.e.
2015-10-01-preview<2015-10-01-preview.1<2015-10-01<2022-03-01-preview<2022-03-01. - A constraint without a prerelease identifer will only match a stable version by default. Set
includePrereleaseto$Trueto include prerelease versions. Alternatively use the@preor@prereleaseflag in a constraint. - The parameter 'inputObject' is null.
- The parameter 'field' is null or empty.
- The field '{0}' does not exist.
- The field value '{0}' is not a version string.
- The version '{0}' does not match the constraint '{1}'.
inputObject- The object being checked for the specified field.field- The name of the field to check. This is a case insensitive compare.text- A string or an array of strings to compare the field value with. Only one string must match. When an empty array of strings is specified or text is an empty string,Containsalways passes.caseSensitive(optional) - Use a case sensitive compare of the field value. Case is ignored by default.- The parameter 'inputObject' is null.
- The parameter 'field' is null or empty.
- The parameter 'text' is null.
- The field '{0}' does not exist.
- The field value '{0}' is not a string.
- The field '{0}' does not contain '{1}'.
inputObject- The object being checked for the specified field.field- The name of the field to check. This is a case insensitive compare.count- The number of items that the field value must contain.- The parameter 'inputObject' is null.
- The parameter 'field' is null or empty.
- The field '{0}' does not exist.
- The field '{0}' is not enumerable.
- The field '{0}' has '{1}' items instead of '{2}'.
inputObject- The object being checked for the specified field.field- The name of the field to check. This is a case insensitive compare.suffix- A suffix or an array of suffixes to compare the field value with. Only one suffix must match. When an empty array of suffixes is specified or suffix is an empty string,EndsWithalways passes.caseSensitive(optional) - Use a case sensitive compare of the field value. Case is ignored by default.- The parameter 'inputObject' is null.
- The parameter 'field' is null or empty.
- The parameter 'suffix' is null.
- The field '{0}' does not exist.
- The field value '{0}' is not a string.
- The field '{0}' does not end with '{1}'.
inputObject- The object being checked for the specified field.field- The name of the field containing a valid file path.header- One or more lines of a header to compare with file contents.prefix(optional) - An optional comment prefix for each line. By default a comment prefix will automatically detected based on file extension. When set, detection by file extension is skipped..bicep,.bicepparam,.cs,.csx,.ts,.tsp,.tsx,.js,.jsx,.fs,.go,.groovy,.php,.cpp,.h,.java,.json,.jsonc,.scala,Jenkinsfile- Use a prefix of (//)..editorconfig,.ipynb,.ps1,.psd1,.psm1,.yaml,.yml,.r,.py,.sh,.tf,.tfvars,.toml,.gitignore,.pl,.rb,Dockerfile- Use a prefix of (#)..sql,.lau- Use a prefix of (--)..bat,.cmd- Use a prefix of (::).- The parameter 'inputObject' is null.
- The parameter 'field' is null or empty.
- The field '{0}' does not exist.
- The field value '{0}' is not a string.
- The file '{0}' does not exist.
- The header was not set.
inputObject- The object being checked for the specified field.field- The name of the field containing a file path.suffix(optional) - Additional file path suffixes to append. When specified each suffix is combined with the file path. Only one full file path must be a valid file for the assertion method to pass.- The parameter 'inputObject' is null.
- The parameter 'field' is null or empty.
- The field '{0}' does not exist.
- The field value '{0}' is not a string.
- The file '{0}' does not exist.
- An integer or float, a numerical comparison is used.
- An array, the number of elements is compared.
- A string, the length of the string is compared.
- A DateTime, the number of days from the current time is compared.
inputObject- The object being checked for the specified field.field- The name of the field to check. This is a case insensitive compare.value- A integer to compare the field value against.convert(optional) - Convert numerical strings and use a numerical comparison instead of using string length. By default the string length is compared.- The parameter 'inputObject' is null.
- The parameter 'field' is null or empty.
- The field '{0}' does not exist.
- The value '{0}' was not > '{1}'.
- The field value '{0}' can not be compared with '{1}'.
- An integer or float, a numerical comparison is used.
- An array, the number of elements is compared.
- A string, the length of the string is compared.
- A DateTime, the number of days from the current time is compared.
inputObject- The object being checked for the specified field.field- The name of the field to check. This is a case insensitive compare.value- A integer to compare the field value against.convert(optional) - Convert numerical strings and use a numerical comparison instead of using string length. By default the string length is compared.- The parameter 'inputObject' is null.
- The parameter 'field' is null or empty.
- The field '{0}' does not exist.
- The value '{0}' was not >= '{1}'.
- The field value '{0}' can not be compared with '{1}'.
inputObject- The object being checked for the specified field.field- The name of the field to check. This is a case insensitive compare.defaultValue- The expected value if the field exists.- The field does not exist.
- The field value is set to
defaultValue. - The field value is set to a value different from
defaultValue. - The parameter 'inputObject' is null.
- The parameter 'field' is null or empty.
- The field '{0}' is set to '{1}'.
inputObject- The object being checked for the specified field.field- The name of one or more fields to check. By default, a case insensitive compare is used. If more than one field is specified, only one must exist.caseSensitive(optional) - Use a case sensitive compare of the field name.- The parameter 'inputObject' is null.
- The parameter 'field' is null or empty.
- Does not exist.
inputObject- The object being checked for the specified fields.field- The name of one or more fields to check. By default, a case insensitive compare is used. If more than one field is specified, all fields must exist.caseSensitive(optional) - Use a case sensitive compare of the field name.- The parameter 'inputObject' is null.
- The parameter 'field' is null or empty.
- The field '{0}' does not exist.
- The field does not exist.
- The field value is
$Null. - The field value is an empty array or collection.
- The field value is an empty string
''. inputObject- The object being checked for the specified field.field- The name of the field to check. This is a case insensitive compare.expectedValue(optional) - Check that the field value is set to a specific value. To check$NulluseNullOrEmptyinstead. IfexpectedValueis$Nullthe field value will not be compared.- The parameter 'inputObject' is null.
- The parameter 'field' is null or empty.
- Does not exist.
- Is null or empty.
- Is set to '{0}'.
inputObject- The object being compared.uri- Optional. When specified, the object being compared must have a$schemaproperty set to one of the specified schemas.ignoreScheme- Optional. By default,ignoreSchemeis$False. When$True, the schema will match ifhttporhttpsis specified.- The parameter 'inputObject' is null.
- The field '$schema' does not exist.
- The field value '$schema' is not a string.
- The value of '$schema' is null or empty.
- None of the specified schemas match '{0}'.
inputObject- The object being compared against the JSON schema.uri- A URL or file path to a JSON schema file formatted as UTF-8. Either a file path or URL can be used to specify the location of the schema file.- The parameter 'inputObject' is null.
- The parameter 'uri' is null or empty.
- The JSON schema '{0}' could not be found.
- Failed schema validation on {0}. {1}
inputObject- The object being checked for the specified field.field- The name of the field to check. This is a case insensitive compare.values- An array of values that the field value is compared against. When an empty array is specified,Inwill always fail.caseSensitive(optional) - Use a case sensitive compare of the field value. Case is ignored by default.- The parameter 'inputObject' is null.
- The parameter 'field' is null or empty.
- The parameter 'values' is null.
- The field '{0}' does not exist.
- The field value '{0}' was not included in the set.
inputObject- The object being checked for the specified field.field- The name of the field to check. This is a case insensitive compare.- The parameter 'inputObject' is null.
- The parameter 'field' is null or empty.
- The field '{0}' does not exist.
- The field value '{0}' is null.
- The field value '{1}' of type {0} is not [array].
inputObject- The object being checked for the specified field.field- The name of the field to check. This is a case insensitive compare.convert(optional) - Try to convert strings. By default strings are not converted.- The parameter 'inputObject' is null.
- The parameter 'field' is null or empty.
- The field '{0}' does not exist.
- The field value '{0}' is null.
- The value '{0}' is not a boolean.
inputObject- The object being checked for the specified field.field- The name of the field to check. This is a case insensitive compare.convert(optional) - Try to convert strings. By default strings are not converted.- The parameter 'inputObject' is null.
- The parameter 'field' is null or empty.
- The field '{0}' does not exist.
- The field value '{0}' is null.
- The value '{0}' is not a date.
inputObject- The object being checked for the specified field.field- The name of the field to check. This is a case insensitive compare.convert(optional) - Try to convert strings. By default strings are not converted.- The parameter 'inputObject' is null.
- The parameter 'field' is null or empty.
- The field '{0}' does not exist.
- The field value '{0}' is null.
- The value '{0}' is not an integer.
inputObject- The object being checked for the specified field.field- The name of the field to check. This is a case insensitive compare.requireLetters(optional) - Require each character to be lowercase letters only. Non-letter characters are ignored by default.- The parameter 'inputObject' is null.
- The parameter 'field' is null or empty.
- The field '{0}' does not exist.
- The field value '{0}' is not a string.
- The value '{0}' does not contain only lowercase characters.
- The value '{0}' does not contain only letters.
inputObject- The object being checked for the specified field.field- The name of the field to check. This is a case insensitive compare.convert(optional) - Try to convert numerical strings. By default strings are not converted.- The parameter 'inputObject' is null.
- The parameter 'field' is null or empty.
- The field '{0}' does not exist.
- The field value '{0}' is null.
- The value '{0}' is not numeric.
inputObject- The object being checked for the specified field.field- The name of the field to check. This is a case insensitive compare.- The parameter 'inputObject' is null.
- The parameter 'field' is null or empty.
- The field '{0}' does not exist.
- The field value '{0}' is null.
- The value '{0}' is not a string.
inputObject- The object being checked for the specified field.field- The name of the field to check. This is a case insensitive compare.requireLetters(optional) - Require each character to be uppercase letters only. Non-letter characters are ignored by default.- The parameter 'inputObject' is null.
- The parameter 'field' is null or empty.
- The field '{0}' does not exist.
- The field value '{0}' is not a string.
- The value '{0}' does not contain only uppercase characters.
- The value '{0}' does not contain only letters.
- An integer or float, a numerical comparison is used.
- An array, the number of elements is compared.
- A string, the length of the string is compared.
- A DateTime, the number of days from the current time is compared.
inputObject- The object being checked for the specified field.field- The name of the field to check. This is a case insensitive compare.value- A integer to compare the field value against.convert(optional) - Convert numerical strings and use a numerical comparison instead of using string length. By default the string length is compared.- The parameter 'inputObject' is null.
- The parameter 'field' is null or empty.
- The field '{0}' does not exist.
- The value '{0}' was not < '{1}'.
- The field value '{0}' can not be compared with '{1}'.
- An integer or float, a numerical comparison is used.
- An array, the number of elements is compared.
- A string, the length of the string is compared.
- A DateTime, the number of days from the current time is compared.
inputObject- The object being checked for the specified field.field- The name of the field to check. This is a case insensitive compare.value- A integer to compare the field value against.convert(optional) - Convert numerical strings and use a numerical comparison instead of using string length. By default the string length is compared.- The parameter 'inputObject' is null.
- The parameter 'field' is null or empty.
- The field '{0}' does not exist.
- The value '{0}' was not <= '{1}'.
- The field value '{0}' can not be compared with '{1}'.
inputObject- The object being checked for the specified field.field- The name of the field to check. This is a case insensitive compare.pattern- A pattern or an array of patterns to compare the field value with. Only one pattern must match. When an empty array of patterns is specified,Likealways passes.caseSensitive(optional) - Use a case sensitive compare of the field value. Case is ignored by default.- The parameter 'inputObject' is null.
- The parameter 'field' is null or empty.
- The parameter 'prefix' is null.
- The field '{0}' does not exist.
- The field value '{0}' is not a string.
- The value '{0}' is not like '{1}'.
inputObject- The object being checked for the specified field.field- The name of the field to check. This is a case insensitive compare.pattern- A regular expression pattern to match.caseSensitive(optional) - Use a case sensitive compare of the field value. Case is ignored by default.- The parameter 'inputObject' is null.
- The parameter 'field' is null or empty.
- The field '{0}' does not exist.
- The field value '{0}' is not a string.
- The field value '{0}' does not match the pattern '{1}'.
inputObject- The object being checked for the specified field.field- The name of the field to check. This is a case insensitive compare.text- A string or an array of strings to compare the field value with. When an empty array of strings is specified or text is an empty string,NotContainsalways passes.caseSensitive(optional) - Use a case sensitive compare of the field value. Case is ignored by default.- The parameter 'inputObject' is null.
- The parameter 'field' is null or empty.
- The parameter 'text' is null.
- The field '{0}' does not exist.
- The value '{0}' contains '{1}'.
inputObject- The object being checked for the specified field.field- The name of the field to check. This is a case insensitive compare.count- The number of items that the field value must contain.- The parameter 'inputObject' is null.
- The parameter 'field' is null or empty.
- The field '{0}' does not exist.
- The field '{0}' is not enumerable.
- The field '{0}' has '{1}' items instead of '{2}'.
inputObject- The object being checked for the specified field.field- The name of the field to check. This is a case insensitive compare.suffix- A suffix or an array of suffixes to compare the field value with. When an empty array of suffixes is specified or suffix is an empty string,NotEndsWithalways passes.caseSensitive(optional) - Use a case sensitive compare of the field value. Case is ignored by default.- The parameter 'inputObject' is null.
- The parameter 'field' is null or empty.
- The parameter 'suffix' is null.
- The field '{0}' does not exist.
- The value '{0}' ends with '{1}'.
inputObject- The object being checked for the specified field.field- The name of one or more fields to check. By default, a case insensitive compare is used. If more than one field is specified, all must not exist.caseSensitive(optional) - Use a case sensitive compare of the field name.- The parameter 'inputObject' is null.
- The parameter 'field' is null or empty.
- The field '{0}' exists.
inputObject- The object being checked for the specified field.field- The name of the field to check. This is a case insensitive compare.values- An array values that the field value is compared against. When an empty array is specified,NotInwill always pass.caseSensitive(optional) - Use a case sensitive compare of the field value. Case is ignored by default.- The parameter 'inputObject' is null.
- The parameter 'field' is null or empty.
- The parameter 'values' is null.
- The field value '{0}' was in the set.
inputObject- The object being checked for the specified field.field- The name of the field to check. This is a case insensitive compare.pattern- A pattern or an array of patterns to compare the field value with. When an empty array of pattens is specified,NotLikealways passes.caseSensitive(optional) - Use a case sensitive compare of the field value. Case is ignored by default.- The parameter 'inputObject' is null.
- The parameter 'field' is null or empty.
- The parameter 'prefix' is null.
- The field '{0}' does not exist.
- The value '{0}' is like '{1}'
inputObject- The object being checked for the specified field.field- The name of the field to check. This is a case insensitive compare.pattern- A regular expression pattern to match.caseSensitive(optional) - Use a case sensitive compare of the field value. Case is ignored by default.- The parameter 'inputObject' is null.
- The parameter 'field' is null or empty.
- The field value '{0}' is not a string.
- The field value '{0}' matches the pattern '{1}'.
inputObject- The object being checked for the specified field.field- The name of the field to check. This is a case insensitive compare.- The parameter 'inputObject' is null.
- The parameter 'field' is null or empty.
- The field '{0}' does not exist.
- The field value '{0}' is null.
inputObject- The object being checked for the specified field.field- The name of the field to check. This is a case insensitive compare.prefix- A prefix or an array of prefixes to compare the field value with. When an empty array of prefixes is specified or prefix is an empty string,NotStartsWithalways passes.caseSensitive(optional) - Use a case sensitive compare of the field value. Case is ignored by default.- The parameter 'inputObject' is null.
- The parameter 'field' is null or empty.
- The parameter 'prefix' is null.
- The field '{0}' does not exist.
- The value '{0}' starts with '{1}'.
inputObject- The object being checked for the specified field.field- The name of the field containing a file path. When the field isInputFileInfoorFileInfo, PSRule will automatically resolve the file path.path- An array of one or more directory paths to check. Only one path must match.caseSensitive(optional) - Determines if case-sensitive path matching is used. This can be set to$Trueor$False. When not set or$Null, the case-sensitivity rules of the working path file system will be used.- The parameter 'inputObject' is null.
- The parameter 'field' is null or empty.
- The parameter 'path' is null or empty.
- The field '{0}' does not exist.
- The file '{0}' is within the path '{1}'.
- The field does not exist.
- The field value is
$Null. inputObject- The object being checked for the specified field.field- The name of the field to check. This is a case insensitive compare.- The parameter 'inputObject' is null.
- The parameter 'field' is null or empty.
- The field value '{0}' is not null.
- The field does not exist.
- The field value is
$Null. - The field value is an empty array or collection.
- The field value is an empty string
''. inputObject- The object being checked for the specified field.field- The name of the field to check. This is a case insensitive compare.- The parameter 'inputObject' is null.
- The parameter 'field' is null or empty.
- The field '{0}' is not empty.
inputObject- The object being checked for the specified field.field- The name of the field to check. This is a case insensitive compare.type- One or more specified types to check. The field value only has to match a single type of more than one type is specified.- The parameter 'inputObject' is null.
- The parameter 'field' is null or empty.
- The parameter 'type' is null or empty.
- The field '{0}' does not exist.
- The field value '{0}' is null.
- The field value '{2}' of type {1} is not {0}.
inputObject- The object being checked for the specified field.field- The name of the field to check. This is a case insensitive compare.values- An array of values that the field value is compared against.caseSensitive(optional) - Use a case sensitive compare of the field value. Case is ignored by default.- The parameter 'inputObject' is null.
- The parameter 'field' is null or empty.
- The parameter 'values' is null.
- The field '{0}' does not exist.
- The field '{0}' is not enumerable.
- The field '{0}' did not contain '{1}'.
- The field '{0}' has '{1}' items instead of '{2}'.
inputObject- The object being checked for the specified field.field- The name of the field to check. This is a case insensitive compare.prefix- A prefix or an array of prefixes to compare the field value with. Only one prefix must match. When an empty array of prefixes is specified or prefix is an empty string,StartsWithalways passes.caseSensitive(optional) - Use a case sensitive compare of the field value. Case is ignored by default.- The parameter 'inputObject' is null.
- The parameter 'field' is null or empty.
- The parameter 'prefix' is null.
- The field '{0}' does not exist.
- The field value '{0}' is not a string.
- The field '{0}' does not start with '{1}'.
inputObject- The object being checked for the specified field.field- The name of the field to check. This is a case insensitive compare.values- An array of values that the field value is compared against. When an empty array is specified,Subsetwill always pass.caseSensitive(optional) - Use a case sensitive compare of the field value. Case is ignored by default.unique(optional) - A boolean value that indicates if the items must be unique. Whentruethe field value must not contain duplicate items.- The parameter 'inputObject' is null.
- The parameter 'field' is null or empty.
- The parameter 'values' is null.
- The field '{0}' does not exist.
- The field '{0}' is not enumerable.
- The field '{0}' did not contain '{1}'.
- The field '{0}' included multiple instances of '{1}'.
inputObject- The object being checked for the specified field.field- The name of the field to check. This is a case insensitive compare.constraint(optional) - A version constraint, see below for details of version constrain format.includePrerelease(optional) - Determines if prerelease versions are included. Unless specified this defaults to$False.version- Must match version exactly. This also accepts the following prefixes;=,v,V.- e.g.
1.2.3,=1.2.3
- e.g.
>version- Must be greater than version.- e.g.
>1.2.3
- e.g.
>=version- Must be greater than or equal to version.- e.g.
>=1.2.3
- e.g.
<version- Must be less than version.- e.g.
<1.2.3
- e.g.
<=version- Must be less than or equal to version.- e.g.
<=1.2.3
- e.g.
^version- Compatible with version.- e.g.
^1.2.3->=1.2.3,<2.0.0
- e.g.
~version- Approximately equivalent to version- e.g.
~1.2.3->=1.2.3,<1.3.0
- e.g.
- Use a space to separate multiple constraints, each must be true (logical AND).
- Separates constraint sets with the double pipe
||. Only one constraint set must be true (logical OR). 1.2.3 || >=3.4.5 <5.0.0results in:- Pass:
1.2.3,3.4.5,3.5.0,4.9.9. - Fail:
3.0.0,5.0.0.
- Pass:
- Constraints and versions containing prerelease identifiers are supported. i.e.
>=1.2.3-build.1or1.2.3-build.1. - A version containing a prerelease identifer follows semantic versioning rules. i.e.
1.2.3-alpha<1.2.3-alpha.1<1.2.3-alpha.beta<1.2.3-beta<1.2.3-beta.2<1.2.3-beta.11<1.2.3-rc.1<1.2.3. - A constraint without a prerelease identifer will only match a stable version by default. Set
includePrereleaseto$Trueto include prerelease versions. - Constraints with a prerelease identifer will only match:
- Matching prerelease versions of the same major.minor.patch version by default. Set
includePrereleaseto$Trueto include prerelease versions of all matching versions. Alternatively use the@preor@prereleaseflag in a constraint. - Matching stable versions.
- Matching prerelease versions of the same major.minor.patch version by default. Set
>=1.2.3results in:- Pass:
1.2.3,9.9.9. - Fail:
1.2.3-build.1,9.9.9-build.1.
- Pass:
>=1.2.3-0results in:- Pass:
1.2.3,1.2.3-build.1,9.9.9. - Fail:
9.9.9-build.1.
- Pass:
<1.2.3results in:- Pass:
1.2.2,1.0.0. - Fail:
1.0.0-build.1,1.2.3-build.1.
- Pass:
<1.2.3-0results in:- Pass:
1.2.2,1.0.0. - Fail:
1.0.0-build.1,1.2.3-build.1.
- Pass:
@pre >=1.2.3results in:- Pass:
1.2.3,9.9.9,9.9.9-build.1 - Fail:
1.2.3-build.1.
- Pass:
@pre >=1.2.3-0results in:- Pass:
1.2.3,1.2.3-build.1,9.9.9,9.9.9-build.1.
- Pass:
- The parameter 'inputObject' is null.
- The parameter 'field' is null or empty.
- The field '{0}' does not exist.
- The field value '{0}' is not a version string.
- The version '{0}' does not match the constraint '{1}'.
inputObject- The object being checked for the specified field.field- The name of the field containing a file path. When the field isInputFileInfoorFileInfo, PSRule will automatically resolve the file path.path- An array of one or more directory paths to check. Only one path must match.caseSensitive(optional) - Determines if case-sensitive path matching is used. This can be set to$Trueor$False. When not set or$Null, the case-sensitivity rules of the working path file system will be used.- The parameter 'inputObject' is null.
- The parameter 'field' is null or empty.
- The parameter 'path' is null or empty.
- The field '{0}' does not exist.
- The file '{0}' is not within the path '{1}'.
- Handles pass/ fail conditions and collection of reason information.
- Allows rules to implement their own handling or forward it up the stack to affect the rule outcome.
Result- Either$True(Pass) or$False(Fail).AddReason(<string> text)- Can be used to append additional reasons to the result. A reason can only be set if the assertion failed. Reason text should be localized before calling this method. Localization can be done using the$LocalizedDataautomatic variable.WithReason(<string> text, <bool> replace)- Can be used to append or replace reasons on the result. In addition,WithReasoncan be chained.Reason(<string> text, params <object[]> args)- Replaces the reason on the results with a formatted string. This method can be chained. For usage see examples below.ReasonFrom(<string> path, <string> text, params <object[]> args)- Replaces the reason on the results with a formatted string. Path specifies the object path that affected the reason. This method can be chained. For usage see examples below.ReasonIf(<bool> condition, <string> text, params <object[]> args)- Replaces the reason if the condition is true. This method can be chained, similar toReason.ReasonIf(<string> path, <bool> condition, <string> text, params <object[]> args)- Replaces the reason if the condition is true. This method can be chained, similar toReasonFrom.PathPrefix(<string> path)- Adds a path prefix to any reasons. This method can be chained. For usage see examples below.GetReason()- Gets any reasons currently associated with the failed result.Complete()- Returns$True(Pass) or$False(Fail) to the rule record. If the assertion failed, any reasons are automatically added to the rule record. To read the result without adding reason to the rule record use theResultproperty.Ignore()- Ignores the result. Nothing future is returned and any reasons are cleared. Use this method when implementing custom handling.type- The issue type. Issues are filtered by type.name- The name of a specific issue.message- The reason message for the issue.Create(<bool> condition, <string> reason, params <object[]> args)- Returns a result either pass or fail assertion result. Additional arguments can be provided to format the custom reason string.Create(<TargetIssueInfo[]>)- Returns a result based on reported downstream issues.Pass()- Returns a pass assertion result.Fail()- Results a fail assertion result.Fail(<string> reason, params <object[]> args)- Results a fail assertion result with a custom reason. Additional arguments can be provided to format the custom reason string.AnyOf(<AssertResult[]> results)- Results from assertion methods are aggregated into a single result. If any result is a pass, the result is a pass. If all results are fails, the result is a fail and any reasons are added to the result. If no results are provided, the result is a fail.AllOf(<AssertResult[]> results)- Results from assertion methods are aggregated into a single result. If all results are passes, the result is a pass. If any result is a fail, the result is a fail and any reasons are added to the result. If no results are provided, the result is a fail.- about_PSRule_Variables
- Invoke-PSRule
- Binding.Field
- Binding.IgnoreCase
- Binding.NameSeparator
- Binding.PreferTargetInfo
- Binding.TargetName
- Binding.TargetType
- Binding.UseQualifiedName
- Configuration
- Rule.Include
- Rule.IncludeLocal
- Rule.Exclude
- Rule.Tag
- Included as a baseline spec within a YAML or JSON file.
- When using this method, multiple baseline specs can be defined within the same YAML/JSON file.
- Each YAML baseline spec is separated using
---. - Each JSON baseline spec is separated by JSON objects in a JSON array.
- Set within a workspace options file like
ps-rule.yamlorps-rule.json.- Only a single baseline can be specified.
- See about_PSRule_Options for details on using this method.
- Parameter -
-Nameand-Tag. - Explicit - A named baseline specified with
-Baseline. - Workspace - Included in
ps-rule.yamlor specified on the command line with-Option. - Module - A baseline object included in a
.Rule.yamlor.Rule.jsonfile. obsolete- Marks the baseline as obsolete when set totrue. PSRule will generate a warning when an obsolete baseline is used.Initializeoccurs once at the beginning of the pipeline. UseInitializeto perform any initialization required by the convention.Beginoccurs once per object before the any rules are executed. UseBeginblocks to perform expansion, set data, or alter the object before rules are processed.Processoccurs once per object after all rules are executed. UseProcessblocks to perform per object tasks such as generate badges.Endoccurs only once after all objects have been processed. UseEndblocks to upload results to an external service.Initializecan not use automatic variables except$PSRule. Most methods and properties of$PSRuleare not available inInitialize.BeginandProcesscan not use rule specific variables such as$Rule. These blocks are executed outside of the context of a single rule.Endcan not use automatic variables except$PSRule. Most methods and properties of$PSRuleare not available inEnd.- Using
-Conventionparameter. - PSRule options.
- Module configuration.
- Invoke-PSRule
- Annotations - Additional metadata included in results.
- Synopsis - A brief description on the intended purpose of the rule.
- Description - A detailed description on the intended purpose of the rule.
- Recommendation - A detailed explanation of the requirements to pass the rule.
- Notes - Any additional information or configuration options.
- Links - Any links to external references.
- When resources are standalone, the culture subdirectory is relative to the
*.Rule.*file. - When packaged in a module, the culture subdirectory is relative to the module manifest
.psd1file. - Get-PSRuleHelp
- APIVersion
- Contains
- Count
- Equals
- EndsWith
- Exists
- Greater
- GreaterOrEquals
- HasDefault
- HasSchema
- HasValue
- In
- IsLower
- IsString
- IsArray
- IsBoolean
- IsDateTime
- IsInteger
- IsNumeric
- IsUpper
- Less
- LessOrEquals
- Like
- Match
- NotContains
- NotCount
- NotEndsWith
- NotEquals
- NotIn
- NotLike
- NotMatch
- NotStartsWith
- NotWithinPath
- SetOf
- StartsWith
- Subset
- WithinPath
- Version
- AllOf
- AnyOf
- Not
- Field
- Name
- Scope
- Source
- Type
caseSensitive- Optionally, a case sensitive-comparison can be performed. By default, case-insensitive comparison is performed.convert- Optionally, types can be converted to string type. By defaultconvertisfalse.- If the operand is a field, and the field does not exist, contains always returns
false. caseSensitive- Optionally, a case sensitive-comparison can be performed. This only applies to string comparisons. By default, case-insensitive comparison is performed.convert- Optionally, perform type conversion on operand type. By defaultconvertisfalse.caseSensitive- Optionally, a case sensitive-comparison can be performed. By default, case-insensitive comparison is performed.convert- Optionally, types can be converted to string type. By defaultconvertisfalse.- If the operand is a field, and the field does not exist, endsWith always returns
false. - When
exists: true, exists will returntrueif the field exists. - When
exists: false, exists will returntrueif the field does not exist. - A property name.
- A key within a hashtable or dictionary.
- An index in an array or collection.
- A nested path through an object.
convert- Optionally, perform type conversion on operand type. By defaultconvertisfalse.- An integer or float, a numerical comparison is used.
- An array, the number of elements is compared.
- A string, the length of the string is compared. If
convertistrue, the string is converted a number instead. - A DateTime, the number of days from the current time is compared.
convert- Optionally, perform type conversion on operand type. By defaultconvertisfalse.- An integer or float, a numerical comparison is used.
- An array, the number of elements is compared.
- A string, the length of the string is compared. If
convertistrue, the string is converted a number instead. - A DateTime, the number of days from the current time is compared.
caseSensitive- Optionally, a case-sensitive comparison can be performed for string values. By default, case-insensitive comparison is performed.caseSensitive- Optionally, a case-sensitive comparison can be performed. By default, case-insensitive comparison is performed.ignoreScheme- Optionally, the URI scheme is ignored in the comparison. By default, the scheme is compared. Whentrue, the schema will match if eitherhttp://orhttps://is specified.- When
hasSchema: [], hasSchema will returntrueif any non-empty$schemaproperty is defined. - When
hasValue: true, hasValue will returntrueif the field is not empty. - When
hasValue: false, hasValue will returntrueif the field is empty. - When
isLower: true, isLower will returntrueif the operand is a lowercase string. Non-letter characters are ignored. - When
isLower: false, isLower will returntrueif the operand is not a lowercase string. - If the operand is a field, and the field does not exist isLower always returns
false. - When
isString: true, isString will returntrueif the operand is a string. - When
isString: false, isString will returntrueif the operand is not a string or is null. - If the operand is a field, and the field does not exist isString always returns
false. - When
isArray: true, isArray will returntrueif the operand is an array. - When
isArray: false, isArray will returntrueif the operand is not an array or null. - If the operand is a field, and the field does not exist, isArray always returns
false. convert- Optionally, types can be converted to boolean type. E.g.'true'can be converted totrue. By defaultconvertisfalse.- When
isBoolean: true, isBoolean will returntrueif the operand is a boolean. - When
isBoolean: false, isBoolean will returnfalseif the operand is not a boolean or null. - When
convert: true, types will be converted to boolean before condition is evaluated. convert- Optionally, types can be converted to datetime type. E.g.'2021-04-03T15:00:00.00+10:00'can be converted to a datetime. By defaultconvertisfalse.- When
isDateTime: true, isDateTime will returntrueif the operand is a datetime. - When
isDateTime: false, isDateTime will returnfalseif the operand is not a datetime or null. - When
convert: true, types will be converted to datetime before condition is evaluated. convert- Optionally, types can be converted to integer type. E.g.'123'can be converted to123. By defaultconvertisfalse.- When
isInteger: true, isInteger will returntrueif the operand is an integer. - When
isInteger: false, isInteger will returnfalseif the operand is not an integer or null. - When
convert: true, types will be converted to integer before condition is evaluated. convert- Optionally, types can be converted to numeric type. E.g.'123'can be converted to123. By defaultconvertisfalse.- When
isNumeric: true, isNumeric will returntrueif the operand is a numeric. - When
isNumeric: false, isNumeric will returnfalseif the operand is not a numeric or null. - When
convert: true, types will be converted to numeric before condition is evaluated. - When
isUpper: true, isUpper will returntrueif the operand is an uppercase string. Non-letter characters are ignored. - When
isUpper: false, isUpper will returntrueif the operand is not an uppercase string. - If the operand is a field, and the field does not exist isUpper always returns
false. convert- Optionally, perform type conversion on operand type. By defaultconvertisfalse.- An integer or float, a numerical comparison is used.
- An array, the number of elements is compared.
- A string, the length of the string is compared. If
convertistrue, the string is converted a number instead. - A DateTime, the number of days from the current time is compared.
convert- Optionally, perform type conversion on operand type. By defaultconvertisfalse.- An integer or float, a numerical comparison is used.
- An array, the number of elements is compared.
- A string, the length of the string is compared. If
convertistrue, the string is converted a number instead. - A DateTime, the number of days from the current time is compared.
caseSensitive- Optionally, a case sensitive-comparison can be performed. By default, case-insensitive comparison is performed.convert- Optionally, types can be converted to string type. By defaultconvertisfalse.- If the operand is a field, and the field does not exist, like always returns
false. caseSensitive- Optionally, a case sensitive-comparison can be performed. By default, case-insensitive comparison is performed.caseSensitive- Optionally, a case sensitive-comparison can be performed. By default, case-insensitive comparison is performed.convert- Optionally, types can be converted to string type. By defaultconvertisfalse.- If the operand is a field, and the field does not exist, notContains always returns
false. caseSensitive- Optionally, a case sensitive-comparison can be performed. By default, case-insensitive comparison is performed.convert- Optionally, types can be converted to string type. By defaultconvertisfalse.- If the operand is a field, and the field does not exist, notEndsWith always returns
false. caseSensitive- Optionally, a case sensitive-comparison can be performed. This only applies to string comparisons. By default, case-insensitive comparison is performed.convert- Optionally, perform type conversion on operand type. By defaultconvertisfalse.caseSensitive- Optionally, a case sensitive-comparison can be performed. By default, case-insensitive comparison is performed.convert- Optionally, types can be converted to string type. By defaultconvertisfalse.- If the operand is a field, and the field does not exist, notLike always returns
false. caseSensitive- Optionally, a case sensitive-comparison can be performed. By default, case-insensitive comparison is performed.caseSensitive- Optionally, a case sensitive-comparison can be performed. By default, case-insensitive comparison is performed.convert- Optionally, types can be converted to string type. By defaultconvertisfalse.- If the operand is a field, and the field does not exist, notStartsWith always returns
false. caseSensitive- Optionally, a case-sensitive comparison can be performed for string values. By default, case-insensitive comparison is performed.caseSensitive- Optionally, a case sensitive-comparison can be performed. By default, case-insensitive comparison is performed.caseSensitive- Optionally, a case sensitive-comparison can be performed. By default, case-insensitive comparison is performed.convert- Optionally, types can be converted to string type. By defaultconvertisfalse.- If the operand is a field, and the field does not exist, startsWith always returns
false. caseSensitive- Optionally, a case-sensitive comparison can be performed. By default, case-insensitive comparison is performed.unique- Optionally, the operand must not contain duplicates. By default, duplicates are allowed.caseSensitive- Optionally, a case-sensitive comparison can be performed for string values. By default, case-insensitive comparison is performed.- Invoke-PSRule
- Baseline.Group
- 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
- Suppression
- Binding.Field
- Binding.IgnoreCase
- Binding.NameSeparator
- Binding.PreferTargetInfo
- Binding.TargetName
- Binding.TargetType
- Binding.UseQualifiedName
- Configuration
- Rule.Baseline
- Rule.Include
- Rule.IncludeLocal
- Rule.Exclude
- Rule.Tag
- Export-PSRuleBaseline
- Get-PSRule
- Get-PSRuleBaseline
- Get-PSRuleHelp
- Invoke-PSRule
- Test-PSRuleTarget
- Using the
-Optionparameter with an object created with theNew-PSRuleOptioncmdlet. See cmdlet help for syntax and examples. - Using the
-Optionparameter with a hashtable object. - Using the
-Optionparameter with a YAML file path. ps-rule.yamlps-rule.ymlpsrule.yamlpsrule.ymlExecution.InconclusiveWarningis configured byPSRULE_EXECUTION_INCONCLUSIVEWARNING.Input.TargetTypeis configured byPSRULE_INPUT_TARGETTYPE.Output.Formatis configured byPSRULE_OUTPUT_FORMAT.- Enum values are set by string. For example
PSRULE_OUTPUT_FORMATcould be set toYaml. Enum values are case-insensitive. - Boolean values are set by
true,false,1, or0. For examplePSRULE_EXECUTION_INCONCLUSIVEWARNINGcould be set tofalse. Boolean values are case-insensitive. - String array values can specify multiple items by using a semi-colon separator. For example
PSRULE_INPUT_TARGETTYPEcould be set tovirtualMachine;virtualNetwork. - By default PSRule will not extract any custom fields.
- If custom fields are configured, PSRule will attempt to bind the field.
- If none of the configured property names exist, the field will be skipped.
- If more then one property name is configured, the order they are specified in the configuration determines precedence.
- i.e. The first configured property name will take precedence over the second property name.
- By default the property name will be matched ignoring case sensitivity. To use a case sensitive match, configure the Binding.IgnoreCase option.
- By default, custom property binding finds the first matching property by name regardless of case. i.e.
Binding.IgnoreCaseistrue. - To make custom bindings case sensitive, set the
Binding.IgnoreCaseoption tofalse.- Changing this option will affect custom property bindings for both TargetName and TargetType.
- Setting this option has no affect on binding defaults or custom scripts.
- By default PSRule will:
- Use
TargetNameorNameproperties on the object. These property names are case insensitive. - If both
TargetNameandNameproperties exist,TargetNamewill take precedence overName. - If neither
TargetNameorNameproperties exist, a hash of the object will be used as TargetName. - The hash algorithm used can be set by the
Execution.HashAlgorithmoption.
- Use
- If custom TargetName binding properties are configured, the property names specified will override the defaults.
- If none of the configured property names exist, PSRule will revert back to
TargetNamethenName. - If more then one property name is configured, the order they are specified in the configuration determines precedence.
- i.e. The first configured property name will take precedence over the second property name.
- By default the property name will be matched ignoring case sensitivity. To use a case sensitive match, configure the Binding.IgnoreCase option.
- If none of the configured property names exist, PSRule will revert back to
- If a custom TargetName binding function is specified, the function will be evaluated first before any other option.
- If the function returns
$Nullthen custom properties,TargetNameandNameproperties will be used. - The custom binding function is executed outside the PSRule engine, so PSRule keywords and variables will not be available.
- Custom binding functions are blocked in constrained language mode is used. See language mode for more information.
- If the function returns
- By default PSRule will:
- Use the default type presented by PowerShell from
TypeNames. i.e..PSObject.TypeNames[0]
- Use the default type presented by PowerShell from
- If custom TargetType binding properties are configured, the property names specified will override the defaults.
- If none of the configured property names exist, PSRule will revert back to the type presented by PowerShell.
- If more then one property name is configured, the order they are specified in the configuration determines precedence.
- i.e. The first configured property name will take precedence over the second property name.
- By default the property name will be matched ignoring case sensitivity. To use a case sensitive match, configure the
Binding.IgnoreCaseoption.
- If a custom TargetType binding function is specified, the function will be evaluated first before any other option.
- If the function returns
$Nullthen custom properties, or the type presented by PowerShell will be used in order instead. - The custom binding function is executed outside the PSRule engine, so PSRule keywords and variables will not be available.
- Custom binding functions are blocked in constrained language mode is used. See language mode for more information.
- If the function returns
None(0) - No preference. Inherits the default ofWarn.Ignore(1) - Continue to execute silently.Warn(2) - Continue to execute but log a warning. This is the default.Error(3) - Abort and throw an error.Debug(4) - Continue to execute but log a debug message.None(0) - No preference. Inherits the default ofError.Ignore(1) - Continue to execute silently.Warn(2) - Continue to execute but log a warning.Error(3) - Abort and throw an error. This is the default.Debug(4) - Continue to execute but log a debug message.SHA512SHA384SHA256FullLanguage- Executes with all language features. This is the default.ConstrainedLanguage- Executes in constrained language mode that restricts the types and methods that can be used.None(0) - No preference. Inherits the default ofWarn.Ignore(1) - Continue to execute silently.Warn(2) - Continue to execute but log a warning. This is the default.Error(3) - Abort and throw an error.Debug(4) - Continue to execute but log a debug message.BuiltIn(0) - Create the initial session state with all built-in cmdlets loaded. This is the default.Minimal(1) - Create the initial session state with only a minimum set of cmdlets loaded.Unrestricted- PowerShell language features are allowed from workspace and modules. This is the default.ModuleOnly- PowerShell language features are allowed from loaded modules, but script files within the workspace are ignored.DisablePowerShell- No PowerShell language features are used during PSRule run. When this mode is used, rules and conventions written in PowerShell will not execute. Modules that use PowerShell rules and conventions may not work as expected.None(0) - No preference. Inherits the default ofWarn.Ignore(1) - Continue to execute silently.Warn(2) - Continue to execute but log a warning. This is the default.Error(3) - Abort and throw an error.Debug(4) - Continue to execute but log a debug message.None(0) - No preference. Inherits the default ofWarn.Ignore(1) - Continue to execute silently.Warn(2) - Continue to execute but log a warning. This is the default.Error(3) - Abort and throw an error.Debug(4) - Continue to execute but log a debug message.None(0) - No preference. Inherits the default ofIgnore.Ignore(1) - Continue to execute silently. This is the default.Warn(2) - Continue to execute but log a warning.Error(3) - Abort and throw an error.Debug(4) - Continue to execute but log a debug message.None(0) - No preference. Inherits the default ofWarn.Ignore(1) - Continue to execute silently.Warn(2) - Continue to execute but log a warning. This is the default.Error(3) - Abort and throw an error.Debug(4) - Continue to execute but log a debug message.None(0) - No preference. Inherits the default ofWarn.Ignore(1) - Continue to execute silently.Warn(2) - Continue to execute but log a warning. This is the default.Error(3) - Abort and throw an error.Debug(4) - Continue to execute but log a debug message.- Modules specified with
Include.Moduleare combined with-Module. Both sets of modules will be imported and used using execution. - Paths specified with
Include.Pathare combined with-Path. Both sets of paths will be imported and used using execution. - The
Include.Pathoption defaults to.ps-rule/. To override this default, specify one or more alternative paths or an empty array. - None - Treat strings as plain text and do not deserialize files.
- Yaml - Deserialize as one or more YAML objects.
- Json - Deserialize as one or more JSON objects.
- Markdown - Deserialize as a markdown object.
- PowerShellData - Deserialize as a PowerShell data object.
- File - Files are not deserialized.
- Detect - Detect format based on file extension. This is the default.
- Yaml -
.yamlor.yml - Json -
.jsonor.jsonc - Markdown -
.mdor.markdown - PowerShellData -
.psd1 README.md.DS_Store.gitignore.gitattributes.gitmodulesLICENSELICENSE.txtCODE_OF_CONDUCT.mdCONTRIBUTING.mdSECURITY.mdSUPPORT.md.vscode/*.json.vscode/*.code-snippets.github/**/*.md.github/CODEOWNERS.pipelines/**/*.yml.pipelines/**/*.yaml.azure-pipelines/**/*.yml.azure-pipelines/**/*.yaml.azuredevops/*.md[Discovery.Source]- Discovery messages for.Rule.ps1files and rule modules.[Discovery.Rule]- Discovery messages for individual rules within.Rule.ps1files.[Discovery.Source]- Discovery messages for.Rule.ps1files and rule modules.[Discovery.Rule]- Discovery messages for individual rules within.Rule.ps1files.- None
- Error
- Warning
- Information
- None
- Error
- Warning
- Information
- Detail - Return a record per rule per object.
- Summary - Return summary results.
Title(1) - Shows the PSRule title ASCII text.Source(2) - Shows rules module versions used in this run.SupportLinks(4) - Shows supporting links for PSRule and rules modules.RepositoryInfo(8) - Show information about the repository where PSRule is being run from.Default- ShowsTitle,Source,SupportLinks,RepositoryInfo. This is the default option.Minimal- ShowsSource.- Default
- UTF-8
- UTF-7
- Unicode
- UTF-32
- ASCII
RuleCount(1) - Shows a summary of rules processed.RunInfo(2) - Shows information about the run.OutputFile(4) - Shows information about the output file if an output path is set.Default- ShowsRuleCount,RunInfo, andOutputFile. This is the default option.- None - Output is presented as an object using PowerShell defaults. This is the default.
- Yaml - Output is serialized as YAML.
- Json - Output is serialized as JSON.
- Markdown - Output is serialized as Markdown.
- NUnit3 - Output is serialized as NUnit3 (XML).
- Csv - Output is serialized as a comma-separated values (CSV).
- The following columns are included for
Detailoutput: RuleName, TargetName, TargetType, Outcome, OutcomeReason, Synopsis, Recommendation - The following columns are included for
Summaryoutput: RuleName, Pass, Fail, Outcome, Synopsis, Recommendation
- The following columns are included for
- Wide - Output is presented using the wide table format, which includes reason and wraps columns.
- Sarif - Output is serialized as SARIF.
None(0) - Results for rules that did not get processed are returned. This include rules that have been suppressed or were not run against a target object.Fail(1) - Results for rules that failed are returned.Pass(2) - Results for rules that passed are returned.Error(4) - Results for rules that raised an error are returned.Processed- Results for rules with theFail,Pass, orErroroutcome. This is the default option.Problem- Results for rules with theFail, orErroroutcome.All- All results for rules are returned.Client- Output is written to the host directly in green/ red to indicate outcome.Plain- Output is written as an unformatted string. This option can be redirected to a file.AzurePipelines- Output is written for integration Azure Pipelines.GitHubActions- Output is written for integration GitHub Actions.VisualStudioCode- Output is written for integration with Visual Studio Code.Detect- Output style will be detected by checking the environment variables. This is the default.- If the
TF_BUILDenvironment variable is set totrue,AzurePipelineswill be used. - If the
GITHUB_ACTIONSenvironment variable is set totrue,GitHubActionswill be used. - If the
TERM_PROGRAMenvironment variable is set tovscode,VisualStudioCodewill be used. - Use
Client. - In GitHub Actions, the repository URL is detected from the
GITHUB_REPOSITORYenvironment variable. - In Azure Pipelines, the repository URL is detected from the
BUILD_REPOSITORY_URIenvironment variable. - A temporary exclusion for an object that is in a known failed state.
- An object should never be processed by any rule. Pre-filter the pipeline instead.
- The rule is not applicable because the object is the wrong type. Use pre-conditions on the rule instead.
- Invoke-PSRule
- New-PSRuleOption
- Set-PSRuleOption
- Each rule is defined PowerShell within a
.Rule.ps1file by using aRuleblock. - PowerShell variables, functions, and cmdlets can be used just like regular PowerShell scripts.
- Built-in assertion helpers can be used to quickly build out rules.
- Pre-conditions can be defined with using a script block, type binding, or YAML-based selector.
- Each rule is defined in a
.Rule.yamlfile by using theRuleresource. - YAML-based expressions can be used.
- Pre-conditions can be defined with using a type binding, or YAML-based selector.
- Script - A PowerShell script block that is executed and if true will cause the rule to be executed. Script block pre-conditions only work with script rules. To use a script block pre-condition, specify the
-Ifscript parameter on theRuleblock. - Type - A type string that is compared against the bound object type. When the type matches the rule will be executed. To use a type pre-conditions, specify the
-Typescript parameter ortypeYAML/JSON property. - Selector - A YAML/JSON based expression that is evaluated against the object. When the expression matches the rule will be executed. To use a selector pre-conditions, specify the
-Withscript parameter orwithYAML/JSON property. - Invoke-PSRule
- A selector is a YAML/JSON based expression that evaluates an object.
- Each selector is comprised of nested conditions, operators, and comparison properties.
- Selectors must use one or more available conditions with a comparison property to evaluate the object.
- Optionally a condition can be nested in an operator.
- Operators can be nested within other operators.
- Contains
- Count
- Equals
- EndsWith
- Exists
- Greater
- GreaterOrEquals
- HasDefault
- HasSchema
- HasValue
- In
- IsLower
- IsString
- IsArray
- IsBoolean
- IsDateTime
- IsInteger
- IsNumeric
- IsUpper
- Less
- LessOrEquals
- Match
- NotEquals
- NotIn
- NotMatch
- SetOf
- StartsWith
- Subset
- Version
- AllOf
- AnyOf
- Not
- Field
- Name
- Type
- Selectors can evaluate:
- Fields of the target object.
- Type and name binding of the target object by using
nameandtypecomparison properties.
- State variables such has
$PSRulecan not be evaluated. - Bound fields can not be evaluated.
- Invoke-PSRule
- Ignore test objects by name.
- Ignore test objects by type.
- Ignore objects with non-production tag.
- Invoke-PSRule
- $Assert
- $Configuration
- $LocalizedData
- $PSRule
- $Rule
- $TargetObject
Contains- The field value must contain at least one of the strings.EndsWith- The field value must match at least one suffix.FileHeader- The file must contain a comment header.FilePath- The file path must exist.Greater- The field value must be greater.GreaterOrEqual- The field value must be greater or equal to.HasDefaultValue- The object should not have the field or the field value is set to the default value.HasField- The object must have any of the specified fields.HasFields- The object must have all of the specified fields.HasFieldValue- The object must have the specified field and that field is not empty.HasJsonSchema- The object must reference a JSON schema with the$schemafield.In- The field value must be included in the set.IsArray- The field value must be an array.IsBoolean- The field value must be a boolean.IsInteger- The field value must be an integer.IsLower- The field value must include only lowercase characters.IsNumeric- The field value must be a numeric type.IsString- The field value must be a string.IsUpper- The field value must include only uppercase characters.JsonSchema- The object must validate successfully against a JSON schema.Less- The field value must be less.LessOrEqual- The field value must be less or equal to.Match- The field value matches a regular expression pattern.NotIn- The field value must not be included in the set.NotMatch- The field value does not match a regular expression pattern.NullOrEmpty- The object must not have the specified field or it must be empty.TypeOf- The field value must be of the specified type.StartsWith- The field value must match at least one prefix.Version- The field value must be a semantic version string.- Configuration keys are case sensitive.
- Configuration values are read only.
- Configuration values can be accessed through helper methods.
GetStringValues(string configurationKey)- Returns an array of strings, based onconfigurationKey.- If the rules are loose (not part of a module), PSRule will search for
PSRule-rules.psd1in the.\\<culture>\\subdirectory relative to where the rule script .ps1 file is located. - When the rules are shipped as part of a module, PSRule will search for
PSRule-rules.psd1in the.\\<culture>\\subdirectory relative to where the module manifest .psd1 file is located. - Message names are case sensitive.
- Message values are read only.
Badges- A helper to generate badges within PSRule. This property can only be called within the-Endblock of a convention.Field- A hashtable of custom bound fields. See optionBinding.Fieldfor more information.Input- Allows adding additional input paths to the pipeline.Repository- Provides access to information about the current repository.Scope- Any scopes assigned to the object currently being processed by the pipeline.Source- A collection of sources for the object currently being processed on the pipeline.TargetObject- The object currently being processed on the pipeline.TargetName- The name of the object currently being processed on the pipeline. This property will automatically default toTargetNameorNameproperties of the object if they exist.TargetType- The type of the object currently being processed on the pipeline. This property will automatically bind toPSObject.TypeNames[0]by default.Output- The output of all rules. This property can only be called within the-Endblock of a convention.Data- A hashtable of custom data. This property can be populated during rule or begin/ process convention execution. Custom data is not used by PSRule directly, and is intended to be used by downstream processes that need to interpret PSRule results.GetContent(PSObject sourceObject)- Returns the content of a file as one or more objects. The parametersourceObjectshould be aInputFileInfo,FileInfo, orUriobject.GetContentField(PSObject sourceObject, string field)- Returns the content of a file as one or more objects. The parametersourceObjectshould be aInputFileInfo,FileInfo, orUriobject. The parameterfieldis an field within each object to return. If the field does not exist on the object, an object is not returned.GetContentFirstOrDefault(PSObject sourceObject)- Returns the content of a file as on object. The parametersourceObjectshould be aInputFileInfo,FileInfo, orUriobject. If more than one object is contained in the file, only the first object is returned. When the source file contains no objects null is returned.Import(PSObject[] sourceObject)- Imports one or more source objects into the pipeline. This method can only be called within the-Initializeor-Beginblock of a convention. Use this method to expand an object into child objects that will be processed independently. Objects imported using this method will be excluded from theInput.ObjectPathoption if set.ImportWithType(string type, PSObject[] sourceObject)- Imports one or more source objects into the pipeline. This method can only be called within the-Initializeor-Beginblock of a convention. Use this method to expand an object into child objects that will be processed independently. Objects imported using this method will be excluded from theInput.ObjectPathoption if set. WhenBinding.PreferTargetInfois true, the type will be automatically used as theTargetTypefor the imported object.AddService(string id, object service)- Add a service to the current context. The service can be retrieved using$PSRule.GetService(id). The service object will be available to all rules and cleaned up after all rules are executed. Services should implement theIDisposableinterface to perform additional cleanup. This method can only be called within the-Initializeblock of a convention.GetService(string id)- Retrieves a service previously added by a convention.GetPath(object sourceObject, string path)- Evalute an object path expression and returns the resulting objects.RuleName- The name of the rule.RuleId- A unique identifier for the rule.- Invoke-PSRule
- run \u2014 Run rules against an input path and output the results.
- module \u2014 Manage or restore modules tracked by the module lock file and configured options.
- module init
- module list
- module add
- module remove
- module restore
- module upgrade
--force- Force the creation of a new lock file, even if one already exists.--version- Specifies a specific version of the module to add. By default, the latest stable version of the module is added. Any required version constraints set by theRequiresoption are taken into consideration.--force- Restore modules even when an existing version that meets constraints is already installed locally.Pass- Results for rules that passed.Fail- Results for rules that did not pass.Error- Results for rules that raised an error are returned.Processed- All results that were processed. This aggregated outcome includesPass,Fail, orErrorresults.Problem- Processed results that did not pass. This aggregated outcome includesFail, orErrorresults.- Transformation \u2014 you need to perform minor transformation before a condition.
- Configuration \u2014 you want to configure an input into a condition.
boolean- Convert a value to a boolean.concat- Concatenate multiple values.configuration- Get a configuration value.first- Return the first element in an array or the first character of a string.integer- Convert a value to an integer.last- Return the last element in an array or the last character of a string.padLeft- Pad a value with a character on the left to meet the specified length.padRight- Pad a value with a character on the right to meet the specified length.path- Get a value from an object path.replace- Replace an old string with a new string.split- Split a string into an array by a delimiter.string- Convert a value to a string.substring- Extract a substring from a string.trim- Remove whitespace from the start and end of a string.equalsnotEqualscountlesslessOrEqualsgreatergreaterOrEquals- Create a standalone rule
- Expressions
- Sub-selectors
- Pre-conditions \u2014 you want to filtering out objects before a rule is run.
- Object filtering \u2014 you want to limit a condition to specific elements in a list of items.
- The
whereproperty is the start of a sub-selector. - The sub-selector checks if the
kindproperty equalsapi. - The object does not have a
kindproperty. OR - The value of the
kindproperty is notapi. - If the array property
resourcesexists, any items with a type ofMicrosoft.Web/sites/configare evaluated.- Each item must have the
properties.detailedErrorLoggingEnabledproperty set totrueto pass. - Items without the
properties.detailedErrorLoggingEnabledproperty fail. - Items with the
properties.detailedErrorLoggingEnabledproperty set to a value other thentruefail.
- Each item must have the
- If the
resourcesproperty does not exist, the rule fails. - If the
resourcesproperty exists but has 0 items of typeMicrosoft.Web/sites/config, the rule fails. - If the
resourcesproperty exists and has any items of typeMicrosoft.Web/sites/configbut any fail, the rule fails. - If the
resourcesproperty exists and has any items of typeMicrosoft.Web/sites/configand all pass, the rule passes. - The
resourcesproperty doesn't exist. OR - The
resourcesproperty doesn't contain any items that match the sub-selector condition. - Use a pre-condition to avoid running the rule.
- Group the sub-selector into a
anyOf, and provide a secondary condition. - Use a quantifier to determine how many items must match sub-selector and match the
allOf/anyOfoperator. - If the array property
resourcesexists, any items with a type ofMicrosoft.Web/sites/configare evaluated.- Each item must have the
properties.detailedErrorLoggingEnabledproperty set totrueto pass. - Items without the
properties.detailedErrorLoggingEnabledproperty fail. - Items with the
properties.detailedErrorLoggingEnabledproperty set to a value other thentruefail.
- Each item must have the
- If the
resourcesproperty does not exist, the rule passes. - If the
resourcesproperty exists but has 0 items of typeMicrosoft.Web/sites/config, the rule fails. - If the
resourcesproperty exists and has any items of typeMicrosoft.Web/sites/configbut any fail, the rule fails. - If the
resourcesproperty exists and has any items of typeMicrosoft.Web/sites/configand all pass, the rule passes. - Selected by the sub-selector.
- Match the condition of the operator.
count\u2014 The number of items must equal then the specified value.less\u2014 The number of items must less then the specified value.lessOrEqual\u2014 The number of items must less or equal to the specified value.greater\u2014 The number of items must greater then the specified value.greaterOrEqual\u2014 The number of items must greater or equal to the specified value.- If the array property
resourcesexists, any items with a type ofMicrosoft.Web/sites/configare evaluated.- Each item must have the
properties.detailedErrorLoggingEnabledproperty set totrueto pass. - The number of items that pass must be greater or equal to
1.
- Each item must have the
- If the
resourcesproperty does not exist or is empty, the number of items is0which fails greater or equal to1. - Create a standalone rule
- Functions
- Expressions
- Rule - Creates a rule definition.
- AnyOf - Assert that any of the child expressions must be true.
- AllOf - Assert that all of the child expressions must be true.
- Exists - Assert that a field or property must exist.
- Match - Assert that the field must match any of the regular expressions.
- Reason - Return a reason for why the rule failed.
- Recommend - Return a recommendation to resolve the issue and pass the rule.
- TypeOf - Assert that the object must be of a specific type.
- Within - Assert that the field must match any of the values.
- Exists - Assert that a field or property must exist.
- Match - Assert that the field must match any of the regular expressions.
- TypeOf - Assert that the object must be of a specific type.
- Within - Assert that the field must match any of the values.
Name- The name of the rule definition. Each rule name must be unique. When packaging rules within a module, rule names must only be unique within the module.Ref- An optional stable and opaque identifier that can be used to reference the rule.Alias- A list of alternative names that can be used to reference the rule.Tag- A hashtable of key/ value metadata that can be used to filter and identify rules and rule results.When- A selector precondition that must evaluate true before the rule is executed.Type- A type precondition that must match the TargetType of the pipeline object before the rule is executed.If- A script precondition that must evaluate to$Truebefore the rule is executed.DependsOn- A list of rules this rule depends on. Rule dependencies must execute successfully before this rule is executed.Configure- A set of default configuration values. These values are only used when the baseline configuration does not contain the key.ErrorAction- The action to take when an error occur. Only a subset of preferences are supported, eitherStoporIgnore. When-ErrorActionis not specified the default preference isStop. When errors are ignored a rule will pass or fail based on the rule condition. Uncaught exceptions will still cause rule return an error outcome.Body- A script block that specifies one or more conditions that are required for the rule to Pass.- Rule conditions should only return
$Trueor$False. Other objects should be caught withOut-Nullor null assigned like$Null = SomeCommand. - The
Rulekeyword can not be nested in aRuledefinition. - Variables and functions defined within
.Rule.ps1files, but outside theRuledefinition block are not accessible unless theGlobalscope is applied. - Functions and variables within the caller's scope (the scope calling
Invoke-PSRule,Get-PSRule,Test-PSRuleTarget) are not accessible. - Cmdlets that require user interaction are not supported, i.e.
Read-Host. - Script preconditions can contain
Exists,Match,TypeOfandWithinkeywords. Field- One or more fields/ properties that must exist on the pipeline object.CaseSensitive- The field name must match exact case.Not- Instead of checking if the field names exists they should not exist.All- All fields must exist on the pipeline object, instead of only one.Reason- A custom reason provided if the condition fails.InputObject- Supports objects being piped directly.Field- The name of the field that will be evaluated on the pipeline object.Expression- One or more regular expressions that will be used to match the value of the field.CaseSensitive- The field value must match exact case.Not- Instead of checking the field value matches, the field value must not match any of the expressions.Reason- A custom reason provided if the condition fails.InputObject- Supports objects being piped directly.Field- The name of the field that will be evaluated on the pipeline object.Value- A list of values that the field value must match.CaseSensitive- The field value must match exact case. Only applies when the field value and allowed values are strings.Not- Instead of checking the field value matches, the field value must not match any of the supplied values.Like- Instead of using an exact match, a wildcard match is used. This switch can only be used whenValuea string type.Reason- A custom reason provided if the condition fails.InputObject- Supports objects being piped directly.Body- A script block definition of the containing one or more PSRule keywords and PowerShell expressions.Body- A script block definition of the containing one or more PSRule keywords and PowerShell expressions.TypeName- One or more type names which will be evaluated against the pipeline object.TypeNameis case sensitive.Reason- A custom reason provided if the condition fails.InputObject- Supports objects being piped directly.Text- A message that includes the reason for the failure.Text- A message that includes the process to resolve the issue and pass the rule.- [Invoke-PSRule]
- Use a short
Synopsis:to describe your rule in a line comment above your rule. This will be shown in output as the default recommendation. For this to be interpreted by PSRule, only a single line is allowed. - Name your rule with a unique name
Yaml.FileType. - The
typeproperty ensures the rule will only run for file info objects. Other objects that might be piped to PSRule will be skipped by theYaml.FileTyperule. - The
conditionproperty determines the checks PSRule will use to test each file returned withGet-ChildItem. Specifically, theExtensionproperty of eachFileInfoobject will be compared. The value ofExtensionshould not be either.jpgor.png. - Use a short
Synopsis:to describe your rule in a line comment above your rule. This will be shown in output as the default recommendation. For this to be interpreted by PSRule, only a single line is allowed. - Name your rule with a unique name
Json.FileType. - The
typeproperty ensures the rule will only run for file info objects. Other objects that might be piped to PSRule will be skipped by theJson.FileTyperule. - The
conditionproperty determines the checks PSRule will use to test each file returned withGet-ChildItem. Specifically, theExtensionproperty of eachFileInfoobject will be compared. The value ofExtensionshould not be either.jpgor.png. - Use a short
Synopsis:to describe your rule in a line comment above your rule. This will be shown in output as the default recommendation. For this to be interpreted by PSRule, only a single line is allowed. - Name your rule with a unique name
PS.FileType. - The
-Typeparameter ensures the rule will only run for file info objects. Other objects that might be piped to PSRule will be skipped by thePS.FileTyperule. - The condition contained within the curly braces
{ }determines the checks PSRule will use to test each file returned withGet-ChildItem. - The
$Assert.NotInmethod checks theExtensionproperty is not set to.jpgor.png. - If you didn't get any results with
Failtry creating or saving a.jpgfile in pathToSeach. -
If you have too many
Passresults you can filter the output to only fails by using-Outcome Fail. For example:$files | Invoke-PSRule -Path $rulePath -Outcome Fail\n - Find any services that are set to start automatically with
StartTypebeginning withAutomatic. - Fail for any service with a
Statusother thanRunning. - If the selector is
truethen the rule will be run and either pass or fail. - If the selector is
falsethen the rule will be skipped. - Use a short
Synopsis:to describe your selector in a line comment above your rule. - Name your selector with a unique name
Yaml.IsAutomaticService. - The
ifproperty determines if PSRule will evaluate the service rule. Specifically, theStartTypeproperty of each service object will be compared. The value ofStartTypemust start withAutomatic. - The
convertproperty automatically converts the enum type ofStartTypeto a string. - Use a short
Synopsis:to describe your selector in a line comment above your rule. - Name your selector with a unique name
Json.IsAutomaticService. - The
ifproperty determines if PSRule will evaluate the service rule. Specifically, theStartTypeproperty of each service object will be compared. The value ofStartTypemust start withAutomatic. - The
convertproperty automatically converts the enum type ofStartTypeto a string. - Use a short
Synopsis:to describe your rule in a line comment above your rule. This will be shown in output as the default recommendation. For this to be interpreted by PSRule, only a single line is allowed. - Name your rule with a unique name
Yaml.ServiceStarted. - The
withproperty indicates to only run this rule on selected service objects. TheYaml.IsAutomaticServiceselector must first returntrueotherwise this rule will be skipped. - The
conditionproperty determines the checks PSRule will use to test each service. Specifically, theStatusproperty will be compared. The value ofStatusmust beRunning. - The
convertproperty automatically converts the enum type ofStatusto a string. - Use a short
Synopsis:to describe your rule in a line comment above your rule. This will be shown in output as the default recommendation. For this to be interpreted by PSRule, only a single line is allowed. - Name your rule with a unique name
Json.ServiceStarted. - The
withproperty indicates to only run this rule on selected service objects. TheJson.IsAutomaticServiceselector must first returntrueotherwise this rule will be skipped. - The
conditionproperty determines the checks PSRule will use to test each service. Specifically, theStatusproperty will be compared. The value ofStatusmust beRunning. - The
convertproperty automatically converts the enum type ofStatusto a string. - Use a short
Synopsis:to describe your rule in a line comment above your rule. This will be shown in output as the default recommendation. For this to be interpreted by PSRule, only a single line is allowed. - Name your rule with a unique name
PS.ServiceStarted. - The
-Withparameter indicates to only run this rule on selected service objects. TheYaml.IsAutomaticServiceselector must first returntrueotherwise this rule will be skipped. - The condition contained within the curly braces
{ }determines the checks PSRule will use to test each service object. - The
Statusenum property is converted to a string. - The
$Assert.HasFieldValuemethod checks the convertedStatusproperty is set toRunning. - Validate Azure resource configuration
- Validate Azure resources tags
- Validate Kubernetes resources
- Using within continuous integration
- Packaging rules in a module
- Writing rule help
- PSRule.Rules.Azure
- PSRule.Rules.CAF
- Defining a basic rule.
- Adding a recommendation.
- Using script pre-conditions.
- Using helper functions.
resources.json- An export for the Azure resource properties saved for offline use.- We use
storageAccounts.UseHttpsdirectly after theRulekeyword to name the rule definition. Each rule must be named uniquely. - The
# Synopsis:comment is used to add additional metadata interpreted by PSRule. - One or more conditions are defined within the curly braces
{ }. - The rule definition is saved within a file named
storageAccounts.Rule.ps1. - We use the
$TargetObjectvariable to get the object on the pipeline and access it's properties. - The condition will return
$Trueor$Falseback to the pipeline, where:$True- the object passed the validation check$False- the object failed the validation check
- Directly after the
Recommendkeyword is a message to help understand why the rule failed or passed. - A check against
$TargetObject.ResourceTypeensured that our rule is only processed for Storage Accounts. - storageAccounts.Rule.ps1 - Example rules for validating Azure Storage.
- appService.Rule.ps1 - Example rules for validating Azure App Service.
- resources.json - Offline export of Azure resources.
- common.Rule.ps1 - ResourceType helper function.
- Defining a basic rule.
- Basic usage of
Exists,WithinandMatchkeywords. - Using configuration in a rule definition.
- Setting configuration in YAML.
- Running rules with configuration.
resources.json- An export of Azure resource properties saved for offline use.- Tag names should be easy to read and understand.
- Tag names will use lower-camel/ pascal casing.
- The following mandatory tags will be used:
- environment: An operational environment for systems and services. Valid environments are production, testing and development.
- costCentre: A allocation account within financial systems used for charging costs to a business unit. A cost centre is a number with 5 digits and can't start with a 0.
- businessUnit: The name of the organizational unit or team that owns the application/ solution.
- We use
environmentTagdirectly after theRulekeyword to name the rule definition. Each rule must be named uniquely. - The
# Synopsis:comment is used to add additional metadata interpreted by PSRule. - One or more conditions are defined within the curly braces
{ }. - The rule definition is saved within a file named
azureTags.Rule.ps1. - We use the
Existskeyword to check if the environment tag exists. - The
-CaseSensitiveswitch is also used to ensure that the tag name uses lowercase. - The condition will return
$Trueor$Falseback to the pipeline, where:$True- the environment tag exists.$False- the environment tag does not exist.
- We use the
Withinkeyword to check if the environment tag uses any of the allowed values. - The
-CaseSensitiveswitch is also used to ensure that the tag value is only a lowercase environment name. - The condition will return
$Trueor$Falseback to the pipeline, where:$True- an allowed environment is used.$False- the environment tag does not use one of the allowed values.
$TargetObjectautomatic variable is used to get the pipeline object being evaluated.- We use the
-cinoperator to check the environment tag only uses allowed values. - The
-cinoperator performs a cases sensitive match on production, test and development. - The condition will return
$Trueor$Falseback to the pipeline, where:$True- an allowed environment is used.$False- the environment tag does not use one of the allowed values.
- We use the
Matchkeyword to check if the costCentre tag uses a numeric only value with 5 digits, not starting with 0. - The condition will return
$Trueor$Falseback to the pipeline, where:$True- the costCentre tag value matches the regular expression.$False- the costCentre tag value does not use match the regular expression.
$TargetObjectautomatic variable is used to get the pipeline object being evaluated.- We use the
-matchoperator to check the costCentre tag value matches the regular expression. - The condition will return
$Trueor$Falseback to the pipeline, where:$True- the costCentre tag value matches the regular expression.$False- the costCentre tag value does not use match the regular expression.
- We use the
Withinkeyword to check if the businessUnit tag uses any of the allowed values. allowedBusinessUnitsconfiguration value can be referenced using the syntax$Configuration.allowedBusinessUnits.- The rule definition is defined in azureTags.Rule.ps1.
- YAML configuration is defined in ps-rule.yaml.
- azureTags.Rule.ps1 - Example rules for validating Azure resource tagging standard rules.
- resources.json - Offline export of Azure resources.
- ps-rule.yaml - A YAML configuration file for PSRule.
- PSRule.Rules.Kubernetes
- Defining a basic rule.
- Configuring custom binding.
- Using a type precondition.
- Running rules using YAML input.
resources.yaml- A Kubernetes manifest containing deployments and services.- The following recommended labels will be used on all services and deployments:
app.kubernetes.io/name- the name of the application/ service.app.kubernetes.io/version- the version of the service.app.kubernetes.io/component- identifies the type of component, valid options areweb,api,databaseandgateway
- For
weborapideployments, a minimum of two (2) replicas must be used. - Deployments must use container images with a specific version tag, and not
latest. - Deployments must declare minimum and maximum memory/ CPU resources.
- We use
metadata.Namedirectly after theRulekeyword to name the rule definition. Each rule must be named uniquely. - The
# Synopsis:comment is used to add additional metadata interpreted by PSRule. - One or more conditions are defined within the curly braces
{ }. - The rule definition is saved within a file named
kubernetes.Rule.ps1. - Any valid PowerShell that returns a true (pass) when the condition is met or false (fail) when the condition is not met.
- More than one condition can be defined, if any condition returns false then the whole rule fails.
- We use the
Existskeyword to check that the resource has theapp.kubernetes.io/namelabel set.- By default, PSRule will step through nested properties separated by a
.. i.e.labelsis a property ofmetadata. - Kubernetes supports and recommends label namespaces, which often use
.in their name. PSRule supports this by enclosing the field name (app.kubernetes.io/name) in apostrophes (') so thatapp.kubernetes.io/nameis checked instead ofapp.
- By default, PSRule will step through nested properties separated by a
- Double apostrophes (
'') are used to encloseapp.kubernetes.io/namebecause the field name uses'at the start and end of the string instead of\"in the previous example. - The
Withinkeyword is used to validate that theapp.kubernetes.io/componentonly uses one of four (4) allowed values. metadata.nameto store the name of a resource.kindto store the type of resource.- TargetName is bound to
metadata.name - TargetType is bound to
kind - Type preconditions are one or more type names that PSRule compares to the
TargetTypebinding, where:- One of the type names names equal
TargetTypethe rule will be processed. - None of the type names equal
TargetTypethe rule be skipped.
- One of the type names names equal
- Script block preconditions is a PowerShell script block that returns true or false, where:
- True - Continue processing the rule.
- False - Skip processing the rule.
- We update our
metadata.Namerule to use the-Typeparameter to specify a type precondition of either Deployment or Service. - In a previous step,
TypeNamewas bound to thekindproperty which will be Deployment or Service for these resource types. - The built-in variable
$TargetObjectis used to get the current pipeline object.- Built-in keywords like
Existsautomatically default to$TargetObject, but can be piped alternative input as shown in the rule definition nameddeployment.ResourcesSet.
- Built-in keywords like
- The
-InputPathparameter is used to load objects from disk as YAML. YAML is automatically detected based on the.yamlfile extension. Alternatively the-Foramt Yamlparameter can be used. - Binding parameters are read from
ps-rule.yamlin the current working path. Alternatively the-Optionparameter could be used to specify an alternative file path. kubectlis called with the-o yamlto output resources as YAML.kubectlis piped toOut-Stringto convert the multi-line output to a single string.- The
-Formatparameter informs PSRule that the string is YAML and it should convert the string into structured objects. - The
-ObjectPathparameter is used with the output fromkubectl. This is required because the output fromkubectlis a collection of resources instead of individual resources. Specifically-ObjectPath itemsgets the resources from theitemsproperty of the output. - kubernetes.Rule.ps1 - Example rules for validating Kubernetes resources.
- resources.yaml - An example Kubernetes manifest.
- ps-rule.yaml - PSRule options configuration file.
- Installing within a CI pipeline.
- Validating objects.
- Formatting output.
- Failing the pipeline.
- Generating NUnit output.
- Additional options.
- When installing modules on Windows, modules will be installed into Program Files by default, which requires administrator permissions. Depending on your environment, the CI worker process may not have administrative permissions. Instead we can install PSRule for the current context running the CI pipeline by using the
-Scope CurrentUserparameter. - By default, this cmdlet will install the module from the PowerShell Gallery which is not trusted by default. Since a CI pipeline is not interactive, use the
-Forceswitch to suppress the confirmation prompt. - Use the
-OutputFormat NUnit3parameter. - Use the
-OutputPathparameter to specify the path of the report file to write. - pipeline-deps.ps1 - Example script installing pipeline dependencies.
- file.Rule.ps1 - Example rules for validating script files.
- validate-files.ps1 - Example script for running files validation.
- azure-pipelines.yaml - An example Azure DevOps Pipeline.
- YAML (
.yamlor.yml). - JSON (
.json). - PowerShell Data Files (
.psd1). - Markdown front matter (
.mdor.markdown). - 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.
- 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.
- 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.
- 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.
- Reuses existing skills within Microsoft and customers who already know how to author PowerShell scripts.
- Builds on existing PowerShell community; allowing existing integrations and cmdlets to be used.
- PowerShell already has an established model for distributing packages (modules). This includes options for trust and hosting (publicly or privately).
- Rules can be written using standard PowerShell operators and conventions. Minimal knowledge of PSRule should be required to author rules.
- Rules validate an object graph. Whether an object originates from a YAML or JSON file should be abstract.
- Implements a test for one or more conditions against an object. When all conditions return true the rule passes, if not the rule fails.
- Is evaluated by executing the rule within a sandbox that provides context to each rule. Such as the deserialized object being processed and configuration.
- Can specify preconditions which determine if a rule should be evaluated based on the object being processed. Rules only run against the objects they are designed to test.
Baseline- A reusable group of rules and configuration defaults for a given scenario.Selector- A reusable filter to determine which objects a rule should be run against.- Separation of rules or features in development. For infrastructure code or rules early in their lifecycle, a recommend practice may not be fully ratified. Baselines allow rules to be distributed but not executed by default.
- Progressive adoption. If validation has been added for a new use case, it may not be possible to adopt all rules at once. Baselines act as checkpoints to allow validation of a subset of rules.
- Begin: TBA
- Process: TBA
- End: TBA
- Invoke: Returns output as pipeline objects so they can be natively processed by PowerShell code.
- Assert: Returns output as styled text to provide readable results within a CI pipeline.
- Test: Returns true or false based on pass or fail of each object. Use this option to use filter objects from a PowerShell pipeline.
- In the parent runspace where PSRule is called using
Invoke-PSRule,Assert-PSRule, orTest-PSRule. The parent runspace is responsible for all input and output. - The sandbox runspace is where rules execute. PSRule keywords and automatic variables are implemented in the sandbox. Flow control within the PSRule pipeline maintains context for each object as it is processed by rules.
- Configuring the default
ps-rule.yamlfile. - Setting at runtime by passing a
-Optionparameter to PSRule cmdlets. - Parameter
- Local options
- Baseline
- Module configuration
v3.0.0-B0084 (pre-release) - April 15, 2024 + April 16, 2024 @@ -2990,14 +3009,14 @@
v3.0.0-B0084 (pre-release) - + -
+
- + -
Next steps - - - - GitHub - - - - - - diff --git a/v3/concepts/cli/run/index.html b/v3/concepts/cli/run/index.html index c93b3d3153..3c5956e5e5 100644 --- a/v3/concepts/cli/run/index.html +++ b/v3/concepts/cli/run/index.html @@ -2819,29 +2819,6 @@
Next steps - - - - GitHub - - - - - - diff --git a/v3/expressions/functions/index.html b/v3/expressions/functions/index.html index ebbeff2b55..2b14708f55 100644 --- a/v3/expressions/functions/index.html +++ b/v3/expressions/functions/index.html @@ -2819,29 +2819,6 @@
Recommended content - - - - GitHub - - - - - - diff --git a/v3/expressions/sub-selectors/index.html b/v3/expressions/sub-selectors/index.html index 1556dfcd9e..fdef204f16 100644 --- a/v3/expressions/sub-selectors/index.html +++ b/v3/expressions/sub-selectors/index.html @@ -3057,29 +3057,6 @@
Recommended content - - - - GitHub - - - - - - diff --git a/v3/keywords/PSRule/en-US/about_PSRule_Keywords/index.html b/v3/keywords/PSRule/en-US/about_PSRule_Keywords/index.html index b0277126ef..fd3759cb8c 100644 --- a/v3/keywords/PSRule/en-US/about_PSRule_Keywords/index.html +++ b/v3/keywords/PSRule/en-US/about_PSRule_Keywords/index.html @@ -3154,29 +3154,6 @@
Links# - - - - - - GitHub - - - - - - diff --git a/v3/quickstart/standalone-rule/index.html b/v3/quickstart/standalone-rule/index.html index ba3543afda..b61d9b562e 100644 --- a/v3/quickstart/standalone-rule/index.html +++ b/v3/quickstart/standalone-rule/index.html @@ -3188,29 +3188,6 @@
Testing service objects - - - - GitHub - - - - - - diff --git a/v3/search/search_index.json b/v3/search/search_index.json index bdbc7afc36..f6143ff73c 100644 --- a/v3/search/search_index.json +++ b/v3/search/search_index.json @@ -1 +1 @@ -{"config":{"lang":["en"],"separator":"[\\s\\-]+","pipeline":["stopWordFilter"]},"docs":[{"location":"CHANGELOG-v0/","title":"Change log","text":"
See upgrade notes for helpful information when upgrading from previous versions.
Attention
PSRule v0 is a prior release. For more information see v2 release notes. Please check out our upgrade notes to get prepared for upgrading to the latest version.
"},{"location":"CHANGELOG-v0/#v0220","title":"v0.22.0","text":"What's changed since v0.21.0:
What's changed since pre-release v0.22.0-B2010014:
What's changed since v0.21.0:
What's changed since v0.20.0:
What's changed since pre-release v0.21.0-B2010010:
What's changed since pre-release v0.21.0-B2010003:
What's changed since pre-release v0.21.0-B2009016:
What's changed since pre-release v0.21.0-B2009006:
What's changed since v0.20.0:
What's changed since v0.19.0:
What's changed since pre-release v0.20.0-B2009013:
What's changed since pre-release v0.20.0-B2009007:
What's changed since pre-release v0.20.0-B2008010:
What's changed since pre-release v0.20.0-B2008002:
What's changed since v0.19.0:
What's changed since v0.18.1:
What's changed since pre-release v0.19.0-B2007030:
What's changed since v0.18.0:
What's changed since v0.17.0:
What's changed since pre-release v0.18.0-B2005015:
What's changed since v0.16.0:
What's changed since pre-release v0.17.0-B2005010:
What's changed since v0.15.0:
What's changed since pre-release v0.16.0-B2003027:
What's changed since v0.14.0:
What's changed since pre-release v0.15.0-B2002031:
What's changed since v0.13.0:
What's changed since pre-release v0.14.0-B2002003:
What's changed since v0.12.0:
What's changed since pre-release v0.13.0-B2001013:
What's changed since v0.11.0:
What's changed since pre-release v0.12.0-B1912007:
What's changed since v0.10.0:
What's changed since pre-release v0.11.0-B1911002:
What's changed since v0.9.0:
What's changed since pre-release v0.10.0-B1910036:
What's changed since v0.8.0:
What's changed since pre-release v0.9.0-B190905:
What's changed since v0.7.0:
What's changed since pre-release v0.8.0-B190806:
What's changed since v0.6.0:
What's changed since pre-release v0.7.0-B190664:
What's changed since v0.5.0:
What's changed since pre-release v0.6.0-B190627:
What's changed since v0.4.0:
What's changed since pre-release v0.5.0-B190423:
What's changed since v0.3.0:
What's changed since pre-release v0.4.0-B190328:
What's changed since v0.2.0:
What's changed since pre-release v0.3.0-B190231:
What's changed since v0.1.0:
What's changed since pre-release v0.2.0-B190121:
What's changed since pre-release v0.1.0-B181235:
See upgrade notes for helpful information when upgrading from previous versions.
Important notes:
Attention
PSRule v1 is a prior release. For more information see v2 release notes. Please check out our upgrade notes to get prepared for upgrading to the latest version.
"},{"location":"CHANGELOG-v1/#v1111","title":"v1.11.1","text":"What's changed since v1.11.1:
What's changed since v1.10.0:
What's changed since pre-release v1.11.0-B2112016:
What's changed since v1.10.0:
What's changed since v1.9.0:
What's changed since pre-release v1.10.0-B2112002:
What's changed since pre-release v1.10.0-B2111024:
What's changed since v1.9.0:
What's changed since v1.8.0:
What's changed since pre-release v1.9.0-B2111024:
What's changed since pre-release v1.9.0-B2111009:
What's changed since pre-release v1.9.0-B2110027:
What's changed since pre-release v1.9.0-B2110015:
What's changed since v1.8.0:
What's changed since v1.7.2:
What's changed since pre-release v1.8.0-B2110030:
What's changed since pre-release v1.8.0-B2110020:
What's changed since pre-release v1.8.0-B2110006:
What's changed since pre-release v1.8.0-B2109022:
What's changed since pre-release v1.8.0-B2109015:
What's changed since v1.7.2:
What's changed since v1.7.1:
What's changed since v1.7.0:
What's changed since v1.6.0:
What's changed since pre-release v1.7.0-B2109002:
What's changed since pre-release v1.7.0-B2108032:
What's changed since pre-release v1.7.0-B2108021:
What's changed since pre-release v1.7.0-B2108016:
What's changed since v1.6.0:
What's changed since v1.6.0:
What's changed since v1.5.0:
What's changed since pre-release v1.6.0-B2108009:
What's changed since pre-release v1.6.0-B2108003:
What's changed since pre-release v1.6.0-B2107008:
What's changed since v1.5.0:
What's changed since v1.4.0:
What's changed since pre-release v1.5.0-B2107009:
What's changed since pre-release v1.5.0-B2106006:
What's changed since v1.4.0:
What's changed since v1.3.0:
What's changed since pre-release v1.4.0-B2105041:
What's changed since pre-release v1.4.0-B2105032:
What's changed since pre-release v1.4.0-B2105019:
What's changed since pre-release v1.4.0-B2105004:
What's changed since v1.3.0:
What's changed since v1.2.0:
What's changed since pre-release v1.3.0-B2105004:
What's changed since pre-release v1.3.0-B2104042:
What's changed since pre-release v1.3.0-B2104030:
What's changed since pre-release v1.3.0-B2104021:
What's changed since v1.2.0:
What's changed since v1.1.0:
What's changed since pre-release v1.2.0-B2103043:
What's changed since pre-release v1.2.0-B2103031:
What's changed since pre-release v1.2.0-B2103023:
What's changed since pre-release v1.2.0-B2103016:
What's changed since pre-release v1.2.0-B2103008:
What's changed since v1.1.0:
What's changed since v1.0.3:
What's changed since pre-release v1.1.0-B2102029:
What's changed since pre-release v1.1.0-B2102024:
What's changed since pre-release v1.1.0-B2102019:
What's changed since v1.0.3:
What's changed since v1.0.2:
What's changed since v1.0.1:
What's changed since v1.0.0:
What's changed since v0.22.0:
What's changed since pre-release v1.0.0-B2011028:
What's changed since v0.22.0:
See upgrade notes for helpful information when upgrading from previous versions.
Important notes:
Experimental features:
Attention
We are currently working towards the next release of PSRule. For more information see v3 release notes. Please check out our upgrade notes to get prepared for upgrading to the latest version.
"},{"location":"CHANGELOG-v2/#v290","title":"v2.9.0","text":"What's changed since release v2.8.1:
What's changed since pre-release v2.9.0-B0068:
What's changed since pre-release v2.9.0-B0033:
What's changed since pre-release v2.9.0-B0013:
What's changed since release v2.8.1:
What's changed since release v2.8.0:
What's changed since release v2.7.0:
What's changed since pre-release v2.8.0-B0171:
What's changed since pre-release v2.8.0-B0121:
What's changed since pre-release v2.8.0-B0076:
What's changed since pre-release v2.8.0-B0034:
What's changed since v2.7.0:
What's changed since v2.6.0:
What's changed since pre-release v2.7.0-B0126:
What's changed since pre-release v2.7.0-B0097:
What's changed since pre-release v2.7.0-B0070:
What's changed since pre-release v2.7.0-B0049:
What's changed since pre-release v2.7.0-B0031:
What's changed since pre-release v2.7.0-B0016:
What's changed since pre-release v2.7.0-B0006:
What's changed since pre-release v2.7.0-B0001:
What's changed since v2.6.0:
What's changed since v2.5.3:
What's changed since pre-release v2.6.0-B0034:
What's changed since pre-release v2.6.0-B0013:
What's changed since v2.5.3:
What's changed since v2.5.2:
What's changed since v2.5.1:
What's changed since v2.5.0:
What's changed since v2.4.2:
What's changed since pre-release v2.5.0-B0080:
What's changed since pre-release v2.5.0-B0045:
What's changed since pre-release v2.5.0-B0015:
What's changed since pre-release v2.5.0-B0004:
What's changed since v2.4.0:
What's changed since v2.4.1:
What's changed since v2.4.0:
What's changed since v2.3.2:
What's changed since pre-release v2.4.0-B0091:
What's changed since pre-release v2.4.0-B0063:
What's changed since pre-release v2.4.0-B0039:
What's changed since pre-release v2.4.0-B0022:
What's changed since pre-release v2.4.0-B0009:
What's changed since v2.3.2:
What's changed since v2.3.1:
What's changed since v2.3.0:
What's changed since v2.2.0:
What's changed since pre-release v2.3.0-B0163:
What's changed since pre-release v2.3.0-B0130:
What's changed since pre-release v2.3.0-B0100:
What's changed since pre-release v2.3.0-B0074:
What's changed since pre-release v2.3.0-B0051:
What's changed since pre-release v2.3.0-B0030:
What's changed since pre-release v2.3.0-B0015:
What's changed since pre-release v2.3.0-B0006:
What's changed since pre-release v2.3.0-B0001:
What's changed since v2.2.0:
What's changed since v2.1.0:
What's changed since pre-release v2.2.0-B0175:
What's changed since pre-release v2.2.0-B0131:
What's changed since pre-release v2.2.0-B0089:
What's changed since pre-release v2.2.0-B0052:
What's changed since pre-release v2.2.0-B0021:
What's changed since v2.1.0:
What's changed since v2.0.1:
What's changed since pre-release v2.1.0-B0069:
What's changed since pre-release v2.1.0-B0040:
What's changed since pre-release v2.1.0-B0015:
What's changed since v2.0.1:
What's changed since v2.0.0:
What's changed since v1.11.1:
What's changed since pre-release v2.0.0-B2203045:
What's changed since pre-release v2.0.0-B2203033:
What's changed since pre-release v2.0.0-B2203019:
What's changed since pre-release v2.0.0-B2202072:
What's changed since pre-release v2.0.0-B2202065:
What's changed since pre-release v2.0.0-B2202056:
What's changed since pre-release v2.0.0-B2202024:
What's changed since pre-release v2.0.0-B2202017:
What's changed since pre-release v2.0.0-B2202006:
What's changed since pre-release v2.0.0-B2201161:
What's changed since pre-release v2.0.0-B2201146:
What's changed since pre-release v2.0.0-B2201135:
What's changed since pre-release v2.0.0-B2201117:
What's changed since pre-release v2.0.0-B2201093:
What's changed since pre-release v2.0.0-B2201075:
What's changed since pre-release v2.0.0-B2201054:
What's changed since v1.11.0:
See upgrade notes for helpful information when upgrading from previous versions.
Experimental features:
What's changed since pre-release v3.0.0-B0153:
What's changed since pre-release v3.0.0-B0151:
What's changed since pre-release v3.0.0-B0141:
What's changed since pre-release v3.0.0-B0137:
What's changed since pre-release v3.0.0-B0122:
What's changed since pre-release v3.0.0-B0093:
What's changed since pre-release v3.0.0-B0084:
What's changed since release v2.9.0:
PSRule is a rules engine geared towards testing Infrastructure as Code (IaC). Rules you write or import perform static analysis on IaC artifacts such as: templates, manifests, pipelines, and workflows.
"},{"location":"about/#why-use-psrule","title":"Why use PSRule?","text":"PSRule aims to provide a rich experience for building and running static analysis tests on IaC. While this has some similarities to traditional testing frameworks it extends on the following:
You can send rule results to Azure Monitor using
"},{"location":"addon-modules/#pre-built-rules","title":"Pre-built rules","text":"PSRule.Monitor.The following modules contain pre-built rules that can be plugged into your pipeline.
Module Description Version / downloads PSRule.Rules.Azure A suite of rules to validate Azure resources and infrastructure as code (IaC) using PSRule. PSRule.Rules.Kubernetes A suite of rules to validate Kubernetes resources using PSRule. PSRule.Rules.CAF A suite of rules to validate Azure resources against the Cloud Adoption Framework (CAF) using PSRule. PSRule.Rules.GitHub A suite of rules to validate GitHub repositories using PSRule. PSRule.Rules.MSFT.OSS A suite of rules to validate repositories against Microsoft Open Source Software (OSS) requirements. PSRule.Monitor Log PSRule analysis results to Azure Monitor."},{"location":"analysis-output/","title":"Analysis output","text":"PSRule supports generating and saving output in a number of different formats.
Abstract
This topic covers the supported formats and options for presenting output from a PSRule run.
"},{"location":"analysis-output/#setting-the-output-format","title":"Setting the output format","text":"The output format can be configuring by setting the
Output.Formatoption to one the following:Tip
To write output to a file, also set the
GitHub ActionsAzure PipelinesPowerShellOptions fileOutput.Pathoption to the file path to save.# Analyze and save results\n- name: Analyze repository\n uses: microsoft/ps-rule@v2.9.0\n with:\n outputFormat: Sarif\n outputPath: reports/ps-rule-results.sarif\n
Invoke-PSRule# Analyze and save results\n- task: ps-rule-assert@2\n displayName: Analyze repository\n inputs:\n inputType: repository\n outputFormat: Sarif\n outputPath: reports/ps-rule-results.sarif\n
Assert-PSRuleInvoke-PSRule -OutputFormat Sarif -OutputPath reports/ps-rule-results.sarif\n
ps-rule.yamlAssert-PSRule -OutputFormat Sarif -OutputPath reports/ps-rule-results.sarif\n
"},{"location":"analysis-output/#formatting-as-yaml","title":"Formatting as YAML","text":"output:\n format: 'Sarif'\n path: reports/ps-rule-results.sarif\nWhen using the YAML output format, results a serialized as YAML. Two spaces are used to indent properties of objects.
Example output
"},{"location":"analysis-output/#formatting-as-json","title":"Formatting as JSON","text":"- data: {}\n info:\n displayName: Local.PS.RequireTLS\n name: Local.PS.RequireTLS\n synopsis: An example rule to require TLS.\n level: Error\n outcome: Fail\n outcomeReason: Processed\n reason:\n - The field 'configure.supportsHttpsTrafficOnly' is set to 'False'.\n - The field 'configure.minTLSVersion' does not exist.\n ruleName: Local.PS.RequireTLS\n runId: 16b0534165ffb5279beeb1672a251fc1ff3124b6\n source:\n - file: C:\\Dev\\Workspace\\PSRule\\docs\\authoring\\writing-rules\\settings.json\n line: 2\n position: 11\n type: File\n targetName: 1fe7c0f476b11301402d5017d87424c36ff085a8\n targetType: app1\n time: 0\nWhen using the JSON output format, results are serialized as JSON. By default, no indentation is used.
Example output
"},{"location":"analysis-output/#configuring-json-indentation","title":"Configuring JSON indentation","text":"[{\"data\":{},\"info\":{\"displayName\":\"Local.PS.RequireTLS\",\"name\":\"Local.PS.RequireTLS\",\"synopsis\":\"An example rule to require TLS.\"},\"level\":1,\"outcome\":\"Fail\",\"outcomeReason\":\"Processed\",\"reason\":[\"The field 'configure.supportsHttpsTrafficOnly' is set to 'False'.\",\"The field 'configure.minTLSVersion' does not exist.\"],\"ruleName\":\"Local.PS.RequireTLS\",\"runId\":\"df662aad3ae7adee6f35b9733c7aaa53dc4d6b96\",\"source\":[{\"file\":\"C:\\\\Dev\\\\Workspace\\\\PSRule\\\\docs\\\\authoring\\\\writing-rules\\\\settings.json\",\"line\":2,\"position\":11,\"type\":\"File\"}],\"targetName\":\"1fe7c0f476b11301402d5017d87424c36ff085a8\",\"targetType\":\"app1\",\"time\":0}]\nv1.8.0
The number of spaces used to indent properties and elements is configurable between
Example output with 2 spaces0to4spaces. By default, no indentation is used.
"},{"location":"analysis-output/#formatting-as-csv","title":"Formatting as CSV","text":"[\n {\n \"data\": {},\n \"info\": {\n \"displayName\": \"Local.PS.RequireTLS\",\n \"name\": \"Local.PS.RequireTLS\",\n \"synopsis\": \"An example rule to require TLS.\"\n },\n \"level\": 1,\n \"outcome\": \"Fail\",\n \"outcomeReason\": \"Processed\",\n \"reason\": [\n \"The field 'configure.supportsHttpsTrafficOnly' is set to 'False'.\",\n \"The field 'configure.minTLSVersion' does not exist.\"\n ],\n \"ruleName\": \"Local.PS.RequireTLS\",\n \"runId\": \"3afadfed32e57f5283ad71c1aa496da822ff0c84\",\n \"source\": [\n {\n \"file\": \"C:\\\\Dev\\\\Workspace\\\\PSRule\\\\docs\\\\authoring\\\\writing-rules\\\\settings.json\",\n \"line\": 2,\n \"position\": 11,\n \"type\": \"File\"\n }\n ],\n \"targetName\": \"1fe7c0f476b11301402d5017d87424c36ff085a8\",\n \"targetType\": \"app1\",\n \"time\": 0\n }\n]\nThe output from analysis can be formatted as comma-separated values (CSV). Formatting as CSV may be useful when manipulating output results by hand. Output of CSV format varies depending on if detailed or summary output is used.
For detailed output, the following columns are added to CSV output for each processed object:
Column DescriptionRuleNameThe name of the rule.TargetNameThe name of the object that was analyzed.TargetTypeThe type of the object that was analyzed.OutcomeThe outcome of the analysis, such asPassorFail.OutcomeReasonAn additional reason for the outcome such asInconclusive.SynopsisA short description of the rule.RecommendationThe recommendation of the rule.For summary output, the following columns are used:
Column DescriptionRuleNameThe name of the rule.PassThe number of objects that passed.FailThe number of objects that failed.OutcomeThe worst case outcome of the analysis, such asPassorFail.SynopsisA short description of the rule.RecommendationThe recommendation of the rule. Example output
"},{"location":"analysis-output/#formatting-as-sarif","title":"Formatting as SARIF","text":"RuleName,TargetName,TargetType,Outcome,OutcomeReason,Synopsis,Recommendation\n\"Local.PS.RequireTLS\",\"1fe7c0f476b11301402d5017d87424c36ff085a8\",\"app1\",\"Fail\",\"Processed\",\"An example rule to require TLS.\",\n\"Local.YAML.RequireTLS\",\"1fe7c0f476b11301402d5017d87424c36ff085a8\",\"app1\",\"Fail\",\"Processed\",\"An example rule to require TLS.\",\n\"Local.JSON.RequireTLS\",\"1fe7c0f476b11301402d5017d87424c36ff085a8\",\"app1\",\"Fail\",\"Processed\",\"An example rule to require TLS.\",\nv2.0.0
Static Analysis Results Interchange Format (SARIF) is a standard output format for static analysis tools. It enables various unrelated tools to consume analysis results from PSRule. You can use SARIF to perform Static Analysis Security Testing (SAST) in DevOps environments at-scale.
"},{"location":"analysis-output/#github-code-scanning-alerts","title":"GitHub code scanning alerts","text":"SARIF results from PSRule can be uploaded to GitHub to create code scanning alerts against a repository. You can see these results in your repository visible under Security > Code scanning alerts.
Tip
Code scanning is available for all public repositories, and for private repositories owned by organizations where GitHub Advanced Security is enabled. For more information, see About GitHub Advanced Security.
To configure GitHub Actions, perform the following steps:
Example
.github/workflows/analyze.yaml
"},{"location":"analysis-output/#azure-devops-scans-tab","title":"Azure DevOps scans tab","text":"name: Analyze\non:\n push:\n branches: [ main ]\n schedule:\n - cron: '24 22 * * 0' # At 10:24 PM, on Sunday each week\n workflow_dispatch:\n\njobs:\n oss:\n name: Analyze with PSRule\n runs-on: ubuntu-latest\n permissions:\n contents: read\n security-events: write\n steps:\n\n - name: Checkout\n uses: actions/checkout@v4\n\n - name: Run PSRule analysis\n uses: microsoft/ps-rule@v2.9.0\n with:\n outputFormat: Sarif\n outputPath: reports/ps-rule-results.sarif\n\n - name: Upload results to security tab\n uses: github/codeql-action/upload-sarif@v3\n with:\n sarif_file: reports/ps-rule-results.sarif\nSARIF results from PSRule can be uploaded and viewed within Azure DevOps. To add the scans tab to build results the SARIF SAST Scans Tab extension needs to be installed.
"},{"location":"analysis-output/#verifying-configuration","title":"Verifying configuration","text":"v3.0.0
The configuration used to run PSRule is included in properties of the run. This can be used to verify the configuration used to run PSRule.
"},{"location":"creating-your-pipeline/","title":"Creating your pipeline","text":"You can use PSRule to test Infrastructure as Code (IaC) artifacts throughout their lifecycle. By using validation within a continuous integration (CI) pipeline, any issues provide fast feedback.
Within the root directory of your IaC repository:
GitHub ActionsAzure PipelinesGeneric with PowerShellCreate a new GitHub Actions workflow by creating
.github/workflows/analyze-arm.yaml.name: Analyze templates\non:\n- pull_request\njobs:\n analyze_arm:\n name: Analyze templates\n runs-on: ubuntu-latest\n steps:\n\n - name: Checkout\n uses: actions/checkout@v4\n\n # Analyze Azure resources using PSRule for Azure\n - name: Analyze Azure template files\n uses: microsoft/ps-rule@v2.9.0\n with:\n modules: 'PSRule.Rules.Azure'\nThis will automatically install compatible versions of all dependencies.
Create a new Azure DevOps YAML pipeline by creating
.azure-pipelines/analyze-arm.yaml.steps:\n\n# Analyze Azure resources using PSRule for Azure\n- task: ps-rule-assert@2\n displayName: Analyze Azure template files\n inputs:\n inputType: repository\n modules: 'PSRule.Rules.Azure'\nThis will automatically install compatible versions of all dependencies.
Create a pipeline in any CI environment by using PowerShell.
$modules = @('PSRule.Rules.Azure')\nInstall-Module -Name $modules -Scope CurrentUser -Force -ErrorAction Stop;\nAssert-PSRule -InputPath '.' -Module $modules -Format File -ErrorAction Stop;\nTip
This example demonstrates using PSRule for Azure, a populate module for testing Azure IaC. Instead, you can write your own module or use one of our pre-built modules.
"},{"location":"creating-your-pipeline/#configuration","title":"Configuration","text":"Configuration options for PSRule are set within the
"},{"location":"creating-your-pipeline/#ignoring-rules","title":"Ignoring rules","text":"ps-rule.yamlfile.To prevent a rule executing you can either:
To exclude a rule, set
Rule.Excludeoption within theps-rule.yamlfile.[ Docs][3]
ps-rule.yamlrule:\n exclude:\n # Ignore the following rules for all objects\n - Azure.VM.UseHybridUseBenefit\n - Azure.VM.Standalone\nTo suppress an individual rule, set
Suppressionoption within theps-rule.yamlfile.[ Docs][4]
ps-rule.yamlsuppression:\n Azure.AKS.AuthorizedIPs:\n # Exclude the following externally managed AKS clusters\n - aks-cluster-prod-eus-001\n Azure.Storage.SoftDelete:\n # Exclude the following non-production storage accounts\n - storagedeveus6jo36t\n - storagedeveus1df278\nTo suppress an rules by condition, create a suppression group.
[ Docs][5]
---\n# Synopsis: Ignore test objects by name.\napiVersion: github.com/microsoft/PSRule/v1\nkind: SuppressionGroup\nmetadata:\n name: SuppressWithTargetName\nspec:\n rule:\n - 'FromFile1'\n - 'FromFile2'\n if:\n name: '.'\n in:\n - 'TestObject1'\n - 'TestObject2'\nTip
Use comments within
"},{"location":"creating-your-pipeline/#processing-changed-files-only","title":"Processing changed files only","text":"ps-rule.yamlto describe the reason why rules are excluded or suppressed. Meaningful comments help during peer review within a Pull Request (PR). Also consider including a date if the exclusions or suppressions are temporary.v2.5.0 \u00b7 Docs
To only process files that have changed within a pull request, set the
GitHub ActionsAzure PipelinesGeneric with PowerShellInput.IgnoreUnchangedPathoption.Update your GitHub Actions workflow by setting the
.github/workflows/analyze-arm.yamlPSRULE_INPUT_IGNOREUNCHANGEDPATHenvironment variable.name: Analyze templates\non:\n- pull_request\njobs:\n analyze_arm:\n name: Analyze templates\n runs-on: ubuntu-latest\n steps:\n\n - name: Checkout\n uses: actions/checkout@v4\n\n # Analyze Azure resources using PSRule for Azure\n - name: Analyze Azure template files\n uses: microsoft/ps-rule@v2.9.0\n with:\n modules: 'PSRule.Rules.Azure'\n env:\n PSRULE_INPUT_IGNOREUNCHANGEDPATH: true\nUpdate your Azure DevOps YAML pipeline by setting the
.azure-pipelines/analyze-arm.yamlPSRULE_INPUT_IGNOREUNCHANGEDPATHenvironment variable.steps:\n\n# Analyze Azure resources using PSRule for Azure\n- task: ps-rule-assert@2\n displayName: Analyze Azure template files\n inputs:\n inputType: repository\n modules: 'PSRule.Rules.Azure'\n env:\n PSRULE_INPUT_IGNOREUNCHANGEDPATH: true\nUpdate your PowerShell command-line to include the
PowerShellInput.IgnoreUnchangedPathoption.$modules = @('PSRule.Rules.Azure')\n$options = @{\n 'Input.IgnoreUnchangedPath' = $True\n}\nInstall-Module -Name $modules -Scope CurrentUser -Force -ErrorAction Stop;\nAssert-PSRule -Options $options -InputPath '.' -Module $modules -Format File -ErrorAction Stop;\nTip
In some cases it may be necessary to set
"},{"location":"deprecations/","title":"Deprecations","text":""},{"location":"deprecations/#deprecations-for-v3","title":"Deprecations for v3","text":""},{"location":"deprecations/#execution-options","title":"Execution options","text":"Repository.BaseRefto the default branch of your repository. By default, PSRule will detect the default branch of the repository from the build system environment variables.PSRule provides a number of execution options that control logging of certain events. In many cases these options turn a warning on or off.
These options are deprecated but replaced to provide more choice to when configuring logging options. Now you can configure the following:
The following execution options have been deprecated and will be removed from v3.
Tip
You do not need to configure both options. If you have the deprecated option configured, switch to the new option.
"},{"location":"deprecations/#rule-output-object","title":"Rule output object","text":"Several properties of the rule object have been renamed to improve consistency with other objects. Previously rules returned by
Get-PSRulereturned a rule object which included the following properties:These have been replaced with the following properties:
The changes apply from v2.1.0, however the old properties are still available for backwards compatibility. From v3 these properties will be removed. These changes do not affect normal usage of PSRule. Supporting scripts that directly use the old names may not work correctly until you update these names.
"},{"location":"deprecations/#language-block-interface","title":"Language block interface","text":"Several properties of Baselines and Selectors have been renamed to improve consistency.
These have been replaced with the following properties:
The changes apply from v2.1.0, however the old properties are still available for backwards compatibility. From v3 these properties will be removed. These changes do not affect normal usage of PSRule. Supporting scripts that directly use the old names may not work correctly until you update these names.
"},{"location":"deprecations/#deprecations-for-v2","title":"Deprecations for v2","text":""},{"location":"deprecations/#default-baseline-by-module-manifest","title":"Default baseline by module manifest","text":"When packaging baselines in a module, you may want to specify a default baseline. PSRule v1.9.0 added support for setting the default baseline in a module configuration.
Previously a default baseline could be set by specifying the baseline in the module manifest. From v1.9.0 this is deprecated and will be removed from v2.
For details on how to migrate to the new default baseline option, continue reading the upgrade notes.
"},{"location":"deprecations/#resources-without-an-api-version","title":"Resources without an API version","text":"When creating YAML and JSON resources you define a resource by specifying the
apiVersionandkind. To allow new schema versions for resources to be introduced in the future, anapiVersionwas introduced. For backwards compatibility, resources without anapiVersiondeprecated but supported. From v2 resources without anapiVersionwill be ignored.For details on how to add an
"},{"location":"faq/","title":"Frequently Asked Questions (FAQ)","text":""},{"location":"faq/#how-is-psrule-different-to-pester","title":"How is PSRule different to Pester?","text":"apiVersionto a resource, continue reading the upgrade notes.PSRule is a framework for testing infrastructure as code (IaC) and objects using rules. Rules can be written in PowerShell, YAML, or JSON. Some features include:
These features make PSRule ideal for validating:
If you want to test PowerShell code, consider using Pester, we do!
"},{"location":"faq/#what-pre-built-modules-are-available-for-psrule","title":"What pre-built modules are available for PSRule?","text":"PSRule rules modules can be found on the PowerShell Gallery using the tag
"},{"location":"faq/#how-do-i-configure-psrule","title":"How do I configure PSRule?","text":"PSRule-rules.PSRule and rules can be configured by:
For example:
# With cmdlet\n$option = New-PSRuleOption -OutputAs Summary -OutputCulture 'en-AU' -ExecutionUnprocessedObject 'Ignore' -Configuration @{\n CUSTOM_VALUE = 'example'\n}\n$items | Assert-PSRule -Option $option\n\n# With hashtable\n$items | Assert-PSRule -Option @{\n 'Output.As' = 'Summary'\n 'Output.Culture' = 'en-AU'\n 'Execution.UnprocessedObject' = 'Ignore'\n 'Configuration.CUSTOM_VALUE' = 'Example'\n}\n# With YAML\noutput:\n as: Summary\n culture: [ 'en-AU' ]\n\nexecution:\n unprocessedObject: Ignore\n\nconfiguration:\n CUSTOM_VALUE: Example\n# With environment variable in bash\nexport PSRULE_EXECUTION_UNPROCESSEDOBJECT=Ignore\nexport PSRULE_OUTPUT_AS=Summary\nexport PSRULE_OUTPUT_CULTURE=en-AU\nexport PSRULE_CONFIGURATION_CUSTOM_VALUE=Example\nFor a list of configuration options and usage see about_PSRule_Options.
"},{"location":"faq/#how-do-i-ignore-a-rule","title":"How do I ignore a rule?","text":"To prevent a rule executing you can either:
To exclude a rule use the
Rule.Excludeoption. To do this in YAML, add the following to theps-rule.yamloptions file.# YAML: Using the rule/exclude property\nrule:\n exclude:\n - 'My.FirstRule' # The name of the first rule to exclude.\n - 'My.SecondRule' # The name of the second rule to exclude.\nTo suppress a rule use the
Suppressionoption. To do this in YAML, add the following to theps-rule.yamloptions file.# YAML: Using the suppression property\nsuppression:\n My.FirstRule: # The name of the rule being suppressed\n - TestObject1 # The name of the first object to suppress\n - TestObject3 # The name of the second object to suppress\n My.SecondRule: # An additional rule to suppress\n - TestObject2\nThe name of the object is reported by PSRule in output results.
See about_PSRule_Options for additional usage for both of these options.
"},{"location":"faq/#how-do-exclude-or-ignore-files-from-being-processed","title":"How do exclude or ignore files from being processed?","text":"To exclude or ignore files from being processed, configure the Input.PathIgnore option. This option allows you to ignore files using a path spec.
For example:
input:\n pathIgnore:\n # Exclude files with these extensions\n - '*.md'\n - '*.png'\n # Exclude specific configuration files\n - 'bicepconfig.json'\nOr:
"},{"location":"faq/#how-do-i-disable-or-suppress-the-not-processed-warning","title":"How do I disable or suppress the not processed warning?","text":"input:\n pathIgnore:\n # Exclude all files\n - '*'\n # Only process deploy.bicep files\n - '!**/deploy.bicep'\nYou may receive a warning message suggesting a file or object has not been processed. If there are no rules that apply to the file or object this warning will be displayed.
Note
This warning is intended as a verification so that you are able to confirm your configuration is correct.
After you have tuned your configuration, you may wish to disable this warning to reduce output noise. To do this you have two options:
PSRule allows rules from modules and standalone (loose) rules to be run together.
To run rules from a standalone path use:
# Note: .ps-rule/ is a standard path to include standalone rules.\n\n# With input from the pipeline\n$items | Assert-PSRule -Path '.ps-rule/'\n\n# With input from file\nAssert-PSRule -Path '.ps-rule/' -InputPath 'src/'\nTo run rules from an installed module use:
# With input from the pipeline\n$items | Assert-PSRule -Module 'PSRule.Rules.Azure'\n\n# With input from file\nAssert-PSRule -Module 'PSRule.Rules.Azure' -InputPath 'src/'\nCombining both:
"},{"location":"faq/#why-should-i-use-psrule-keywords-and-assertions","title":"Why should I use PSRule keywords and assertions?","text":"Assert-PSRule -Module 'PSRule.Rules.Azure', 'PSRule.Rules.CAF' -Path '.ps-rule/' -InputPath 'src/'\nExcept for the
Rulekeyword, using the built-in language features are optional.The built-in keywords and assertions accelerate rule creation. They do this by providing a condition and a set of reasons in a single command.
Reasons are also optional; however, they provide additional context as to why the rule failed. Alternatively, you can provide your own reasons to complement standard PowerShell with the
"},{"location":"faq/#collection-of-telemetry","title":"Collection of telemetry","text":"Reasonkeyword.PSRule currently does not collect any telemetry during installation or execution.
PowerShell (used by PSRule) does collect basic telemetry by default. Collection of telemetry in PowerShell and how to opt-out is explained in about_Telemetry.
"},{"location":"features/","title":"Features","text":""},{"location":"features/#devops","title":"DevOps","text":"PSRule allows you to quickly plug-in Infrastructure as Code (IaC) controls into your DevOps pipeline.
Run on MacOS, Linux, and Windows or anywhere PowerShell is supported. Native support for popular continuous integration (CI) systems includes:
Import pre-built rules or define your own using YAML, JSON, or PowerShell format. Regardless of the format you choose, any combination of YAML, JSON, or PowerShell rules can be used together.
Rules can be authored using any text editor, but we provide a native extension for Visual Studio Code. Use the extension to quickly author rules or run tests locally before you commit your IaC.
"},{"location":"features/#reusable","title":"Reusable","text":"Typically unit tests in traditional testing frameworks are written for a specific case. This makes it hard invest in tests that are not easily reusable between projects. Several features of PSRule make it easier to reuse and share rules across teams or organizations.
The following built-in features improve portability:
PSRule supports running within continuous integration (CI) systems or locally. It is shipped as a PowerShell module which makes it easy to install and distribute updates.
Task Options Run tests within CI pipelines With GitHub Actions or Azure Pipelines or CLI or PowerShell Run tests locally during development With Visual Studio Code and CLI / PowerShell Create custom tests for your organization With Visual Studio Code and CLI / PowerShellTip
PSRule provides native integration to popular CI systems such as GitHub Actions and Azure Pipelines. If you are using a different CI system you can use the local install to run on MacOS, Linux, and Windows worker nodes.
"},{"location":"install/#with-github-actions","title":"With GitHub Actions","text":"GitHub Action
Install and use PSRule with GitHub Actions by referencing the
Specific versionLatest stable v2Latest stable GitHub Actionsmicrosoft/ps-ruleaction.
GitHub Actions- name: Analyze with PSRule\n uses: microsoft/ps-rule@v2.9.0\n
GitHub Actions- name: Analyze with PSRule\n uses: microsoft/ps-rule@v2\n- name: Analyze with PSRule\n uses: microsoft/ps-rule@latest\nThis will automatically install compatible versions of all dependencies.
Tip
The recommended approach is to pin to the latest specific version. Pinning to a specific version reduces the risk of new versions breaking your pipeline. You can easily update to the latest version by changing the version number. At such time, you can test the new version in a feature branch before merging to main.
"},{"location":"install/#working-with-dependabot","title":"Working with Dependabot","text":"You can use Dependabot to automatically upgrade your PSRule action if you use a specific version. When new versions a released Dependabot will automatically add a pull request (PR) for you to review and merge.
.github/dependabot.yaml
"},{"location":"install/#with-azure-pipelines","title":"With Azure Pipelines","text":"#\n# Dependabot configuration\n#\nversion: 2\nupdates:\n\n # Maintain GitHub Actions\n - package-ecosystem: github-actions\n directory: \"/\"\n schedule:\n interval: daily\nExtension
Install and use PSRule with Azure Pipeline by using extension tasks. Install the extension from the marketplace, then use the
ps-rule-asserttask in pipeline steps.- task: ps-rule-assert@2\n displayName: Analyze Azure template files\n inputs:\n inputType: repository\nThis will automatically install compatible versions of all dependencies.
"},{"location":"install/#with-visual-studio-code","title":"With Visual Studio Code","text":"Extension
An extension for Visual Studio Code is available for an integrated experience using PSRule. The Visual Studio Code extension includes a built-in tasks and configuration schemas for working with PSRule.
"},{"location":"install/#with-cli","title":"With CLI","text":"PSRule can be installed from NuGet.org using the .NET CLI where the .NET 8.0 SDK is available. You can use this option to install on CI workers that are not natively supported.
To install PSRule as a global tool use the following command line:
dotnet tool install -g Microsoft.PSRule.Tool\nTo install a specific version use the following command line:
dotnet tool install -g Microsoft.PSRule.Tool --version 3.0.0-B0151\nFor a list of commands supported by the CLI, see PSRule CLI.
"},{"location":"install/#with-powershell","title":"With PowerShell","text":"PSRule can be installed locally from the PowerShell Gallery using PowerShell. You can use this option to install on CI workers that are not natively supported.
"},{"location":"install/#prerequisites","title":"Prerequisites","text":"Operating System Tool Installation Link Windows Windows PowerShell 5.1 with .NET Framework 4.7.2 or greater. link Windows, MacOS, Linux PowerShell version 7.4.x or greater. linkNote
If you are using Windows PowerShell you may need to bootstrap NuGet before you can install modules. The NuGet package provider is not installed in Windows PowerShell be default. For instructions see Bootstrapping NuGet.
"},{"location":"install/#installing-powershell","title":"Installing PowerShell","text":"PowerShell 7.x can be installed on MacOS, Linux, and Windows but is not installed by default. For a list of platforms that PowerShell 7.4 is supported on and install instructions see Get PowerShell.
"},{"location":"install/#getting-the-modules","title":"Getting the modules","text":"Module
PSRule can be installed or updated from the PowerShell Gallery. Use the following command line examples from a PowerShell terminal to install or update PSRule.
For the current userFor all usersTo install PSRule for the current user use:
Install-Module -Name 'PSRule' -Repository PSGallery -Scope CurrentUser\nTo update PSRule for the current user use:
Update-Module -Name 'PSRule' -Scope CurrentUser\nOpen PowerShell with Run as administrator on Windows or
sudo pwshon Linux.To install PSRule for all users (requires admin/ root permissions) use:
Install-Module -Name 'PSRule' -Repository PSGallery -Scope AllUsers\nTo update PSRule for all users (requires admin/ root permissions) use:
"},{"location":"install/#pre-release-versions","title":"Pre-release versions","text":"Update-Module -Name 'PSRule' -Scope AllUsers\nTo use a pre-release version of PSRule add the
-AllowPrereleaseswitch when callingInstall-Module,Update-Module, orSave-Modulecmdlets.Tip
To install pre-release module versions, the latest version of PowerShellGet may be required.
For the current userFor all users# Install the latest PowerShellGet version\nInstall-Module -Name PowerShellGet -Repository PSGallery -Scope CurrentUser -Force\nTo install PSRule for the current user use:
Install-Module -Name PowerShellGet -Repository PSGallery -Scope CurrentUser -Force\nInstall-Module -Name 'PSRule' -Repository PSGallery -Scope CurrentUser -AllowPrerelease\nOpen PowerShell with Run as administrator on Windows or
sudo pwshon Linux.To install PSRule for all users (requires admin/ root permissions) use:
"},{"location":"install/#building-from-source","title":"Building from source","text":"Install-Module -Name PowerShellGet -Repository PSGallery -Scope CurrentUser -Force\nInstall-Module -Name 'PSRule' -Repository PSGallery -Scope AllUsers -AllowPrerelease\nSource
PSRule is provided as open source on GitHub. To build PSRule from source code:
This build script will compile the module and documentation then output the result into
"},{"location":"install/#development-dependencies","title":"Development dependencies","text":"out/modules/PSRule.The following PowerShell modules will be automatically install if the required versions are not present:
These additional modules are only required for building PSRule.
Additionally .NET SDK v8 is required. .NET will not be automatically downloaded and installed. To download and install the latest SDK see Download .NET 8.0.
"},{"location":"install/#limited-access-networks","title":"Limited access networks","text":"If you are on a network that does not permit Internet access to the PowerShell Gallery, download the required PowerShell modules on an alternative device that has access. PowerShell provides the
Save-Modulecmdlet that can be run from a PowerShell terminal to do this.The following command lines can be used to download the required modules using a PowerShell terminal. After downloading the modules, copy the module directories to devices with restricted Internet access.
Runtime modulesDevelopment modulesTo save PSRule for offline use:
Save-Module -Name 'PSRule' -Path '.\\modules'\nThis will save PSRule into the
modulessub-directory.To save PSRule development module dependencies for offline use:
$modules = @('PlatyPS', 'Pester', 'PSScriptAnalyzer', 'PowerShellGet',\n'PackageManagement', 'InvokeBuild')\nSave-Module -Name $modules -Repository PSGallery -Path '.\\modules';\nThis will save required developments dependencies into the
modulessub-directory.Tip
If you use additional rules modules such as PSRule for Azure you should also save these for offline use.
Note
If you are using Windows PowerShell you may need to bootstrap NuGet before you can install modules. The NuGet package provider is not installed in Windows PowerShell be default. For instructions see Bootstrapping NuGet.
"},{"location":"license-contributing/","title":"License and contributing","text":"PSRule is licensed with an MIT License, which means it's free to use and modify. But please check out the details.
We open source at Microsoft.
In addition to our team, we hope you will think about contributing too. Here is how you can get started:
The PSRule project is distributed across multiple repositories. You can find out more by visiting each repository.
Name Description ps-rule GitHub continuous integration using GitHub Actions. PSRule-pipelines Azure DevOps continuous integration using Azure Pipelines. PSRule-vscode Support for running and authoring rules within Visual Studio Code. PSRule.Monitor Support for logging PSRule analysis results to Azure Monitor. PSRule.Rules.Azure Rules to validate Azure resources and infrastructure as code (IaC) using PSRule. PSRule.Rules.Azure-quickstart Sample code you can use to quickly start using PSRule for Azure. PSRule.Rules.CAF A suite of rules to validate Azure resources against the Cloud Adoption Framework (CAF) using PSRule. PSRule.Rules.GitHub A suite of rules to validate GitHub repositories using PSRule. PSRule.Rules.Kubernetes A suite of rules to validate Kubernetes resources using PSRule. PSRule.Rules.MSFT.OSS A suite of rules to validate repositories against Microsoft Open Source Software (OSS) requirements."},{"location":"related-projects/#community-modules","title":"Community modules","text":"The following third-party modules are created, maintained, supported, and licensed by their respective authors. Before consuming these module, double check they meet your organization's support, security, and licensing expectations.
Author Name Description cloudyspells PSRule.Rules.AzureDevOps A suite of rules to validate Azure DevOps projects using PSRule."},{"location":"support/","title":"Support","text":"This project uses GitHub Issues to track bugs and feature requests.
Please search the existing issues before filing new issues to avoid duplicates.
Support for this project/ product is limited to the resources listed above.
"},{"location":"troubleshooting/","title":"Troubleshooting","text":"Abstract
This article provides troubleshooting instructions for common errors generic to PSRule or core functionality.
Tip
See troubleshooting specific to PSRule for Azure for common errors when testing Azure resources using the
"},{"location":"troubleshooting/#custom-rules-are-not-running","title":"Custom rules are not running","text":"PSRule.Rules.Azuremodule.There is a few common causes of this issue including:
Tip
You may be able to use
"},{"location":"troubleshooting/#windows-powershell-is-in-noninteractive-mode","title":"Windows PowerShell is in NonInteractive mode","text":"git mvto change the case of a file if it is committed to the repository incorrectly.When running PSRule on a Windows self-hosted agent/ private runner you may encounter an error similar to the following:
Error
Exception calling \"ShouldContinue\" with \"2\" argument(s): \"Windows PowerShell is in NonInteractive mode. Read and Prompt functionality is not available.\"
This error may be caused by the PowerShell NuGet package provider not being installed. By default, Windows PowerShell does not have these components installed. These components are required for installing and checking versions of PSRule modules.
To resolve this issue, install the NuGet package provider during setup the agent/ runner by using the following script:
if ($Null -eq (Get-PackageProvider -Name NuGet -ErrorAction Ignore)) {\n Install-PackageProvider -Name NuGet -Force -Scope CurrentUser;\n}\nAdditionally consider installing the latest version of
PowerShellGetby using the following script:
"},{"location":"troubleshooting/#format-default-error-when-running-invoke-psrule","title":"Format-Default error when running Invoke-PSRule","text":"if ($Null -eq (Get-InstalledModule -Name PowerShellGet -MinimumVersion 2.2.1 -ErrorAction Ignore)) {\n Install-Module PowerShellGet -MinimumVersion 2.2.1 -Scope CurrentUser -Force -AllowClobber;\n}\nWhen running PSRule you may encounter an error similar to the following:
Error
Format-Default: Cannot process argument because the value of argument \"name\" is not valid. Change the value of the \"name\" argument and run the operation again.
This error is caused by a known issue in PowerShell 7.4.0 and 7.4.1. To resolve this issue, upgrade to PowerShell 7.4.2 or later.
For more details see #1723.
"},{"location":"troubleshooting/#psr0001-unable-to-read-options-file","title":"PSR0001 - Unable to read options file","text":"When running PSRule you may encounter an error similar to the following:
Error
PSR0001: Unable to read options file 'ps-rule.yaml'.
This error typically indicates a problem with the YAML syntax in the
ps-rule.yamlfile. Double check the file for incorrect indentation or missing punctuation such as-and:characters.If you still have an issue, try re-saving the file as UTF-8 in an editor such as Visual Studio Code.
"},{"location":"troubleshooting/#psr0002-summary-results-are-not-supported-with-job-summaries","title":"PSR0002 - Summary results are not supported with Job Summaries","text":"Error
PSR0002: Summary results are not supported with Job Summaries.
Currently using the
Output.Aswith theSummaryoption is not supported with job summaries. Choose to use one or the other.If you have a specific use case your would like to enable, please start a discussion.
"},{"location":"troubleshooting/#psr0003-the-specified-baseline-group-is-not-known","title":"PSR0003 - The specified baseline group is not known","text":"Error
PSR0003: The specified baseline group 'latest' is not known.
This error is caused by attempting to reference a baseline group which has not been defined. To define a baseline group, see Baseline.Group option.
"},{"location":"troubleshooting/#psr0004-the-specified-resource-is-not-known","title":"PSR0004 - The specified resource is not known","text":"Error
PSR0004: The specified Baseline resource 'TestModule4\\Module4' is not known.
This error is caused when you attempt to reference a resource such as a baseline, rule, or selector which has not been defined.
"},{"location":"upgrade-notes/","title":"Upgrade notes","text":"This document contains notes to help upgrade from previous versions of PSRule.
"},{"location":"upgrade-notes/#upgrading-to-v300","title":"Upgrading to v3.0.0","text":""},{"location":"upgrade-notes/#unbound-object-names","title":"Unbound object names","text":"When an object is processed by PSRule, it is assigned a name. This name is used to identify the object in the output and to suppress the object from future processing.
Prior to v3.0.0, the name was generated using a SHA-1 hash of the object. The SHA-1 algorithm is no longer considered secure and has been replaced with SHA-512.
From v3.0.0, if the name of an object can not be determined, the SHA-512 hash of the object will be used. Any objects that have previously been suppressed with a name based on a SHA-1 hash will no longer be suppressed.
To resolve any issue caused by this change, you can:
From v3.0.0, PSRule requires:
Support for Windows PowerShell 5.1 is deprecated and will be removed in a future release of PSRule (v4). We recommend upgrading to PowerShell 7.3 or later.
At the time of writing, PowerShell 7.3 is the most recent version of PowerShell. PowerShell 7.4 is expected, and PSRule v4 will aim to support the latest version of PowerShell as the minimum requirement.
"},{"location":"upgrade-notes/#changes-to-cli-commands","title":"Changes to CLI commands","text":"From v3.0.0, the CLI command names have been renamed to simplify usage. The following changes have been made:
The
runcommand provides similar output to theAssert-PSRulecmdlet in PowerShell.Previously the
restorecommand installed modules based on the configuration of the Requires option. From v3.0.0, themodule restorecommand installs modules based on:When naming resources such as rules or selectors, the following restrictions apply:
Prior to v2.0.0, there was no specific naming restriction for resources. However functionally PSRule and downstream components could not support all resource names. To avoid confusion, we have decided to restrict resource names to a specific set of characters.
From v2.0.0, resource names that do not meet the naming restrictions will generate an error.
Regular expression for valid resource names
"},{"location":"upgrade-notes/#setting-default-module-baseline","title":"Setting default module baseline","text":"^[^<>:/\\\\|?*\"'`+@._\\-\\x00-\\x1F][^<>:/\\\\|?*\"'`+@\\x00-\\x1F]{1,126}[^<>:/\\\\|?*\"'`+@._\\-\\x00-\\x1F]$\nWhen packaging rules in a module, you can set the default baseline. The default baseline from the module will be automatically used unless overridden.
Prior to v1.9.0 the default baseline was set by configuring the module manifest
.psd1file. From v1.9.0 the default baseline can be configured by within a module configuration. Using module configuration is the recommended method. Setting the default baseline from module manifest and has been removed from v2.0.0.A module configuration can be defined in YAML.
Example
"},{"location":"upgrade-notes/#setting-resource-api-version","title":"Setting resource API version","text":"---\n# Synopsis: Example module configuration for Enterprise.Rules module.\napiVersion: github.com/microsoft/PSRule/v1\nkind: ModuleConfig\nmetadata:\n name: Enterprise.Rules\nspec:\n rule:\n baseline: Enterprise.Default\nWhen creating YAML and JSON resources you define a resource by specifying the
apiVersionandkind. AnapiVersionwas added as a requirement from v1.2.0. For compatibility, resources without anapiVersionwere supported however deprecated for removal. This has now been removed from v2.0.0.When defining resource specify an
YAMLJSONapiVersion. Currently this must be set togithub.com/microsoft/PSRule/v1.---\n# Synopsis: An example rule to require TLS.\napiVersion: github.com/microsoft/PSRule/v1\nkind: Rule\nmetadata:\n name: 'Local.YAML.RequireTLS'\nspec:\n condition:\n field: 'configure.supportsHttpsTrafficOnly'\n equals: true\n
"},{"location":"upgrade-notes/#change-in-source-file-discovery-for-get-psrulehelp","title":"Change in source file discovery for Get-PSRuleHelp","text":"[\n {\n // Synopsis: An example rule to require TLS.\n \"apiVersion\": \"github.com/microsoft/PSRule/v1\",\n \"kind\": \"Rule\",\n \"metadata\": {\n \"name\": \"Local.JSON.RequireTLS\"\n },\n \"spec\": {\n \"condition\": {\n \"field\": \"configure.supportsHttpsTrafficOnly\",\n \"equals\": true\n }\n }\n }\n]\nPreviously in PSRule v1.11.0 and prior versions, rules would show up twice when running
Get-PSRuleHelpin the context of a module and in the same working directory of the module. This behavior has now been removed from v2.0.0.Module files are now preferred over loose files, and rules are only shown once in the output. Any duplicate rule names from loose files are outputted as a warning instead.
The old behavior:
Name ModuleName Synopsis\n---- ---------- --------\nM1.Rule1 This is the default\nM1.Rule2 This is the default\nM1.Rule1 TestModule Synopsis en-AU.\nM1.Rule2 TestModule This is the default\nThe new behavior:
"},{"location":"upgrade-notes/#require-source-discovery-from-current-working-directory-to-be-explicitly-included","title":"Require source discovery from current working directory to be explicitly included","text":"WARNING: A rule with the same name 'M1.Rule1' already exists.\nWARNING: A rule with the same name 'M1.Rule2' already exists.\n\nName ModuleName Synopsis\n---- ---------- --------\nM1.Rule1 TestModule Synopsis en-AU.\nM1.Rule2 TestModule This is the default\nPreviously in PSRule v1.11.0 and prior versions, rule sources from the current working directory without the
-Pathand-Moduleparameters were automatically included. This behavior has now been removed from v2.0.0.Rules sources in the current working directory are only included if
-Path .or-Path $PWDis specified.The old behavior:
PowerShellSet-Location docs\\scenarios\\azure-resources\nGet-PSRule\n\nRuleName ModuleName Synopsis\n-------- ---------- --------\nappServicePlan.MinInstanceCount App Service Plan has multiple instances\nappServicePlan.MinPlan Use at least a Standard App Service Plan\nappServiceApp.ARRAffinity Disable client affinity for stateless services\nappServiceApp.UseHTTPS Use HTTPS only\nstorageAccounts.UseHttps Configure storage accounts to only accept encrypted traffic i.e. HTTPS/SMB\nstorageAccounts.UseEncryption Use at-rest storage encryption\nThe new behavior:
PowerShell
"},{"location":"upgrade-notes/#upgrading-to-v140","title":"Upgrading to v1.4.0","text":"Set-Location docs\\scenarios\\azure-resources\nGet-PSRule\n\n# No output, need to specify -Path explicitly\n\nGet-PSRule -Path $PWD\n\nRuleName ModuleName Synopsis\n-------- ---------- --------\nappServicePlan.MinInstanceCount App Service Plan has multiple instances\nappServicePlan.MinPlan Use at least a Standard App Service Plan\nappServiceApp.ARRAffinity Disable client affinity for stateless services\nappServiceApp.UseHTTPS Use HTTPS only\nstorageAccounts.UseHttps Configure storage accounts to only accept encrypted traffic i.e. HTTPS/SMB\nstorageAccounts.UseEncryption \nFollow these notes to upgrade to PSRule v1.4.0 from previous versions.
"},{"location":"upgrade-notes/#change-in-default-output-styles","title":"Change in default output styles","text":"Previously in PSRule v1.3.0 and prior the default style when using
Assert-PSRulewasClient. From v1.4.0 PSRule now defaults toDetect.The
Detectoutput style falls back toClienthowever may detect one of the following styles instead:Detect uses the following logic:
To force usage of the
ps-rule.yamlClientoutput style set theOutput.Styleoption. For example:# YAML: Using the output/style property\noutput:\n style: Client\n
GitHub Actions# Bash: Using environment variable\nexport PSRULE_OUTPUT_STYLE=Client\n
Azure Pipelines# GitHub Actions: Using environment variable\nenv:\n PSRULE_OUTPUT_STYLE: Client\n
"},{"location":"upgrade-notes/#upgrading-to-v100","title":"Upgrading to v1.0.0","text":"# Azure Pipelines: Using environment variable\nvariables:\n- name: PSRULE_OUTPUT_STYLE\n value: Client\nFollow these notes to upgrade to PSRule v1.0.0 from previous versions.
"},{"location":"upgrade-notes/#replaced-rule-target-properties","title":"Replaced $Rule target properties","text":"Previously in PSRule v0.22.0 and prior the
$Ruleautomatic variable had the following properties:For example:
PowerShell rulesRule 'Rule1' {\n $Rule.TargetName -eq 'Name1';\n $Rule.TargetType -eq '.json';\n $Rule.TargetObject.someProperty -eq 1;\n}\nIn v1.0.0 these properties have been removed after being deprecated in v0.12.0. These properties are instead available on the
$PSRulevariable. Rules referencing the deprecated properties of$Rulemust be updated.For example:
PowerShell rules
"},{"location":"validating-locally/","title":"Validating locally","text":"Rule 'Rule1' {\n $PSRule.TargetName -eq 'Name1';\n $PSRule.TargetType -eq '.json';\n $PSRule.TargetObject.someProperty -eq 1;\n}\nPSRule can be installed locally on MacOS, Linux, and Windows for local validation. This allows you to test Infrastructure as Code (IaC) artifacts before pushing changes to a repository.
Tip
If you haven't already, follow the instructions on installing locally before continuing.
"},{"location":"validating-locally/#with-visual-studio-code","title":"With Visual Studio Code","text":"Extension
An extension for Visual Studio Code is available for an integrated experience using PSRule. The Visual Studio Code extension includes a built-in task PSRule: Run analysis task.
Info
To learn about tasks in Visual Studio Code see Integrate with External Tools via Tasks.
"},{"location":"validating-locally/#customizing-the-task","title":"Customizing the task","text":"The PSRule: Run analysis task will be available automatically after you install the PSRule extension. You can customize the defaults of the task by editing or inserting the task into
JSON.vscode/tasks.jsonwithin your workspace.{\n \"type\": \"PSRule\",\n \"problemMatcher\": [\n \"$PSRule\"\n ],\n \"label\": \"PSRule: Run analysis\",\n \"modules\": [\n \"PSRule.Rules.Azure\"\n ],\n \"presentation\": {\n \"clear\": true,\n \"panel\": \"dedicated\"\n }\n}\nExample
A complete
.vscode/tasks.json.vscode/tasks.jsonmight look like the following:
"},{"location":"versioning/","title":"Changes and versioning","text":"{\n \"version\": \"2.0.0\",\n \"tasks\": [\n {\n \"type\": \"PSRule\",\n \"problemMatcher\": [\n \"$PSRule\"\n ],\n \"label\": \"PSRule: Run analysis\",\n \"modules\": [\n \"PSRule.Rules.Azure\"\n ],\n \"presentation\": {\n \"clear\": true,\n \"panel\": \"dedicated\"\n }\n }\n ]\n}\nPSRule uses semantic versioning to declare breaking changes. The latest module version can be installed from the PowerShell Gallery. For a list of module changes please see the change log.
"},{"location":"versioning/#pre-releases","title":"Pre-releases","text":"Pre-release module versions are created on major commits and can be installed from the PowerShell Gallery. Module versions and change log details for pre-releases will be removed as stable releases are made available.
Important
Pre-release versions should be considered work in progress. These releases should not be used in production. We may introduce breaking changes between a pre-release as we work towards a stable version release.
"},{"location":"versioning/#experimental-features","title":"Experimental features","text":"From time to time we may ship experiential features. These features are generally marked experiential in the change log as these features ship. Experimental features may ship in stable releases, however to use them you may need to:
Important
Experimental features should be considered work in progress. These features may be incomplete and should not be used in production. We may introduce breaking changes for experimental features as we work towards a general release for the feature.
"},{"location":"versioning/#reporting-bugs","title":"Reporting bugs","text":"If you experience an issue with an pre-release or experimental feature please let us know by logging an issue as a bug.
"},{"location":"authoring/packaging-rules/","title":"Packaging rules in a module","text":"PSRule supports distribution of rules within modules. Using a module, rules can be published and installed using standard PowerShell cmdlets.
You should consider packaging rules into a module to:
This scenario covers the following:
When creating a PowerShell module, a module manifest is an optional file that stores module metadata. Module manifests use the
"},{"location":"authoring/packaging-rules/#creating-the-manifest-file","title":"Creating the manifest file","text":".psd1file extension. When packaging rules in a module, a module manifest is required for PSRule discover the module.A module manifest can be created from PowerShell using the
New-ModuleManifestcmdlet. Additionally, Visual Studio Code and many other tools also include snippets for creating a module manifest.For example:
# Create a directory for the module\nmd ./Enterprise.Rules;\n\n# Create the manifest\nNew-ModuleManifest -Path ./Enterprise.Rules/Enterprise.Rules.psd1 -Tags 'PSRule-rules';\nThe example above creates a module manifest for a module named Enterprise.Rules tagged with
"},{"location":"authoring/packaging-rules/#setting-module-tags","title":"Setting module tags","text":"PSRule-rules. The use of thePSRule-rulestag is explained in the following section.When PSRule cmdlets are used with the
-Moduleparameter, PSRule discovers rule modules. If the module is already imported, that module is used. If the module is not imported, PSRule will import the highest version of the module automatically.For a module to be discovered by PSRule, tag the module with
PSRule-rules. To tag modules, find theTagssection thePSDatahashtable in the module manifest and addPSRule-rules.An updated module manifest may look like this:
"},{"location":"authoring/packaging-rules/#including-rules-and-baselines","title":"Including rules and baselines","text":"# Private data to pass to the module specified in RootModule/ModuleToProcess. This may also contain a PSData hashtable with additional module metadata used by PowerShell.\nPrivateData = @{\n PSData = @{\n # Tags applied to this module. These help with module discovery in online galleries.\n Tags = @('PSRule-rules')\n }\n}\nRules and baselines can be included anywhere within the module directory structure. Such as in the root directory of the module or in a nested sub-directory.
By convention, consider including rules and baselines within a
rulessub-directory within the module.For example:
For PSRule to find rules included in a module, rule file names must end with the
.Rule.ps1suffix. We recommend using the exact case.Rule.ps1. This is because some file systems are case-sensitive. For example, on LinuxStandards.rule.ps1would be ignored by PSRule.Similarly, when including baselines within a module use the
"},{"location":"authoring/packaging-rules/#defining-a-module-configuration","title":"Defining a module configuration","text":".Rule.yamlsuffix.A module configuration that sets options defaults and can be optionally packaged with a module. To set a module configuration, define a
ModuleConfigresource within an included.Rule.yamlfile. A module configuration.Rule.yamlfile must be distributed within the module directory structure.PSRule only supports a single
ModuleConfigresource. The name of theModuleConfigmust match the name of the module. AdditionalModuleConfigresources or with an alternative name are ignored. PSRule does not support module configurations distributed outside of a module.Example
---\n# Synopsis: Example module configuration for Enterprise.Rules module.\napiVersion: github.com/microsoft/PSRule/v1\nkind: ModuleConfig\nmetadata:\n name: Enterprise.Rules\nspec:\n binding:\n targetName:\n - ResourceName\n - FullName\n - name\n targetType:\n - ResourceType\n - type\n - Extension\n field:\n resourceId: [ 'ResourceId' ]\n subscriptionId: [ 'SubscriptionId' ]\n resourceGroupName: [ 'ResourceGroupName' ]\n rule:\n baseline: Enterprise.Default\nThe following options are allowed within a
ModuleConfig:Optionally, baselines can be included in rule modules. If a baseline contains configuration or binding options then setting a default baseline is often desirable. When a default baseline is set, PSRule will use the named baseline automatically when processing rules from that module. This feature removes the need for users to specify it manually.
To set a default baseline, set the
Rule.Baselineproperty of theModuleConfigresource.Example
---\n# Synopsis: Example module configuration for Enterprise.Rules module.\napiVersion: github.com/microsoft/PSRule/v1\nkind: ModuleConfig\nmetadata:\n name: Enterprise.Rules\nspec:\n binding:\n targetName:\n - ResourceName\n - FullName\n - name\n targetType:\n - ResourceType\n - type\n - Extension\n field:\n resourceId: [ 'ResourceId' ]\n subscriptionId: [ 'SubscriptionId' ]\n resourceGroupName: [ 'ResourceGroupName' ]\n rule:\n baseline: Enterprise.Default\nThis examples set the default baseline to
"},{"location":"authoring/packaging-rules/#including-documentation","title":"Including documentation","text":"Enterprise.Default. The default baseline must be included in file ending with.Rule.yamlwithin the module directory structure.PSRule supports write and packaging rule modules with markdown documentation. Markdown documentation is automatically interpreted by PSRule and included in output.
When including markdown, files are copied into a directory structure based on the target culture.
For example, store documentation targeted to the culture
en-USin a directory nameden-US. Similarly, documentation for cultures such asen-AU,en-GBandfr-FRwould be in separate directories.If a directory for the exact culture
en-USdoesn't exist, PSRule will attempt to find the parent culture. For example, documentation would be read from a directory nameden.When naming directories for their culture, use exact case. This is because some file systems are case-sensitive. For example on Linux
en-uswould not match.For example:
Rules are stored in one or more files and each file can contain one or many rules. Additionally, rules can be grouped into a module and distributed.
Abstract
This topic covers recommendations for naming and storing rules.
"},{"location":"authoring/storing-rules/#using-a-standard-file-path","title":"Using a standard file path","text":"Rules can be standalone or packaged within a module. Standalone rules are ideal for a single project such as an Infrastructure as Code (IaC) repository. To reuse rules across multiple projects consider packaging these as a module.
The instructions for packaging rules in a module can be found here:
To store standalone rules we recommend that you:
Note
Build pipelines are often case-sensitive or run on Linux-based systems. Using the casing rule above reduces confusion latter when you configure continuous integration (CI).
"},{"location":"authoring/storing-rules/#naming-rules","title":"Naming rules","text":"When running PSRule, rule names must be unique. For example, PSRule for Azure uses the name prefix of
Azure.for rules included in the module.Example
The following names are examples of rules included within PSRule for Azure:
In addition, names for rules and other resources must meet the following requirements:
^[^<>:/\\\\|?*\"'`+@._\\-\\x00-\\x1F][^<>:/\\\\|?*\"'`+@\\x00-\\x1F]{1,126}[^<>:/\\\\|?*\"'`+@._\\-\\x00-\\x1F]$\nWhen naming rules we recommend that you:
You can use PSRule to create tests for Infrastructure as Code (IaC). Each test is called a rule.
PSRule allows you to write rules using YAML, JSON, or PowerShell. Regardless of the format you choose, any combination of YAML, JSON, or PowerShell rules can be used together.
Abstract
This topic covers how to create a rule using YAML, JSON, and PowerShell by example. This example, while fictitious is indicative of common testing and validation scenarios for IaC.
"},{"location":"authoring/testing-infrastructure/#sample-data","title":"Sample data","text":"To get started authoring a rule, we will be working with a sample file
settings.json. This sample configuration file configures an application.For the purpose of this example, one configuration setting
supportsHttpsTrafficOnlyis set. This configuration setting can be eithertrueorfalse. When set totrue, Transport Layer Security (TLS) is enforced. When set tofalse, the application permits insecure communication with HTTP.Contents of
settings.jsonCreate a
settings.jsonfile in the root of your repository with the following contents.
"},{"location":"authoring/testing-infrastructure/#define-a-rule","title":"Define a rule","text":"{\n \"type\": \"app1\",\n \"version\": 1,\n \"configure\": {\n \"supportsHttpsTrafficOnly\": false\n }\n}\nTo meet the requirements of our organization we want to write a rule to:
In this section the same rule will be authored using YAML, JSON, and PowerShell.
Tip
To make you editing experience even better, consider installing the Visual Studio Code extension.
YAMLJSONPowerShellCreate a
.ps-rule/Local.Rule.yamlfile in your repository with the following contents.---\n# Synopsis: An example rule to require TLS.\napiVersion: github.com/microsoft/PSRule/v1\nkind: Rule\nmetadata:\n name: 'Local.YAML.RequireTLS'\nspec:\n condition:\n field: 'configure.supportsHttpsTrafficOnly'\n equals: true\nCreate a
.ps-rule/Local.Rule.jsoncfile in your repository with the following contents.[\n {\n // Synopsis: An example rule to require TLS.\n \"apiVersion\": \"github.com/microsoft/PSRule/v1\",\n \"kind\": \"Rule\",\n \"metadata\": {\n \"name\": \"Local.JSON.RequireTLS\"\n },\n \"spec\": {\n \"condition\": {\n \"field\": \"configure.supportsHttpsTrafficOnly\",\n \"equals\": true\n }\n }\n }\n]\nCreate a
.ps-rule/Local.Rule.ps1file in your repository with the following contents.# Synopsis: An example rule to require TLS.\nRule 'Local.PS.RequireTLS' {\n $Assert.HasFieldValue($TargetObject, 'configure.supportsHttpsTrafficOnly', $True)\n}\nTip
To learn more about recommended file and naming conventions for rules, continue reading Storing and naming rules.
"},{"location":"authoring/testing-infrastructure/#using-multiple-conditions","title":"Using multiple conditions","text":"Each rule must have at least one condition. Additional conditions can be combined to check multiple test cases.
In the example a
YAMLJSONPowerShellminTLSVersionconfiguration setting does not exist and is not set.Update
.ps-rule/Local.Rule.yamlin your repository with the following contents.---\n# Synopsis: An example rule to require TLS.\napiVersion: github.com/microsoft/PSRule/v1\nkind: Rule\nmetadata:\n name: 'Local.YAML.RequireTLS'\nspec:\n condition:\n allOf:\n - field: 'configure.supportsHttpsTrafficOnly'\n equals: true\n - field: 'configure.minTLSVersion'\n equals: '1.2'\nUpdate
.ps-rule/Local.Rule.jsoncin your repository with the following contents.[\n {\n // Synopsis: An example rule to require TLS.\n \"apiVersion\": \"github.com/microsoft/PSRule/v1\",\n \"kind\": \"Rule\",\n \"metadata\": {\n \"name\": \"Local.JSON.RequireTLS\"\n },\n \"spec\": {\n \"condition\": {\n \"allOf\": [\n {\n \"field\": \"configure.supportsHttpsTrafficOnly\",\n \"equals\": true\n },\n {\n \"field\": \"configure.minTLSVersion\",\n \"equals\": \"1.2\"\n }\n ]\n }\n }\n }\n]\nUpdate
.ps-rule/Local.Rule.ps1in your repository with the following contents.# Synopsis: An example rule to require TLS.\nRule 'Local.PS.RequireTLS' {\n $Assert.HasFieldValue($TargetObject, 'configure.supportsHttpsTrafficOnly', $True)\n $Assert.HasFieldValue($TargetObject, 'configure.minTLSVersion', '1.2')\n}\nTo test the rule manually, run the following command.
"},{"location":"authoring/testing-infrastructure/#advanced-usage","title":"Advanced usage","text":""},{"location":"authoring/testing-infrastructure/#severity-level","title":"Severity level","text":"Assert-PSRule -f ./settings.json\nv2.0.0
When defining a rule, you can specify a severity level. The severity level is used if the rule fails. By default, the severity level for a rule is
Error.In a continuous integration (CI) pipeline, severity level is particularly important. If any rule fails with a severity level of
Errorthe pipeline will fail. This helps prevent serious problems from being introduced into the code base or deployed.The following example shows how to set the severity level to
YAMLJSONPowerShellWarning.---\n# Synopsis: An example rule to require TLS.\napiVersion: github.com/microsoft/PSRule/v1\nkind: Rule\nmetadata:\n name: 'Local.YAML.RequireTLS'\nspec:\n level: Warning\n condition:\n allOf:\n - field: 'configure.supportsHttpsTrafficOnly'\n equals: true\n - field: 'configure.minTLSVersion'\n equals: '1.2'\n[\n {\n // Synopsis: An example rule to require TLS.\n \"apiVersion\": \"github.com/microsoft/PSRule/v1\",\n \"kind\": \"Rule\",\n \"metadata\": {\n \"name\": \"Local.JSON.RequireTLS\"\n },\n \"spec\": {\n \"level\": \"Warning\",\n \"condition\": {\n \"allOf\": [\n {\n \"field\": \"configure.supportsHttpsTrafficOnly\",\n \"equals\": true\n },\n {\n \"field\": \"configure.minTLSVersion\",\n \"equals\": \"1.2\"\n }\n ]\n }\n }\n }\n]\nUpdate
.ps-rule/Local.Rule.ps1in your repository with the following contents.
"},{"location":"authoring/using-expressions/","title":"Using expressions","text":"# Synopsis: An example rule to require TLS.\nRule 'Local.PS.RequireTLS' -Level Warning {\n $Assert.HasFieldValue($TargetObject, 'configure.supportsHttpsTrafficOnly', $True)\n $Assert.HasFieldValue($TargetObject, 'configure.minTLSVersion', '1.2')\n}\nPSRule allows you to write rules using YAML, JSON, or PowerShell. This offers a lot of flexibility to use PSRule for a variety of use cases. Some examples of use cases for each format include:
Abstract
This topic covers the differences and limitations between authoring rules using YAML, JSON, and PowerShell. For an example of authoring rules see Writing rules or Testing infrastructure topics.
"},{"location":"authoring/using-expressions/#language-comparison","title":"Language comparison","text":"Expressions and assertion methods can be used to build similar conditions.
In most cases expressions and assertion method names match. There are some cases where these names do not directly align. This lookup table provides a quick reference for expressions and their assertion method counterpart.
Expression Assertion method Contains Contains Count Count Equals 1 n/a EndsWith EndsWith Exists HasField Greater Greater GreaterOrEquals GreaterOrEqual HasDefault HasDefaultValue HasSchema HasJsonSchema HasValue 1 n/a In In IsLower IsLower IsString IsString IsUpper IsUpper Less Less LessOrEquals LessOrEqual Match Match NotEquals n/a NotIn NotIn NotMatch NotMatch SetOf SetOf StartsWith StartsWith Subset Subset Version Version n/a FileHeader n/a FilePath n/a HasFields n/a HasFieldValue 1 IsArray IsArray IsBoolean IsBoolean IsDateTime IsDateTime IsInteger IsInteger IsNumeric IsNumeric n/a JsonSchema Exists NotHasField n/a NotNull NotWithinPath NotWithinPath n/a Null n/a NullOrEmpty n/a TypeOf WithinPath WithinPathPSRule has built-in support for help. Documentation can optionally be added for each rule to provide detailed information or remediation steps.
This scenario covers the following:
With authoring rules in YAML and JSON, PSRule provides the following syntax features:
Specify the synopsis of the rule with the
YAMLJSONSynopsiscomment above the rule properties.---\n# Synopsis: An example rule to require TLS.\napiVersion: github.com/microsoft/PSRule/v1\nkind: Rule\nmetadata:\n name: 'Local.YAML.RequireTLS'\nspec:\n condition:\n field: 'configure.supportsHttpsTrafficOnly'\n equals: true\n[\n {\n // Synopsis: An example rule to require TLS.\n \"apiVersion\": \"github.com/microsoft/PSRule/v1\",\n \"kind\": \"Rule\",\n \"metadata\": {\n \"name\": \"Local.JSON.RequireTLS\"\n },\n \"spec\": {\n \"condition\": {\n \"field\": \"configure.supportsHttpsTrafficOnly\",\n \"equals\": true\n }\n }\n }\n]\nNote
The resource comment is not localized. Use markdown documentation for a localized synopsis.
"},{"location":"authoring/writing-rule-help/#display-name-property","title":"Display name property","text":"Specify the display name of the rule with the
YAMLJSONmetadata.displayNameproperty.---\n# Synopsis: An example rule to require TLS.\napiVersion: github.com/microsoft/PSRule/v1\nkind: Rule\nmetadata:\n name: 'Local.YAML.RequireTLS'\n displayName: Require TLS\nspec:\n condition:\n field: 'configure.supportsHttpsTrafficOnly'\n equals: true\n[\n {\n // Synopsis: An example rule to require TLS.\n \"apiVersion\": \"github.com/microsoft/PSRule/v1\",\n \"kind\": \"Rule\",\n \"metadata\": {\n \"name\": \"Local.JSON.RequireTLS\",\n \"displayName\": \"Require TLS\"\n },\n \"spec\": {\n \"condition\": {\n \"field\": \"configure.supportsHttpsTrafficOnly\",\n \"equals\": true\n }\n }\n }\n]\nNote
This property is not localized. Use markdown documentation for a localized display name.
"},{"location":"authoring/writing-rule-help/#description-property","title":"Description property","text":"Specify the description of the rule with the
YAMLJSONmetadata.descriptionproperty.---\n# Synopsis: An example rule to require TLS.\napiVersion: github.com/microsoft/PSRule/v1\nkind: Rule\nmetadata:\n name: 'Local.YAML.RequireTLS'\n description: The resource should only use TLS.\nspec:\n condition:\n field: 'configure.supportsHttpsTrafficOnly'\n equals: true\n[\n {\n // Synopsis: An example rule to require TLS.\n \"apiVersion\": \"github.com/microsoft/PSRule/v1\",\n \"kind\": \"Rule\",\n \"metadata\": {\n \"name\": \"Local.JSON.RequireTLS\",\n \"description\": \"The resource should only use TLS.\"\n },\n \"spec\": {\n \"condition\": {\n \"field\": \"configure.supportsHttpsTrafficOnly\",\n \"equals\": true\n }\n }\n }\n]\nNote
This property is not localized. Use markdown documentation for a localized description.
"},{"location":"authoring/writing-rule-help/#link-property","title":"Link property","text":"Specify the online help URL of the rule with the
YAMLJSONmetadata.linkproperty.---\n# Synopsis: An example rule to require TLS.\napiVersion: github.com/microsoft/PSRule/v1\nkind: Rule\nmetadata:\n name: 'Local.YAML.RequireTLS'\n link: https://aka.ms/ps-rule\nspec:\n condition:\n field: 'configure.supportsHttpsTrafficOnly'\n equals: true\n[\n {\n // Synopsis: An example rule to require TLS.\n \"apiVersion\": \"github.com/microsoft/PSRule/v1\",\n \"kind\": \"Rule\",\n \"metadata\": {\n \"name\": \"Local.JSON.RequireTLS\",\n \"link\": \"https://aka.ms/ps-rule\"\n },\n \"spec\": {\n \"condition\": {\n \"field\": \"configure.supportsHttpsTrafficOnly\",\n \"equals\": true\n }\n }\n }\n]\nNote
This property is not localized. Use markdown documentation for a localized online help URL.
"},{"location":"authoring/writing-rule-help/#recommend-property","title":"Recommend property","text":"Specify the rule recommendation with the
YAMLJSONspec.recommendproperty.---\n# Synopsis: An example rule to require TLS.\napiVersion: github.com/microsoft/PSRule/v1\nkind: Rule\nmetadata:\n name: 'Local.YAML.RequireTLS'\nspec:\n recommend: The resource should only use TLS.\n condition:\n field: 'configure.supportsHttpsTrafficOnly'\n equals: true\n[\n {\n // Synopsis: An example rule to require TLS.\n \"apiVersion\": \"github.com/microsoft/PSRule/v1\",\n \"kind\": \"Rule\",\n \"metadata\": {\n \"name\": \"Local.JSON.RequireTLS\"\n },\n \"spec\": {\n \"recommend\": \"\",\n \"condition\": {\n \"field\": \"configure.supportsHttpsTrafficOnly\",\n \"equals\": true\n }\n }\n }\n]\nNote
This property is not localized. Use markdown documentation for a localized recommendation.
"},{"location":"authoring/writing-rule-help/#inline-help-with-powershell","title":"Inline help with PowerShell","text":"When authoring rules in PowerShell, PSRule provides the following syntax features:
These features are each describe in detail in the following sections.
"},{"location":"authoring/writing-rule-help/#synopsis-script-comment","title":"Synopsis script comment","text":"Comment metadata can be included directly above a rule block by using the syntax
# Synopsis: <text>. This is only supported for populating a rule synopsis.For example:
PowerShell# Synopsis: Must have the app.kubernetes.io/name label\nRule 'metadata.Name' -Type 'Deployment', 'Service' {\n Exists \"metadata.labels.'app.kubernetes.io/name'\"\n}\nThis example above would set the synopsis to
Must have the app.kubernetes.io/name label.Including comment metadata improves authoring by indicating the rules purpose. Only a single line is supported. A rule synopsis is displayed when using
Get-PSRuleandGet-PSRuleHelp. The synopsis can not break over multiple lines.The key limitation of only using comment metadata is that it can not be localized for multiple languages. Consider using comment metadata and also using markdown documentation for a multi-language experience.
Note
The script comment is not localized. Use markdown documentation for a localized synopsis.
"},{"location":"authoring/writing-rule-help/#recommend-keyword","title":"Recommend keyword","text":"The
Recommendkeyword sets the recommendation for a rule. Use the keyword with a text recommendation at the top of your rule body.Using the
Recommendkeyword is recommended for rules that are not packaged in a module. When packaging rules in a module consider using markdown help instead.For example:
PowerShell# Synopsis: Must have the app.kubernetes.io/name label\nRule 'metadata.Name' -Type 'Deployment', 'Service' {\n Recommend 'Consider setting the recommended label ''app.kubernetes.io/name'' on deployment and service resources.'\n Exists \"metadata.labels.'app.kubernetes.io/name'\"\n}\nA rule recommendation is displayed when using
Invoke-PSRuleorGet-PSRuleHelp.Only use the
Recommendkeyword once to set the recommendation text and avoid formatting with variables. Recommendations are cached the first time they are used. Supplying a unique recommendation within a rule based on conditions/ logic is not supported. To return a custom unique reason for why the rule failed, use theReasonkeyword.Localized recommendations can set by using the
$LocalizedData.For example:
PowerShell
"},{"location":"authoring/writing-rule-help/#reason-keyword","title":"Reason keyword","text":"# Synopsis: Must have the app.kubernetes.io/name label\nRule 'metadata.Name' -Type 'Deployment', 'Service' {\n Recommend $LocalizedData.RecommendNameLabel\n Exists \"metadata.labels.'app.kubernetes.io/name'\"\n}\nThe
Reasonkeyword sets the reason the rule failed when usingInvoke-PSRuleandAssert-PSRule. The reason is only included in detailed output if the rule did not pass. If the rule passed, then reason is empty it returned output.Reasons are not included in the default view when using
Invoke-PSRule. Use-OutputFormat Wideto display reason messages.To set a reason use the
PowerShellReasonkeyword followed by the reason. For example:# Synopsis: Must have the app.kubernetes.io/name label\nRule 'metadata.Name' -Type 'Deployment', 'Service' {\n Recommend $LocalizedData.RecommendNameLabel\n Exists \"metadata.labels.'app.kubernetes.io/name'\"\n\n Reason 'The standard name label is not set.'\n}\nThe
Reasonkeyword can be used multiple times within conditional logic to return a list of reasons the rule failed. Additionally the reason messages can be localized by using the$LocalizedDatavariable.For example:
PowerShell
"},{"location":"authoring/writing-rule-help/#writing-markdown-documentation","title":"Writing markdown documentation","text":"# Synopsis: Must have the app.kubernetes.io/name label\nRule 'metadata.Name' -Type 'Deployment', 'Service' {\n Recommend $LocalizedData.RecommendNameLabel\n Exists \"metadata.labels.'app.kubernetes.io/name'\"\n\n # $LocalizedData.ReasonLabelMissing is set to 'The standard {0} label is not set.'.\n Reason ($LocalizedData.ReasonLabelMissing -f 'name')\n}\nIn addition to inline help, documentation can be written in markdown to provide online and offline help. Extended documentation is generally easier to author using markdown. Additionally markdown documentation is easily localized.
Markdown documentation is authored by creating one or more
.mdfiles, one for each rule. PSRule uses a naming convention with a file name the same as the rule to match rule to markdown.For example,
metadata.Name.mdwould be used for a rule namedmetadata.Name.We recommend matching the rule name case exactly when naming markdown files. This is because some file systems are case-sensitive. For example on Linux
Metadata.Name.mdwould not match.Within each markdown file a number of predefined sections are automatically interpreted by PSRule. While it is possible to have additional sections, they will be ignored by the help system.
The basic structure of markdown help is as follows:
---\n{{ Annotations }}\n---\n\n# {{ Name of rule }}\n\n## SYNOPSIS\n\n{{ A brief summary of the rule }}\n\n## DESCRIPTION\n\n{{ A detailed description of the rule }}\n\n## RECOMMENDATION\n\n{{ A detailed explanation of the steps required to pass the rule }}\n\n## NOTES\n\n{{ Additional information or configuration options }}\n\n## LINKS\n\n{{ Links to external references }}\nThe PSRule Visual Studio Code extension includes snippets for writing markdown documentation.
"},{"location":"authoring/writing-rule-help/#annotations","title":"Annotations","text":"The annotation front matter at the top of the markdown document, is a set of key value pairs. Front matter follows YAML conventions and must start on the first line of the markdown document.
A
---on a separate line indicates the start and end of the front matter block. Within the front matter block, all key value pairs are treated as annotations by PSRule.Annotations are optional metadata that are associated with the rule. Any annotations associated with a rule are included in output. Some examples of annotations include;
severity,category,author.Annotations differ from tags in two key ways:
The following reserved annotation exists:
---\nonline version: https://github.com/microsoft/PSRule/blob/main/docs/scenarios/rule-docs/rule-docs.md\n---\nThe front matter start and end
"},{"location":"authoring/writing-rule-help/#display-name","title":"Display name","text":"---are not required and can be removed if no annotations are defined.The document title, indicated by a level one heading
#is the display name of the rule. The rule display name is shown when usingGet-PSRuleHelpand is included in output.Specify the display name on a single line. Wrapping the display name across multiple lines is not supported.
For example:
"},{"location":"authoring/writing-rule-help/#synopsis-section","title":"Synopsis section","text":"# Use recommended name label\nThe synopsis section is indicated by the heading
## SYNOPSIS. Any text following the heading is interpreted by PSRule and included in output. The synopsis is displayed when usingGet-PSRuleandGet-PSRuleHelpcmdlets.The synopsis is intended to be a brief description of the rule, over a single line. A good synopsis should convey the purpose of the rule. A more verbose description can be included in the description section.
For example:
"},{"location":"authoring/writing-rule-help/#description-section","title":"Description section","text":"## SYNOPSIS\n\nDeployments and services must use the app.kubernetes.io/name label.\nThe description section is indicated by the heading
## DESCRIPTION. Any text following the heading is interpreted by PSRule and included in output. The description is displayed when using theGet-PSRuleHelpcmdlet.The description is intended to be a verbose description of the rule. If your rule documentation needs to include background information include it here.
PSRule supports semantic line breaks, and will automatically run together lines into a single paragraph. Use a blank line to separate paragraphs.
For example:
"},{"location":"authoring/writing-rule-help/#recommendation-section","title":"Recommendation section","text":"## DESCRIPTION\n\nKubernetes defines a common set of labels that are recommended for tool interoperability.\nThese labels should be used to consistently apply standard metadata.\n\nThe `app.kubernetes.io/name` label should be used to specify the name of the application.\nThe recommendation section is indicated by the heading
## RECOMMENDATION. Any text following the heading is interpreted by PSRule and included in output. The recommendation is displayed when using theInvoke-PSRuleandGet-PSRuleHelpcmdlets.The recommendation is intended to identify corrective actions that can be taken to address any failures. Avoid using URLs within the recommendation. Use the links section to include references to external sources.
PSRule supports semantic line breaks, and will automatically run together lines into a single paragraph. Use a blank line to separate paragraphs.
For example:
"},{"location":"authoring/writing-rule-help/#notes-section","title":"Notes section","text":"## RECOMMENDATION\n\nConsider setting the recommended label `app.kubernetes.io/name` on deployment and service resources.\nThe notes section is indicated by the heading
## NOTES. Any text following the heading is interpreted by PSRule and included in pipeline output. Notes are excluded when formatting output as YAML and JSON.To view any included notes use the
Get-PSRuleHelpcmdlet with the-Fullswitch.Use notes to include additional information such configuration options.
PSRule supports semantic line breaks, and will automatically run together lines into a single paragraph. Use a blank line to separate paragraphs.
For example:
"},{"location":"authoring/writing-rule-help/#links-section","title":"Links section","text":"## NOTES\n\nThe Kubernetes recommended labels include:\n\n- `app.kubernetes.io/name`\n- `app.kubernetes.io/instance`\n- `app.kubernetes.io/version`\n- `app.kubernetes.io/component`\n- `app.kubernetes.io/part-of`\n- `app.kubernetes.io/managed-by`\nThe links section is indicated by the heading
## LINKS. Any markdown links following the heading are interpreted by PSRule and included in pipeline output. Links are excluded when formatting output as YAML and JSON.To view any included links use the
Get-PSRuleHelpcmdlet with the-Fullswitch.Use links to reference external sources with a URL.
To specify links, use the markdown syntax
[display name](url). Include each link on a separate line. To improve display in web rendered markdown, use a list of links by prefixing the line with-.Additional text such as
See additional information:is useful for web rendered views, but ignored by PSRule.For example:
"},{"location":"authoring/writing-rule-help/#localizing-documentation-files","title":"Localizing documentation files","text":"## LINKS\n\n- [Recommended Labels](https://kubernetes.io/docs/concepts/overview/working-with-objects/common-labels/)\nWhen distributing rules, you may need to provide rule help in different languages. PSRule builds on the culture system in PowerShell.
"},{"location":"authoring/writing-rule-help/#using-cultures","title":"Using cultures","text":"A directory structure is used to identify the markdown documentation that should be used for each culture.
To get a list of cultures in PowerShell the use cmdlet
Get-Culture -ListAvailable.For example, store documentation targeted to the culture
en-USin a directory nameden-US. Similarly, documentation for cultures such asen-AU,en-GBandfr-FRwould be in separate directories.If a directory for the exact culture
en-USdoesn't exist, PSRule will attempt to find the parent culture. For example, documentation would be read from a directory nameden.When naming directories for their culture, use exact case. This is because some file systems are case-sensitive. For example on Linux
"},{"location":"authoring/writing-rule-help/#culture-directory-search-path","title":"Culture directory search path","text":"en-uswould not match.The path that PSRule looks for a culture directory in varies depending on how the rule is redistributed. Rules can be redistributed individually (loose) or included in a module.
The following logic is used to locate the culture directory.
For example, loose file structure:
Module file structure:
Each resource must be tagged with mandatory tags.
"},{"location":"authoring/packaging-rules/Enterprise.Rules/en/Org.Az.Resource.Tagging/#description","title":"DESCRIPTION","text":"Azure resources can be tagged with additional metadata. Our enterprise standard requires that the following tags are used:
Consider tagging Azure resource with mandatory tags.
"},{"location":"authoring/packaging-rules/Enterprise.Rules/en/Org.Az.Resource.Tagging/#links","title":"LINKS","text":"Storage accounts should only accept encrypted connections.
"},{"location":"authoring/packaging-rules/Enterprise.Rules/en/Org.Az.Storage.UseHttps/#description","title":"DESCRIPTION","text":"An Azure Storage Account is configured to allow unencrypted connections. This does not indicate that unencrypted connections are being used.
Unencrypted communication to storage accounts could allow disclosure of information to an untrusted party.
Storage Accounts can be configured to require encrypted connections, by setting the Secure transfer required option. If secure transfer required is not enabled (the default), unencrypted and encrypted connections are permitted.
When secure transfer required is enabled, attempts to connect to storage using HTTP or unencrypted SMB connections are rejected.
"},{"location":"authoring/packaging-rules/Enterprise.Rules/en/Org.Az.Storage.UseHttps/#recommendation","title":"RECOMMENDATION","text":"Storage accounts should only accept secure traffic. Consider setting secure transfer required if there is no requirement to access storage over unencrypted connections. Also consider using Azure Policy to audit or enforce this configuration.
"},{"location":"authoring/packaging-rules/Enterprise.Rules/en/Org.Az.Storage.UseHttps/#links","title":"LINKS","text":"Deployments and services must use the app.kubernetes.io/name label.
"},{"location":"authoring/writing-rule-help/en-US/metadata.Name/#description","title":"DESCRIPTION","text":"Kubernetes defines a common set of labels that are recommended for tool interoperability. These labels should be used to consistently apply standard metadata.
The
"},{"location":"authoring/writing-rule-help/en-US/metadata.Name/#recommendation","title":"RECOMMENDATION","text":"app.kubernetes.io/namelabel should be used to specify the name of the application.Consider setting the recommended label
"},{"location":"authoring/writing-rule-help/en-US/metadata.Name/#notes","title":"NOTES","text":"app.kubernetes.io/nameon deployment and service resources.The Kubernetes recommended labels include:
Evaluate objects against matching rules and assert any failures.
"},{"location":"commands/PSRule/en-US/Assert-PSRule/#syntax","title":"SYNTAX","text":""},{"location":"commands/PSRule/en-US/Assert-PSRule/#input-default","title":"Input (Default)","text":"
"},{"location":"commands/PSRule/en-US/Assert-PSRule/#inputpath","title":"InputPath","text":"Assert-PSRule [-Module <String[]>] [-Format <InputFormat>] [-Baseline <BaselineOption>]\n [-Convention <String[]>] [-Style <OutputStyle>] [-Outcome <RuleOutcome>] [-As <ResultFormat>]\n [[-Path] <String[]>] [-Name <String[]>] [-Tag <Hashtable>] [-OutputPath <String>]\n [-OutputFormat <OutputFormat>] [-Option <PSRuleOption>] [-ObjectPath <String>] [-TargetType <String[]>]\n [-Culture <String[]>] -InputObject <PSObject> [-ResultVariable <String>] [-WhatIf] [-Confirm]\n [<CommonParameters>]\n
"},{"location":"commands/PSRule/en-US/Assert-PSRule/#description","title":"DESCRIPTION","text":"Assert-PSRule -InputPath <String[]> [-Module <String[]>] [-Format <InputFormat>] [-Baseline <BaselineOption>]\n [-Convention <String[]>] [-Style <OutputStyle>] [-Outcome <RuleOutcome>] [-As <ResultFormat>]\n [[-Path] <String[]>] [-Name <String[]>] [-Tag <Hashtable>] [-OutputPath <String>]\n [-OutputFormat <OutputFormat>] [-Option <PSRuleOption>] [-ObjectPath <String>] [-TargetType <String[]>]\n [-Culture <String[]>] [-ResultVariable <String>] [-WhatIf] [-Confirm] [<CommonParameters>]\nEvaluate objects against matching rules and assert any failures. Objects can be specified directly from the pipeline or provided from file.
The commands
Invoke-PSRuleandAssert-PSRuleprovide similar functionality, as differ as follows:@{ Name = 'Item 1' } | Assert-PSRule;\nEvaluate a simple hashtable on the pipeline against rules loaded from the current working path.
"},{"location":"commands/PSRule/en-US/Assert-PSRule/#example-2","title":"Example 2","text":"# Define objects to validate\n$items = @();\n$items += [PSCustomObject]@{ Name = 'Fridge' };\n$items += [PSCustomObject]@{ Name = 'Apple' };\n\n# Validate each item using rules saved in current working path\n$items | Assert-PSRule -Path .\\docs\\scenarios\\fruit\\\n-> Fridge : System.Management.Automation.PSCustomObject\n\n [FAIL] isFruit\n\n-> Apple : System.Management.Automation.PSCustomObject\n\n [PASS] isFruit\n\nAssert-PSRule : One or more rules reported failure.\nAt line:1 char:10\n+ $items | Assert-PSRule -Path .\\docs\\scenarios\\fruit\\\n+ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n+ CategoryInfo : InvalidData: (:) [Assert-PSRule], FailPipelineException\n+ FullyQualifiedErrorId : PSRule.Fail,Assert-PSRule\nEvaluate an array of objects on the pipeline against rules loaded a specified relative path.
"},{"location":"commands/PSRule/en-US/Assert-PSRule/#example-3","title":"Example 3","text":"$items | Assert-PSRule -Module PSRule.Rules.Azure -o NUnit3 -OutputPath .\\reports\\results.xml\nEvaluate items from a pre-installed rules module PSRule.Rules.Azure. Additionally save the results as a NUnit report.
"},{"location":"commands/PSRule/en-US/Assert-PSRule/#example-4","title":"Example 4","text":"$items | Assert-PSRule -Path .\\docs\\scenarios\\fruit\\ -ResultVariable resultRecords;\nEvaluate items and additionally save the results into a variable
"},{"location":"commands/PSRule/en-US/Assert-PSRule/#parameters","title":"PARAMETERS","text":""},{"location":"commands/PSRule/en-US/Assert-PSRule/#-inputpath","title":"-InputPath","text":"resultRecords.Instead of processing objects from the pipeline, import objects file the specified file paths.
"},{"location":"commands/PSRule/en-US/Assert-PSRule/#-format","title":"-Format","text":"Type: String[]\nParameter Sets: InputPath\nAliases: f\n\nRequired: True\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nConfigures the input format for when a string is passed in as a target object.
When the
-InputObjectparameter or pipeline input is used, strings are treated as plain text by default. Set this option to eitherYaml,Json,Markdown,PowerShellDatato have PSRule deserialize the object.When the
-InputPathparameter is used with a file path or URL. If theDetectformat is used, the file extension will be used to automatically detect the format. When-InputPathis not used,Detectis the same asNone.When this option is set to
FilePSRule scans the path and subdirectories specified by-InputPath. Files are treated as objects instead of being deserialized. Additional, PSRule uses the file extension as the object type. When files have no extension the whole file name is used.See
about_PSRule_Optionsfor details.This parameter takes precedence over the
Input.Formatoption if set.
"},{"location":"commands/PSRule/en-US/Assert-PSRule/#-baseline","title":"-Baseline","text":"Type: InputFormat\nParameter Sets: (All)\nAliases:\nAccepted values: None, Yaml, Json, Markdown, PowerShellData, File, Detect\n\nRequired: False\nPosition: Named\nDefault value: Detect\nAccept pipeline input: False\nAccept wildcard characters: False\nSpecifies an explicit baseline by name to use for evaluating rules. Baselines can contain filters and custom configuration that overrides the defaults.
"},{"location":"commands/PSRule/en-US/Assert-PSRule/#-convention","title":"-Convention","text":"Type: BaselineOption\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nSpecifies conventions by name to execute in the pipeline when processing objects.
"},{"location":"commands/PSRule/en-US/Assert-PSRule/#-culture","title":"-Culture","text":"Type: String[]\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nSpecifies the culture to use for rule documentation and messages. By default, the culture of PowerShell is used.
This option does not affect the culture used for the PSRule engine, which always uses the culture of PowerShell.
The PowerShell cmdlet
Get-Cultureshows the current culture of PowerShell.
"},{"location":"commands/PSRule/en-US/Assert-PSRule/#-module","title":"-Module","text":"Type: String[]\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nSearch for rule definitions within a module. If no sources are specified by
-Path,-Module, or options, the current working directory is used.
"},{"location":"commands/PSRule/en-US/Assert-PSRule/#-name","title":"-Name","text":"Type: String[]\nParameter Sets: (All)\nAliases: m\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nThe name of a specific rule to evaluate. If this parameter is not specified all rules in search paths will be evaluated.
"},{"location":"commands/PSRule/en-US/Assert-PSRule/#-objectpath","title":"-ObjectPath","text":"Type: String[]\nParameter Sets: (All)\nAliases: n\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nThe name of a property to use instead of the pipeline object. If the property specified by
ObjectPathis a collection or an array, then each item in evaluated separately.
"},{"location":"commands/PSRule/en-US/Assert-PSRule/#-targettype","title":"-TargetType","text":"Type: String\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nFilters input objects by TargetType.
If specified, only objects with the specified TargetType are processed. Objects that do not match TargetType are ignored. If multiple values are specified, only one TargetType must match. This parameter is not case-sensitive.
By default, all objects are processed.
This parameter if set, overrides the
Input.TargetTypeoption.To change the field TargetType is bound to set the
Binding.TargetTypeoption. For details see the about_PSRule_Options help topic.
"},{"location":"commands/PSRule/en-US/Assert-PSRule/#-option","title":"-Option","text":"Type: String[]\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nAdditional options that configure execution. A
PSRuleOptioncan be created by using theNew-PSRuleOptioncmdlet. Alternatively, a hashtable or path to YAML file can be specified with options.For more information on PSRule options see about_PSRule_Options.
"},{"location":"commands/PSRule/en-US/Assert-PSRule/#-outputpath","title":"-OutputPath","text":"Type: PSRuleOption\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nSpecifies the output file path to write results. Directories along the file path will automatically be created if they do not exist.
"},{"location":"commands/PSRule/en-US/Assert-PSRule/#-outputformat","title":"-OutputFormat","text":"Type: String\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nConfigures the format that output is written. This parameter has no affect when
-OutputPathis not specified.The following format options are available:
The
Wideformat is not applicable toAssert-PSRule.
"},{"location":"commands/PSRule/en-US/Assert-PSRule/#-style","title":"-Style","text":"Type: OutputFormat\nParameter Sets: (All)\nAliases: o\nAccepted values: None, Yaml, Json, Markdown, NUnit3, Csv, Sarif\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nConfigures the style that results will be presented in.
The following styles are available:
Detect uses the following logic:
Each of these styles outputs to the host. To capture output as a string redirect the information stream. For example:
6>&1
"},{"location":"commands/PSRule/en-US/Assert-PSRule/#-as","title":"-As","text":"Type: OutputStyle\nParameter Sets: (All)\nAliases:\nAccepted values: Client, Plain, AzurePipelines, GitHubActions, VisualStudioCode, Detect\n\nRequired: False\nPosition: Named\nDefault value: Client\nAccept pipeline input: False\nAccept wildcard characters: False\nThe type of results to produce. Detailed results are generated by default.
The following result formats are available:
"},{"location":"commands/PSRule/en-US/Assert-PSRule/#-outcome","title":"-Outcome","text":"Type: ResultFormat\nParameter Sets: (All)\nAliases:\nAccepted values: Detail, Summary\n\nRequired: False\nPosition: Named\nDefault value: Detail\nAccept pipeline input: False\nAccept wildcard characters: False\nFilter output to only show rule results with a specific outcome.
"},{"location":"commands/PSRule/en-US/Assert-PSRule/#-path","title":"-Path","text":"Type: RuleOutcome\nParameter Sets: (All)\nAliases:\nAccepted values: Pass, Fail, Error, None, Processed, All\n\nRequired: False\nPosition: Named\nDefault value: Pass, Fail, Error\nAccept pipeline input: False\nAccept wildcard characters: False\nOne or more paths to search for rule definitions within.
"},{"location":"commands/PSRule/en-US/Assert-PSRule/#-tag","title":"-Tag","text":"Type: String[]\nParameter Sets: (All)\nAliases: p\n\nRequired: False\nPosition: 0\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nOnly get rules with the specified tags set. If this parameter is not specified all rules in search paths will be returned.
When more than one tag is used, all tags must match. Tags are not case sensitive. A tag value of
*may be used to filter rules to any rule with the tag set, regardless of tag value.An array of tag values can be used to match a rule with either value. i.e.
severity = important, criticalmatches rules with a category of eitherimportantorcritical.
"},{"location":"commands/PSRule/en-US/Assert-PSRule/#-inputobject","title":"-InputObject","text":"Type: Hashtable\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nThe pipeline object to process rules for.
"},{"location":"commands/PSRule/en-US/Assert-PSRule/#-resultvariable","title":"-ResultVariable","text":"Type: PSObject\nParameter Sets: Input\nAliases: TargetObject\n\nRequired: True\nPosition: Named\nDefault value: None\nAccept pipeline input: True (ByValue)\nAccept wildcard characters: False\nStores output result objects in the specified variable.
"},{"location":"commands/PSRule/en-US/Assert-PSRule/#-whatif","title":"-WhatIf","text":"Type: String\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nShows what would happen if the cmdlet runs. The cmdlet is not run.
"},{"location":"commands/PSRule/en-US/Assert-PSRule/#-confirm","title":"-Confirm","text":"Type: SwitchParameter\nParameter Sets: (All)\nAliases: wi\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nPrompts you for confirmation before running the cmdlet.
"},{"location":"commands/PSRule/en-US/Assert-PSRule/#commonparameters","title":"CommonParameters","text":"Type: SwitchParameter\nParameter Sets: (All)\nAliases: cf\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nThis cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters.
"},{"location":"commands/PSRule/en-US/Assert-PSRule/#inputs","title":"INPUTS","text":""},{"location":"commands/PSRule/en-US/Assert-PSRule/#systemmanagementautomationpsobject","title":"System.Management.Automation.PSObject","text":"You can pipe any object to Assert-PSRule.
"},{"location":"commands/PSRule/en-US/Assert-PSRule/#outputs","title":"OUTPUTS","text":""},{"location":"commands/PSRule/en-US/Assert-PSRule/#systemstring","title":"System.String","text":""},{"location":"commands/PSRule/en-US/Assert-PSRule/#notes","title":"NOTES","text":""},{"location":"commands/PSRule/en-US/Assert-PSRule/#related-links","title":"RELATED LINKS","text":"Get-PSRule
Invoke-PSRule
Test-PSRuleTarget
"},{"location":"commands/PSRule/en-US/Export-PSRuleBaseline/","title":"Export-PSRuleBaseline","text":""},{"location":"commands/PSRule/en-US/Export-PSRuleBaseline/#synopsis","title":"SYNOPSIS","text":"Exports a list of baselines.
"},{"location":"commands/PSRule/en-US/Export-PSRuleBaseline/#syntax","title":"SYNTAX","text":"
"},{"location":"commands/PSRule/en-US/Export-PSRuleBaseline/#description","title":"DESCRIPTION","text":"Export-PSRuleBaseline [-Module <String[]>] [[-Path] <String[]>] [-Name <String[]>] [-Option <PSRuleOption>]\n [-Culture <String>] [-OutputFormat <OutputFormat>] -OutputPath <String> [-OutputEncoding <OutputEncoding>]\n [-WhatIf] [-Confirm] [<CommonParameters>]\nExports a list of baselines to a file.
"},{"location":"commands/PSRule/en-US/Export-PSRuleBaseline/#examples","title":"EXAMPLES","text":""},{"location":"commands/PSRule/en-US/Export-PSRuleBaseline/#example-1","title":"Example 1","text":"Export-PSRuleBaseline -Module PSRule.Rules.Azure -OutputFormat Yaml -OutputPath Baseline.Rule.yml\nExports list of baselines from
"},{"location":"commands/PSRule/en-US/Export-PSRuleBaseline/#parameters","title":"PARAMETERS","text":""},{"location":"commands/PSRule/en-US/Export-PSRuleBaseline/#-module","title":"-Module","text":"PSRule.Rules.Azuremodule to fileBaseline.Rule.ymlin YAML output format.Search for baselines definitions within a module. If no sources are specified by
-Path,-Module, or options, the current working directory is used.
"},{"location":"commands/PSRule/en-US/Export-PSRuleBaseline/#-path","title":"-Path","text":"Type: String[]\nParameter Sets: (All)\nAliases: m\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nOne or more paths to search for baselines within.
"},{"location":"commands/PSRule/en-US/Export-PSRuleBaseline/#-name","title":"-Name","text":"Type: String[]\nParameter Sets: (All)\nAliases: p\n\nRequired: False\nPosition: 1\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nThe name of a specific baseline to list. If this parameter is not specified all baselines in search paths will be listed.
"},{"location":"commands/PSRule/en-US/Export-PSRuleBaseline/#-option","title":"-Option","text":"Type: String[]\nParameter Sets: (All)\nAliases: n\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: True\nAdditional options that configure execution. A
PSRuleOptioncan be created by using theNew-PSRuleOptioncmdlet. Alternatively a hashtable or path to YAML file can be specified with options.For more information on PSRule options see about_PSRule_Options.
"},{"location":"commands/PSRule/en-US/Export-PSRuleBaseline/#-culture","title":"-Culture","text":"Type: PSRuleOption\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nSpecifies the culture to use for documentation and messages. By default, the culture of PowerShell is used.
This option does not affect the culture used for the PSRule engine, which always uses the culture of PowerShell.
The PowerShell cmdlet
Get-Cultureshows the current culture of PowerShell.
"},{"location":"commands/PSRule/en-US/Export-PSRuleBaseline/#-outputformat","title":"-OutputFormat","text":"Type: String\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nConfigures the format that output is presented in.
The following format options are available:
"},{"location":"commands/PSRule/en-US/Export-PSRuleBaseline/#-outputencoding","title":"-OutputEncoding","text":"Type: OutputFormat\nParameter Sets: (All)\nAliases: o\nAccepted values: Yaml, Json\n\nRequired: False\nPosition: Named\nDefault value: Yaml\nAccept pipeline input: False\nAccept wildcard characters: False\nSets the option
Output.Encoding. TheOutput.Encodingoption configured the encoding used to write results to file.
"},{"location":"commands/PSRule/en-US/Export-PSRuleBaseline/#-outputpath","title":"-OutputPath","text":"Type: OutputEncoding\nParameter Sets: (All)\nAliases:\nAccepted values: Default, UTF8, UTF7, Unicode, UTF32, ASCII\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nSets the option
Output.Path. TheOutput.Pathoption configures the output path the results are written to.
"},{"location":"commands/PSRule/en-US/Export-PSRuleBaseline/#-whatif","title":"-WhatIf","text":"Type: String\nParameter Sets: (All)\nAliases:\n\nRequired: True\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nShows what would happen if the cmdlet runs. The cmdlet is not run.
"},{"location":"commands/PSRule/en-US/Export-PSRuleBaseline/#-confirm","title":"-Confirm","text":"Type: SwitchParameter\nParameter Sets: (All)\nAliases: wi\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nPrompts you for confirmation before running the cmdlet.
"},{"location":"commands/PSRule/en-US/Export-PSRuleBaseline/#commonparameters","title":"CommonParameters","text":"Type: SwitchParameter\nParameter Sets: (All)\nAliases: cf\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nThis cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters.
"},{"location":"commands/PSRule/en-US/Export-PSRuleBaseline/#inputs","title":"INPUTS","text":""},{"location":"commands/PSRule/en-US/Export-PSRuleBaseline/#outputs","title":"OUTPUTS","text":""},{"location":"commands/PSRule/en-US/Export-PSRuleBaseline/#notes","title":"NOTES","text":""},{"location":"commands/PSRule/en-US/Export-PSRuleBaseline/#related-links","title":"RELATED LINKS","text":"Get-PSRuleBaseline
"},{"location":"commands/PSRule/en-US/Get-PSRule/","title":"Get-PSRule","text":""},{"location":"commands/PSRule/en-US/Get-PSRule/#synopsis","title":"SYNOPSIS","text":"Get a list of rule definitions.
"},{"location":"commands/PSRule/en-US/Get-PSRule/#syntax","title":"SYNTAX","text":"
"},{"location":"commands/PSRule/en-US/Get-PSRule/#description","title":"DESCRIPTION","text":"Get-PSRule [-Module <String[]>] [-ListAvailable] [-OutputFormat <OutputFormat>] [-Baseline <BaselineOption>]\n [[-Path] <String[]>] [-Name <String[]>] [-Tag <Hashtable>] [-Option <PSRuleOption>] [-Culture <String>]\n [-IncludeDependencies] [<CommonParameters>]\nGet a list of matching rule definitions within the search path.
"},{"location":"commands/PSRule/en-US/Get-PSRule/#examples","title":"EXAMPLES","text":""},{"location":"commands/PSRule/en-US/Get-PSRule/#example-1","title":"Example 1","text":"Get-PSRule;\nRuleName ModuleName Synopsis\n-------- ---------- --------\nisFruit An example rule\nGet a list of rule definitions from the current working path.
"},{"location":"commands/PSRule/en-US/Get-PSRule/#example-2","title":"Example 2","text":"Get-PSRule -Module PSRule.Rules.Azure;\nRuleName ModuleName Synopsis\n-------- ---------- --------\nAzure.ACR.AdminUser PSRule.Rules.Azure Use Azure AD accounts instead of using the registry adm\u2026\nAzure.ACR.MinSku PSRule.Rules.Azure ACR should use the Premium or Standard SKU for producti\u2026\nAzure.AKS.MinNodeCount PSRule.Rules.Azure AKS clusters should have minimum number of nodes for fa\u2026\nAzure.AKS.Version PSRule.Rules.Azure AKS clusters should meet the minimum version.\nAzure.AKS.UseRBAC PSRule.Rules.Azure AKS cluster should use role-based access control (RBAC).\nGet a list of rule definitions included in the module
"},{"location":"commands/PSRule/en-US/Get-PSRule/#example-3","title":"Example 3","text":"PSRule.Rules.Azure.Get-PSRule -Module PSRule.Rules.Azure -OutputFormat Wide;\nRuleName ModuleName Synopsis Tag\n-------- ---------- -------- ---\nAzure.ACR.AdminUser PSRule.Rules.Azure Use Azure AD accounts severity='Critical'\n instead of using the category='Security\n registry admin user. configuration'\nAzure.ACR.MinSku PSRule.Rules.Azure ACR should use the Premium severity='Important'\n or Standard SKU for category='Performance'\n production deployments.\nAzure.AKS.MinNodeCount PSRule.Rules.Azure AKS clusters should have severity='Important'\n minimum number of nodes for category='Reliability'\n failover and updates.\nAzure.AKS.Version PSRule.Rules.Azure AKS clusters should meet severity='Important'\n the minimum version. category='Operations\n management'\nAzure.AKS.UseRBAC PSRule.Rules.Azure AKS cluster should use severity='Important'\n role-based access control category='Security\n (RBAC). configuration'\nGet a list of rule definitions included in the module
"},{"location":"commands/PSRule/en-US/Get-PSRule/#parameters","title":"PARAMETERS","text":""},{"location":"commands/PSRule/en-US/Get-PSRule/#-name","title":"-Name","text":"PSRule.Rules.Azureincluding tags with line wrapping.The name of a specific rule to list. If this parameter is not specified all rules in search paths will be listed.
"},{"location":"commands/PSRule/en-US/Get-PSRule/#-path","title":"-Path","text":"Type: String[]\nParameter Sets: (All)\nAliases: n\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nOne or more paths to search for rule definitions within.
"},{"location":"commands/PSRule/en-US/Get-PSRule/#-tag","title":"-Tag","text":"Type: String[]\nParameter Sets: (All)\nAliases: p\n\nRequired: False\nPosition: 0\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nOnly get rules with the specified tags set. If this parameter is not specified all rules in search paths will be returned.
When more than one tag is used, all tags must match. Tags are not case sensitive. A tag value of
*may be used to filter rules to any rule with the tag set, regardless of tag value.An array of tag values can be used to match a rule with either value. i.e.
severity = important, criticalmatches rules with a category of eitherimportantorcritical.
"},{"location":"commands/PSRule/en-US/Get-PSRule/#-option","title":"-Option","text":"Type: Hashtable\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nAdditional options that configure execution. A
PSRuleOptioncan be created by using theNew-PSRuleOptioncmdlet. Alternatively a hashtable or path to YAML file can be specified with options.For more information on PSRule options see about_PSRule_Options.
"},{"location":"commands/PSRule/en-US/Get-PSRule/#-listavailable","title":"-ListAvailable","text":"Type: PSRuleOption\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nLook for modules containing rule definitions including modules that are currently not imported.
This switch is used with the
-Moduleparameter.
"},{"location":"commands/PSRule/en-US/Get-PSRule/#-module","title":"-Module","text":"Type: SwitchParameter\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nSearch for rule definitions within a module. If no sources are specified by
-Path,-Module, or options, the current working directory is used.
"},{"location":"commands/PSRule/en-US/Get-PSRule/#-culture","title":"-Culture","text":"Type: String[]\nParameter Sets: (All)\nAliases: m\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nSpecifies the culture to use for documentation and messages. By default, the culture of PowerShell is used.
This option does not affect the culture used for the PSRule engine, which always uses the culture of PowerShell.
The PowerShell cmdlet
Get-Cultureshows the current culture of PowerShell.
"},{"location":"commands/PSRule/en-US/Get-PSRule/#-outputformat","title":"-OutputFormat","text":"Type: String\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nConfigures the format that output is presented in.
The following format options are available:
"},{"location":"commands/PSRule/en-US/Get-PSRule/#-includedependencies","title":"-IncludeDependencies","text":"Type: OutputFormat\nParameter Sets: (All)\nAliases: o\nAccepted values: None, Wide, Yaml, Json\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nWhen this switch is specified, dependencies of the rules that meet the
-Nameand-Tagfilters are included even if they would normally be excluded.This switch has no affect when getting an unfiltered list of rules.
"},{"location":"commands/PSRule/en-US/Get-PSRule/#-baseline","title":"-Baseline","text":"Type: SwitchParameter\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nWhen specified, rules are filtered so that only rules that are included in the baselines are returned.
"},{"location":"commands/PSRule/en-US/Get-PSRule/#commonparameters","title":"CommonParameters","text":"Type: BaselineOption\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nThis cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters.
"},{"location":"commands/PSRule/en-US/Get-PSRule/#inputs","title":"INPUTS","text":""},{"location":"commands/PSRule/en-US/Get-PSRule/#none","title":"None","text":""},{"location":"commands/PSRule/en-US/Get-PSRule/#outputs","title":"OUTPUTS","text":""},{"location":"commands/PSRule/en-US/Get-PSRule/#psruledefinitionsrulesirulev1","title":"PSRule.Definitions.Rules.IRuleV1","text":""},{"location":"commands/PSRule/en-US/Get-PSRule/#notes","title":"NOTES","text":""},{"location":"commands/PSRule/en-US/Get-PSRule/#related-links","title":"RELATED LINKS","text":"Invoke-PSRule
"},{"location":"commands/PSRule/en-US/Get-PSRuleBaseline/","title":"Get-PSRuleBaseline","text":""},{"location":"commands/PSRule/en-US/Get-PSRuleBaseline/#synopsis","title":"SYNOPSIS","text":"Get a list of baselines.
"},{"location":"commands/PSRule/en-US/Get-PSRuleBaseline/#syntax","title":"SYNTAX","text":"
"},{"location":"commands/PSRule/en-US/Get-PSRuleBaseline/#description","title":"DESCRIPTION","text":"Get-PSRuleBaseline [-Module <String[]>] [-ListAvailable] [[-Path] <String[]>] [-Name <String[]>]\n [-Option <PSRuleOption>] [-Culture <String>] [-OutputFormat <OutputFormat>] [<CommonParameters>]\nGet a list of matching baselines within the search path.
"},{"location":"commands/PSRule/en-US/Get-PSRuleBaseline/#examples","title":"EXAMPLES","text":""},{"location":"commands/PSRule/en-US/Get-PSRuleBaseline/#example-1","title":"Example 1","text":"Get-PSRuleBaseline;\nGet a list of baselines from the current working path.
"},{"location":"commands/PSRule/en-US/Get-PSRuleBaseline/#parameters","title":"PARAMETERS","text":""},{"location":"commands/PSRule/en-US/Get-PSRuleBaseline/#-module","title":"-Module","text":"Search for baselines definitions within a module. If no sources are specified by
-Path,-Module, or options, the current working directory is used.
"},{"location":"commands/PSRule/en-US/Get-PSRuleBaseline/#-listavailable","title":"-ListAvailable","text":"Type: String[]\nParameter Sets: (All)\nAliases: m\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nLook for modules containing baselines including modules that are currently not imported.
This switch is used with the
-Moduleparameter.
"},{"location":"commands/PSRule/en-US/Get-PSRuleBaseline/#-path","title":"-Path","text":"Type: SwitchParameter\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: False\nAccept pipeline input: False\nAccept wildcard characters: False\nOne or more paths to search for baselines within.
"},{"location":"commands/PSRule/en-US/Get-PSRuleBaseline/#-name","title":"-Name","text":"Type: String[]\nParameter Sets: (All)\nAliases: p\n\nRequired: False\nPosition: 1\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nThe name of a specific baseline to list. If this parameter is not specified all baselines in search paths will be listed.
"},{"location":"commands/PSRule/en-US/Get-PSRuleBaseline/#-option","title":"-Option","text":"Type: String[]\nParameter Sets: (All)\nAliases: n\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: True\nAdditional options that configure execution. A
PSRuleOptioncan be created by using theNew-PSRuleOptioncmdlet. Alternatively a hashtable or path to YAML file can be specified with options.For more information on PSRule options see about_PSRule_Options.
"},{"location":"commands/PSRule/en-US/Get-PSRuleBaseline/#-culture","title":"-Culture","text":"Type: PSRuleOption\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nSpecifies the culture to use for documentation and messages. By default, the culture of PowerShell is used.
This option does not affect the culture used for the PSRule engine, which always uses the culture of PowerShell.
The PowerShell cmdlet
Get-Cultureshows the current culture of PowerShell.
"},{"location":"commands/PSRule/en-US/Get-PSRuleBaseline/#-outputformat","title":"-OutputFormat","text":"Type: String\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nConfigures the format that output is presented in.
The following format options are available:
"},{"location":"commands/PSRule/en-US/Get-PSRuleBaseline/#commonparameters","title":"CommonParameters","text":"Type: OutputFormat\nParameter Sets: (All)\nAliases: o\nAccepted values: None, Yaml, Json\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nThis cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters.
"},{"location":"commands/PSRule/en-US/Get-PSRuleBaseline/#inputs","title":"INPUTS","text":""},{"location":"commands/PSRule/en-US/Get-PSRuleBaseline/#outputs","title":"OUTPUTS","text":""},{"location":"commands/PSRule/en-US/Get-PSRuleBaseline/#psruledefinitionsbaseline","title":"PSRule.Definitions.Baseline","text":"This is the default.
"},{"location":"commands/PSRule/en-US/Get-PSRuleBaseline/#systemstring","title":"System.String","text":"When you use
"},{"location":"commands/PSRule/en-US/Get-PSRuleBaseline/#notes","title":"NOTES","text":""},{"location":"commands/PSRule/en-US/Get-PSRuleBaseline/#related-links","title":"RELATED LINKS","text":"-OutputFormat Yamlor-OutputFormat Json.Get-PSRule
"},{"location":"commands/PSRule/en-US/Get-PSRuleHelp/","title":"Get-PSRuleHelp","text":""},{"location":"commands/PSRule/en-US/Get-PSRuleHelp/#synopsis","title":"SYNOPSIS","text":"Displays information about a rule.
"},{"location":"commands/PSRule/en-US/Get-PSRuleHelp/#syntax","title":"SYNTAX","text":"
"},{"location":"commands/PSRule/en-US/Get-PSRuleHelp/#description","title":"DESCRIPTION","text":"Get-PSRuleHelp [-Module <String>] [-Online] [-Full] [[-Name] <String[]>] [-Path <String>]\n [-Option <PSRuleOption>] [-Culture <String>] [<CommonParameters>]\nThe
Get-PSRuleHelpcmdlet display information about a rule.By default, this cmdlet will look for rules in the current path and loaded modules. To get help for a specific rule or module use the
-Nameor-Moduleparameters.If the rule has an online version of the documentation, use the
"},{"location":"commands/PSRule/en-US/Get-PSRuleHelp/#examples","title":"EXAMPLES","text":""},{"location":"commands/PSRule/en-US/Get-PSRuleHelp/#example-1","title":"Example 1","text":"-Onlineparameter to view it in your default web browser.Get-PSRuleHelp;\nGet a list of rule help within the current path or loaded modules.
"},{"location":"commands/PSRule/en-US/Get-PSRuleHelp/#example-2","title":"Example 2","text":"Get-PSRuleHelp Azure.ACR.AdminUser;\nGet rule documentation for the rule
"},{"location":"commands/PSRule/en-US/Get-PSRuleHelp/#example-3","title":"Example 3","text":"Azure.ACR.AdminUser.Get-PSRuleHelp Azure.ACR.AdminUser -Online;\nBrowse to the online version of documentation for
"},{"location":"commands/PSRule/en-US/Get-PSRuleHelp/#parameters","title":"PARAMETERS","text":""},{"location":"commands/PSRule/en-US/Get-PSRuleHelp/#-name","title":"-Name","text":"Azure.ACR.AdminUserusing the default web browser.The name of the rule to get documentation for.
"},{"location":"commands/PSRule/en-US/Get-PSRuleHelp/#-path","title":"-Path","text":"Type: String[]\nParameter Sets: (All)\nAliases: n\n\nRequired: False\nPosition: 1\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: True\nA path to check documentation for. By default, help from the current working path and loaded modules is listed. Results can be filtered by using
-Name,-Pathor-Module.
"},{"location":"commands/PSRule/en-US/Get-PSRuleHelp/#-module","title":"-Module","text":"Type: String\nParameter Sets: (All)\nAliases: p\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nLimit returned information to rules in the specified module. By default, help from the current working path and loaded modules is listed. Results can be filtered by using
-Name,-Pathor-Module.
"},{"location":"commands/PSRule/en-US/Get-PSRuleHelp/#-culture","title":"-Culture","text":"Type: String\nParameter Sets: (All)\nAliases: m\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nSpecifies the culture to use for rule documentation and messages. By default, the culture of PowerShell is used.
This option does not affect the culture used for the PSRule engine, which always uses the culture of PowerShell.
The PowerShell cmdlet
Get-Cultureshows the current culture of PowerShell.
"},{"location":"commands/PSRule/en-US/Get-PSRuleHelp/#-online","title":"-Online","text":"Type: String\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nInstead of displaying documentation within PowerShell, browse to the online version using the default web browser.
"},{"location":"commands/PSRule/en-US/Get-PSRuleHelp/#-full","title":"-Full","text":"Type: SwitchParameter\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: False\nAccept pipeline input: False\nAccept wildcard characters: False\nDisplay additional information such as notes and links.
"},{"location":"commands/PSRule/en-US/Get-PSRuleHelp/#-option","title":"-Option","text":"Type: SwitchParameter\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nAdditional options that configure execution. A
PSRuleOptioncan be created by using theNew-PSRuleOptioncmdlet. Alternatively a hashtable or path to YAML file can be specified with options.For more information on PSRule options see about_PSRule_Options.
"},{"location":"commands/PSRule/en-US/Get-PSRuleHelp/#commonparameters","title":"CommonParameters","text":"Type: PSRuleOption\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nThis cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters.
"},{"location":"commands/PSRule/en-US/Get-PSRuleHelp/#inputs","title":"INPUTS","text":""},{"location":"commands/PSRule/en-US/Get-PSRuleHelp/#none","title":"None","text":""},{"location":"commands/PSRule/en-US/Get-PSRuleHelp/#outputs","title":"OUTPUTS","text":""},{"location":"commands/PSRule/en-US/Get-PSRuleHelp/#psrulerulesrulehelpinfo","title":"PSRule.Rules.RuleHelpInfo","text":""},{"location":"commands/PSRule/en-US/Get-PSRuleHelp/#notes","title":"NOTES","text":""},{"location":"commands/PSRule/en-US/Get-PSRuleHelp/#related-links","title":"RELATED LINKS","text":""},{"location":"commands/PSRule/en-US/Get-PSRuleTarget/","title":"Get-PSRuleTarget","text":""},{"location":"commands/PSRule/en-US/Get-PSRuleTarget/#synopsis","title":"SYNOPSIS","text":"Get a list of target objects.
"},{"location":"commands/PSRule/en-US/Get-PSRuleTarget/#syntax","title":"SYNTAX","text":""},{"location":"commands/PSRule/en-US/Get-PSRuleTarget/#input-default","title":"Input (Default)","text":"
"},{"location":"commands/PSRule/en-US/Get-PSRuleTarget/#inputpath","title":"InputPath","text":"Get-PSRuleTarget [-Format <InputFormat>] [-Option <PSRuleOption>] [-ObjectPath <String>]\n -InputObject <PSObject> [-WhatIf] [-Confirm] [<CommonParameters>]\n
"},{"location":"commands/PSRule/en-US/Get-PSRuleTarget/#description","title":"DESCRIPTION","text":"Get-PSRuleTarget -InputPath <String[]> [-Format <InputFormat>] [-Option <PSRuleOption>] [-ObjectPath <String>]\n [-WhatIf] [-Confirm] [<CommonParameters>]\nGet a list of target objects from input.
"},{"location":"commands/PSRule/en-US/Get-PSRuleTarget/#examples","title":"EXAMPLES","text":""},{"location":"commands/PSRule/en-US/Get-PSRuleTarget/#example-1","title":"Example 1","text":"Get-PSRuleTarget -InputPath .\\resources.json;\nGet target objects from
"},{"location":"commands/PSRule/en-US/Get-PSRuleTarget/#parameters","title":"PARAMETERS","text":""},{"location":"commands/PSRule/en-US/Get-PSRuleTarget/#-inputpath","title":"-InputPath","text":"resources.json.Instead of processing objects from the pipeline, import objects file the specified file paths.
"},{"location":"commands/PSRule/en-US/Get-PSRuleTarget/#-format","title":"-Format","text":"Type: String[]\nParameter Sets: InputPath\nAliases: f\n\nRequired: True\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nConfigures the input format for when a string is passed in as a target object.
When the
-InputObjectparameter or pipeline input is used, strings are treated as plain text by default. Set this option to eitherYaml,Json,Markdown,PowerShellDatato have PSRule deserialize the object.When the
-InputPathparameter is used with a file path or URL. If theDetectformat is used, the file extension will be used to automatically detect the format. When-InputPathis not used,Detectis the same asNone.See
about_PSRule_Optionsfor details.This parameter takes precedence over the
Input.Formatoption if set.
"},{"location":"commands/PSRule/en-US/Get-PSRuleTarget/#-option","title":"-Option","text":"Type: InputFormat\nParameter Sets: (All)\nAliases:\nAccepted values: None, Yaml, Json, Markdown, PowerShellData, File, Detect\n\nRequired: False\nPosition: Named\nDefault value: Detect\nAccept pipeline input: False\nAccept wildcard characters: False\nAdditional options that configure execution. A
PSRuleOptioncan be created by using theNew-PSRuleOptioncmdlet. Alternatively, a hashtable or path to YAML file can be specified with options.For more information on PSRule options see about_PSRule_Options.
"},{"location":"commands/PSRule/en-US/Get-PSRuleTarget/#-objectpath","title":"-ObjectPath","text":"Type: PSRuleOption\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nThe name of a property to use instead of the pipeline object. If the property specified by
ObjectPathis a collection or an array, then each item in evaluated separately.
"},{"location":"commands/PSRule/en-US/Get-PSRuleTarget/#-inputobject","title":"-InputObject","text":"Type: String\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nThe pipeline object to process rules for.
"},{"location":"commands/PSRule/en-US/Get-PSRuleTarget/#-whatif","title":"-WhatIf","text":"Type: PSObject\nParameter Sets: Input\nAliases: TargetObject\n\nRequired: True\nPosition: Named\nDefault value: None\nAccept pipeline input: True (ByValue)\nAccept wildcard characters: False\nShows what would happen if the cmdlet runs. The cmdlet is not run.
"},{"location":"commands/PSRule/en-US/Get-PSRuleTarget/#-confirm","title":"-Confirm","text":"Type: SwitchParameter\nParameter Sets: (All)\nAliases: wi\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nPrompts you for confirmation before running the cmdlet.
"},{"location":"commands/PSRule/en-US/Get-PSRuleTarget/#commonparameters","title":"CommonParameters","text":"Type: SwitchParameter\nParameter Sets: (All)\nAliases: cf\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nThis cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters.
"},{"location":"commands/PSRule/en-US/Get-PSRuleTarget/#inputs","title":"INPUTS","text":""},{"location":"commands/PSRule/en-US/Get-PSRuleTarget/#outputs","title":"OUTPUTS","text":""},{"location":"commands/PSRule/en-US/Get-PSRuleTarget/#systemmanagementautomationpsobject","title":"System.Management.Automation.PSObject","text":""},{"location":"commands/PSRule/en-US/Get-PSRuleTarget/#notes","title":"NOTES","text":""},{"location":"commands/PSRule/en-US/Get-PSRuleTarget/#related-links","title":"RELATED LINKS","text":""},{"location":"commands/PSRule/en-US/Invoke-PSRule/","title":"Invoke-PSRule","text":""},{"location":"commands/PSRule/en-US/Invoke-PSRule/#synopsis","title":"SYNOPSIS","text":"Evaluate objects against matching rules and output the results.
"},{"location":"commands/PSRule/en-US/Invoke-PSRule/#syntax","title":"SYNTAX","text":""},{"location":"commands/PSRule/en-US/Invoke-PSRule/#input-default","title":"Input (Default)","text":"
"},{"location":"commands/PSRule/en-US/Invoke-PSRule/#inputpath","title":"InputPath","text":"Invoke-PSRule [-Module <String[]>] [-Outcome <RuleOutcome>] [-As <ResultFormat>] [-Format <InputFormat>]\n [-OutputPath <String>] [-OutputFormat <OutputFormat>] [-Baseline <BaselineOption>] [-Convention <String[]>]\n [[-Path] <String[]>] [-Name <String[]>] [-Tag <Hashtable>] [-Option <PSRuleOption>] [-ObjectPath <String>]\n [-TargetType <String[]>] [-Culture <String[]>] -InputObject <PSObject> [-WhatIf] [-Confirm]\n [<CommonParameters>]\n
"},{"location":"commands/PSRule/en-US/Invoke-PSRule/#description","title":"DESCRIPTION","text":"Invoke-PSRule -InputPath <String[]> [-Module <String[]>] [-Outcome <RuleOutcome>] [-As <ResultFormat>]\n [-Format <InputFormat>] [-OutputPath <String>] [-OutputFormat <OutputFormat>] [-Baseline <BaselineOption>]\n [-Convention <String[]>] [[-Path] <String[]>] [-Name <String[]>] [-Tag <Hashtable>] [-Option <PSRuleOption>]\n [-ObjectPath <String>] [-TargetType <String[]>] [-Culture <String[]>] [-WhatIf] [-Confirm]\n [<CommonParameters>]\nEvaluate objects against matching rules and output the results. Objects can be specified directly from the pipeline or provided from file.
The commands
Invoke-PSRuleandAssert-PSRuleprovide similar functionality, as differ as follows:@{ Name = 'Item 1' } | Invoke-PSRule;\nEvaluate a simple hashtable on the pipeline against rules loaded from the current working path.
"},{"location":"commands/PSRule/en-US/Invoke-PSRule/#example-2","title":"Example 2","text":"# Define objects to validate\n$items = @();\n$items += [PSCustomObject]@{ Name = 'Fridge' };\n$items += [PSCustomObject]@{ Name = 'Apple' };\n\n# Validate each item using rules saved in current working path\n$items | Invoke-PSRule;\nTargetName: Fridge\n\nRuleName Outcome Recommendation\n-------- ------- --------------\nisFruit Fail Fruit is only Apple, Orange and Pear\n\n\n TargetName: Apple\n\nRuleName Outcome Recommendation\n-------- ------- --------------\nisFruit Pass Fruit is only Apple, Orange and Pear\nEvaluate an array of objects on the pipeline against rules loaded from the current working path.
"},{"location":"commands/PSRule/en-US/Invoke-PSRule/#example-3","title":"Example 3","text":"# Define objects to validate\n$items = @();\n$items += [PSCustomObject]@{ Name = 'Fridge' };\n$items += [PSCustomObject]@{ Name = 'Apple' };\n\n# Validate each item and only return failing results\n$items | Invoke-PSRule -Outcome Fail;\nTargetName: Fridge\n\nRuleName Outcome Recommendation\n-------- ------- --------------\nisFruit Fail Fruit is only Apple, Orange and Pear\nEvaluate an array of objects, only failing object results are returned.
"},{"location":"commands/PSRule/en-US/Invoke-PSRule/#example-4","title":"Example 4","text":"# Define objects to validate\n$items = @();\n$items += [PSCustomObject]@{ Name = 'Fridge' };\n$items += [PSCustomObject]@{ Name = 'Apple' };\n\n# Validate each item and show rule summary\n$items | Invoke-PSRule -As Summary;\nRuleName Pass Fail Outcome\n-------- ---- ---- -------\nisFruit 1 1 Fail\nEvaluate an array of objects. The results for each rule is returned as a summary. Outcome is represented as the worst outcome.
"},{"location":"commands/PSRule/en-US/Invoke-PSRule/#parameters","title":"PARAMETERS","text":""},{"location":"commands/PSRule/en-US/Invoke-PSRule/#-name","title":"-Name","text":"The name of a specific rule to evaluate. If this parameter is not specified all rules in search paths will be evaluated.
"},{"location":"commands/PSRule/en-US/Invoke-PSRule/#-path","title":"-Path","text":"Type: String[]\nParameter Sets: (All)\nAliases: n\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nOne or more paths to search for rule definitions within.
"},{"location":"commands/PSRule/en-US/Invoke-PSRule/#-outcome","title":"-Outcome","text":"Type: String[]\nParameter Sets: (All)\nAliases: p\n\nRequired: False\nPosition: 0\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nFilter output to only show rule results with a specific outcome.
"},{"location":"commands/PSRule/en-US/Invoke-PSRule/#-tag","title":"-Tag","text":"Type: RuleOutcome\nParameter Sets: (All)\nAliases:\nAccepted values: Pass, Fail, Error, None, Processed, All\n\nRequired: False\nPosition: Named\nDefault value: Pass, Fail, Error\nAccept pipeline input: False\nAccept wildcard characters: False\nOnly get rules with the specified tags set. If this parameter is not specified all rules in search paths will be returned.
When more than one tag is used, all tags must match. Tags are not case sensitive. A tag value of
*may be used to filter rules to any rule with the tag set, regardless of tag value.An array of tag values can be used to match a rule with either value. i.e.
severity = important, criticalmatches rules with a category of eitherimportantorcritical.
"},{"location":"commands/PSRule/en-US/Invoke-PSRule/#-inputobject","title":"-InputObject","text":"Type: Hashtable\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nThe pipeline object to process rules for.
"},{"location":"commands/PSRule/en-US/Invoke-PSRule/#-option","title":"-Option","text":"Type: PSObject\nParameter Sets: Input\nAliases: TargetObject\n\nRequired: True\nPosition: Named\nDefault value: None\nAccept pipeline input: True (ByValue)\nAccept wildcard characters: False\nAdditional options that configure execution. A
PSRuleOptioncan be created by using theNew-PSRuleOptioncmdlet. Alternatively, a hashtable or path to YAML file can be specified with options.For more information on PSRule options see about_PSRule_Options.
"},{"location":"commands/PSRule/en-US/Invoke-PSRule/#-as","title":"-As","text":"Type: PSRuleOption\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nThe type of results to produce. Detailed results are generated by default.
The following result formats are available:
"},{"location":"commands/PSRule/en-US/Invoke-PSRule/#-format","title":"-Format","text":"Type: ResultFormat\nParameter Sets: (All)\nAliases:\nAccepted values: Detail, Summary\n\nRequired: False\nPosition: Named\nDefault value: Detail\nAccept pipeline input: False\nAccept wildcard characters: False\nConfigures the input format for when a string is passed in as a target object.
When the
-InputObjectparameter or pipeline input is used, strings are treated as plain text by default. Set this option to eitherYaml,Json,Markdown,PowerShellDatato have PSRule deserialize the object.When the
-InputPathparameter is used with a file path or URL. If theDetectformat is used, the file extension will be used to automatically detect the format. When-InputPathis not used,Detectis the same asNone.When this option is set to
FilePSRule scans the path and subdirectories specified by-InputPath. Files are treated as objects instead of being deserialized. Additional, PSRule uses the file extension as the object type. When files have no extension the whole file name is used.See
about_PSRule_Optionsfor details.This parameter takes precedence over the
Input.Formatoption if set.
"},{"location":"commands/PSRule/en-US/Invoke-PSRule/#-baseline","title":"-Baseline","text":"Type: InputFormat\nParameter Sets: (All)\nAliases:\nAccepted values: None, Yaml, Json, Markdown, PowerShellData, File, Detect\n\nRequired: False\nPosition: Named\nDefault value: Detect\nAccept pipeline input: False\nAccept wildcard characters: False\nSpecifies an explicit baseline by name to use for evaluating rules. Baselines can contain filters and custom configuration that overrides the defaults.
"},{"location":"commands/PSRule/en-US/Invoke-PSRule/#-convention","title":"-Convention","text":"Type: BaselineOption\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nSpecifies conventions by name to execute in the pipeline when processing objects.
"},{"location":"commands/PSRule/en-US/Invoke-PSRule/#-culture","title":"-Culture","text":"Type: String[]\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nSpecifies the culture to use for rule documentation and messages. By default, the culture of PowerShell is used.
This option does not affect the culture used for the PSRule engine, which always uses the culture of PowerShell.
The PowerShell cmdlet
Get-Cultureshows the current culture of PowerShell.
"},{"location":"commands/PSRule/en-US/Invoke-PSRule/#-objectpath","title":"-ObjectPath","text":"Type: String[]\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nThe name of a property to use instead of the pipeline object. If the property specified by
ObjectPathis a collection or an array, then each item in evaluated separately.
"},{"location":"commands/PSRule/en-US/Invoke-PSRule/#-targettype","title":"-TargetType","text":"Type: String\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nFilters input objects by TargetType.
If specified, only objects with the specified TargetType are processed. Objects that do not match TargetType are ignored. If multiple values are specified, only one TargetType must match. This parameter is not case-sensitive.
By default, all objects are processed.
This parameter if set, overrides the
Input.TargetTypeoption.To change the field TargetType is bound to set the
Binding.TargetTypeoption. For details see the about_PSRule_Options help topic.
"},{"location":"commands/PSRule/en-US/Invoke-PSRule/#-module","title":"-Module","text":"Type: String[]\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nSearch for rule definitions within a module. If no sources are specified by
-Path,-Module, or options, the current working directory is used.
"},{"location":"commands/PSRule/en-US/Invoke-PSRule/#-inputpath","title":"-InputPath","text":"Type: String[]\nParameter Sets: (All)\nAliases: m\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nInstead of processing objects from the pipeline, import objects file the specified file paths.
"},{"location":"commands/PSRule/en-US/Invoke-PSRule/#-outputpath","title":"-OutputPath","text":"Type: String[]\nParameter Sets: InputPath\nAliases: f\n\nRequired: True\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nSpecifies the output file path to write results. Directories along the file path will automatically be created if they do not exist.
"},{"location":"commands/PSRule/en-US/Invoke-PSRule/#-outputformat","title":"-OutputFormat","text":"Type: String\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nConfigures the format that output is presented in.
The following format options are available:
"},{"location":"commands/PSRule/en-US/Invoke-PSRule/#-confirm","title":"-Confirm","text":"Type: OutputFormat\nParameter Sets: (All)\nAliases: o\nAccepted values: None, Yaml, Json, Markdown, NUnit3, Csv, Wide, Sarif\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nPrompts you for confirmation before running the cmdlet.
"},{"location":"commands/PSRule/en-US/Invoke-PSRule/#-whatif","title":"-WhatIf","text":"Type: SwitchParameter\nParameter Sets: (All)\nAliases: cf\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nShows what would happen if the cmdlet runs. The cmdlet is not run.
"},{"location":"commands/PSRule/en-US/Invoke-PSRule/#commonparameters","title":"CommonParameters","text":"Type: SwitchParameter\nParameter Sets: (All)\nAliases: wi\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nThis cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters.
"},{"location":"commands/PSRule/en-US/Invoke-PSRule/#inputs","title":"INPUTS","text":""},{"location":"commands/PSRule/en-US/Invoke-PSRule/#systemmanagementautomationpsobject","title":"System.Management.Automation.PSObject","text":"You can pipe any object to Invoke-PSRule.
"},{"location":"commands/PSRule/en-US/Invoke-PSRule/#outputs","title":"OUTPUTS","text":""},{"location":"commands/PSRule/en-US/Invoke-PSRule/#psrulerulesrulerecord","title":"PSRule.Rules.RuleRecord","text":"This is the default.
"},{"location":"commands/PSRule/en-US/Invoke-PSRule/#psrulerulesrulesummaryrecord","title":"PSRule.Rules.RuleSummaryRecord","text":"When you use the
"},{"location":"commands/PSRule/en-US/Invoke-PSRule/#notes","title":"NOTES","text":""},{"location":"commands/PSRule/en-US/Invoke-PSRule/#related-links","title":"RELATED LINKS","text":"-As Summary. Otherwise, it returns aRuleRecordobject.Get-PSRule
Assert-PSRule
Test-PSRuleTarget
"},{"location":"commands/PSRule/en-US/New-PSRuleOption/","title":"New-PSRuleOption","text":""},{"location":"commands/PSRule/en-US/New-PSRuleOption/#synopsis","title":"SYNOPSIS","text":"Create options to configure PSRule execution.
"},{"location":"commands/PSRule/en-US/New-PSRuleOption/#syntax","title":"SYNTAX","text":""},{"location":"commands/PSRule/en-US/New-PSRuleOption/#frompath-default","title":"FromPath (Default)","text":"
"},{"location":"commands/PSRule/en-US/New-PSRuleOption/#fromoption","title":"FromOption","text":"New-PSRuleOption [[-Path] <String>] [-Configuration <ConfigurationOption>]\n [-SuppressTargetName <SuppressionOption>] [-BindTargetName <BindTargetName[]>]\n [-BindTargetType <BindTargetName[]>] [-BaselineGroup <Hashtable>] [-BindingIgnoreCase <Boolean>]\n [-BindingField <Hashtable>] [-BindingNameSeparator <String>] [-BindingPreferTargetInfo <Boolean>]\n [-TargetName <String[]>] [-TargetType <String[]>] [-BindingUseQualifiedName <Boolean>]\n [-Convention <String[]>] [-DuplicateResourceId <ExecutionActionPreference>]\n [-InitialSessionState <SessionState>] [-SuppressionGroupExpired <ExecutionActionPreference>]\n [-ExecutionRuleExcluded <ExecutionActionPreference>] [-ExecutionRuleSuppressed <ExecutionActionPreference>]\n [-ExecutionAliasReference <ExecutionActionPreference>]\n [-ExecutionRuleInconclusive <ExecutionActionPreference>]\n [-ExecutionInvariantCulture <ExecutionActionPreference>]\n [-ExecutionUnprocessedObject <ExecutionActionPreference>] [-IncludeModule <String[]>]\n [-IncludePath <String[]>] [-Format <InputFormat>] [-InputIgnoreGitPath <Boolean>]\n [-InputIgnoreRepositoryCommon <Boolean>] [-InputIgnoreObjectSource <Boolean>]\n [-InputIgnoreUnchangedPath <Boolean>] [-ObjectPath <String>] [-InputTargetType <String[]>]\n [-InputPathIgnore <String[]>] [-LoggingLimitDebug <String[]>] [-LoggingLimitVerbose <String[]>]\n [-LoggingRuleFail <OutcomeLogStream>] [-LoggingRulePass <OutcomeLogStream>] [-OutputAs <ResultFormat>]\n [-OutputBanner <BannerFormat>] [-OutputCulture <String[]>] [-OutputEncoding <OutputEncoding>]\n [-OutputFooter <FooterFormat>] [-OutputFormat <OutputFormat>] [-OutputJobSummaryPath <String>]\n [-OutputJsonIndent <Int32>] [-OutputOutcome <RuleOutcome>] [-OutputPath <String>]\n [-OutputSarifProblemsOnly <Boolean>] [-OutputStyle <OutputStyle>] [-RepositoryBaseRef <String>]\n [-RepositoryUrl <String>] [-RuleIncludeLocal <Boolean>] [<CommonParameters>]\n
"},{"location":"commands/PSRule/en-US/New-PSRuleOption/#fromdefault","title":"FromDefault","text":"New-PSRuleOption [-Option] <PSRuleOption> [-Configuration <ConfigurationOption>]\n [-SuppressTargetName <SuppressionOption>] [-BindTargetName <BindTargetName[]>]\n [-BindTargetType <BindTargetName[]>] [-BaselineGroup <Hashtable>] [-BindingIgnoreCase <Boolean>]\n [-BindingField <Hashtable>] [-BindingNameSeparator <String>] [-BindingPreferTargetInfo <Boolean>]\n [-TargetName <String[]>] [-TargetType <String[]>] [-BindingUseQualifiedName <Boolean>]\n [-Convention <String[]>] [-DuplicateResourceId <ExecutionActionPreference>]\n [-InitialSessionState <SessionState>] [-SuppressionGroupExpired <ExecutionActionPreference>]\n [-ExecutionRuleExcluded <ExecutionActionPreference>] [-ExecutionRuleSuppressed <ExecutionActionPreference>]\n [-ExecutionAliasReference <ExecutionActionPreference>]\n [-ExecutionRuleInconclusive <ExecutionActionPreference>]\n [-ExecutionInvariantCulture <ExecutionActionPreference>]\n [-ExecutionUnprocessedObject <ExecutionActionPreference>] [-IncludeModule <String[]>]\n [-IncludePath <String[]>] [-Format <InputFormat>] [-InputIgnoreGitPath <Boolean>]\n [-InputIgnoreRepositoryCommon <Boolean>] [-InputIgnoreObjectSource <Boolean>]\n [-InputIgnoreUnchangedPath <Boolean>] [-ObjectPath <String>] [-InputTargetType <String[]>]\n [-InputPathIgnore <String[]>] [-LoggingLimitDebug <String[]>] [-LoggingLimitVerbose <String[]>]\n [-LoggingRuleFail <OutcomeLogStream>] [-LoggingRulePass <OutcomeLogStream>] [-OutputAs <ResultFormat>]\n [-OutputBanner <BannerFormat>] [-OutputCulture <String[]>] [-OutputEncoding <OutputEncoding>]\n [-OutputFooter <FooterFormat>] [-OutputFormat <OutputFormat>] [-OutputJobSummaryPath <String>]\n [-OutputJsonIndent <Int32>] [-OutputOutcome <RuleOutcome>] [-OutputPath <String>]\n [-OutputSarifProblemsOnly <Boolean>] [-OutputStyle <OutputStyle>] [-RepositoryBaseRef <String>]\n [-RepositoryUrl <String>] [-RuleIncludeLocal <Boolean>] [<CommonParameters>]\n
"},{"location":"commands/PSRule/en-US/New-PSRuleOption/#description","title":"DESCRIPTION","text":"New-PSRuleOption [-Default] [-Configuration <ConfigurationOption>] [-SuppressTargetName <SuppressionOption>]\n [-BindTargetName <BindTargetName[]>] [-BindTargetType <BindTargetName[]>] [-BaselineGroup <Hashtable>]\n [-BindingIgnoreCase <Boolean>] [-BindingField <Hashtable>] [-BindingNameSeparator <String>]\n [-BindingPreferTargetInfo <Boolean>] [-TargetName <String[]>] [-TargetType <String[]>]\n [-BindingUseQualifiedName <Boolean>] [-Convention <String[]>]\n [-DuplicateResourceId <ExecutionActionPreference>] [-InitialSessionState <SessionState>]\n [-SuppressionGroupExpired <ExecutionActionPreference>] [-ExecutionRuleExcluded <ExecutionActionPreference>]\n [-ExecutionRuleSuppressed <ExecutionActionPreference>] [-ExecutionAliasReference <ExecutionActionPreference>]\n [-ExecutionRuleInconclusive <ExecutionActionPreference>]\n [-ExecutionInvariantCulture <ExecutionActionPreference>]\n [-ExecutionUnprocessedObject <ExecutionActionPreference>] [-IncludeModule <String[]>]\n [-IncludePath <String[]>] [-Format <InputFormat>] [-InputIgnoreGitPath <Boolean>]\n [-InputIgnoreRepositoryCommon <Boolean>] [-InputIgnoreObjectSource <Boolean>]\n [-InputIgnoreUnchangedPath <Boolean>] [-ObjectPath <String>] [-InputTargetType <String[]>]\n [-InputPathIgnore <String[]>] [-LoggingLimitDebug <String[]>] [-LoggingLimitVerbose <String[]>]\n [-LoggingRuleFail <OutcomeLogStream>] [-LoggingRulePass <OutcomeLogStream>] [-OutputAs <ResultFormat>]\n [-OutputBanner <BannerFormat>] [-OutputCulture <String[]>] [-OutputEncoding <OutputEncoding>]\n [-OutputFooter <FooterFormat>] [-OutputFormat <OutputFormat>] [-OutputJobSummaryPath <String>]\n [-OutputJsonIndent <Int32>] [-OutputOutcome <RuleOutcome>] [-OutputPath <String>]\n [-OutputSarifProblemsOnly <Boolean>] [-OutputStyle <OutputStyle>] [-RepositoryBaseRef <String>]\n [-RepositoryUrl <String>] [-RuleIncludeLocal <Boolean>] [<CommonParameters>]\nThe New-PSRuleOption cmdlet creates an options object that can be passed to PSRule cmdlets to configure execution.
"},{"location":"commands/PSRule/en-US/New-PSRuleOption/#examples","title":"EXAMPLES","text":""},{"location":"commands/PSRule/en-US/New-PSRuleOption/#example-1","title":"Example 1","text":"$option = New-PSRuleOption -Option @{ 'execution.mode' = 'ConstrainedLanguage' }\n@{ Name = 'Item 1' } | Invoke-PSRule -Option $option\nCreate an options object and run rules in constrained mode.
"},{"location":"commands/PSRule/en-US/New-PSRuleOption/#example-2","title":"Example 2","text":"$option = New-PSRuleOption -SuppressTargetName @{ 'storageAccounts.UseHttps' = 'TestObject1', 'TestObject3' };\nCreate an options object that suppresses
"},{"location":"commands/PSRule/en-US/New-PSRuleOption/#example-3","title":"Example 3","text":"TestObject1andTestObject3for a rule namedstorageAccounts.UseHttps.# Create a custom function that returns a TargetName string\n$bindFn = {\n param ($TargetObject)\n\n $otherName = $TargetObject.PSObject.Properties['OtherName'];\n\n if ($otherName -eq $Null) {\n return $Null\n }\n\n return $otherName.Value;\n}\n\n# Specify the binding function script block code to execute\n$option = New-PSRuleOption -BindTargetName $bindFn;\nCreates an options object that uses a custom function to bind the TargetName of an object.
"},{"location":"commands/PSRule/en-US/New-PSRuleOption/#example-4","title":"Example 4","text":"$option = New-PSRuleOption -Configuration @{ 'appServiceMinInstanceCount' = 2 };\nCreate an options object that sets the
"},{"location":"commands/PSRule/en-US/New-PSRuleOption/#parameters","title":"PARAMETERS","text":""},{"location":"commands/PSRule/en-US/New-PSRuleOption/#-option","title":"-Option","text":"appServiceMinInstanceCountbaseline configuration option to2.Additional options that configure execution. Option also accepts a hashtable to configure options. See about_PSRule_Options for more information.
"},{"location":"commands/PSRule/en-US/New-PSRuleOption/#-path","title":"-Path","text":"Type: PSRuleOption\nParameter Sets: FromOption\nAliases:\n\nRequired: True\nPosition: 0\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nThe path to a YAML file containing options.
Either a directory or file path can be specified. When a directory is used,
ps-rule.yamlwill be used as the file name.If the
-Pathparameter is specified and the file does not exist, an exception will be generated.
"},{"location":"commands/PSRule/en-US/New-PSRuleOption/#-default","title":"-Default","text":"Type: String\nParameter Sets: FromPath\nAliases:\n\nRequired: False\nPosition: 1\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nWhen specified, defaults are used for any options not overridden.
"},{"location":"commands/PSRule/en-US/New-PSRuleOption/#-suppresstargetname","title":"-SuppressTargetName","text":"Type: SwitchParameter\nParameter Sets: FromDefault\nAliases:\n\nRequired: True\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nConfigures suppression for a list of objects by TargetName. SuppressTargetName also accepts a hashtable to configure rule suppression. See about_PSRule_Options for more information.
"},{"location":"commands/PSRule/en-US/New-PSRuleOption/#-bindtargetname","title":"-BindTargetName","text":"Type: SuppressionOption\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nConfigures a custom function to use to bind TargetName of an object. See about_PSRule_Options for more information.
"},{"location":"commands/PSRule/en-US/New-PSRuleOption/#-configuration","title":"-Configuration","text":"Type: BindTargetName[]\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nConfigures a set of baseline configuration values that can be used in rule definitions instead of using hard coded values. Configuration also accepts a hashtable of configuration values as key/ value pairs. See about_PSRule_Options for more information.
"},{"location":"commands/PSRule/en-US/New-PSRuleOption/#-baselinegroup","title":"-BaselineGroup","text":"Type: ConfigurationOption\nParameter Sets: (All)\nAliases: BaselineConfiguration\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nSets the option
Baseline.Group. The optionBaseline.Groupallows a named group of baselines to be defined and later referenced. See about_PSRule_Options for more information.
"},{"location":"commands/PSRule/en-US/New-PSRuleOption/#-bindtargettype","title":"-BindTargetType","text":"Type: Hashtable\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nConfigures a custom function to use to bind TargetType of an object. See about_PSRule_Options for more information.
"},{"location":"commands/PSRule/en-US/New-PSRuleOption/#-bindingignorecase","title":"-BindingIgnoreCase","text":"Type: BindTargetName[]\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nSets the option
Binding.IgnoreCase. The optionBinding.IgnoreCasedetermines if binding operations are case-sensitive or not. See about_PSRule_Options for more information.
"},{"location":"commands/PSRule/en-US/New-PSRuleOption/#-bindingfield","title":"-BindingField","text":"Type: Boolean\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: True\nAccept pipeline input: False\nAccept wildcard characters: False\nSets the option
Binding.Field. The option specified one or more custom field bindings. See about_PSRule_Options for more information.
"},{"location":"commands/PSRule/en-US/New-PSRuleOption/#-bindingnameseparator","title":"-BindingNameSeparator","text":"Type: Hashtable\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nSets the option
Binding.NameSeparator. This option specifies the separator to use for qualified names. See about_PSRule_Options for more information.
"},{"location":"commands/PSRule/en-US/New-PSRuleOption/#-bindingprefertargetinfo","title":"-BindingPreferTargetInfo","text":"Type: String\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nSets the option
Binding.PreferTargetInfo. This option specifies if automatic binding is preferred over configured binding options. See about_PSRule_Options for more information.
"},{"location":"commands/PSRule/en-US/New-PSRuleOption/#-convention","title":"-Convention","text":"Type: Boolean\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: False\nAccept pipeline input: False\nAccept wildcard characters: False\nSets the
Option.ConventionIncludeoption. This option specifies the name of conventions to execute in the pipeline when processing objects. See about_PSRule_Options for more information.
"},{"location":"commands/PSRule/en-US/New-PSRuleOption/#-targetname","title":"-TargetName","text":"Type: String[]\nParameter Sets: (All)\nAliases: ConventionInclude\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nSets the option
Binding.TargetName. This option specifies one or more properties of TargetObject to use to bind TargetName to. See about_PSRule_Options for more information.
"},{"location":"commands/PSRule/en-US/New-PSRuleOption/#-targettype","title":"-TargetType","text":"Type: String[]\nParameter Sets: (All)\nAliases: BindingTargetName\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nSets the option
Binding.TargetType. This option specifies one or more properties of TargetObject to use to bind TargetType to. See about_PSRule_Options for more information.
"},{"location":"commands/PSRule/en-US/New-PSRuleOption/#-bindingusequalifiedname","title":"-BindingUseQualifiedName","text":"Type: String[]\nParameter Sets: (All)\nAliases: BindingTargetType\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nSets the option
Binding.UseQualifiedName. This option specifies is qualified target names are used. See about_PSRule_Options for more information.
"},{"location":"commands/PSRule/en-US/New-PSRuleOption/#-executionaliasreference","title":"-ExecutionAliasReference","text":"Type: Boolean\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nSets the
Execution.AliasReferenceoption. Determines how to handle when an alias to a resource is used. See about_PSRule_Options for more information.
"},{"location":"commands/PSRule/en-US/New-PSRuleOption/#-executioninvariantculture","title":"-ExecutionInvariantCulture","text":"Type: ExecutionActionPreference\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nSets the
Execution.InvariantCultureoption. Determines how to report when an invariant culture is used. See about_PSRule_Options for more information.
"},{"location":"commands/PSRule/en-US/New-PSRuleOption/#-executionruleinconclusive","title":"-ExecutionRuleInconclusive","text":"Type: ExecutionActionPreference\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nSets the
Execution.RuleInconclusiveoption. Determines how to handle rules that generate inconclusive results. See about_PSRule_Options for more information.
"},{"location":"commands/PSRule/en-US/New-PSRuleOption/#-executionunprocessedobject","title":"-ExecutionUnprocessedObject","text":"Type: ExecutionActionPreference\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nSets the
Execution.UnprocessedObjectoption. Determines how to report objects that are not processed by any rule. See about_PSRule_Options for more information.
"},{"location":"commands/PSRule/en-US/New-PSRuleOption/#-includemodule","title":"-IncludeModule","text":"Type: ExecutionActionPreference\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nSets the
Include.Moduleoption to include additional module sources. See about_PSRule_Options for more information.
"},{"location":"commands/PSRule/en-US/New-PSRuleOption/#-includepath","title":"-IncludePath","text":"Type: String[]\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nSets the
Include.Pathoption to include additional standalone sources. See about_PSRule_Options for more information.
"},{"location":"commands/PSRule/en-US/New-PSRuleOption/#-format","title":"-Format","text":"Type: String[]\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nSets the
Input.Formatoption to configure the input format for when a string is passed in as a target object. See about_PSRule_Options for more information.
"},{"location":"commands/PSRule/en-US/New-PSRuleOption/#-inputignoregitpath","title":"-InputIgnoreGitPath","text":"Type: InputFormat\nParameter Sets: (All)\nAliases: InputFormat\nAccepted values: None, Yaml, Json, Markdown, PowerShellData, File, Detect\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nSets the
Input.IgnoreGitPathoption to determine if files within the .git path are ignored. See about_PSRule_Options for more information.
"},{"location":"commands/PSRule/en-US/New-PSRuleOption/#-inputignorerepositorycommon","title":"-InputIgnoreRepositoryCommon","text":"Type: Boolean\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: True\nAccept pipeline input: False\nAccept wildcard characters: False\nSets the
Input.IgnoreRepositoryCommonoption to determine if files common repository files are ignored. See about_PSRule_Options for more information.
"},{"location":"commands/PSRule/en-US/New-PSRuleOption/#-inputignoreunchangedpath","title":"-InputIgnoreUnchangedPath","text":"Type: Boolean\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nSets the option
Input.IgnoreUnchangedPath. TheInput.IgnoreUnchangedPathoption determine if unchanged files are ignored.
"},{"location":"commands/PSRule/en-US/New-PSRuleOption/#-objectpath","title":"-ObjectPath","text":"Type: Boolean\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nSets the
Input.ObjectPathoption to use an object path to use instead of the pipeline object. See about_PSRule_Options for more information.
"},{"location":"commands/PSRule/en-US/New-PSRuleOption/#-inputpathignore","title":"-InputPathIgnore","text":"Type: String\nParameter Sets: (All)\nAliases: InputObjectPath\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nSets the
Input.PathIgnoreoption. If specified, files that match the path spec will not be processed. See about_PSRule_Options for more information.
"},{"location":"commands/PSRule/en-US/New-PSRuleOption/#-inputtargettype","title":"-InputTargetType","text":"Type: String[]\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nSets the
Input.TargetTypeoption to only process objects with the specified TargetType. See about_PSRule_Options for more information.
"},{"location":"commands/PSRule/en-US/New-PSRuleOption/#-inputignoreobjectsource","title":"-InputIgnoreObjectSource","text":"Type: String[]\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nSets the option
Input.IgnoreObjectSource. TheInput.IgnoreObjectSourceoption determines if objects will be skipped if the source path has been ignored.
"},{"location":"commands/PSRule/en-US/New-PSRuleOption/#-logginglimitdebug","title":"-LoggingLimitDebug","text":"Type: Boolean\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nSets the
Logging.LimitDebugoption to limit debug messages to a list of named debug scopes. See about_PSRule_Options for more information.
"},{"location":"commands/PSRule/en-US/New-PSRuleOption/#-logginglimitverbose","title":"-LoggingLimitVerbose","text":"Type: String[]\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nSets the
Logging.LimitVerboseoption to limit verbose messages to a list of named verbose scopes. See about_PSRule_Options for more information.
"},{"location":"commands/PSRule/en-US/New-PSRuleOption/#-loggingrulefail","title":"-LoggingRuleFail","text":"Type: String[]\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nSets the
Logging.RuleFailoption to generate an informational message for each rule fail. See about_PSRule_Options for more information.
"},{"location":"commands/PSRule/en-US/New-PSRuleOption/#-loggingrulepass","title":"-LoggingRulePass","text":"Type: OutcomeLogStream\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nSets the
Logging.RulePassoption to generate an informational message for each rule pass. See about_PSRule_Options for more information.
"},{"location":"commands/PSRule/en-US/New-PSRuleOption/#-outputas","title":"-OutputAs","text":"Type: OutcomeLogStream\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nSets the option
Output.As. TheOutput.Asoption configures the type of results to produce, either detail or summary.
"},{"location":"commands/PSRule/en-US/New-PSRuleOption/#-outputbanner","title":"-OutputBanner","text":"Type: ResultFormat\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nSets the option
Output.Banner. TheOutput.Banneroption configure information displayed with PSRule banner. This option is only applicable when usingAssert-PSRulecmdlet.
"},{"location":"commands/PSRule/en-US/New-PSRuleOption/#-outputculture","title":"-OutputCulture","text":"Type: BannerFormat\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: Default\nAccept pipeline input: False\nAccept wildcard characters: False\nSets the option
Output.Culture. TheOutput.Cultureoption configures the culture used to generated output. When multiple cultures are specified, the first matching culture will be used. See about_PSRule_Options for more information.
"},{"location":"commands/PSRule/en-US/New-PSRuleOption/#-outputencoding","title":"-OutputEncoding","text":"Type: String[]\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nSets the option
Output.Encoding. TheOutput.Encodingoption configured the encoding used to write results to file.
"},{"location":"commands/PSRule/en-US/New-PSRuleOption/#-outputfooter","title":"-OutputFooter","text":"Type: OutputEncoding\nParameter Sets: (All)\nAliases:\nAccepted values: Default, UTF8, UTF7, Unicode, UTF32, ASCII\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nSets the option
Output.Footer. TheOutput.Footeroption configures the information displayed for PSRule footer. See about_PSRule_Options for more information.
"},{"location":"commands/PSRule/en-US/New-PSRuleOption/#-outputformat","title":"-OutputFormat","text":"Type: FooterFormat\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: Default\nAccept pipeline input: False\nAccept wildcard characters: False\nSets the option
Output.Format. TheOutput.Formatoption configures the format that results will be presented in. See about_PSRule_Options for more information.
"},{"location":"commands/PSRule/en-US/New-PSRuleOption/#-outputjobsummarypath","title":"-OutputJobSummaryPath","text":"Type: OutputFormat\nParameter Sets: (All)\nAliases:\nAccepted values: None, Yaml, Json, Markdown, NUnit3, Csv, Wide, Sarif\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nSet the option
Output.JobSummaryPath. TheOutput.JobSummaryPathoption configures the path to a job summary output file.
"},{"location":"commands/PSRule/en-US/New-PSRuleOption/#-outputjsonindent","title":"-OutputJsonIndent","text":"Type: String\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nSets the option
Output.JsonIndent. TheOutput.JsonIndentoption configures indentation for JSON output.This option only applies to
Get-PSRule,Invoke-PSRuleandAssert-PSRulecmdlets.
"},{"location":"commands/PSRule/en-US/New-PSRuleOption/#-outputoutcome","title":"-OutputOutcome","text":"Type: Int32\nParameter Sets: (All)\nAliases: JsonIndent\nAccepted values: 0, 1, 2, 3, 4\n\nRequired: False\nPosition: Named\nDefault value: 0\nAccept pipeline input: False\nAccept wildcard characters: False\nSets the
Output.Outcomeoption. This option can be set to include or exclude output results. See about_PSRule_Options for more information.
"},{"location":"commands/PSRule/en-US/New-PSRuleOption/#-outputpath","title":"-OutputPath","text":"Type: RuleOutcome\nParameter Sets: (All)\nAliases: Outcome\n\nRequired: False\nPosition: Named\nDefault value: Processed\nAccept pipeline input: False\nAccept wildcard characters: False\nSets the option
Output.Path. TheOutput.Pathoption configures an output file path to write results.
"},{"location":"commands/PSRule/en-US/New-PSRuleOption/#-outputsarifproblemsonly","title":"-OutputSarifProblemsOnly","text":"Type: String\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nSets the option
Option.SarifProblemsOnly. TheOutput.SarifProblemsOnlyoption determines if SARIF output only includes fail and error outcomes.
"},{"location":"commands/PSRule/en-US/New-PSRuleOption/#-outputstyle","title":"-OutputStyle","text":"Type: Boolean\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: True\nAccept pipeline input: False\nAccept wildcard characters: False\nSets the option
Option.Style. TheOutput.Styleoption configures the style that results will be presented in.This option only applies to
Assert-PSRule.
"},{"location":"commands/PSRule/en-US/New-PSRuleOption/#-repositorybaseref","title":"-RepositoryBaseRef","text":"Type: OutputStyle\nParameter Sets: (All)\nAliases:\nAccepted values: Client, Plain, AzurePipelines, GitHubActions\n\nRequired: False\nPosition: Named\nDefault value: Client\nAccept pipeline input: False\nAccept wildcard characters: False\nSets the option
Repository.BaseRef. TheRepository.BaseRefoption sets the repository base ref used for comparisons of changed files.
"},{"location":"commands/PSRule/en-US/New-PSRuleOption/#-repositoryurl","title":"-RepositoryUrl","text":"Type: String\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nSets the option
Repository.Url. TheRepository.Urloption sets the repository URL reported in output.
"},{"location":"commands/PSRule/en-US/New-PSRuleOption/#-ruleincludelocal","title":"-RuleIncludeLocal","text":"Type: String\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nSets the option
Rule.IncludeLocal. TheRule.IncludeLocaloption configures if local rules are automatically included. See about_PSRule_Options for more information.
"},{"location":"commands/PSRule/en-US/New-PSRuleOption/#-duplicateresourceid","title":"-DuplicateResourceId","text":"Type: Boolean\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: False\nAccept pipeline input: False\nAccept wildcard characters: False\nSets the option
Execution.DuplicateResourceId. TheExecution.DuplicateResourceIdoption determines how to handle duplicate resources identifiers during execution.
"},{"location":"commands/PSRule/en-US/New-PSRuleOption/#-initialsessionstate","title":"-InitialSessionState","text":"Type: ExecutionActionPreference\nParameter Sets: (All)\nAliases: ExecutionDuplicateResourceId\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nSets the option
Execution.InitialSessionState. TheExecution.InitialSessionStateoption determines how the initial session state for executing PowerShell code is created.
"},{"location":"commands/PSRule/en-US/New-PSRuleOption/#-executionruleexcluded","title":"-ExecutionRuleExcluded","text":"Type: SessionState\nParameter Sets: (All)\nAliases: ExecutionInitialSessionState\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nSets the option
Execution.RuleExcluded. TheExecution.RuleExcludedoption determines how to handle excluded rules.
"},{"location":"commands/PSRule/en-US/New-PSRuleOption/#-executionrulesuppressed","title":"-ExecutionRuleSuppressed","text":"Type: ExecutionActionPreference\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nSets the option
Execution.RuleSuppressed. TheExecution.RuleSuppressedoption determines how to handle suppressed rules.
"},{"location":"commands/PSRule/en-US/New-PSRuleOption/#-suppressiongroupexpired","title":"-SuppressionGroupExpired","text":"Type: ExecutionActionPreference\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nSets the option
Execution.SuppressionGroupExpired. TheExecution.SuppressionGroupExpiredoption determines how to handle expired suppression groups.
"},{"location":"commands/PSRule/en-US/New-PSRuleOption/#commonparameters","title":"CommonParameters","text":"Type: ExecutionActionPreference\nParameter Sets: (All)\nAliases: ExecutionSuppressionGroupExpired\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nThis cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters.
"},{"location":"commands/PSRule/en-US/New-PSRuleOption/#inputs","title":"INPUTS","text":""},{"location":"commands/PSRule/en-US/New-PSRuleOption/#none","title":"None","text":""},{"location":"commands/PSRule/en-US/New-PSRuleOption/#outputs","title":"OUTPUTS","text":""},{"location":"commands/PSRule/en-US/New-PSRuleOption/#psruleconfigurationpsruleoption","title":"PSRule.Configuration.PSRuleOption","text":""},{"location":"commands/PSRule/en-US/New-PSRuleOption/#notes","title":"NOTES","text":""},{"location":"commands/PSRule/en-US/New-PSRuleOption/#related-links","title":"RELATED LINKS","text":"Invoke-PSRule
Set-PSRuleOption
"},{"location":"commands/PSRule/en-US/PSRule/","title":"PSRule Module","text":""},{"location":"commands/PSRule/en-US/PSRule/#description","title":"Description","text":"A PowerShell rules engine.
"},{"location":"commands/PSRule/en-US/PSRule/#psrule-cmdlets","title":"PSRule Cmdlets","text":""},{"location":"commands/PSRule/en-US/PSRule/#assert-psrule","title":"Assert-PSRule","text":"Evaluate objects against matching rules and assert any failures.
"},{"location":"commands/PSRule/en-US/PSRule/#export-psrulebaseline","title":"Export-PSRuleBaseline","text":"Exports a list of baselines to a file.
"},{"location":"commands/PSRule/en-US/PSRule/#get-psrule","title":"Get-PSRule","text":"Get a list of matching rule definitions within the search path.
"},{"location":"commands/PSRule/en-US/PSRule/#get-psrulebaseline","title":"Get-PSRuleBaseline","text":"Get a list of matching baselines within the search path.
"},{"location":"commands/PSRule/en-US/PSRule/#get-psrulehelp","title":"Get-PSRuleHelp","text":"Get documentation for a rule.
"},{"location":"commands/PSRule/en-US/PSRule/#get-psruletarget","title":"Get-PSRuleTarget","text":"Get a list of target object.
"},{"location":"commands/PSRule/en-US/PSRule/#invoke-psrule","title":"Invoke-PSRule","text":"Evaluate objects against matching rules and output the results.
"},{"location":"commands/PSRule/en-US/PSRule/#new-psruleoption","title":"New-PSRuleOption","text":"Create options to configure PSRule execution.
"},{"location":"commands/PSRule/en-US/PSRule/#set-psruleoption","title":"Set-PSRuleOption","text":"Set options to configure PSRule execution.
"},{"location":"commands/PSRule/en-US/PSRule/#test-psruletarget","title":"Test-PSRuleTarget","text":"Evaluate pipeline objects against matching rules.
"},{"location":"commands/PSRule/en-US/Set-PSRuleOption/","title":"Set-PSRuleOption","text":""},{"location":"commands/PSRule/en-US/Set-PSRuleOption/#synopsis","title":"SYNOPSIS","text":"Sets options that configure PSRule execution.
"},{"location":"commands/PSRule/en-US/Set-PSRuleOption/#syntax","title":"SYNTAX","text":"
"},{"location":"commands/PSRule/en-US/Set-PSRuleOption/#description","title":"DESCRIPTION","text":"Set-PSRuleOption [[-Path] <String>] [-Option <PSRuleOption>] [-PassThru] [-Force] [-AllowClobber]\n [-BaselineGroup <Hashtable>] [-BindingIgnoreCase <Boolean>] [-BindingField <Hashtable>]\n [-BindingNameSeparator <String>] [-BindingPreferTargetInfo <Boolean>] [-TargetName <String[]>]\n [-TargetType <String[]>] [-BindingUseQualifiedName <Boolean>] [-Convention <String[]>]\n [-DuplicateResourceId <ExecutionActionPreference>] [-InitialSessionState <SessionState>]\n [-SuppressionGroupExpired <ExecutionActionPreference>] [-ExecutionRuleExcluded <ExecutionActionPreference>]\n [-ExecutionRuleSuppressed <ExecutionActionPreference>] [-ExecutionAliasReference <ExecutionActionPreference>]\n [-ExecutionRuleInconclusive <ExecutionActionPreference>]\n [-ExecutionInvariantCulture <ExecutionActionPreference>]\n [-ExecutionUnprocessedObject <ExecutionActionPreference>] [-IncludeModule <String[]>]\n [-IncludePath <String[]>] [-Format <InputFormat>] [-InputIgnoreGitPath <Boolean>]\n [-InputIgnoreObjectSource <Boolean>] [-InputIgnoreRepositoryCommon <Boolean>]\n [-InputIgnoreUnchangedPath <Boolean>] [-ObjectPath <String>] [-InputPathIgnore <String[]>]\n [-InputTargetType <String[]>] [-LoggingLimitDebug <String[]>] [-LoggingLimitVerbose <String[]>]\n [-LoggingRuleFail <OutcomeLogStream>] [-LoggingRulePass <OutcomeLogStream>] [-OutputAs <ResultFormat>]\n [-OutputBanner <BannerFormat>] [-OutputCulture <String[]>] [-OutputEncoding <OutputEncoding>]\n [-OutputFooter <FooterFormat>] [-OutputFormat <OutputFormat>] [-OutputJobSummaryPath <String>]\n [-OutputJsonIndent <Int32>] [-OutputOutcome <RuleOutcome>] [-OutputPath <String>]\n [-OutputSarifProblemsOnly <Boolean>] [-OutputStyle <OutputStyle>] [-RepositoryBaseRef <String>]\n [-RepositoryUrl <String>] [-RuleIncludeLocal <Boolean>] [-WhatIf] [-Confirm] [<CommonParameters>]\nSets options that configure PSRule execution.
"},{"location":"commands/PSRule/en-US/Set-PSRuleOption/#examples","title":"EXAMPLES","text":""},{"location":"commands/PSRule/en-US/Set-PSRuleOption/#example-1","title":"Example 1","text":"PS C:\\> Set-PSRuleOption -OutputFormat Yaml;\nSets the
"},{"location":"commands/PSRule/en-US/Set-PSRuleOption/#example-2","title":"Example 2","text":"Output.FormattoYamlforps-rule.yamlin the current working path. If theps-rule.yamlfile exists, it is merged with the existing file and overwritten. If the file does not exist, a new file is created.PS C:\\> Set-PSRuleOption -OutputFormat Yaml -Path .\\project-options.yaml;\nSets the
"},{"location":"commands/PSRule/en-US/Set-PSRuleOption/#parameters","title":"PARAMETERS","text":""},{"location":"commands/PSRule/en-US/Set-PSRuleOption/#-path","title":"-Path","text":"Output.FormattoYamlforproject-options.yamlin the current working path. If theproject-options.yamlfile exists, it is merged with the existing file and overwritten. If the file does not exist, a new file is created.The path to a YAML file where options will be set.
Either a directory or file path can be specified. When a directory is used,
ps-rule.yamlwill be used as the file name.The file will be created if it does not exist. If the file already exists it will be merged with the existing options and overwritten.
If the directory does not exist an error will be generated. To force the creation of the directory path use the
-Forceswitch.
"},{"location":"commands/PSRule/en-US/Set-PSRuleOption/#-option","title":"-Option","text":"Type: String\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: 1\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nAn options object to use.
"},{"location":"commands/PSRule/en-US/Set-PSRuleOption/#-passthru","title":"-PassThru","text":"Type: PSRuleOption\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: True (ByValue)\nAccept wildcard characters: False\nUse this option to return the options object to the pipeline instead of saving to disk.
"},{"location":"commands/PSRule/en-US/Set-PSRuleOption/#-force","title":"-Force","text":"Type: SwitchParameter\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: False\nAccept pipeline input: False\nAccept wildcard characters: False\nForce creation of directory path for Path parameter, when the directory does not already exist.
"},{"location":"commands/PSRule/en-US/Set-PSRuleOption/#-allowclobber","title":"-AllowClobber","text":"Type: SwitchParameter\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nOverwrite YAML files that contain comments.
"},{"location":"commands/PSRule/en-US/Set-PSRuleOption/#-baselinegroup","title":"-BaselineGroup","text":"Type: SwitchParameter\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nSets the option
Baseline.Group. The optionBaseline.Groupallows a named group of baselines to be defined and later referenced. See about_PSRule_Options for more information.
"},{"location":"commands/PSRule/en-US/Set-PSRuleOption/#-bindingignorecase","title":"-BindingIgnoreCase","text":"Type: Hashtable\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nSets the option
Binding.IgnoreCase. The optionBinding.IgnoreCasedetermines if binding operations are case-sensitive or not. See about_PSRule_Options for more information.
"},{"location":"commands/PSRule/en-US/Set-PSRuleOption/#-bindingfield","title":"-BindingField","text":"Type: Boolean\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: True\nAccept pipeline input: False\nAccept wildcard characters: False\nSets the option
Binding.Field. The option specified one or more custom field bindings. See about_PSRule_Options for more information.
"},{"location":"commands/PSRule/en-US/Set-PSRuleOption/#-bindingnameseparator","title":"-BindingNameSeparator","text":"Type: Hashtable\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nSets the option
Binding.NameSeparator. This option specifies the separator to use for qualified names. See about_PSRule_Options for more information.
"},{"location":"commands/PSRule/en-US/Set-PSRuleOption/#-bindingprefertargetinfo","title":"-BindingPreferTargetInfo","text":"Type: String\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nSets the option
Binding.PreferTargetInfo. This option specifies if automatic binding is preferred over configured binding options. See about_PSRule_Options for more information.
"},{"location":"commands/PSRule/en-US/Set-PSRuleOption/#-convention","title":"-Convention","text":"Type: Boolean\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: False\nAccept pipeline input: False\nAccept wildcard characters: False\nSets the
Option.ConventionIncludeoption. This option specifies the name of conventions to execute in the pipeline when processing objects. See about_PSRule_Options for more information.
"},{"location":"commands/PSRule/en-US/Set-PSRuleOption/#-targetname","title":"-TargetName","text":"Type: String[]\nParameter Sets: (All)\nAliases: ConventionInclude\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nSets the option
Binding.TargetName. This option specifies one or more properties of TargetObject to use to bind TargetName to. See about_PSRule_Options for more information.
"},{"location":"commands/PSRule/en-US/Set-PSRuleOption/#-targettype","title":"-TargetType","text":"Type: String[]\nParameter Sets: (All)\nAliases: BindingTargetName\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nSets the option
Binding.TargetType. This option specifies one or more properties of TargetObject to use to bind TargetType to. See about_PSRule_Options for more information.
"},{"location":"commands/PSRule/en-US/Set-PSRuleOption/#-bindingusequalifiedname","title":"-BindingUseQualifiedName","text":"Type: String[]\nParameter Sets: (All)\nAliases: BindingTargetType\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nSets the option
Binding.UseQualifiedName. This option specifies is qualified target names are used. See about_PSRule_Options for more information.
"},{"location":"commands/PSRule/en-US/Set-PSRuleOption/#-executionaliasreference","title":"-ExecutionAliasReference","text":"Type: Boolean\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nSets the
Execution.AliasReferenceoption. Determines how to handle when an alias to a resource is used. See about_PSRule_Options for more information.
"},{"location":"commands/PSRule/en-US/Set-PSRuleOption/#-executioninvariantculture","title":"-ExecutionInvariantCulture","text":"Type: ExecutionActionPreference\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nSets the
Execution.InvariantCultureoption. Determines how to report when an invariant culture is used. See about_PSRule_Options for more information.
"},{"location":"commands/PSRule/en-US/Set-PSRuleOption/#-executionruleinconclusive","title":"-ExecutionRuleInconclusive","text":"Type: ExecutionActionPreference\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nSets the
Execution.RuleInconclusiveoption. Determines how to handle rules that generate inconclusive results. See about_PSRule_Options for more information.
"},{"location":"commands/PSRule/en-US/Set-PSRuleOption/#-executionunprocessedobject","title":"-ExecutionUnprocessedObject","text":"Type: ExecutionActionPreference\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nSets the
Execution.UnprocessedObjectoption. Determines how to report objects that are not processed by any rule. See about_PSRule_Options for more information.
"},{"location":"commands/PSRule/en-US/Set-PSRuleOption/#-includemodule","title":"-IncludeModule","text":"Type: ExecutionActionPreference\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nSets the
Include.Moduleoption to include additional module sources. See about_PSRule_Options for more information.
"},{"location":"commands/PSRule/en-US/Set-PSRuleOption/#-includepath","title":"-IncludePath","text":"Type: String[]\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nSets the
Include.Pathoption to include additional standalone sources. See about_PSRule_Options for more information.
"},{"location":"commands/PSRule/en-US/Set-PSRuleOption/#-format","title":"-Format","text":"Type: String[]\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nSets the
Input.Formatoption to configure the input format for when a string is passed in as a target object. See about_PSRule_Options for more information.
"},{"location":"commands/PSRule/en-US/Set-PSRuleOption/#-inputignoregitpath","title":"-InputIgnoreGitPath","text":"Type: InputFormat\nParameter Sets: (All)\nAliases: InputFormat\nAccepted values: None, Yaml, Json, Markdown, PowerShellData, File, Detect\n\nRequired: False\nPosition: Named\nDefault value: Detect\nAccept pipeline input: False\nAccept wildcard characters: False\nSets the
Input.IgnoreGitPathoption to determine if files within the .git path are ignored. See about_PSRule_Options for more information.
"},{"location":"commands/PSRule/en-US/Set-PSRuleOption/#-inputignorerepositorycommon","title":"-InputIgnoreRepositoryCommon","text":"Type: Boolean\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: True\nAccept pipeline input: False\nAccept wildcard characters: False\nSets the
Input.IgnoreRepositoryCommonoption to determine if files common repository files are ignored. See about_PSRule_Options for more information.
"},{"location":"commands/PSRule/en-US/Set-PSRuleOption/#-inputignoreunchangedpath","title":"-InputIgnoreUnchangedPath","text":"Type: Boolean\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nSets the option
Input.IgnoreUnchangedPath. TheInput.IgnoreUnchangedPathoption determine if unchanged files are ignored.
"},{"location":"commands/PSRule/en-US/Set-PSRuleOption/#-objectpath","title":"-ObjectPath","text":"Type: Boolean\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nSets the
Input.ObjectPathoption to use an object path to use instead of the pipeline object. See about_PSRule_Options for more information.
"},{"location":"commands/PSRule/en-US/Set-PSRuleOption/#-inputpathignore","title":"-InputPathIgnore","text":"Type: String\nParameter Sets: (All)\nAliases: InputObjectPath\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nSets the
Input.PathIgnoreoption. If specified, files that match the path spec will not be processed. See about_PSRule_Options for more information.
"},{"location":"commands/PSRule/en-US/Set-PSRuleOption/#-inputtargettype","title":"-InputTargetType","text":"Type: String[]\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nSets the
Input.TargetTypeoption to only process objects with the specified TargetType.
"},{"location":"commands/PSRule/en-US/Set-PSRuleOption/#-inputignoreobjectsource","title":"-InputIgnoreObjectSource","text":"Type: String[]\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nSets the option
Input.IgnoreObjectSource. TheInput.IgnoreObjectSourceoption determines if objects will be skipped if the source path has been ignored.
"},{"location":"commands/PSRule/en-US/Set-PSRuleOption/#-logginglimitdebug","title":"-LoggingLimitDebug","text":"Type: Boolean\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nSets the
Logging.LimitDebugoption to limit debug messages to a list of named debug scopes.
"},{"location":"commands/PSRule/en-US/Set-PSRuleOption/#-logginglimitverbose","title":"-LoggingLimitVerbose","text":"Type: String[]\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nSets the
Logging.LimitVerboseoption to limit verbose messages to a list of named verbose scopes.
"},{"location":"commands/PSRule/en-US/Set-PSRuleOption/#-loggingrulefail","title":"-LoggingRuleFail","text":"Type: String[]\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nSets the
Logging.RuleFailoption to generate an informational message for each rule fail.
"},{"location":"commands/PSRule/en-US/Set-PSRuleOption/#-loggingrulepass","title":"-LoggingRulePass","text":"Type: OutcomeLogStream\nParameter Sets: (All)\nAliases:\nAccepted values: None, Error, Warning, Information\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nSets the
Logging.RulePassoption to generate an informational message for each rule pass.
"},{"location":"commands/PSRule/en-US/Set-PSRuleOption/#-outputas","title":"-OutputAs","text":"Type: OutcomeLogStream\nParameter Sets: (All)\nAliases:\nAccepted values: None, Error, Warning, Information\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nSets the option
Output.As. TheOutput.Asoption configures the type of results to produce, either detail or summary.
"},{"location":"commands/PSRule/en-US/Set-PSRuleOption/#-outputbanner","title":"-OutputBanner","text":"Type: ResultFormat\nParameter Sets: (All)\nAliases:\nAccepted values: Detail, Summary\n\nRequired: False\nPosition: Named\nDefault value: Detail\nAccept pipeline input: False\nAccept wildcard characters: False\nSets the option
Output.Banner. TheOutput.Banneroption configure information displayed with PSRule banner. This option is only applicable when usingAssert-PSRulecmdlet.
"},{"location":"commands/PSRule/en-US/Set-PSRuleOption/#-outputculture","title":"-OutputCulture","text":"Type: BannerFormat\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: Default\nAccept pipeline input: False\nAccept wildcard characters: False\nSets the option
Output.Culture. TheOutput.Cultureoption configures the culture used to generated output. When multiple cultures are specified, the first matching culture will be used.
"},{"location":"commands/PSRule/en-US/Set-PSRuleOption/#-outputencoding","title":"-OutputEncoding","text":"Type: String[]\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nSets the option
Output.Encoding. TheOutput.Encodingoption configured the encoding used to write results to file.
"},{"location":"commands/PSRule/en-US/Set-PSRuleOption/#-outputfooter","title":"-OutputFooter","text":"Type: OutputEncoding\nParameter Sets: (All)\nAliases:\nAccepted values: Default, UTF8, UTF7, Unicode, UTF32, ASCII\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nSets the option
Output.Footer. TheOutput.Footeroption configures the information displayed for PSRule footer. See about_PSRule_Options for more information.
"},{"location":"commands/PSRule/en-US/Set-PSRuleOption/#-outputformat","title":"-OutputFormat","text":"Type: FooterFormat\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: Default\nAccept pipeline input: False\nAccept wildcard characters: False\nSets the option
Output.Format. TheOutput.Formatoption configures the format that results will be presented in.
"},{"location":"commands/PSRule/en-US/Set-PSRuleOption/#-outputjobsummarypath","title":"-OutputJobSummaryPath","text":"Type: OutputFormat\nParameter Sets: (All)\nAliases:\nAccepted values: None, Yaml, Json, Markdown, NUnit3, Csv, Wide, Sarif\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nSet the option
Output.JobSummaryPath. TheOutput.JobSummaryPathoption configures the path to a job summary output file.
"},{"location":"commands/PSRule/en-US/Set-PSRuleOption/#-outputjsonindent","title":"-OutputJsonIndent","text":"Type: String\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nSets the option
Output.JsonIndent. TheOutput.JsonIndentoption configures indentation for JSON output.This option only applies to
Get-PSRule,Invoke-PSRuleandAssert-PSRulecmdlets.
"},{"location":"commands/PSRule/en-US/Set-PSRuleOption/#-outputoutcome","title":"-OutputOutcome","text":"Type: Int32\nParameter Sets: (All)\nAliases: JsonIndent\nAccepted values: 0, 1, 2, 3, 4\n\nRequired: False\nPosition: Named\nDefault value: 0\nAccept pipeline input: False\nAccept wildcard characters: False\nSets the
Output.Outcomeoption. This option can be set to include or exclude output results. See about_PSRule_Options for more information.
"},{"location":"commands/PSRule/en-US/Set-PSRuleOption/#-outputpath","title":"-OutputPath","text":"Type: RuleOutcome\nParameter Sets: (All)\nAliases: Outcome\n\nRequired: False\nPosition: Named\nDefault value: Processed\nAccept pipeline input: False\nAccept wildcard characters: False\nSets the option
Output.Path. TheOutput.Pathoption configures an output file path to write results.
"},{"location":"commands/PSRule/en-US/Set-PSRuleOption/#-outputsarifproblemsonly","title":"-OutputSarifProblemsOnly","text":"Type: String\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nSets the option
Option.SarifProblemsOnly. TheOutput.SarifProblemsOnlyoption determines if SARIF output only includes fail and error outcomes.
"},{"location":"commands/PSRule/en-US/Set-PSRuleOption/#-outputstyle","title":"-OutputStyle","text":"Type: Boolean\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: True\nAccept pipeline input: False\nAccept wildcard characters: False\nSets the option
Option.Style. TheOutput.Styleoption configures the style that results will be presented in.This option only applies to
Assert-PSRule.
"},{"location":"commands/PSRule/en-US/Set-PSRuleOption/#-whatif","title":"-WhatIf","text":"Type: OutputStyle\nParameter Sets: (All)\nAliases:\nAccepted values: Client, Plain, AzurePipelines, GitHubActions\n\nRequired: False\nPosition: Named\nDefault value: Client\nAccept pipeline input: False\nAccept wildcard characters: False\nShows what would happen if the cmdlet runs. The cmdlet is not run.
"},{"location":"commands/PSRule/en-US/Set-PSRuleOption/#-confirm","title":"-Confirm","text":"Type: SwitchParameter\nParameter Sets: (All)\nAliases: wi\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nPrompts you for confirmation before running the cmdlet.
"},{"location":"commands/PSRule/en-US/Set-PSRuleOption/#-repositorybaseref","title":"-RepositoryBaseRef","text":"Type: SwitchParameter\nParameter Sets: (All)\nAliases: cf\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nSets the option
Repository.BaseRef. TheRepository.BaseRefoption sets the repository base ref used for comparisons of changed files.
"},{"location":"commands/PSRule/en-US/Set-PSRuleOption/#-repositoryurl","title":"-RepositoryUrl","text":"Type: String\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nSets the option
Repository.Url. TheRepository.Urloption sets the repository URL reported in output.
"},{"location":"commands/PSRule/en-US/Set-PSRuleOption/#-ruleincludelocal","title":"-RuleIncludeLocal","text":"Type: String\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nSets the option
Rule.IncludeLocal. TheRule.IncludeLocaloption configures if local rules are automatically included. See about_PSRule_Options for more information.
"},{"location":"commands/PSRule/en-US/Set-PSRuleOption/#-duplicateresourceid","title":"-DuplicateResourceId","text":"Type: Boolean\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: False\nAccept pipeline input: False\nAccept wildcard characters: False\nSets the option
Execution.DuplicateResourceId. TheExecution.DuplicateResourceIdoption determines how to handle duplicate resources identifiers during execution.
"},{"location":"commands/PSRule/en-US/Set-PSRuleOption/#-initialsessionstate","title":"-InitialSessionState","text":"Type: ExecutionActionPreference\nParameter Sets: (All)\nAliases: ExecutionDuplicateResourceId\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nSets the option
Execution.InitialSessionState. TheExecution.InitialSessionStateoption determines how the initial session state for executing PowerShell code is created.
"},{"location":"commands/PSRule/en-US/Set-PSRuleOption/#-executionruleexcluded","title":"-ExecutionRuleExcluded","text":"Type: SessionState\nParameter Sets: (All)\nAliases: ExecutionInitialSessionState\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nSets the option
Execution.RuleExcluded. TheExecution.RuleExcludedoption determines how to handle excluded rules.
"},{"location":"commands/PSRule/en-US/Set-PSRuleOption/#-executionrulesuppressed","title":"-ExecutionRuleSuppressed","text":"Type: ExecutionActionPreference\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nSets the option
Execution.RuleSuppressed. TheExecution.RuleSuppressedoption determines how to handle suppressed rules.
"},{"location":"commands/PSRule/en-US/Set-PSRuleOption/#-suppressiongroupexpired","title":"-SuppressionGroupExpired","text":"Type: ExecutionActionPreference\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nSets the option
Execution.SuppressionGroupExpired. TheExecution.SuppressionGroupExpiredoption determines how to handle expired suppression groups.
"},{"location":"commands/PSRule/en-US/Set-PSRuleOption/#commonparameters","title":"CommonParameters","text":"Type: ExecutionActionPreference\nParameter Sets: (All)\nAliases: ExecutionSuppressionGroupExpired\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nThis cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters.
"},{"location":"commands/PSRule/en-US/Set-PSRuleOption/#inputs","title":"INPUTS","text":""},{"location":"commands/PSRule/en-US/Set-PSRuleOption/#outputs","title":"OUTPUTS","text":""},{"location":"commands/PSRule/en-US/Set-PSRuleOption/#psruleconfigurationpsruleoption","title":"PSRule.Configuration.PSRuleOption","text":"When you use the
"},{"location":"commands/PSRule/en-US/Set-PSRuleOption/#notes","title":"NOTES","text":""},{"location":"commands/PSRule/en-US/Set-PSRuleOption/#related-links","title":"RELATED LINKS","text":"-PassThruswitch, an options object is returned to the pipeline.New-PSRuleOption
"},{"location":"commands/PSRule/en-US/Test-PSRuleTarget/","title":"Test-PSRuleTarget","text":""},{"location":"commands/PSRule/en-US/Test-PSRuleTarget/#synopsis","title":"SYNOPSIS","text":"Pass or fail objects against matching rules.
"},{"location":"commands/PSRule/en-US/Test-PSRuleTarget/#syntax","title":"SYNTAX","text":""},{"location":"commands/PSRule/en-US/Test-PSRuleTarget/#input-default","title":"Input (Default)","text":"
"},{"location":"commands/PSRule/en-US/Test-PSRuleTarget/#inputpath","title":"InputPath","text":"Test-PSRuleTarget [-Module <String[]>] [-Outcome <RuleOutcome>] [-Format <InputFormat>]\n [-Convention <String[]>] [[-Path] <String[]>] [-Name <String[]>] [-Tag <Hashtable>] -InputObject <PSObject>\n [-Option <PSRuleOption>] [-ObjectPath <String>] [-TargetType <String[]>] [-Culture <String>]\n [<CommonParameters>]\n
"},{"location":"commands/PSRule/en-US/Test-PSRuleTarget/#description","title":"DESCRIPTION","text":"Test-PSRuleTarget -InputPath <String[]> [-Module <String[]>] [-Outcome <RuleOutcome>] [-Format <InputFormat>]\n [-Convention <String[]>] [[-Path] <String[]>] [-Name <String[]>] [-Tag <Hashtable>] [-Option <PSRuleOption>]\n [-ObjectPath <String>] [-TargetType <String[]>] [-Culture <String>] [<CommonParameters>]\nEvaluate objects against matching rules and return an overall pass or fail for the object as
$True(pass) or$False(fail).PSRule uses the following logic to determine overall pass or fail for an object:
By default, objects that do match any rules are not returned in results. To return
"},{"location":"commands/PSRule/en-US/Test-PSRuleTarget/#examples","title":"EXAMPLES","text":""},{"location":"commands/PSRule/en-US/Test-PSRuleTarget/#example-1","title":"Example 1","text":"$Truefor these objects, use-Outcome All.@{ Name = 'Item 1' } | Test-PSRuleTarget;\nEvaluate a simple hashtable on the pipeline against rules loaded from the current working path.
"},{"location":"commands/PSRule/en-US/Test-PSRuleTarget/#parameters","title":"PARAMETERS","text":""},{"location":"commands/PSRule/en-US/Test-PSRuleTarget/#-path","title":"-Path","text":"One or more paths to search for rule definitions within.
If the
-Moduleparameter is used, rule definitions from the currently working path will not be included by default.
"},{"location":"commands/PSRule/en-US/Test-PSRuleTarget/#-name","title":"-Name","text":"Type: String[]\nParameter Sets: (All)\nAliases: p\n\nRequired: False\nPosition: 1\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nThe name of a specific rule to evaluate. If this parameter is not specified all rules in search paths will be evaluated.
"},{"location":"commands/PSRule/en-US/Test-PSRuleTarget/#-outcome","title":"-Outcome","text":"Type: String[]\nParameter Sets: (All)\nAliases: n\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nFilter output to only show pipeline objects with a specific outcome.
"},{"location":"commands/PSRule/en-US/Test-PSRuleTarget/#-tag","title":"-Tag","text":"Type: RuleOutcome\nParameter Sets: (All)\nAliases:\nAccepted values: Pass, Fail, Error, None, Processed, All\n\nRequired: False\nPosition: Named\nDefault value: Pass, Fail, Error\nAccept pipeline input: False\nAccept wildcard characters: False\nOnly get rules with the specified tags set. If this parameter is not specified all rules in search paths will be returned.
When more than one tag is used, all tags must match. Tags are not case sensitive. A tag value of
*may be used to filter rules to any rule with the tag set, regardless of tag value.An array of tag values can be used to match a rule with either value. i.e.
severity = important, criticalmatches rules with a category of eitherimportantorcritical.
"},{"location":"commands/PSRule/en-US/Test-PSRuleTarget/#-inputobject","title":"-InputObject","text":"Type: Hashtable\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nThe pipeline object to process rules for.
"},{"location":"commands/PSRule/en-US/Test-PSRuleTarget/#-option","title":"-Option","text":"Type: PSObject\nParameter Sets: Input\nAliases: TargetObject\n\nRequired: True\nPosition: Named\nDefault value: None\nAccept pipeline input: True (ByValue)\nAccept wildcard characters: False\nAdditional options that configure execution. A
PSRuleOptioncan be created by using theNew-PSRuleOptioncmdlet. Alternatively, a hashtable or path to YAML file can be specified with options.For more information on PSRule options see about_PSRule_Options.
"},{"location":"commands/PSRule/en-US/Test-PSRuleTarget/#-format","title":"-Format","text":"Type: PSRuleOption\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nConfigures the input format for when a string is passed in as a target object.
When the
-InputObjectparameter or pipeline input is used, strings are treated as plain text by default. Set this option to eitherYaml,Json,Markdown,PowerShellDatato have PSRule deserialize the object.When the
-InputPathparameter is used with a file path or URL. If theDetectformat is used, the file extension will be used to automatically detect the format. When-InputPathis not used,Detectis the same asNone.When this option is set to
FilePSRule scans the path and subdirectories specified by-InputPath. Files are treated as objects instead of being deserialized. Additional, PSRule uses the file extension as the object type. When files have no extension the whole file name is used.See
about_PSRule_Optionsfor details.This parameter takes precedence over the
Input.Formatoption if set.
"},{"location":"commands/PSRule/en-US/Test-PSRuleTarget/#-convention","title":"-Convention","text":"Type: InputFormat\nParameter Sets: (All)\nAliases:\nAccepted values: None, Yaml, Json, Markdown, PowerShellData, Repository, Detect\n\nRequired: False\nPosition: Named\nDefault value: Detect\nAccept pipeline input: False\nAccept wildcard characters: False\nSpecifies conventions by name to execute in the pipeline when processing objects.
"},{"location":"commands/PSRule/en-US/Test-PSRuleTarget/#-culture","title":"-Culture","text":"Type: String[]\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nSpecifies the culture to use for rule documentation and messages. By default, the culture of PowerShell is used.
This option does not affect the culture used for the PSRule engine, which always uses the culture of PowerShell.
The PowerShell cmdlet
Get-Cultureshows the current culture of PowerShell.
"},{"location":"commands/PSRule/en-US/Test-PSRuleTarget/#-objectpath","title":"-ObjectPath","text":"Type: String\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nThe name of a property to use instead of the pipeline object. If the property specified by
ObjectPathis a collection or an array, then each item in evaluated separately.
"},{"location":"commands/PSRule/en-US/Test-PSRuleTarget/#-targettype","title":"-TargetType","text":"Type: String\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nFilters input objects by TargetType.
If specified, only objects with the specified TargetType are processed. Objects that do not match TargetType are ignored. If multiple values are specified, only one TargetType must match. This parameter is not case-sensitive.
By default, all objects are processed.
This parameter if set, overrides the
Input.TargetTypeoption.To change the field TargetType is bound to set the
Binding.TargetTypeoption. For details see the about_PSRule_Options help topic.
"},{"location":"commands/PSRule/en-US/Test-PSRuleTarget/#-module","title":"-Module","text":"Type: String[]\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nSearch for rule definitions within a module. When specified without the
-Pathparameter, only rule definitions in the module will be discovered.When both
-Pathand-Moduleare specified, rule definitions from both are discovered.
"},{"location":"commands/PSRule/en-US/Test-PSRuleTarget/#-inputpath","title":"-InputPath","text":"Type: String[]\nParameter Sets: (All)\nAliases: m\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nInstead of processing objects from the pipeline, import objects file the specified file paths.
"},{"location":"commands/PSRule/en-US/Test-PSRuleTarget/#commonparameters","title":"CommonParameters","text":"Type: String[]\nParameter Sets: InputPath\nAliases: f\n\nRequired: True\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nThis cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters.
"},{"location":"commands/PSRule/en-US/Test-PSRuleTarget/#inputs","title":"INPUTS","text":""},{"location":"commands/PSRule/en-US/Test-PSRuleTarget/#systemmanagementautomationpsobject","title":"System.Management.Automation.PSObject","text":"You can pipe any object to Test-PSRuleTarget.
"},{"location":"commands/PSRule/en-US/Test-PSRuleTarget/#outputs","title":"OUTPUTS","text":""},{"location":"commands/PSRule/en-US/Test-PSRuleTarget/#systemboolean","title":"System.Boolean","text":"Returns
"},{"location":"commands/PSRule/en-US/Test-PSRuleTarget/#notes","title":"NOTES","text":""},{"location":"commands/PSRule/en-US/Test-PSRuleTarget/#related-links","title":"RELATED LINKS","text":"$Truewhen the object passes and$Falsewhen the object fails.Invoke-PSRule
Assert-PSRule
Get-PSRule
"},{"location":"concepts/baselines/","title":"Baselines","text":"Abstract
A baseline is a set of rules and configuration options. You can define a named baseline to run a set of rules for a specific use case.
Baselines cover two (2) main scenarios:
A baseline is defined as a resource within YAML or JSON. Baselines can be defined side-by-side with rules you create or included separately as a custom baseline.
Continue reading baseline reference.
"},{"location":"concepts/baselines/#baseline-groups","title":"Baseline groups","text":"v2.9.0
In addition to regular baselines, you can use a baseline group to provide a friendly name to an existing baseline. A baseline groups are set by configuring the Baseline.Group option.
Experimental
Baseline groups are a work in progress and subject to change. Currently, baseline groups allow only a single baseline to be referenced. Join or start a discussion to let us know how we can improve this feature going forward.
Tip
You can use baseline groups to reference a baseline. If a new baseline is made available in the future, update your baseline group in one place to start using the new baseline.
In the following example, two baseline groups
ps-rule.yamllatestandprevieware defined:baseline:\n group:\n latest: PSRule.Rules.Azure\\Azure.GA_2023_03\n preview: PSRule.Rules.Azure\\Azure.Preview_2023_03\nTo use the baseline group, prefix the group name with
GitHub ActionsAzure PipelinesGeneric with PowerShell@when running PSRule. For example:- name: Run PSRule\n uses: microsoft/ps-rule@v2.9.0\n with:\n modules: 'PSRule.Rules.Azure'\n baseline: '@latest'\n- task: ps-rule-assert@2\n displayName: Run PSRule\n inputs:\n modules: 'PSRule.Rules.Azure'\n baseline: '@latest'\n
"},{"location":"concepts/grouping-rules/","title":"Grouping rules","text":"Assert-PSRule -InputPath '.' -Baseline '@latest' -Module PSRule.Rules.Azure -Format File;\nAbstract
Labels are additional metadata that can be used to classify rules. Together with tags they can be used to group or filter rules.
"},{"location":"concepts/grouping-rules/#using-labels","title":"Using labels","text":"When defining a rule you can specify labels to classify or link rules using a framework or standard. A single rule can be can linked to multiple labels. For example:
To specify labels in YAML, use the
labelsproperty:---\n# Synopsis: A rule with labels defined.\napiVersion: github.com/microsoft/PSRule/v1\nkind: Rule\nmetadata:\n name: WithLabels\n labels:\n Azure.WAF/pillar: Security\n Azure.ASB.v3/control: [ 'ID-1', 'ID-2' ]\nspec: { }\nTo specify labels in JSON, use the
labelsproperty:{\n // Synopsis: A rule with labels defined.\n \"apiVersion\": \"github.com/microsoft/PSRule/v1\",\n \"kind\": \"Rule\",\n \"metadata\": {\n \"name\": \"WithLabels\",\n \"labels\": {\n \"Azure.WAF/pillar\": \"Security\",\n \"Azure.ASB.v3/control\": [ \"ID-1\", \"ID-2\" ]\n }\n },\n \"spec\": { }\n}\nTo specify labels in PowerShell, use the
-Labelsparameter:
"},{"location":"concepts/grouping-rules/#filtering-with-labels","title":"Filtering with labels","text":"# Synopsis: A rule with labels defined.\nRule 'WithLabels' -Labels @{ 'Azure.WAF/pillar' = 'Security'; 'Azure.ASB.v3/control' = @('ID-1', 'ID-2') } {\n # Define conditions here\n} \nA reason for assigning labels to rules is to perform filtering of rules to a specific subset. This can be accomplished using baselines and the
spec.rule.labelsproperty. For example:
"},{"location":"concepts/lockfile/","title":"Lock file","text":"---\n# Synopsis: A baseline which returns only security rules.\napiVersion: github.com/microsoft/PSRule/v1\nkind: Baseline\nmetadata:\n name: TestBaseline6\nspec:\n rule:\n labels:\n Azure.WAF/pillar: [ 'Security' ]\n\n---\n# Synopsis: A baseline which returns any rules that are classified to Azure.WAF/pillar.\napiVersion: github.com/microsoft/PSRule/v1\nkind: Baseline\nmetadata:\n name: TestBaseline6\nspec:\n rule:\n labels:\n Azure.WAF/pillar: '*'\nAbstract
PSRule v3 and later uses a lock file to define the modules and versions used to run analysis. This article describes the lock file and how to manage it.
An optional lock file can be used to define the modules and versions used to run analysis. Using the lock file ensures that the same modules and versions are used across multiple machines, improving consistency.
Important
The lock file only applies to PSRule outside of PowerShell. When using PSRule as a PowerShell module, the lock file is ignored.
"},{"location":"concepts/lockfile/#restoring-modules","title":"Restoring modules","text":"When the lock file is present, PSRule will restore the modules and versions defined in the lock file.
"},{"location":"concepts/PSRule/en-US/about_PSRule_Assert/","title":"Assertion methods","text":"Describes the assertion helper that can be used within PSRule rule definitions.
","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Assert/#description","title":"Description","text":"PSRule includes an assertion helper exposed as a built-in variable
$Assert. The$Assertobject provides a consistent set of methods to evaluate objects.Each
$Assertmethod returns anAssertResultobject that contains the result of the assertion.The following built-in assertion methods are provided:
The
","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Assert/#using-assertion-methods","title":"Using assertion methods","text":"$Assertvariable can only be used within a rule definition block or script pre-conditions.An assertion method can be used like other methods in PowerShell. i.e.
$Assert.methodName(parameters).Assertion methods use the following standard pattern:
Some assertion methods may overlap or provide similar functionality to built-in keywords. Where you have the choice, use built-in keywords. Use assertion methods for advanced cases or increased flexibility.
In the following example,
Assert.HasFieldValueasserts that$TargetObjectshould have a field namedTypewith a non-empty value.Rule 'Assert.HasTypeField' {\n $Assert.HasFieldValue($TargetObject, 'Type')\n}\nTo find perform multiple assertions use.
","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Assert/#field-names","title":"Field names","text":"Rule 'Assert.HasRequiredFields' {\n $Assert.HasFieldValue($TargetObject, 'Name')\n $Assert.HasFieldValue($TargetObject, 'Type')\n $Assert.HasFieldValue($TargetObject, 'Value')\n}\nMany of the built-in assertion methods accept an object path or field name. An object path is an expression that traverses object properties, keys or indexes of the input object. The syntax for an object path is inspired by JSONPath which is current an IETF Internet-Draft.
The object path expression can contain:
For example:
Notable differences between object paths and JSONPath are:
The
APIVersionassertion method checks the field value is a valid date version. A constraint can optionally be provided to require the date version to be within a range.A date version uses the format
yyyy-MM-dd(2015-10-01). Additionally an optional string prerelease identifier can be usedyyyy-MM-dd-prerelease(2015-10-01-preview.1).The following parameters are accepted:
The following are supported constraints:
An empty, null or
*constraint matches all valid date versions.Multiple constraints can be joined together:
By example:
Handling for prerelease versions:
Reasons include:
Examples:
","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Assert/#contains","title":"Contains","text":"Rule 'ValidAPIVersion' {\n $Assert.APIVersion($TargetObject, 'apiVersion')\n}\n\nRule 'MinimumAPIVersion' {\n $Assert.APIVersion($TargetObject, 'apiVersion', '>=2015-10-01')\n}\n\nRule 'MinimumAPIVersionWithPrerelease' {\n $Assert.APIVersion($TargetObject, 'apiVersion', '>=2015-10-01-0', $True)\n}\n\nRule 'MinimumAPIVersionWithFlag' {\n $Assert.APIVersion($TargetObject, 'apiVersion', '@pre >=2015-10-01-0')\n}\nThe
Containsassertion method checks the operand contains the specified string. If the operand is an array of strings, only one string must contain the specified string. Optionally a case-sensitive compare can be used, however case is ignored by default.The following parameters are accepted:
Reasons include:
Examples:
","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Assert/#count","title":"Count","text":"Rule 'Contains' {\n $Assert.Contains($TargetObject, 'ResourceGroupName', 'prod')\n $Assert.Contains($TargetObject, 'Name', @('prod', 'test'), $True)\n}\nThe
Countassertion method checks the field value contains the specified number of items. The field value must be an array or collection.The following parameters are accepted:
Reasons include:
Examples:
","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Assert/#endswith","title":"EndsWith","text":"Rule 'Count' {\n $Assert.Count($TargetObject, 'items', 2)\n}\nThe
EndsWithassertion method checks the operand ends with the specified suffix. If the operand is an array of strings, only one string must end with the specified suffix. Optionally a case-sensitive compare can be used, however case is ignored by default.The following parameters are accepted:
Reasons include:
Examples:
","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Assert/#fileheader","title":"FileHeader","text":"Rule 'EndsWith' {\n $Assert.EndsWith($TargetObject, 'ResourceGroupName', 'eus')\n $Assert.EndsWith($TargetObject, 'Name', @('db', 'web'), $True)\n}\nThe
FileHeaderassertion method checks a file for a comment header. When comparing the file header, the format of line comments are automatically detected by file extension. Single line comments are supported. Multi-line comments are not supported.The following parameters are accepted:
Prefix detection for line comments is supported with the following file extensions:
Reasons include:
Examples:
","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Assert/#filepath","title":"FilePath","text":"Rule 'FileHeader' {\n $Assert.FileHeader($TargetObject, 'FullName', @(\n 'Copyright (c) Microsoft Corporation.'\n 'Licensed under the MIT License.'\n ));\n}\nThe
FilePathassertion method checks the file exists. Checks use file system case-sensitivity rules.The following parameters are accepted:
Reasons include:
Examples:
","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Assert/#greater","title":"Greater","text":"Rule 'FilePath' {\n $Assert.FilePath($TargetObject, 'FullName', @('CHANGELOG.md'));\n $Assert.FilePath($TargetObject, 'FullName', @('LICENSE', 'LICENSE.txt'));\n $Assert.FilePath($TargetObject, 'FullName', @('CODE_OF_CONDUCT.md'));\n $Assert.FilePath($TargetObject, 'FullName', @('CONTRIBUTING.md'));\n $Assert.FilePath($TargetObject, 'FullName', @('SECURITY.md'));\n $Assert.FilePath($TargetObject, 'FullName', @('README.md'));\n $Assert.FilePath($TargetObject, 'FullName', @('.github/CODEOWNERS'));\n $Assert.FilePath($TargetObject, 'FullName', @('.github/PULL_REQUEST_TEMPLATE.md'));\n}\nThe
Greaterassertion method checks the field value is greater than the specified value. The field value can either be an integer, float, array, or string. When the field value is:The following parameters are accepted:
Reasons include:
Examples:
","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Assert/#greaterorequal","title":"GreaterOrEqual","text":"Rule 'Greater' {\n $Assert.Greater($TargetObject, 'value', 3)\n}\nThe
GreaterOrEqualassertion method checks the field value is greater or equal to the specified value. The field value can either be an integer, float, array, or string. When the field value is:The following parameters are accepted:
Reasons include:
Examples:
","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Assert/#hasdefaultvalue","title":"HasDefaultValue","text":"Rule 'GreaterOrEqual' {\n $Assert.GreaterOrEqual($TargetObject, 'value', 3)\n}\nThe
HasDefaultValueassertion method check that the field does not exist or the field value is set to the default value.The following parameters are accepted:
This assertion will pass if:
This assertion will fail if:
Reasons include:
Examples:
","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Assert/#hasfield","title":"HasField","text":"Rule 'HasDefaultValue' {\n $Assert.HasDefaultValue($TargetObject, 'Properties.osProfile.linuxConfiguration.provisionVMAgent', $True)\n}\nThe
HasFieldassertion method checks the object has any of the specified fields.The following parameters are accepted:
Reasons include:
Examples:
","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Assert/#hasfields","title":"HasFields","text":"Rule 'HasField' {\n $Assert.HasField($TargetObject, 'Name')\n $Assert.HasField($TargetObject, 'tag.Environment', $True)\n $Assert.HasField($TargetObject, @('tag.Environment', 'tag.Env'), $True)\n}\nThe
HasFieldsassertion method checks the object has all of the specified fields.The following parameters are accepted:
Reasons include:
Examples:
","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Assert/#hasfieldvalue","title":"HasFieldValue","text":"Rule 'HasFields' {\n $Assert.HasFields($TargetObject, 'Name')\n $Assert.HasFields($TargetObject, 'tag.Environment', $True)\n $Assert.HasFields($TargetObject, @('tag.Environment', 'tag.Env'), $True)\n}\nThe
HasFieldValueassertion method checks the field value of the object is not empty.A field value is empty if any of the following are true:
The following parameters are accepted:
Reasons include:
Examples:
","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Assert/#hasjsonschema","title":"HasJsonSchema","text":"Rule 'HasFieldValue' {\n $Assert.HasFieldValue($TargetObject, 'Name')\n $Assert.HasFieldValue($TargetObject, 'tag.Environment', 'production')\n}\nThe
HasJsonSchemaassertion method determines if the input object has a$schemaproperty defined. If the$schemaproperty is defined, it must not be empty and match one of the supplied schemas. If a trailing#is specified it is ignored from the$schemaproperty anduriparameter below.The following parameters are accepted:
Reasons include:
Examples:
","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Assert/#jsonschema","title":"JsonSchema","text":"Rule 'HasFieldValue' {\n $Assert.HasJsonSchema($TargetObject)\n $Assert.HasJsonSchema($TargetObject, \"http://json-schema.org/draft-07/schema`#\")\n $Assert.HasJsonSchema($TargetObject, \"https://json-schema.org/draft-07/schema\", $True)\n}\nThe
JsonSchemaassertion method compares the input object against a defined JSON schema.The following parameters are accepted:
Reasons include:
Examples:
","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Assert/#in","title":"In","text":"Rule 'JsonSchema' {\n $Assert.JsonSchema($TargetObject, 'tests/PSRule.Tests/FromFile.Json.schema.json')\n}\nThe
Inassertion method checks the field value is included in a set of values. The field value can either be an integer, float, array, or string. When the field value is an array, only one item must be included in the set.The following parameters are accepted:
Reasons include:
Examples:
","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Assert/#isarray","title":"IsArray","text":"Rule 'In' {\n $Assert.In($TargetObject, 'Sku.tier', @('PremiumV2', 'Premium', 'Standard'))\n $Assert.In($TargetObject, 'Sku.tier', @('PremiumV2', 'Premium', 'Standard'), $True)\n}\nThe
IsArrayassertion method checks the field value is an array type.The following parameters are accepted:
Reasons include:
Examples:
","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Assert/#isboolean","title":"IsBoolean","text":"Rule 'IsArray' {\n # Require Value1 to be an array\n $Assert.IsArray($TargetObject, 'Value1')\n}\nThe
IsBooleanassertion method checks the field value is a boolean type.The following parameters are accepted:
Reasons include:
Examples:
","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Assert/#isdatetime","title":"IsDateTime","text":"Rule 'IsBoolean' {\n # Require Value1 to be a boolean\n $Assert.IsBoolean($TargetObject, 'Value1')\n\n # Require Value1 to be a boolean or a boolean string\n $Assert.IsBoolean($TargetObject, 'Value1', $True)\n}\nThe
IsDateTimeassertion method checks the field value is a DateTime type.The following parameters are accepted:
Reasons include:
Examples:
","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Assert/#isinteger","title":"IsInteger","text":"Rule 'IsDateTime' {\n # Require Value1 to be a DateTime\n $Assert.IsDateTime($TargetObject, 'Value1')\n\n # Require Value1 to be a DateTime or a DateTime string\n $Assert.IsDateTime($TargetObject, 'Value1', $True)\n}\nThe
IsIntegerassertion method checks the field value is a integer type. The following types are considered integer typesint,long,byte.The following parameters are accepted:
Reasons include:
Examples:
","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Assert/#islower","title":"IsLower","text":"Rule 'IsInteger' {\n # Require Value1 to be an integer\n $Assert.IsInteger($TargetObject, 'Value1')\n\n # Require Value1 to be an integer or a integer string\n $Assert.IsInteger($TargetObject, 'Value1', $True)\n}\nThe
IsLowerassertion method checks the field value uses only lowercase characters. Non-letter characters are ignored by default and will pass.The following parameters are accepted:
Reasons include:
Examples:
","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Assert/#isnumeric","title":"IsNumeric","text":"Rule 'IsLower' {\n # Require Name to be lowercase\n $Assert.IsLower($TargetObject, 'Name')\n\n # Require Name to only contain lowercase letters\n $Assert.IsLower($TargetObject, 'Name', $True)\n}\nThe
IsNumericassertion method checks the field value is a numeric type. The following types are considered numeric typesint,long,float,byte,double.The following parameters are accepted:
Reasons include:
Examples:
","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Assert/#isstring","title":"IsString","text":"Rule 'IsNumeric' {\n # Require Value1 to be numeric\n $Assert.IsNumeric($TargetObject, 'Value1')\n\n # Require Value1 to be numeric or a numerical string\n $Assert.IsNumeric($TargetObject, 'Value1', $True)\n}\nThe
IsStringassertion method checks the field value is a string type.The following parameters are accepted:
Reasons include:
Examples:
","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Assert/#isupper","title":"IsUpper","text":"Rule 'IsString' {\n # Require Value1 to be a string\n $Assert.IsString($TargetObject, 'Value1')\n}\nThe
IsUpperassertion method checks the field value uses only uppercase characters. Non-letter characters are ignored by default and will pass.The following parameters are accepted:
Reasons include:
Examples:
","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Assert/#less","title":"Less","text":"Rule 'IsUpper' {\n # Require Name to be uppercase\n $Assert.IsUpper($TargetObject, 'Name')\n\n # Require Name to only contain uppercase letters\n $Assert.IsUpper($TargetObject, 'Name', $True)\n}\nThe
Lessassertion method checks the field value is less than the specified value. The field value can either be an integer, float, array, or string. When the field value is:The following parameters are accepted:
Reasons include:
Examples:
","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Assert/#lessorequal","title":"LessOrEqual","text":"Rule 'Less' {\n $Assert.Less($TargetObject, 'value', 3)\n}\nThe
LessOrEqualassertion method checks the field value is less or equal to the specified value. The field value can either be an integer, float, array, or string. When the field value is:The following parameters are accepted:
Reasons include:
Examples:
","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Assert/#like","title":"Like","text":"Rule 'LessOrEqual' {\n $Assert.LessOrEqual($TargetObject, 'value', 3)\n}\nThe
Likeassertion method checks the field value matches a specified pattern. Optionally a case-sensitive compare can be used, however case is ignored by default.The following parameters are accepted:
Reasons include:
Examples:
","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Assert/#match","title":"Match","text":"Rule 'Like' {\n $Assert.Like($TargetObject, 'ResourceGroupName', 'rg-*')\n $Assert.Like($TargetObject, 'Name', @('st*', 'diag*'), $True)\n}\nThe
Matchassertion method checks the field value matches a regular expression pattern.The following parameters are accepted:
Reasons include:
Examples:
","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Assert/#notcontains","title":"NotContains","text":"Rule 'Match' {\n $Assert.Match($TargetObject, 'value', '^[a-z]*$')\n $Assert.Match($TargetObject, 'value', '^[a-z]*$', $True)\n}\nThe
NotContainsassertion method checks the operand contains the specified string. This condition fails when any of the specified sub-strings are found. If the operand is an array of strings, this condition fails if any of the strings contain the specified string. Optionally a case-sensitive compare can be used, however case is ignored by default.The following parameters are accepted:
Reasons include:
Examples:
","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Assert/#notcount","title":"NotCount","text":"Rule 'NotContains' {\n $Assert.NotContains($TargetObject, 'ResourceGroupName', 'prod')\n $Assert.NotContains($TargetObject, 'Name', @('prod', 'test'), $True)\n}\nThe
NotCountassertion method checks the field value does not contain the specified number of items. The field value must be an array or collection.The following parameters are accepted:
Reasons include:
Examples:
","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Assert/#notendswith","title":"NotEndsWith","text":"Rule 'NotCount' {\n $Assert.NotCount($TargetObject, 'items', 2)\n}\nThe
NotEndsWithassertion method checks the operand ends with the specified suffix. This condition fails when any of the specified sub-strings are found at the end of the operand. If the operand is an array of strings, this condition fails if any of the strings ends with the specified suffix. Optionally a case-sensitive compare can be used, however case is ignored by default.The following parameters are accepted:
Reasons include:
Examples:
","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Assert/#nothasfield","title":"NotHasField","text":"Rule 'NotEndsWith' {\n $Assert.NotEndsWith($TargetObject, 'ResourceGroupName', 'eus')\n $Assert.NotEndsWith($TargetObject, 'Name', @('db', 'web'), $True)\n}\nThe
NotHasFieldassertion method checks the object does not have any of the specified fields.The following parameters are accepted:
Reasons include:
Examples:
","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Assert/#notin","title":"NotIn","text":"Rule 'NotHasField' {\n $Assert.NotHasField($TargetObject, 'Name')\n $Assert.NotHasField($TargetObject, 'tag.Environment', $True)\n $Assert.NotHasField($TargetObject, @('tag.Environment', 'tag.Env'), $True)\n}\nThe
NotInassertion method checks the field value is not in a set of values. The field value can either be an integer, array, float, or string. When the field value is an array, none of the items must be included in the set. If the field does not exist at all, it is not in the set and passes. To check the field exists combine this assertion method withHasFieldValue.The following parameters are accepted:
Reasons include:
Examples:
","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Assert/#notlike","title":"NotLike","text":"Rule 'In' {\n $Assert.NotIn($TargetObject, 'Sku.tier', @('Free', 'Shared', 'Basic'))\n $Assert.NotIn($TargetObject, 'Sku.tier', @('Free', 'Shared', 'Basic'), $True)\n}\nThe
NotLikeassertion method checks the field value matches a specified pattern. This condition fails when any of the specified patterns match the field value. Optionally a case-sensitive compare can be used, however case is ignored by default.The following parameters are accepted:
Reasons include:
Examples:
","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Assert/#notmatch","title":"NotMatch","text":"Rule 'NotLike' {\n $Assert.NotLike($TargetObject, 'ResourceGroupName', 'rg-*')\n $Assert.NotLike($TargetObject, 'Name', @('st*', 'diag*'), $True)\n}\nThe
NotMatchassertion method checks the field value does not match a regular expression pattern. If the field does not exist at all, it does not match and passes. To check the field exists combine this assertion method withHasFieldValue.The following parameters are accepted:
Reasons include:
Examples:
","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Assert/#notnull","title":"NotNull","text":"Rule 'NotMatch' {\n $Assert.NotMatch($TargetObject, 'value', '^[a-z]*$')\n $Assert.NotMatch($TargetObject, 'value', '^[a-z]*$', $True)\n}\nThe
NotNullassertion method checks the field value of the object is not null.The following parameters are accepted:
Reasons include:
Examples:
","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Assert/#notstartswith","title":"NotStartsWith","text":"Rule 'NotNull' {\n $Assert.NotNull($TargetObject, 'Name')\n $Assert.NotNull($TargetObject, 'tag.Environment')\n}\nThe
NotStartsWithassertion method checks the operand starts with the specified prefix. This condition fails when any of the specified sub-strings are found at the start of the operand. If the operand is an array of strings, this condition fails if any of the strings start with the specified prefix. Optionally a case-sensitive compare can be used, however case is ignored by default.The following parameters are accepted:
Reasons include:
Examples:
","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Assert/#notwithinpath","title":"NotWithinPath","text":"Rule 'NotStartsWith' {\n $Assert.NotStartsWith($TargetObject, 'ResourceGroupName', 'rg-')\n $Assert.NotStartsWith($TargetObject, 'Name', @('st', 'diag'), $True)\n}\nThe
NotWithinPathassertion method checks the file is not within a specified path. Checks use file system case-sensitivity rules by default.The following parameters are accepted:
Reasons include:
Examples:
","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Assert/#null","title":"Null","text":"Rule 'NotWithinPath' {\n # The file must not be within either policy/ or security/ sub-directories.\n $Assert.NotWithinPath($TargetObject, 'FullName', @('policy/', 'security/'));\n}\nThe
Nullassertion method checks the field value of the object is null.A field value is null if any of the following are true:
The following parameters are accepted:
Reasons include:
Examples:
","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Assert/#nullorempty","title":"NullOrEmpty","text":"Rule 'Null' {\n $Assert.Null($TargetObject, 'NotField')\n $Assert.Null($TargetObject, 'tag.NullField')\n}\nThe
NullOrEmptyassertion method checks the field value of the object is null or empty.A field value is null or empty if any of the following are true:
The following parameters are accepted:
Reasons include:
Examples:
","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Assert/#typeof","title":"TypeOf","text":"Rule 'NullOrEmpty' {\n $Assert.NullOrEmpty($TargetObject, 'Name')\n $Assert.NullOrEmpty($TargetObject, 'tag.Environment')\n}\nThe
TypeOfassertion method checks the field value is a specified type.The following parameters are accepted:
Reasons include:
Examples:
","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Assert/#setof","title":"SetOf","text":"Rule 'TypeOf' {\n # Require Value1 to be [int]\n $Assert.TypeOf($TargetObject, 'Value1', [int])\n\n # Require Value1 to be [int] or [long]\n $Assert.TypeOf($TargetObject, 'Value1', @([int], [long]))\n}\nThe
SetOfassertion method checks the field value only includes all of the specified values. The field value must be an array or collection. Specified values can be included in the field value in any order.The following parameters are accepted:
Reasons include:
Examples:
","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Assert/#startswith","title":"StartsWith","text":"Rule 'Subset' {\n $Assert.SetOf($TargetObject, 'zones', @('1', '2', '3'))\n}\nThe
StartsWithassertion method checks the operand starts with the specified prefix. If the operand is an array of strings, only one string must start with the specified prefix. Optionally a case-sensitive compare can be used, however case is ignored by default.The following parameters are accepted:
Reasons include:
Examples:
","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Assert/#subset","title":"Subset","text":"Rule 'StartsWith' {\n $Assert.StartsWith($TargetObject, 'ResourceGroupName', 'rg-')\n $Assert.StartsWith($TargetObject, 'Name', @('st', 'diag'), $True)\n}\nThe
Subsetassertion method checks the field value includes all of the specified values. The field value may also contain additional values that are not specified in thevaluesparameter. The field value must be an array or collection. Specified values can be included in the field value in any order.The following parameters are accepted:
Reasons include:
Examples:
","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Assert/#version","title":"Version","text":"Rule 'Subset' {\n $Assert.Subset($TargetObject, 'logs', @('cluster-autoscaler', 'kube-apiserver', 'kube-scheduler'), $True, $True)\n}\nThe
Versionassertion method checks the field value is a valid semantic version. A constraint can optionally be provided to require the semantic version to be within a range.The following parameters are accepted:
The following are supported constraints:
An empty, null or
*constraint matches all valid semantic versions.Multiple constraints can be joined together:
By example:
Handling for prerelease versions:
By example:
Reasons include:
Examples:
","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Assert/#withinpath","title":"WithinPath","text":"Rule 'ValidVersion' {\n $Assert.Version($TargetObject, 'version')\n}\n\nRule 'MinimumVersion' {\n $Assert.Version($TargetObject, 'version', '>=1.2.3')\n}\n\nRule 'MinimumVersionWithPrerelease' {\n $Assert.Version($TargetObject, 'version', '>=1.2.3-0', $True)\n}\n\nRule 'MinimumVersionWithFlag' {\n $Assert.Version($TargetObject, 'version', '@pre >=1.2.3-0')\n}\nThe
WithinPathassertion method checks if the file path is within a required path. Checks use file system case-sensitivity rules by default.The following parameters are accepted:
Reasons include:
Examples:
","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Assert/#advanced-usage","title":"Advanced usage","text":"Rule 'WithinPath' {\n # Require the file to be within either policy/ or security/ sub-directories.\n $Assert.WithinPath($TargetObject, 'FullName', @('policy/', 'security/'));\n}\nThe
AssertResultobject returned from assertion methods:The following properties are available:
The following methods are available:
Use of
Completeis optional, uncompleted results are automatically completed after the rule has executed. Uncompleted results may return reasons out of sequence.Using these advanced methods is not supported in rule script pre-conditions.
In this example,
Completeis used to find the first field with an empty value.Rule 'Assert.HasFieldValue' {\n $Assert.HasFieldValue($TargetObject, 'Name').Complete() -and\n $Assert.HasFieldValue($TargetObject, 'Type').Complete() -and\n $Assert.HasFieldValue($TargetObject, 'Value').Complete()\n}\nIn this example, the built-in reason is replaced with a custom reason, and immediately returned. The reason text is automatically formatted with any parameters provided.
Rule 'Assert.HasCustomValue' {\n $Assert.\n HasDefaultValue($TargetObject, 'value', 'test').\n Reason('The field {0} is using a non-default value: {1}', 'value', $TargetObject.value)\n\n # With localized string\n $Assert.\n HasDefaultValue($TargetObject, 'value', 'test').\n Reason($LocalizedData.NonDefaultValue, 'value', $TargetObject.value)\n}\nIn this example, the built-in reason has a path prefix added to any reasons.
","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Assert/#downstream-issues","title":"Downstream issues","text":"Rule 'Assert.ChildHasFieldValue' {\n $items = @($TargetObject.items)\n for ($i = 0; $i -lt $items.Length; $i++) {\n $Assert.HasFieldValue($items[$i], 'Name').PathPrefix(\"items[$i]\")\n }\n}\nBefore PSRule performs analysis external tools or rules modules may have already performed analysis. Issues identified by downstream tools can be consumed by PSRule using the
_PSRule.issueproperty. If a_PSRuleproperty exists withissuesub-property PSRule will consumeissueas an array of issues.Each issue has the following properties:
To get issues for an object use the
GetorAnymethods.# Get an array of all issues for the current object.\n$PSRule.Issue.Get();\n\n# Get an array of issues of a specific type.\n$PSRule.Issue.Get('CustomIssue');\n\n# Return true of any issues exist.\n$PSRule.Issue.Any();\n\n# Return true of any issues of a specific type exist.\n$PSRule.Issue.Any('CustomIssue');\nFor example:
","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Assert/#authoring-assertion-methods","title":"Authoring assertion methods","text":"# Synopsis: Fail if the object has any 'PSRule.Rules.Azure.Parameter.Insecure' issues.\nRule 'IssueReportTest' {\n $Assert.Create($PSRule.Issue.Get('PSRule.Rules.Azure.Parameter.Insecure'));\n}\nThe following built-in helper methods are provided for working with
$Assertwhen authoring new assertion methods:The following built-in helper methods are provided for aggregating assertion results:
For example:
","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Assert/#links","title":"Links","text":"Rule 'Assert.HasFieldValue' {\n $Assert.AllOf(\n $Assert.HasFieldValue($TargetObject, 'Name'),\n $Assert.HasFieldValue($TargetObject, 'Type'),\n $Assert.HasFieldValue($TargetObject, 'Value')\n )\n}\nDescribes using the badge API with PSRule.
"},{"location":"concepts/PSRule/en-US/about_PSRule_Badges/#description","title":"Description","text":"PSRule executes rules to validate an object from input. When processing input it may be necessary to perform custom actions before or after rules execute. Conventions provide an extensibility point that can be shipped with or external to standard rules. The badge API can be used to create badges within a convention.
"},{"location":"concepts/PSRule/en-US/about_PSRule_Badges/#using-the-api","title":"Using the API","text":"PSRule provides the
$PSRulebuilt-in variable that exposes the badge API. By using the$PSRule.Badges.Createmethod you can create a standard or custom badge.The create method provides the following overloads:
// Create a badge for the worst case of an analyzed object.\nIBadge Create(InvokeResult result);\n\n// Create a badge for the worst case of all analyzed objects.\nIBadge Create(IEnumerable<InvokeResult> result);\n\n// Create a custom badge.\nIBadge Create(string title, BadgeType type, string label);\nA badge once created can be read as a string or written to disk with the following methods:
"},{"location":"concepts/PSRule/en-US/about_PSRule_Badges/#defining-conventions","title":"Defining conventions","text":"// Get the badge as SVG text content.\nstring ToSvg();\n\n// Write the SVG badge content directly to disk.\nvoid ToFile(string path);\nTo define a convention, add a
Export-PSRuleConventionblock within a.Rule.ps1file. The.Rule.ps1must be in an included path or module with-Pathor-Module.The
Export-PSRuleConventionblock works similar to theRuleblock. Each convention must have a unique name. Currently the badge API support creating badges in the-Endblock.For example:
# Synopsis: A convention that generates a badge for an aggregate result.\nExport-PSRuleConvention 'Local.Aggregate' -End {\n $PSRule.Badges.Create($PSRule.Output).ToFile('out/badges/aggregate.svg');\n}\n
"},{"location":"concepts/PSRule/en-US/about_PSRule_Badges/#using-conventions","title":"Using conventions","text":"# Synopsis: A convention that generates a custom badge.\nExport-PSRuleConvention 'Local.CustomBadge' -End {\n $PSRule.Badges.Create('PSRule', [PSRule.Badges.BadgeType]::Success, 'OK').ToFile('out/badges/custom.svg');\n}\nA convention can be included by using the
-Conventionparameter when executing a PSRule cmdlet. Alternatively, conventions can be included with options. To use a convention specify the name of the convention by name. For example:
"},{"location":"concepts/PSRule/en-US/about_PSRule_Badges/#links","title":"Links","text":"Invoke-PSRule -Convention 'Local.Aggregate';\nDescribes usage of baselines within PSRule.
"},{"location":"concepts/PSRule/en-US/about_PSRule_Baseline/#description","title":"Description","text":"PSRule lets you define a baseline. A baseline includes a set of rule and configuration options that are used for evaluating objects.
The following baseline options can be configured:
Baseline options can be:
YAML baseline specs are saved within a YAML file with a
.Rule.yamlor.Rule.ymlextension, for exampleBaseline.Rule.yaml.JSON baseline specs are saved within a file with a
.Rule.jsonor.Rule.jsoncextension, for exampleBaseline.Rule.json. Use.jsoncto view JSON with Comments in Visual Studio Code.To define a YAML baseline spec use the following structure:
---\n# Synopsis: <synopsis>\napiVersion: github.com/microsoft/PSRule/v1\nkind: Baseline\nmetadata:\n name: <name>\n annotations: { }\nspec:\n # One or more baseline options\n binding: { }\n rule: { }\n configuration: { }\nFor example:
---\n# Synopsis: This is an example baseline\napiVersion: github.com/microsoft/PSRule/v1\nkind: Baseline\nmetadata:\n name: Baseline1\nspec:\n binding:\n field:\n id:\n - ResourceId\n targetName:\n - Name\n - ResourceName\n - ResourceGroupName\n targetType:\n - ResourceType\n rule:\n include:\n - Rule1\n - Rule2\n configuration:\n allowedLocations:\n - 'Australia East'\n - 'Australia South East'\n\n---\n# Synopsis: This is an example baseline\napiVersion: github.com/microsoft/PSRule/v1\nkind: Baseline\nmetadata:\n name: Baseline2\nspec:\n binding:\n targetName:\n - Name\n - ResourceName\n - ResourceGroupName\n targetType:\n - ResourceType\n rule:\n include:\n - Rule1\n - Rule3\n configuration:\n allowedLocations:\n - 'Australia East'\nTo define a JSON baseline spec use the following structure:
[\n {\n // Synopsis: <synopsis>\n \"apiVersion\": \"github.com/microsoft/PSRule/v1\",\n \"kind\": \"Baseline\",\n \"metadata\": {\n \"name\": \"<name>\",\n \"annotations\": {}\n },\n \"spec\": {\n \"binding\": {},\n \"rule\": {},\n \"configuration\": {}\n }\n }\n]\nFor example:
"},{"location":"concepts/PSRule/en-US/about_PSRule_Baseline/#baseline-scopes","title":"Baseline scopes","text":"[\n {\n // Synopsis: This is an example baseline\n \"apiVersion\": \"github.com/microsoft/PSRule/v1\",\n \"kind\": \"Baseline\",\n \"metadata\": {\n \"name\": \"Baseline1\"\n },\n \"spec\": {\n \"binding\": {\n \"field\": {\n \"id\": [\n \"ResourceId\"\n ]\n },\n \"targetName\": [\n \"Name\",\n \"ResourceName\",\n \"ResourceGroupName\"\n ],\n \"targetType\": [\n \"ResourceType\"\n ]\n },\n \"rule\": {\n \"include\": [\n \"Rule1\",\n \"Rule2\"\n ]\n },\n \"configuration\": {\n \"allowedLocations\": [\n \"Australia East\",\n \"Australia South East\"\n ]\n }\n }\n },\n {\n // Synopsis: This is an example baseline\n \"apiVersion\": \"github.com/microsoft/PSRule/v1\",\n \"kind\": \"Baseline\",\n \"metadata\": {\n \"name\": \"Baseline2\"\n },\n \"spec\": {\n \"binding\": {\n \"targetName\": [\n \"Name\",\n \"ResourceName\",\n \"ResourceGroupName\"\n ],\n \"targetType\": [\n \"ResourceType\"\n ]\n },\n \"rule\": {\n \"include\": [\n \"Rule1\",\n \"Rule3\"\n ]\n },\n \"configuration\": {\n \"allowedLocations\": [\n \"Australia East\"\n ]\n }\n }\n }\n]\nWhen baseline options are set, PSRule uses the following order to determine precedence.
After precedence is determined, baselines are merged and null values are ignored, such that:
"},{"location":"concepts/PSRule/en-US/about_PSRule_Baseline/#annotations","title":"Annotations","text":"Additional baseline annotations can be provided as key/ value pairs. Annotations can be used to provide additional information that is available in
Get-PSRuleBaselineoutput.The following reserved annotation exists:
YAML example:
---\n# Synopsis: This is an example baseline that is obsolete\napiVersion: github.com/microsoft/PSRule/v1\nkind: Baseline\nmetadata:\n name: ObsoleteBaseline\n annotations:\n obsolete: true\nspec: { }\nJSON example:
"},{"location":"concepts/PSRule/en-US/about_PSRule_Baseline/#examples","title":"Examples","text":""},{"location":"concepts/PSRule/en-US/about_PSRule_Baseline/#example-baselineruleyaml","title":"Example Baseline.Rule.yaml","text":"[\n {\n // Synopsis: This is an example baseline that is obsolete\n \"apiVersion\": \"github.com/microsoft/PSRule/v1\",\n \"kind\": \"Baseline\",\n \"metadata\": {\n \"name\": \"ObsoleteBaseline\",\n \"annotations\": {\n \"obsolete\": true\n }\n },\n \"spec\": {}\n }\n]\n
"},{"location":"concepts/PSRule/en-US/about_PSRule_Baseline/#example-baselinerulejson","title":"Example Baseline.Rule.json","text":"# Example Baseline.Rule.yaml\n\n---\n# Synopsis: This is an example baseline\napiVersion: github.com/microsoft/PSRule/v1\nkind: Baseline\nmetadata:\n name: TestBaseline1\nspec:\n binding:\n targetName:\n - AlternateName\n targetType:\n - kind\n rule:\n include:\n - 'WithBaseline'\n configuration:\n key1: value1\n\n---\n# Synopsis: This is an example baseline\napiVersion: github.com/microsoft/PSRule/v1\nkind: Baseline\nmetadata:\n name: TestBaseline2\nspec:\n binding:\n targetName:\n - AlternateName\n targetType:\n - kind\n rule:\n include:\n - 'WithBaseline'\n configuration:\n key1: value1\n
"},{"location":"concepts/PSRule/en-US/about_PSRule_Conventions/","title":"Conventions","text":"// Example Baseline.Rule.json\n\n[\n {\n // Synopsis: This is an example baseline\n \"apiVersion\": \"github.com/microsoft/PSRule/v1\",\n \"kind\": \"Baseline\",\n \"metadata\": {\n \"name\": \"TestBaseline1\"\n },\n \"spec\": {\n \"binding\": {\n \"targetName\": [\n \"AlternateName\"\n ],\n \"targetType\": [\n \"kind\"\n ]\n },\n \"rule\": {\n \"include\": [\n \"WithBaseline\"\n ]\n },\n \"configuration\": {\n \"key1\": \"value1\"\n }\n }\n },\n {\n // Synopsis: This is an example baseline\n \"apiVersion\": \"github.com/microsoft/PSRule/v1\",\n \"kind\": \"Baseline\",\n \"metadata\": {\n \"name\": \"TestBaseline2\"\n },\n \"spec\": {\n \"binding\": {\n \"targetName\": [\n \"AlternateName\"\n ],\n \"targetType\": [\n \"kind\"\n ]\n },\n \"rule\": {\n \"include\": [\n \"WithBaseline\"\n ]\n },\n \"configuration\": {\n \"key1\": \"value1\"\n }\n }\n }\n]\nDescribes PSRule Conventions including how to use and author them.
"},{"location":"concepts/PSRule/en-US/about_PSRule_Conventions/#description","title":"Description","text":"PSRule executes rules to validate an object from input. When processing input it may be necessary to perform custom actions before or after rules execute. Conventions provide an extensibility point that can be shipped with or external to standard rules. Each convention, hooks into one or more places within the pipeline.
"},{"location":"concepts/PSRule/en-US/about_PSRule_Conventions/#using-conventions","title":"Using conventions","text":"A convention can be included by using the
-Conventionparameter when executing a PSRule cmdlet. Alternatively, conventions can be included with options. To use a convention specify the name of the convention by name. For example:Invoke-PSRule -Convention 'ExampleConvention';\nIf multiple conventions are specified in an array, all are executed in they are specified. As a result, the convention specified last may override state set by earlier conventions.
"},{"location":"concepts/PSRule/en-US/about_PSRule_Conventions/#defining-conventions","title":"Defining conventions","text":"Assert-PSRule -Convention 'ExampleConvention1', 'ExampleConvention2';\nTo define a convention, add a
Export-PSRuleConventionblock within a.Rule.ps1file. The.Rule.ps1must be in an included path or module with-Pathor-Module.The
Export-PSRuleConventionblock works similar to theRuleblock. Each convention must have a unique name. For example:
"},{"location":"concepts/PSRule/en-US/about_PSRule_Conventions/#initialize-begin-process-end-blocks","title":"Initialize Begin Process End blocks","text":"# Synopsis: An example convention.\nExport-PSRuleConvention 'ExampleConvention' {\n # Add code here\n}\nConventions define four executable blocks
Initialize,Begin,Process,Endsimilar to a PowerShell function. Each block is injected in a different part of the pipeline as follows:Convention block limitations:
By default, the
Processblock used. For example:# Synopsis: The default { } executes the process block\nExport-PSRuleConvention 'ExampleConvention' {\n # Process block\n}\n\n# Synopsis: With optional -Process parameter name\nExport-PSRuleConvention 'ExampleConvention' -Process {\n # Process block\n}\nTo use
Initialize,Begin, orEndexplicitly add these blocks. For example:
"},{"location":"concepts/PSRule/en-US/about_PSRule_Conventions/#including-with-options","title":"Including with options","text":"Export-PSRuleConvention 'ExampleConvention' -Process {\n # Process block\n} -Begin {\n # Begin block\n} -End {\n # End block\n} -Initialize {\n # Initialize block\n}\nConventions can be included by name within options in addition to using the
ps-rule.yaml-Conventionparameter. To specify a convention within YAML options use the following:
"},{"location":"concepts/PSRule/en-US/about_PSRule_Conventions/#using-within-modules","title":"Using within modules","text":"convention:\n include:\n - 'ExampleConvention1'\n - 'ExampleConvention2'\nConventions can be shipped within a module using the same packaging and distribution process as rules. Additionally, conventions shipped within a module can be automatically included. By default, PSRule does not include conventions shipped within a module. To use a convention included in a module use the
-Conventionparameter or options configuration.A module can automatically include a convention by specifying the convention by name in module configuration. For example:
Config.Rule.yaml
"},{"location":"concepts/PSRule/en-US/about_PSRule_Conventions/#execution-order","title":"Execution order","text":"---\napiVersion: github.com/microsoft/PSRule/v1\nkind: ModuleConfig\nmetadata:\n name: ExampleModule\nspec:\n convention:\n include:\n - 'ExampleConvention1'\n - 'ExampleConvention2'\nConventions are executed in the order they are specified. This is true for
Initialize,Begin,Process, andEndblocks. i.e. In the following exampleExampleConvention1is execute beforeExampleConvention2.Assert-PSRule -Convention 'ExampleConvention1', 'ExampleConvention2';\nWhen conventions are specified from multiple locations PSRule orders conventions as follows:
Describes usage of documentation within PSRule.
"},{"location":"concepts/PSRule/en-US/about_PSRule_Docs/#description","title":"Description","text":"PSRule includes a built-in documentation system that provide culture specific help and metadata for resources. Documentation is composed of markdown files that can be optionally shipped with a module.
When markdown documentation is defined, this content will be used instead of inline synopsis comments. Markdown documentation is supported for rules and suppression groups.
"},{"location":"concepts/PSRule/en-US/about_PSRule_Docs/#getting-documentation","title":"Getting documentation","text":"To get documentation for a rule use the
Get-PSRuleHelpcmdlet.For example:
Get-PSRuleHelp <rule-name>\nEach rule can include the following documentation:
See cmdlet help for detailed information on the
"},{"location":"concepts/PSRule/en-US/about_PSRule_Docs/#online-help","title":"Online help","text":"Get-PSRuleHelpcmdlet.Rule documentation may optionally include a link to an online version. When included, the
-Onlineparameter can be used to open the online version in the default web browser.For example:
"},{"location":"concepts/PSRule/en-US/about_PSRule_Docs/#creating-documentation-for-rules","title":"Creating documentation for rules","text":"Get-PSRuleHelp <rule-name> -Online\nRule documentation is composed of markdown files, one per rule. When creating rules for more then one culture, a separate markdown file is created per rule per culture.
The markdown files for each rule is automatically discovered based on naming convention.
Markdown is saved in a file with the same filename as the rule name with the
.mdextension. The file name should match the same case exactly, with a lower case extension.As an example, the
storageAccounts.UseHttps.mdmarkdown file would be created.# Synopsis: Configure storage accounts to only accept encrypted traffic i.e. HTTPS/SMB\nRule 'storageAccounts.UseHttps' -If { ResourceType 'Microsoft.Storage/storageAccounts' } {\n Recommend 'Storage accounts should only allow secure traffic'\n\n $TargetObject.Properties.supportsHttpsTrafficOnly\n}\nThe markdown of each file uses following structure.
---\n{{ Annotations }}\n---\n\n# {{ Name of rule }}\n\n\n\n{{ A brief summary of the rule }}\n\n## Description\n\n{{ A detailed description of the rule }}\n\n## Recommendation\n\n{{ A detailed explanation of the steps required to pass the rule }}\n\n## Notes\n\n{{ Additional information or configuration options }}\n\n## Links\n\n{{ Links to external references }}\nOptionally, one or more annotations formatted as YAML key value pairs can be included. i.e.
severity: CriticalAdditional sections such as
"},{"location":"concepts/PSRule/en-US/about_PSRule_Docs/#creating-documentation-for-suppression-groups","title":"Creating documentation for suppression groups","text":"EXAMPLEScan be included although are not exposed withGet-PSRuleHelp.Suppression groups support documentation similar to rules that allows a synopsis to be defined. Other sections can be added to the markdown content, but are ignored. Set the synopsis in markdown to allow a culture specific message to be displayed.
The markdown of each file uses following structure.
"},{"location":"concepts/PSRule/en-US/about_PSRule_Docs/#storing-markdown-files","title":"Storing markdown files","text":"---\n{{ Annotations }}\n---\n\n# {{ Name of suppression group }}\n\n\n\n{{ A brief summary of the suppression group }}\nThe location PSRule uses to find markdown documentation depends on how the rules/ resources are packaged. In each case, documentation will be in a culture
/<culture>/specific subdirectory. Resources can be either shipped as part of a module, or standalone.The
"},{"location":"concepts/PSRule/en-US/about_PSRule_Docs/#links","title":"Links","text":"<culture>subdirectory will be the current culture that PowerShell is executed under. To determine the current culture use(Get-Culture).Name. Alternatively, the culture can set by using the-Cultureparameter of PSRule cmdlets.Describes PSRule expressions and how to use them.
","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Expressions/#description","title":"Description","text":"PSRule expressions are used within YAML-based rules or selectors to evaluate an object. Expressions are comprised of nested conditions, operators, and comparison properties.
The following conditions are available:
The following operators are available:
The following comparison properties are available:
The
allOfoperator is used to require all nested expressions to match. When any nested expression does not match,allOfdoes not match. This is similar to a logical and operation.Additionally sub-selectors can be used to modify the
allOfoperator. Sub-selectors allow filtering and looping through arrays of objects before theallOfoperator is applied. See sub-selectors for more information.Syntax:
allOf: <expression[]>\nFor example:
","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Expressions/#anyof","title":"AnyOf","text":"---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Rule\nmetadata:\n name: 'ExampleAllOf'\nspec:\n condition:\n allOf:\n # Both Name and Description must exist.\n - field: 'Name'\n exists: true\n - field: 'Description'\n exists: true\n\n---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Selector\nmetadata:\n name: 'ExampleAllOf'\nspec:\n if:\n allOf:\n # Both Name and Description must exist.\n - field: 'Name'\n exists: true\n - field: 'Description'\n exists: true\nThe
anyOfoperator is used to require one or more nested expressions to match. When any nested expression matches,allOfmatches. This is similar to a logical or operation.Additionally sub-selectors can be used to modify the
anyOfoperator. Sub-selectors allow filtering and looping through arrays of objects before theanyOfoperator is applied. See sub-selectors for more information.Syntax:
anyOf: <expression[]>\nFor example:
","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Expressions/#apiversion","title":"APIVersion","text":"---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Rule\nmetadata:\n name: 'ExampleAnyOf'\nspec:\n condition:\n anyOf:\n # Name and/ or AlternativeName must exist.\n - field: 'Name'\n exists: true\n - field: 'AlternativeName'\n exists: true\n\n---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Selector\nmetadata:\n name: 'ExampleAnyOf'\nspec:\n if:\n anyOf:\n # Name and/ or AlternativeName must exist.\n - field: 'Name'\n exists: true\n - field: 'AlternativeName'\n exists: true\nThe
apiVersioncondition determines if the operand is a valid date version. A constraint can optionally be provided to require the date version to be within a range. Supported version constraints for expression are the same as the$Assert.APIVersionassertion helper.Syntax:
apiVersion: <string>\nincludePrerelease: <bool>\nFor example:
","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Expressions/#contains","title":"Contains","text":"---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Rule\nmetadata:\n name: 'ExampleAPIVersion'\nspec:\n condition:\n field: 'engine.apiVersion'\n apiVersion: '>=2015-10-01'\n\n---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Selector\nmetadata:\n name: 'ExampleAnyAPIVersion'\nspec:\n if:\n field: 'engine.apiVersion'\n apiVersion: ''\n\n---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Selector\nmetadata:\n name: 'ExampleAPIVersionIncludingPrerelease'\nspec:\n if:\n field: 'engine.apiVersion'\n apiVersion: '>=2015-10-01'\n includePrerelease: true\nThe
containscondition can be used to determine if the operand contains a specified sub-string. One or more strings to compare can be specified.Syntax:
contains: <string | array>\ncaseSensitive: <boolean>\nconvert: <boolean>\nFor example:
","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Expressions/#count","title":"Count","text":"---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Rule\nmetadata:\n name: 'ExampleContains'\nspec:\n condition:\n anyOf:\n - field: 'url'\n contains: '/azure/'\n - field: 'url'\n contains:\n - 'github.io'\n - 'github.com'\n\n---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Selector\nmetadata:\n name: 'ExampleContains'\nspec:\n if:\n anyOf:\n - field: 'url'\n contains: '/azure/'\n - field: 'url'\n contains:\n - 'github.io'\n - 'github.com'\nThe
countcondition is used to determine if the operand contains a specified number of items.Syntax:
count: <int>\nFor example:
","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Expressions/#equals","title":"Equals","text":"---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Rule\nmetadata:\n name: 'ExampleCount'\nspec:\n condition:\n field: 'items'\n count: 2\n\n---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Selector\nmetadata:\n name: 'ExampleCount'\nspec:\n if:\n field: 'items'\n count: 2\nThe
equalscondition can be used to compare if the operand is equal to a supplied value.Syntax:
equals: <string | int | bool>\ncaseSensitive: <boolean>\nconvert: <boolean>\nFor example:
","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Expressions/#endswith","title":"EndsWith","text":"---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Rule\nmetadata:\n name: 'ExampleEquals'\nspec:\n condition:\n field: 'Name'\n equals: 'TargetObject1'\n\n---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Selector\nmetadata:\n name: 'ExampleEquals'\nspec:\n if:\n field: 'Name'\n equals: 'TargetObject1'\nThe
endsWithcondition can be used to determine if the operand ends with a specified string. One or more strings to compare can be specified.Syntax:
endsWith: <string | array>\ncaseSensitive: <boolean>\nconvert: <boolean>\nFor example:
","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Expressions/#exists","title":"Exists","text":"---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Rule\nmetadata:\n name: 'ExampleEndsWith'\nspec:\n condition:\n anyOf:\n - field: 'hostname'\n endsWith: '.com'\n - field: 'hostname'\n endsWith:\n - '.com.au'\n - '.com'\n\n---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Selector\nmetadata:\n name: 'ExampleEndsWith'\nspec:\n if:\n anyOf:\n - field: 'hostname'\n endsWith: '.com'\n - field: 'hostname'\n endsWith:\n - '.com.au'\n - '.com'\nThe
existscondition determines if the specified field exists.Syntax:
exists: <bool>\nFor example:
","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Expressions/#field","title":"Field","text":"---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Rule\nmetadata:\n name: 'ExampleExists'\nspec:\n condition:\n field: 'Name'\n exists: true\n\n---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Selector\nmetadata:\n name: 'ExampleExists'\nspec:\n if:\n field: 'Name'\n exists: true\nThe comparison property
fieldis used with a condition to determine field of the object to evaluate. A field can be:Syntax:
field: <string>\nFor example:
","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Expressions/#greater","title":"Greater","text":"---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Rule\nmetadata:\n name: 'ExampleField'\nspec:\n condition:\n field: 'Properties.securityRules[0].name'\n exists: true\n\n---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Selector\nmetadata:\n name: 'ExampleField'\nspec:\n if:\n field: 'Properties.securityRules[0].name'\n exists: true\nThe
greatercondition determines if the operand is greater than a supplied value. The field value can either be an integer, float, array, or string.When the field value is:
Syntax:
greater: <int>\nconvert: <boolean>\nFor example:
","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Expressions/#greaterorequals","title":"GreaterOrEquals","text":"---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Rule\nmetadata:\n name: 'ExampleGreater'\nspec:\n condition:\n field: 'Name'\n greater: 3\n\n---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Selector\nmetadata:\n name: 'ExampleGreater'\nspec:\n if:\n field: 'Name'\n greater: 3\nThe
greaterOrEqualscondition determines if the operand is greater or equal to the supplied value. The field value can either be an integer, float, array, or string.When the field value is:
Syntax:
greaterOrEquals: <int>\nconvert: <boolean>\nFor example:
","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Expressions/#hasdefault","title":"HasDefault","text":"---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Rule\nmetadata:\n name: 'ExampleGreaterOrEquals'\nspec:\n condition:\n field: 'Name'\n greaterOrEquals: 3\n\n---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Selector\nmetadata:\n name: 'ExampleGreaterOrEquals'\nspec:\n if:\n field: 'Name'\n greaterOrEquals: 3\nThe
hasDefaultcondition determines if the field exists that it is set to the specified value. If the field does not exist, the condition will returntrue.The following properties are accepted:
Syntax:
hasDefault: <string | int | bool>\ncaseSensitive: <bool>\nFor example:
","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Expressions/#hasschema","title":"HasSchema","text":"---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Rule\nmetadata:\n name: 'ExampleHasDefault'\nspec:\n condition:\n field: 'enabled'\n hasDefault: true\n\n---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Selector\nmetadata:\n name: 'ExampleHasDefault'\nspec:\n if:\n field: 'enabled'\n hasDefault: true\nThe
hasSchemacondition determines if the operand has a$schemaproperty defined. If the$schemaproperty is defined, it must match one of the specified schemas. If a trailing#is specified it is ignored.The following properties are accepted:
Syntax:
hasSchema: <array>\ncaseSensitive: <bool>\nignoreScheme: <bool>\nFor example:
","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Expressions/#hasvalue","title":"HasValue","text":"---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Rule\nmetadata:\n name: 'ExampleHasSchema'\nspec:\n condition:\n field: '.'\n hasSchema:\n - https://schema.management.azure.com/schemas/2019-04-01/deploymentParameters.json#\n\n---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Selector\nmetadata:\n name: 'ExampleHasSchema'\nspec:\n if:\n field: '.'\n hasSchema:\n - https://schema.management.azure.com/schemas/2019-04-01/deploymentParameters.json#\n - https://schema.management.azure.com/schemas/2015-01-01/deploymentParameters.json#\n ignoreScheme: true\n\n---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Selector\nmetadata:\n name: 'ExampleHasAnySchema'\nspec:\n if:\n field: '.'\n hasSchema: []\nThe
hasValuecondition determines if the field exists and has a non-empty value.Syntax:
hasValue: <bool>\nFor example:
","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Expressions/#in","title":"In","text":"---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Rule\nmetadata:\n name: 'ExampleHasValue'\nspec:\n condition:\n field: 'Name'\n hasValue: true\n\n---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Selector\nmetadata:\n name: 'ExampleHasValue'\nspec:\n if:\n field: 'Name'\n hasValue: true\nThe
incondition can be used to compare if a field contains one of the specified values.Syntax:
in: <array>\nFor example:
","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Expressions/#islower","title":"IsLower","text":"---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Rule\nmetadata:\n name: 'ExampleIn'\nspec:\n condition:\n field: 'Name'\n in:\n - 'Value1'\n - 'Value2'\n\n---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Selector\nmetadata:\n name: 'ExampleIn'\nspec:\n if:\n field: 'Name'\n in:\n - 'Value1'\n - 'Value2'\nThe
isLowercondition determines if the operand is a lowercase string.Syntax:
isLower: <bool>\nFor example:
","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Expressions/#isstring","title":"IsString","text":"---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Rule\nmetadata:\n name: 'ExampleIsLower'\nspec:\n condition:\n field: 'Name'\n isLower: true\n\n---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Selector\nmetadata:\n name: 'ExampleIsLower'\nspec:\n if:\n field: 'Name'\n isLower: true\nThe
isStringcondition determines if the operand is a string or other type.Syntax:
isString: <bool>\nFor example:
","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Expressions/#isarray","title":"IsArray","text":"---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Rule\nmetadata:\n name: 'ExampleIsString'\nspec:\n condition:\n field: 'Name'\n isString: true\n\n---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Selector\nmetadata:\n name: 'ExampleIsString'\nspec:\n if:\n field: 'Name'\n isString: true\nThe
isArraycondition determines if the operand is an array or other type.Syntax:
isArray: <bool>\nFor example:
","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Expressions/#isboolean","title":"IsBoolean","text":"---\n# Synopsis: Using isArray\napiVersion: github.com/microsoft/PSRule/v1\nkind: Selector\nmetadata:\n name: IsArrayExample\nspec:\n if:\n field: 'Value'\n isArray: true\nThe
isBooleancondition determines if the operand is a boolean or other type.isBoolean: <bool>\nconvert: <bool>\nFor example:
","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Expressions/#isdatetime","title":"IsDateTime","text":"---\n# Synopsis: Using isBoolean\napiVersion: github.com/microsoft/PSRule/v1\nkind: Selector\nmetadata:\n name: IsBooleanExample\nspec:\n if:\n field: 'Value'\n isBoolean: true\n\n---\n# Synopsis: Using isBoolean with conversion\napiVersion: github.com/microsoft/PSRule/v1\nkind: Selector\nmetadata:\n name: IsBooleanExampleWithConversion\nspec:\n if:\n field: 'Value'\n isBoolean: true\n convert: true\nThe
isDateTimecondition determines if the operand is a datetime or other type.isDateTime: <bool>\nconvert: <bool>\nFor example:
","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Expressions/#isinteger","title":"IsInteger","text":"---\n# Synopsis: Using isDateTime\napiVersion: github.com/microsoft/PSRule/v1\nkind: Selector\nmetadata:\n name: IsDateTimeExample\nspec:\n if:\n field: 'Value'\n isDateTime: true\n\n---\n# Synopsis: Using isDateTime with conversion\napiVersion: github.com/microsoft/PSRule/v1\nkind: Selector\nmetadata:\n name: IsDateTimeExampleWithConversion\nspec:\n if:\n field: 'Value'\n isDateTime: true\n convert: true\nThe
isIntegercondition determines if the operand is a an integer or other type. The following types are considered integer typesint,long,byte.isInteger: <bool>\nconvert: <bool>\nFor example:
","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Expressions/#isnumeric","title":"IsNumeric","text":"---\n# Synopsis: Using isInteger\napiVersion: github.com/microsoft/PSRule/v1\nkind: Selector\nmetadata:\n name: IsIntegerExample\nspec:\n if:\n field: 'Value'\n isInteger: true\n\n---\n# Synopsis: Using isInteger with conversion\napiVersion: github.com/microsoft/PSRule/v1\nkind: Selector\nmetadata:\n name: IsIntegerExampleWithConversion\nspec:\n if:\n field: 'Value'\n isInteger: true\n convert: true\nThe
isNumericcondition determines if the operand is a a numeric or other type. The following types are considered numeric typesint,long,float,byte,double.isNumeric: <bool>\nconvert: <bool>\nFor example:
","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Expressions/#isupper","title":"IsUpper","text":"---\n# Synopsis: Using isNumeric\napiVersion: github.com/microsoft/PSRule/v1\nkind: Selector\nmetadata:\n name: IsNumericExample\nspec:\n if:\n field: 'Value'\n isNumeric: true\n\n---\n# Synopsis: Using isNumeric with conversion\napiVersion: github.com/microsoft/PSRule/v1\nkind: Selector\nmetadata:\n name: IsNumercExampleWithConversion\nspec:\n if:\n field: 'Value'\n isNumeric: true\n convert: true\nThe
isUppercondition determines if the operand is an uppercase string.Syntax:
isUpper: <bool>\nFor example:
","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Expressions/#less","title":"Less","text":"---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Rule\nmetadata:\n name: 'ExampleIsUpper'\nspec:\n condition:\n field: 'Name'\n isUpper: true\n\n---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Selector\nmetadata:\n name: 'ExampleIsUpper'\nspec:\n if:\n field: 'Name'\n isUpper: true\nThe
lesscondition determines if the operand is less than a supplied value. The field value can either be an integer, float, array, or string.When the field value is:
Syntax:
less: <int>\nconvert: <boolean>\nFor example:
","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Expressions/#lessorequals","title":"LessOrEquals","text":"---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Rule\nmetadata:\n name: 'ExampleLess'\nspec:\n condition:\n field: 'Name'\n less: 3\n\n---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Selector\nmetadata:\n name: 'ExampleLess'\nspec:\n if:\n field: 'Name'\n less: 3\nThe
lessOrEqualscondition determines if the operand is less or equal to the supplied value. The field value can either be an integer, float, array, or string.When the field value is:
Syntax:
lessOrEquals: <int>\nconvert: <boolean>\nFor example:
","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Expressions/#like","title":"Like","text":"---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Rule\nmetadata:\n name: 'ExampleLessOrEquals'\nspec:\n condition:\n field: 'Name'\n lessOrEquals: 3\n\n---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Selector\nmetadata:\n name: 'ExampleLessOrEquals'\nspec:\n if:\n field: 'Name'\n lessOrEquals: 3\nThe
likecondition can be used to determine if the operand matches a wildcard pattern. One or more patterns to compare can be specified.Syntax:
like: <string | array>\ncaseSensitive: <boolean>\nconvert: <boolean>\nFor example:
","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Expressions/#match","title":"Match","text":"---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Rule\nmetadata:\n name: 'ExampleLike'\nspec:\n condition:\n anyOf:\n - field: 'url'\n like: 'http://*'\n - field: 'url'\n like:\n - 'http://*'\n - 'https://*'\n\n---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Selector\nmetadata:\n name: 'ExampleLike'\nspec:\n if:\n anyOf:\n - field: 'url'\n like: 'http://*'\n - field: 'url'\n like:\n - 'http://*'\n - 'https://*'\nThe
matchcondition can be used to compare if a field matches a supplied regular expression.Syntax:
match: <string>\ncaseSensitive: <boolean>\nFor example:
","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Expressions/#name","title":"Name","text":"---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Rule\nmetadata:\n name: 'ExampleMatch'\nspec:\n condition:\n field: 'Name'\n match: '$(abc|efg)$'\n\n---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Selector\nmetadata:\n name: 'ExampleMatch'\nspec:\n if:\n field: 'Name'\n match: '$(abc|efg)$'\nThe comparison property
nameis used with a condition to evaluate the target name of the object. Thenameproperty must be set to.. Any other value will cause the condition to evaluate tofalse.Syntax:
name: '.'\nFor example:
","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Expressions/#not","title":"Not","text":"---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Rule\nmetadata:\n name: 'ExampleName'\nspec:\n condition:\n name: '.'\n equals: 'TargetObject1'\n\n---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Selector\nmetadata:\n name: 'ExampleName'\nspec:\n if:\n name: '.'\n in:\n - 'TargetObject1'\n - 'TargetObject2'\nThe
anyoperator is used to invert the result of the nested expression. When a nested expression matches,notdoes not match. When a nested expression does not match,notmatches.Syntax:
not: <expression>\nFor example:
","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Expressions/#notcontains","title":"NotContains","text":"---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Rule\nmetadata:\n name: 'ExampleNot'\nspec:\n condition:\n not:\n # The AlternativeName field must not exist.\n field: 'AlternativeName'\n exists: true\n\n---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Selector\nmetadata:\n name: 'ExampleNot'\nspec:\n if:\n not:\n # The AlternativeName field must not exist.\n field: 'AlternativeName'\n exists: true\nThe
notContainscondition can be used to determine if the operand contains a specified sub-string. This condition fails when any of the specified sub-strings are found in the operand. One or more strings to compare can be specified.Syntax:
notContains: <string | array>\ncaseSensitive: <boolean>\nconvert: <boolean>\nFor example:
","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Expressions/#notcount","title":"NotCount","text":"---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Rule\nmetadata:\n name: 'ExampleNotContains'\nspec:\n condition:\n anyOf:\n - field: 'url'\n notContains: '/azure/'\n - field: 'url'\n notContains:\n - 'github.io'\n - 'github.com'\n\n---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Selector\nmetadata:\n name: 'ExampleNotContains'\nspec:\n if:\n anyOf:\n - field: 'url'\n notContains: '/azure/'\n - field: 'url'\n notContains:\n - 'github.io'\n - 'github.com'\nThe
notCountcondition is used to determine if the operand does not contain a specified number of items.Syntax:
notCount: <int>\nFor example:
","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Expressions/#notendswith","title":"NotEndsWith","text":"---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Rule\nmetadata:\n name: 'ExampleNotCount'\nspec:\n condition:\n field: 'items'\n notCount: 2\n\n---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Selector\nmetadata:\n name: 'ExampleNotCount'\nspec:\n if:\n field: 'items'\n notCount: 2\nThe
notEndsWithcondition can be used to determine if the operand ends with a specified string. This condition fails when any of the specified sub-strings are found at the end of the operand. One or more strings to compare can be specified.Syntax:
notEndsWith: <string | array>\ncaseSensitive: <boolean>\nconvert: <boolean>\nFor example:
","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Expressions/#notequals","title":"NotEquals","text":"---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Rule\nmetadata:\n name: 'ExampleNotEndsWith'\nspec:\n condition:\n anyOf:\n - field: 'hostname'\n notEndsWith: '.com'\n - field: 'hostname'\n notEndsWith:\n - '.com.au'\n - '.com'\n\n---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Selector\nmetadata:\n name: 'ExampleNotEndsWith'\nspec:\n if:\n anyOf:\n - field: 'hostname'\n notEndsWith: '.com'\n - field: 'hostname'\n notEndsWith:\n - '.com.au'\n - '.com'\nThe
notEqualscondition can be used to compare if a field is equal to a supplied value.Syntax:
notEquals: <string | int | bool>\ncaseSensitive: <boolean>\nconvert: <boolean>\nFor example:
","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Expressions/#notin","title":"NotIn","text":"---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Rule\nmetadata:\n name: 'ExampleNotEquals'\nspec:\n condition:\n field: 'Name'\n notEquals: 'TargetObject1'\n\n---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Selector\nmetadata:\n name: 'ExampleNotEquals'\nspec:\n if:\n field: 'Name'\n notEquals: 'TargetObject1'\nThe
notIncondition can be used to compare if a field does not contains one of the specified values.Syntax:
notIn: <array>\nFor example:
","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Expressions/#notlike","title":"NotLike","text":"---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Rule\nmetadata:\n name: 'ExampleNotIn'\nspec:\n condition:\n field: 'Name'\n notIn:\n - 'Value1'\n - 'Value2'\n\n---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Selector\nmetadata:\n name: 'ExampleNotIn'\nspec:\n if:\n field: 'Name'\n notIn:\n - 'Value1'\n - 'Value2'\nThe
notLikecondition can be used to determine if the operand matches a wildcard pattern. This condition fails when any of the specified patterns match the operand. One or more patterns to compare can be specified.Syntax:
notLike: <string | array>\ncaseSensitive: <boolean>\nconvert: <boolean>\nFor example:
","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Expressions/#notmatch","title":"NotMatch","text":"---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Rule\nmetadata:\n name: 'ExampleNotLike'\nspec:\n condition:\n anyOf:\n - field: 'url'\n notLike: 'http://*'\n - field: 'url'\n notLike:\n - 'http://'\n - 'https://'\n\n---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Selector\nmetadata:\n name: 'ExampleNotLike'\nspec:\n if:\n anyOf:\n - field: 'url'\n notLike: 'http://*'\n - field: 'url'\n notLike:\n - 'http://'\n - 'https://'\nThe
notMatchcondition can be used to compare if a field does not matches a supplied regular expression.Syntax:
notMatch: <string>\ncaseSensitive: <boolean>\nFor example:
","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Expressions/#notstartswith","title":"NotStartsWith","text":"---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Rule\nmetadata:\n name: 'ExampleNotMatch'\nspec:\n condition:\n field: 'Name'\n notMatch: '$(abc|efg)$'\n\n---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Selector\nmetadata:\n name: 'ExampleNotMatch'\nspec:\n if:\n field: 'Name'\n notMatch: '$(abc|efg)$'\nThe
notStartsWithcondition can be used to determine if the operand starts with a specified string. This condition fails when any of the specified sub-strings are found at the start of the operand. One or more strings to compare can be specified.Syntax:
notStartsWith: <string | array>\ncaseSensitive: <boolean>\nconvert: <boolean>\nFor example:
","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Expressions/#notwithinpath","title":"NotWithinPath","text":"---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Rule\nmetadata:\n name: 'ExampleNotStartsWith'\nspec:\n condition:\n anyOf:\n - field: 'url'\n notStartsWith: 'http'\n - field: 'url'\n notStartsWith:\n - 'http://'\n - 'https://'\n\n---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Selector\nmetadata:\n name: 'ExampleNotStartsWith'\nspec:\n if:\n anyOf:\n - field: 'url'\n notStartsWith: 'http'\n - field: 'url'\n notStartsWith:\n - 'http://'\n - 'https://'\nThe
notWithinPathcondition determines if a file path is not within a required path.If the path is not within the required path, the condition will return
true. If the path is within the required path, the condition will returnfalse.The following properties are accepted:
Syntax:
notWithinPath: <array>\ncaseSensitive: <boolean>\nFor example:
","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Expressions/#scope","title":"Scope","text":"---\n# Synopsis: Test notWithinPath with source\napiVersion: github.com/microsoft/PSRule/v1\nkind: Selector\nmetadata:\n name: YamlSourceNotWithinPath\nspec:\n if:\n source: 'Template'\n notWithinPath:\n - \"deployments/path/\"\n\n---\n# Synopsis: Test notWithinPath with source and case sensitive\napiVersion: github.com/microsoft/PSRule/v1\nkind: Selector\nmetadata:\n name: YamlSourceNotWithinPathCaseSensitive\nspec:\n if:\n source: 'Template'\n notWithinPath:\n - \"Deployments/Path/\"\n caseSensitive: true\nThe comparison property
scopeis used with a condition to evaluate any scopes assigned to the object. Thescopeproperty must be set to.. Any other value will cause the condition to evaluate tofalse.Syntax:
scope: '.'\nFor example:
","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Expressions/#setof","title":"SetOf","text":"---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Rule\nmetadata:\n name: 'ExampleScope'\nspec:\n condition:\n scope: '.'\n startsWith: '/'\n\n---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Selector\nmetadata:\n name: 'ExampleScope'\nspec:\n if:\n scope: '.'\n startsWith: '/'\nThe
setOfcondition can be used to determine if the operand is a set of specified values. Additionally the following properties are accepted:Syntax:
setOf: <array>\ncaseSensitive: <bool>\nFor example:
","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Expressions/#source","title":"Source","text":"---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Rule\nmetadata:\n name: 'ExampleSetOf'\nspec:\n condition:\n field: 'zones'\n setOf:\n - 1\n - 2\n - 3\n caseSensitive: false\n\n---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Selector\nmetadata:\n name: 'ExampleSetOf'\nspec:\n if:\n field: 'zones'\n setOf:\n - 1\n - 2\n - 3\n caseSensitive: false\nThe comparison property
sourceis used with a condition to expose the source path for the resource. Thesourceproperty can be set to any value. The default isfilewhen objects loaded from a file don't identify a source.Syntax:
source: 'file'\nFor example:
","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Expressions/#startswith","title":"StartsWith","text":"---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Selector\nmetadata:\n name: IgnoreTestFiles\nspec:\n if:\n source: 'file'\n withinPath: 'tests/PSRule.Tests/'\nThe
startsWithcondition can be used to determine if the operand starts with a specified string. One or more strings to compare can be specified.Syntax:
startsWith: <string | array>\ncaseSensitive: <boolean>\nconvert: <boolean>\nFor example:
","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Expressions/#subset","title":"Subset","text":"---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Rule\nmetadata:\n name: 'ExampleStartsWith'\nspec:\n condition:\n anyOf:\n - field: 'url'\n startsWith: 'http'\n - field: 'url'\n startsWith:\n - 'http://'\n - 'https://'\n\n---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Selector\nmetadata:\n name: 'ExampleStartsWith'\nspec:\n if:\n anyOf:\n - field: 'url'\n startsWith: 'http'\n - field: 'url'\n startsWith:\n - 'http://'\n - 'https://'\nThe
subsetcondition can be used to determine if the operand is a set of specified values. The following properties are accepted:Syntax:
subset: <array>\ncaseSensitive: <bool>\nunique: <bool>\nFor example:
","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Expressions/#type","title":"Type","text":"---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Rule\nmetadata:\n name: 'ExampleSubset'\nspec:\n condition:\n field: 'logs'\n subset:\n - 'cluster-autoscaler'\n - 'kube-apiserver'\n - 'kube-scheduler'\n caseSensitive: true\n unique: true\n\n---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Selector\nmetadata:\n name: 'ExampleSubset'\nspec:\n if:\n field: 'logs'\n subset:\n - 'cluster-autoscaler'\n - 'kube-apiserver'\n - 'kube-scheduler'\n caseSensitive: true\n unique: true\nThe comparison property
typeis used with a condition to evaluate the target type of the object. Thetypeproperty must be set to.. Any other value will cause the condition to evaluate tofalse.Syntax:
type: '.'\nFor example:
","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Expressions/#version","title":"Version","text":"---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Rule\nmetadata:\n name: 'ExampleType'\nspec:\n condition:\n type: '.'\n equals: 'CustomType'\n\n---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Selector\nmetadata:\n name: 'ExampleType'\nspec:\n if:\n type: '.'\n in:\n - 'Microsoft.Storage/storageAccounts'\n - 'Microsoft.Storage/storageAccounts/blobServices'\nThe
versioncondition determines if the operand is a valid semantic version. A constraint can optionally be provided to require the semantic version to be within a range. Supported version constraints for expression are the same as the$Assert.Versionassertion helper.Syntax:
version: <string>\nincludePrerelease: <bool>\nFor example:
","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Expressions/#withinpath","title":"WithinPath","text":"---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Rule\nmetadata:\n name: 'ExampleVersion'\nspec:\n condition:\n field: 'engine.version'\n version: '^1.2.3'\n\n---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Selector\nmetadata:\n name: 'ExampleAnyVersion'\nspec:\n if:\n field: 'engine.version'\n version: ''\n\n---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Selector\nmetadata:\n name: 'ExampleVersionIncludingPrerelease'\nspec:\n if:\n field: 'engine.version'\n version: '>=1.5.0'\n includePrerelease: true\nThe
withinPathcondition determines if a file path is within a required path.If the path is within the required path, the condition will return
true. If the path is not within the required path, the condition will returnfalse.The following properties are accepted:
Syntax:
withinPath: <array>\ncaseSensitive: <boolean>\nFor example:
","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Expressions/#links","title":"Links","text":"---\n# Synopsis: Test withinPath with source\napiVersion: github.com/microsoft/PSRule/v1\nkind: Selector\nmetadata:\n name: YamlSourceWithinPath\nspec:\n if:\n source: 'Template'\n withinPath:\n - \"deployments/path/\"\n\n---\n# Synopsis: Test withinPath with source and case sensitive\napiVersion: github.com/microsoft/PSRule/v1\nkind: Selector\nmetadata:\n name: YamlSourceWithinPathCaseSensitive\nspec:\n if:\n source: 'Template'\n withinPath:\n - \"Deployments/Path/\"\n caseSensitive: true\nDescribes additional options that can be used during rule execution.
"},{"location":"concepts/PSRule/en-US/about_PSRule_Options/#description","title":"Description","text":"PSRule lets you use options when calling cmdlets such as
Invoke-PSRuleandTest-PSRuleTargetto change how rules are processed. This topic describes what options are available, when to and how to use them.The following workspace options are available for use:
Additionally the following baseline options can be included:
See about_PSRule_Baseline for more information on baseline options.
Options can be used with the following PSRule cmdlets:
Each of these cmdlets support:
When using a hashtable object
@{}, one or more options can be specified as keys using a dotted notation.For example:
$option = @{ 'Output.Format' = 'Yaml' };\nInvoke-PSRule -Path . -Option $option;\nInvoke-PSRule -Path . -Option @{ 'Output.Format' = 'Yaml' };\nThe above example shows how the
Output.Formatoption as a hashtable key can be used. Continue reading for a full list of options and how each can be used.Alternatively, options can be stored in a YAML formatted file and loaded from disk. Storing options as YAML allows different configurations to be loaded in a repeatable way instead of having to create an options object each time.
Options are stored as YAML properties using a lower camel case naming convention, for example:
output:\n format: Yaml\nThe
Set-PSRuleOptioncmdlet can be used to set options stored in YAML or the YAML file can be manually edited.Set-PSRuleOption -OutputFormat Yaml;\nBy default, PSRule will automatically look for a default YAML options file in the current working directory. Alternatively, you can specify a specific file path.
For example:
Invoke-PSRule -Option '.\\myconfig.yml';\nNew-PSRuleOption -Path '.\\myconfig.yaml';\nPSRule uses any of the following file names (in order) as the default YAML options file. If more than one of these files exist, the following order will be used to find the first match.
We recommend only using lowercase characters as shown above. This is because not all operating systems treat case in the same way.
Most options can be set using environment variables. When configuring environment variables we recommend that all capital letters are used. This is because environment variables are case-sensitive on some operating systems.
PSRule environment variables use a consistent naming pattern of
PSRULE_<PARENT>_<NAME>. Where<PARENT>is the parent class and<NAME>is the specific option. For example:When setting environment variables:
You can use a baseline group to provide a friendly name to an existing baseline. When you run PSRule you can opt to use the baseline group name as an alternative name for the baseline. To indicate a baseline group, prefix the group name with
@where you would use the name of a baseline.Baseline groups can be specified using:
# PowerShell: Using the BaselineGroup parameter\n$option = New-PSRuleOption -BaselineGroup @{ latest = 'YourBaseline' };\n# PowerShell: Using the Baseline.Group hashtable key\n$option = New-PSRuleOption -Option @{ 'Baseline.Group' = @{ latest = 'YourBaseline' } };\n# PowerShell: Using the BaselineGroup parameter to set YAML\nSet-PSRuleOption -BaselineGroup @{ latest = 'YourBaseline' };\n# YAML: Using the baseline/group property\nbaseline:\n group:\n latest: YourBaseline\n# Bash: Using environment variable\nexport PSRULE_BASELINE_GROUP='latest=YourBaseline'\n# GitHub Actions: Using environment variable\nenv:\n PSRULE_BASELINE_GROUP: 'latest=YourBaseline'\n
"},{"location":"concepts/PSRule/en-US/about_PSRule_Options/#bindingfield","title":"Binding.Field","text":"# Azure Pipelines: Using environment variable\nvariables:\n- name: PSRULE_BASELINE_GROUP\n value: 'latest=YourBaseline'\nWhen an object is passed from the pipeline, PSRule automatically extracts fields from object properties. PSRule provides standard fields such as
TargetNameandTargetType. In addition to standard fields, custom fields can be bound. Custom fields are available to rules and included in output.PSRule uses the following logic to determine which property should be used for binding:
Custom field bindings can be specified using:
# PowerShell: Using the BindingField parameter\n$option = New-PSRuleOption -BindingField @{ id = 'ResourceId', 'AlternativeId' };\n# PowerShell: Using the Binding.Field hashtable key\n$option = New-PSRuleOption -Option @{ 'Binding.Field' = @{ id = 'ResourceId', 'AlternativeId' } };\n# PowerShell: Using the BindingField parameter to set YAML\nSet-PSRuleOption -BindingField @{ id = 'ResourceId', 'AlternativeId' };\n
"},{"location":"concepts/PSRule/en-US/about_PSRule_Options/#bindingignorecase","title":"Binding.IgnoreCase","text":"# YAML: Using the binding/field property\nbinding:\n field:\n id:\n - ResourceId\n - AlternativeId\nWhen evaluating an object, PSRule extracts a few key properties from the object to help filter rules and display output results. The process of extract these key properties is called binding. The properties that PSRule uses for binding can be customized by providing a order list of alternative properties to use. See
Binding.TargetNameandBinding.TargetTypefor these options.This option can be specified using:
# PowerShell: Using the BindingIgnoreCase parameter\n$option = New-PSRuleOption -BindingIgnoreCase $False;\n# PowerShell: Using the Binding.IgnoreCase hashtable key\n$option = New-PSRuleOption -Option @{ 'Binding.IgnoreCase' = $False };\n# PowerShell: Using the BindingIgnoreCase parameter to set YAML\nSet-PSRuleOption -BindingIgnoreCase $False;\n# YAML: Using the binding/ignoreCase property\nbinding:\n ignoreCase: false\n# Bash: Using environment variable\nexport PSRULE_BINDING_IGNORECASE=false\n# GitHub Actions: Using environment variable\nenv:\n PSRULE_BINDING_IGNORECASE: false\n
"},{"location":"concepts/PSRule/en-US/about_PSRule_Options/#bindingnameseparator","title":"Binding.NameSeparator","text":"# Azure Pipelines: Using environment variable\nvariables:\n- name: PSRULE_BINDING_IGNORECASE\n value: false\nWhen an object is passed from the pipeline, PSRule assigns the object a TargetName. TargetName is used in output results to identify one object from another.
In cases where different types of objects share the same TargetName, this may become confusing. Using a qualified name, prefixes the TargetName with TargetType. i.e. TargetType/TargetName
To use a qualified name, see the
Binding.UseQualifiedNameoption.By default, PSRule uses
/to separate TargetType from TargetName. This option configures the separator that PSRule uses between the two components.This option can be specified using:
# PowerShell: Using the BindingNameSeparator parameter\n$option = New-PSRuleOption -BindingNameSeparator '::';\n# PowerShell: Using the Binding.NameSeparator hashtable key\n$option = New-PSRuleOption -Option @{ 'Binding.NameSeparator' = '::' };\n# PowerShell: Using the BindingNameSeparator parameter to set YAML\nSet-PSRuleOption -BindingNameSeparator '::';\n# YAML: Using the binding/nameSeparator property\nbinding:\n nameSeparator: '::'\n# Bash: Using environment variable\nexport PSRULE_BINDING_NAMESEPARATOR='::'\n# GitHub Actions: Using environment variable\nenv:\n PSRULE_BINDING_NAMESEPARATOR: '::'\n
"},{"location":"concepts/PSRule/en-US/about_PSRule_Options/#bindingprefertargetinfo","title":"Binding.PreferTargetInfo","text":"# Azure Pipelines: Using environment variable\nvariables:\n- name: PSRULE_BINDING_NAMESEPARATOR\n value: '::'\nSome built-in objects within PSRule perform automatic binding of TargetName and TargetType. These built-in objects provide their own target info.
When binding has been configured these values override automatic binding by default. This can occur when the built-in object uses one of the fields specified by the custom configuration. The common occurrences of this are on fields such as
NameandFullNamewhich are widely used. To prefer automatic binding when specified set this option to$True.This option can be specified using:
# PowerShell: Using the BindingPreferTargetInfo parameter\n$option = New-PSRuleOption -BindingPreferTargetInfo $True;\n# PowerShell: Using the Binding.PreferTargetInfo hashtable key\n$option = New-PSRuleOption -Option @{ 'Binding.PreferTargetInfo' = $True };\n# PowerShell: Using the BindingPreferTargetInfo parameter to set YAML\nSet-PSRuleOption -BindingPreferTargetInfo $True;\n# YAML: Using the binding/preferTargetInfo property\nbinding:\n preferTargetInfo: true\n# Bash: Using environment variable\nexport PSRULE_BINDING_PREFERTARGETINFO=false\n# GitHub Actions: Using environment variable\nenv:\n PSRULE_BINDING_PREFERTARGETINFO: false\n
"},{"location":"concepts/PSRule/en-US/about_PSRule_Options/#bindingtargetname","title":"Binding.TargetName","text":"# Azure Pipelines: Using environment variable\nvariables:\n- name: PSRULE_BINDING_PREFERTARGETINFO\n value: false\nWhen an object is passed from the pipeline, PSRule assigns the object a TargetName. TargetName is used in output results to identify one object from another. Many objects could be passed down the pipeline at the same time, so using a TargetName that is meaningful is important. TargetName is also used for advanced features such as rule suppression.
The value that PSRule uses for TargetName is configurable. PSRule uses the following logic to determine what TargetName should be used:
Custom property names to use for binding can be specified using:
# PowerShell: Using the TargetName parameter\n$option = New-PSRuleOption -TargetName 'ResourceName', 'AlternateName';\n# PowerShell: Using the Binding.TargetName hashtable key\n$option = New-PSRuleOption -Option @{ 'Binding.TargetName' = 'ResourceName', 'AlternateName' };\n# PowerShell: Using the TargetName parameter to set YAML\nSet-PSRuleOption -TargetName 'ResourceName', 'AlternateName';\n# YAML: Using the binding/targetName property\nbinding:\n targetName:\n - ResourceName\n - AlternateName\n# Bash: Using environment variable\nexport PSRULE_BINDING_TARGETNAME='ResourceName;AlternateName'\n# GitHub Actions: Using environment variable\nenv:\n PSRULE_BINDING_TARGETNAME: 'ResourceName;AlternateName'\n# Azure Pipelines: Using environment variable\nvariables:\n- name: PSRULE_BINDING_TARGETNAME\n value: 'ResourceName;AlternateName'\nTo specify a custom binding function use:
"},{"location":"concepts/PSRule/en-US/about_PSRule_Options/#bindingtargettype","title":"Binding.TargetType","text":"# Create a custom function that returns a TargetName string\n$bindFn = {\n param ($TargetObject)\n\n $otherName = $TargetObject.PSObject.Properties['OtherName'];\n if ($Null -eq $otherName) { return $Null }\n return $otherName.Value;\n}\n\n# Specify the binding function script block code to execute\n$option = New-PSRuleOption -BindTargetName $bindFn;\nWhen an object is passed from the pipeline, PSRule assigns the object a TargetType. TargetType is used to filter rules based on object type and appears in output results.
The value that PSRule uses for TargetType is configurable. PSRule uses the following logic to determine what TargetType should be used:
Custom property names to use for binding can be specified using:
# PowerShell: Using the TargetType parameter\n$option = New-PSRuleOption -TargetType 'ResourceType', 'kind';\n# PowerShell: Using the Binding.TargetType hashtable key\n$option = New-PSRuleOption -Option @{ 'Binding.TargetType' = 'ResourceType', 'kind' };\n# PowerShell: Using the TargetType parameter to set YAML\nSet-PSRuleOption -TargetType 'ResourceType', 'kind';\n# YAML: Using the binding/targetType property\nbinding:\n targetType:\n - ResourceType\n - kind\n# Bash: Using environment variable\nexport PSRULE_BINDING_TARGETTYPE='ResourceType;kind'\n# GitHub Actions: Using environment variable\nenv:\n PSRULE_BINDING_TARGETTYPE: 'ResourceType;kind'\n# Azure Pipelines: Using environment variable\nvariables:\n- name: PSRULE_BINDING_TARGETTYPE\n value: 'ResourceType;kind'\nTo specify a custom binding function use:
"},{"location":"concepts/PSRule/en-US/about_PSRule_Options/#bindingusequalifiedname","title":"Binding.UseQualifiedName","text":"# Create a custom function that returns a TargetType string\n$bindFn = {\n param ($TargetObject)\n\n $otherType = $TargetObject.PSObject.Properties['OtherType'];\n\n if ($otherType -eq $Null) {\n return $Null\n }\n\n return $otherType.Value;\n}\n\n# Specify the binding function script block code to execute\n$option = New-PSRuleOption -BindTargetType $bindFn;\nWhen an object is passed from the pipeline, PSRule assigns the object a TargetName. TargetName is used in output results to identify one object from another.
In cases where different types of objects share the same TargetName, this may become confusing. Using a qualified name, prefixes the TargetName with TargetType. i.e. TargetType/TargetName
This option determines if PSRule uses qualified or unqualified names (default).
By default, PSRule uses
/to separate TargetType from TargetName. SetBinding.NameSeparatorto change.This option can be specified using:
# PowerShell: Using the BindingUseQualifiedName parameter\n$option = New-PSRuleOption -BindingUseQualifiedName $True;\n# PowerShell: Using the Binding.UseQualifiedName hashtable key\n$option = New-PSRuleOption -Option @{ 'Binding.UseQualifiedName' = $True };\n# PowerShell: Using the BindingUseQualifiedName parameter to set YAML\nSet-PSRuleOption -BindingUseQualifiedName $True;\n# YAML: Using the binding/useQualifiedName property\nbinding:\n useQualifiedName: true\n# Bash: Using environment variable\nexport PSRULE_BINDING_USEQUALIFIEDNAME=false\n# GitHub Actions: Using environment variable\nenv:\n PSRULE_BINDING_USEQUALIFIEDNAME: false\n
"},{"location":"concepts/PSRule/en-US/about_PSRule_Options/#configuration","title":"Configuration","text":"# Azure Pipelines: Using environment variable\nvariables:\n- name: PSRULE_BINDING_USEQUALIFIEDNAME\n value: false\nConfigures a set of baseline configuration values that can be used in rule definitions. Configuration values can be overridden at different scopes.
This option can be specified using:
# PowerShell: Using the Configuration option with a hashtable\n$option = New-PSRuleOption -Configuration @{ LOCAL_APPSERVICEMININSTANCECOUNT = 2 };\n# YAML: Using the configuration property\nconfiguration:\n LOCAL_APPSERVICEMININSTANCECOUNT: 2\nConfiguration values can be specified using environment variables. To specify a configuration value, prefix the configuration value with
PSRULE_CONFIGURATION_.# Bash: Using environment variable\nexport PSRULE_CONFIGURATION_LOCAL_APPSERVICEMININSTANCECOUNT=2\n# GitHub Actions: Using environment variable\nenv:\n PSRULE_CONFIGURATION_LOCAL_APPSERVICEMININSTANCECOUNT: '2'\n
"},{"location":"concepts/PSRule/en-US/about_PSRule_Options/#conventioninclude","title":"Convention.Include","text":"# Azure Pipelines: Using environment variable\nvariables:\n- name: PSRULE_CONFIGURATION_LOCAL_APPSERVICEMININSTANCECOUNT\n value: '2'\nSpecifies conventions to execute when the pipeline run. Conventions are included by name and must be defined within files included in
-Pathor-Module.This option can be specified using:
# PowerShell: Using the Convention parameter\n$option = New-PSRuleOption -Convention 'Convention1', 'Convention2';\n# PowerShell: Using the Convention.Include hashtable key\n$option = New-PSRuleOption -Option @{ 'Convention.Include' = $True };\n# PowerShell: Using the Convention parameter to set YAML\nSet-PSRuleOption -Convention 'Convention1', 'Convention2';\n# YAML: Using the convention/include property\nconvention:\n include:\n - 'Convention1'\n - 'Convention2'\n# Bash: Using environment variable\nexport PSRULE_CONVENTION_INCLUDE='Convention1;Convention2'\n# GitHub Actions: Using environment variable\nenv:\n PSRULE_CONVENTION_INCLUDE: 'Convention1;Convention2'\n
"},{"location":"concepts/PSRule/en-US/about_PSRule_Options/#executionaliasreference","title":"Execution.AliasReference","text":"# Azure Pipelines: Using environment variable\nvariables:\n- name: PSRULE_CONVENTION_INCLUDE\n value: 'Convention1;Convention2'\nv2.9.0
Determines how to handle when an alias to a resource is used. By default, a warning is generated, however this behavior can be modified by this option.
The following preferences are available:
This option can be specified using:
# PowerShell: Using the ExecutionAliasReference parameter\n$option = New-PSRuleOption -ExecutionAliasReference 'Error';\n# PowerShell: Using the Execution.AliasReference hashtable key\n$option = New-PSRuleOption -Option @{ 'Execution.AliasReference' = 'Error' };\n# PowerShell: Using the ExecutionAliasReference parameter to set YAML\nSet-PSRuleOption -ExecutionAliasReference 'Error';\n# YAML: Using the execution/aliasReference property\nexecution:\n aliasReference: Error\n# Bash: Using environment variable\nexport PSRULE_EXECUTION_ALIASREFERENCE=Error\n# GitHub Actions: Using environment variable\nenv:\n PSRULE_EXECUTION_ALIASREFERENCE: Error\n
"},{"location":"concepts/PSRule/en-US/about_PSRule_Options/#executionduplicateresourceid","title":"Execution.DuplicateResourceId","text":"# Azure Pipelines: Using environment variable\nvariables:\n- name: PSRULE_EXECUTION_ALIASREFERENCE\n value: Error\nv2.4.0
Determines how to handle duplicate resources identifiers during execution. A duplicate resource identifier may exist if two resources are defined with the same name, ref, or alias. By default, an error is thrown, however this behavior can be modified by this option.
If this option is configured to
WarnorIgnoreonly the first resource will be used, however PSRule will continue to execute.The following preferences are available:
This option can be specified using:
# PowerShell: Using the DuplicateResourceId parameter\n$option = New-PSRuleOption -DuplicateResourceId 'Warn';\n# PowerShell: Using the Execution.DuplicateResourceId hashtable key\n$option = New-PSRuleOption -Option @{ 'Execution.DuplicateResourceId' = 'Warn' };\n# PowerShell: Using the DuplicateResourceId parameter to set YAML\nSet-PSRuleOption -DuplicateResourceId 'Warn';\n# YAML: Using the execution/duplicateResourceId property\nexecution:\n duplicateResourceId: Warn\n# Bash: Using environment variable\nexport PSRULE_EXECUTION_DUPLICATERESOURCEID=Warn\n# GitHub Actions: Using environment variable\nenv:\n PSRULE_EXECUTION_DUPLICATERESOURCEID: Warn\n
"},{"location":"concepts/PSRule/en-US/about_PSRule_Options/#executionhashalgorithm","title":"Execution.HashAlgorithm","text":"# Azure Pipelines: Using environment variable\nvariables:\n- name: PSRULE_EXECUTION_DUPLICATERESOURCEID\n value: Warn\nv3.0.0
Specifies the hashing algorithm used by the PSRule runtime. This hash algorithm is used when generating a resource identifier for an object that does not have a bound name.
By default, the SHA512 algorithm is used.
The following algorithms are available for use in PSRule:
This option can be specified using:
# PowerShell: Using the Execution.HashAlgorithm hashtable key\n$option = New-PSRuleOption -Option @{ 'Execution.HashAlgorithm' = 'SHA256' };\n# YAML: Using the execution/hashAlgorithm property\nexecution:\n hashAlgorithm: SHA256\n# Bash: Using environment variable\nexport PSRULE_EXECUTION_HASHALGORITHM=SHA256\n# GitHub Actions: Using environment variable\nenv:\n PSRULE_EXECUTION_HASHALGORITHM: SHA256\n
"},{"location":"concepts/PSRule/en-US/about_PSRule_Options/#executionlanguagemode","title":"Execution.LanguageMode","text":"# Azure Pipelines: Using environment variable\nvariables:\n- name: PSRULE_EXECUTION_HASHALGORITHM\n value: SHA256\nUnless PowerShell has been constrained, full language features of PowerShell are available to use within rule definitions. In locked down environments, a reduced set of language features may be desired.
When PSRule is executed in an environment configured for Device Guard, only constrained language features are available.
The following language modes are available for use in PSRule:
This option can be specified using:
# PowerShell: Using the Execution.LanguageMode hashtable key\n$option = New-PSRuleOption -Option @{ 'Execution.LanguageMode' = 'ConstrainedLanguage' };\n# YAML: Using the execution/languageMode property\nexecution:\n languageMode: ConstrainedLanguage\n# Bash: Using environment variable\nexport PSRULE_EXECUTION_LANGUAGEMODE=ConstrainedLanguage\n# GitHub Actions: Using environment variable\nenv:\n PSRULE_EXECUTION_LANGUAGEMODE: ConstrainedLanguage\n
"},{"location":"concepts/PSRule/en-US/about_PSRule_Options/#executioninvariantculture","title":"Execution.InvariantCulture","text":"# Azure Pipelines: Using environment variable\nvariables:\n- name: PSRULE_EXECUTION_LANGUAGEMODE\n value: ConstrainedLanguage\nv2.9.0
Determines how to report when an invariant culture is used. By default, a warning is generated, however this behavior can be modified by this option.
The following preferences are available:
This option can be specified using:
# PowerShell: Using the ExecutionInvariantCulture parameter\n$option = New-PSRuleOption -ExecutionInvariantCulture 'Error';\n# PowerShell: Using the Execution.InvariantCulture hashtable key\n$option = New-PSRuleOption -Option @{ 'Execution.InvariantCulture' = 'Error' };\n# PowerShell: Using the ExecutionInvariantCulture parameter to set YAML\nSet-PSRuleOption -ExecutionInvariantCulture 'Error';\n# YAML: Using the execution/invariantCulture property\nexecution:\n invariantCulture: Error\n# Bash: Using environment variable\nexport PSRULE_EXECUTION_INVARIANTCULTURE=Error\n# GitHub Actions: Using environment variable\nenv:\n PSRULE_EXECUTION_INVARIANTCULTURE: Error\n
"},{"location":"concepts/PSRule/en-US/about_PSRule_Options/#executioninitialsessionstate","title":"Execution.InitialSessionState","text":"# Azure Pipelines: Using environment variable\nvariables:\n- name: PSRULE_EXECUTION_INVARIANTCULTURE\n value: Error\nv2.5.0
Determines how the initial session state for executing PowerShell code is created.
The following preferences are available:
This option can be specified using:
# PowerShell: Using the InitialSessionState parameter\n$option = New-PSRuleOption -InitialSessionState 'Minimal';\n# PowerShell: Using the Execution.InitialSessionState hashtable key\n$option = New-PSRuleOption -Option @{ 'Execution.InitialSessionState' = 'Minimal' };\n# PowerShell: Using the InitialSessionState parameter to set YAML\nSet-PSRuleOption -InitialSessionState 'Minimal';\n# YAML: Using the execution/initialSessionState property\nexecution:\n initialSessionState: Minimal\n# Bash: Using environment variable\nexport PSRULE_EXECUTION_INITIALSESSIONSTATE=Minimal\n# GitHub Actions: Using environment variable\nenv:\n PSRULE_EXECUTION_INITIALSESSIONSTATE: Minimal\n
"},{"location":"concepts/PSRule/en-US/about_PSRule_Options/#executionrestrictscriptsource","title":"Execution.RestrictScriptSource","text":"# Azure Pipelines: Using environment variable\nvariables:\n- name: PSRULE_EXECUTION_INITIALSESSIONSTATE\n value: Minimal\nv3.0.0
Configures where to allow PowerShell language features (such as rules and conventions) to run from. In locked down environments, running PowerShell scripts from the workspace may not be allowed. Only run scripts from a trusted source.
This option does not affect YAML or JSON based rules and resources.
The following script source restrictions are available:
This option can be specified using:
# PowerShell: Using the RestrictScriptSource parameter\n$option = New-PSRuleOption -RestrictScriptSource 'ModuleOnly';\n# PowerShell: Using the Execution.RestrictScriptSource hashtable key\n$option = New-PSRuleOption -Option @{ 'Execution.RestrictScriptSource' = 'ModuleOnly' };\n# PowerShell: Using the RestrictScriptSource parameter to set YAML\nSet-PSRuleOption -RestrictScriptSource 'ModuleOnly';\n# YAML: Using the execution/restrictScriptSource property\nexecution:\n restrictScriptSource: ModuleOnly\n# Bash: Using environment variable\nexport PSRULE_EXECUTION_RESTRICTSCRIPTSOURCE=ModuleOnly\n# GitHub Actions: Using environment variable\nenv:\n PSRULE_EXECUTION_RESTRICTSCRIPTSOURCE: ModuleOnly\n
"},{"location":"concepts/PSRule/en-US/about_PSRule_Options/#executionruleinconclusive","title":"Execution.RuleInconclusive","text":"# Azure Pipelines: Using environment variable\nvariables:\n- name: PSRULE_EXECUTION_RESTRICTSCRIPTSOURCE\n value: ModuleOnly\nv2.9.0
Determines how to handle rules that generate inconclusive results. By default, a warning is generated, however this behavior can be modified by this option.
The following preferences are available:
This option can be specified using:
# PowerShell: Using the ExecutionRuleInconclusive parameter\n$option = New-PSRuleOption -ExecutionRuleInconclusive 'Error';\n# PowerShell: Using the Execution.RuleInconclusive hashtable key\n$option = New-PSRuleOption -Option @{ 'Execution.RuleInconclusive' = 'Error' };\n# PowerShell: Using the ExecutionRuleInconclusive parameter to set YAML\nSet-PSRuleOption -ExecutionRuleInconclusive 'Error';\n# YAML: Using the execution/ruleInconclusive property\nexecution:\n ruleInconclusive: Error\n# Bash: Using environment variable\nexport PSRULE_EXECUTION_RULEINCONCLUSIVE=Error\n# GitHub Actions: Using environment variable\nenv:\n PSRULE_EXECUTION_RULEINCONCLUSIVE: Error\n
"},{"location":"concepts/PSRule/en-US/about_PSRule_Options/#executionsuppressiongroupexpired","title":"Execution.SuppressionGroupExpired","text":"# Azure Pipelines: Using environment variable\nvariables:\n- name: PSRULE_EXECUTION_RULEINCONCLUSIVE\n value: Error\nv2.6.0
Determines how to handle expired suppression groups. Regardless of the value, an expired suppression group will be ignored. By default, a warning is generated, however this behavior can be modified by this option.
The following preferences are available:
This option can be specified using:
# PowerShell: Using the SuppressionGroupExpired parameter\n$option = New-PSRuleOption -SuppressionGroupExpired 'Error';\n# PowerShell: Using the Execution.SuppressionGroupExpired hashtable key\n$option = New-PSRuleOption -Option @{ 'Execution.SuppressionGroupExpired' = 'Error' };\n# PowerShell: Using the SuppressionGroupExpired parameter to set YAML\nSet-PSRuleOption -SuppressionGroupExpired 'Error';\n# YAML: Using the execution/suppressionGroupExpired property\nexecution:\n suppressionGroupExpired: Error\n# Bash: Using environment variable\nexport PSRULE_EXECUTION_SUPPRESSIONGROUPEXPIRED=Error\n# GitHub Actions: Using environment variable\nenv:\n PSRULE_EXECUTION_SUPPRESSIONGROUPEXPIRED: Error\n
"},{"location":"concepts/PSRule/en-US/about_PSRule_Options/#executionruleexcluded","title":"Execution.RuleExcluded","text":"# Azure Pipelines: Using environment variable\nvariables:\n- name: PSRULE_EXECUTION_SUPPRESSIONGROUPEXPIRED\n value: Error\nv2.8.0
Determines how to handle excluded rules. Regardless of the value, excluded rules are ignored. By default, a rule is excluded silently, however this behavior can be modified by this option.
The following preferences are available:
This option can be specified using:
# PowerShell: Using the ExecutionRuleExcluded parameter\n$option = New-PSRuleOption -ExecutionRuleExcluded 'Warn';\n# PowerShell: Using the Execution.RuleExcluded hashtable key\n$option = New-PSRuleOption -Option @{ 'Execution.RuleExcluded' = 'Warn' };\n# PowerShell: Using the ExecutionRuleExcluded parameter to set YAML\nSet-PSRuleOption -ExecutionRuleExcluded 'Warn';\n# YAML: Using the execution/ruleExcluded property\nexecution:\n ruleExcluded: Warn\n# Bash: Using environment variable\nexport PSRULE_EXECUTION_RULEEXCLUDED=Warn\n# GitHub Actions: Using environment variable\nenv:\n PSRULE_EXECUTION_RULEEXCLUDED: Warn\n
"},{"location":"concepts/PSRule/en-US/about_PSRule_Options/#executionrulesuppressed","title":"Execution.RuleSuppressed","text":"# Azure Pipelines: Using environment variable\nvariables:\n- name: PSRULE_EXECUTION_RULEEXCLUDED\n value: Warn\nv2.8.0
Determines how to handle suppressed rules. Regardless of the value, a suppressed rule is ignored. By default, a warning is generated, however this behavior can be modified by this option.
The following preferences are available:
# PowerShell: Using the ExecutionRuleSuppressed parameter\n$option = New-PSRuleOption -ExecutionRuleSuppressed 'Error';\n# PowerShell: Using the Execution.RuleSuppressed hashtable key\n$option = New-PSRuleOption -Option @{ 'Execution.RuleSuppressed' = 'Error' };\n# PowerShell: Using the ExecutionRuleSuppressed parameter to set YAML\nSet-PSRuleOption -ExecutionRuleSuppressed 'Error';\n# YAML: Using the execution/ruleSuppressed property\nexecution:\n ruleSuppressed: Error\n# Bash: Using environment variable\nexport PSRULE_EXECUTION_RULESUPPRESSED=Error\n# GitHub Actions: Using environment variable\nenv:\n PSRULE_EXECUTION_RULESUPPRESSED: Error\n
"},{"location":"concepts/PSRule/en-US/about_PSRule_Options/#executionunprocessedobject","title":"Execution.UnprocessedObject","text":"# Azure Pipelines: Using environment variable\nvariables:\n- name: PSRULE_EXECUTION_RULESUPPRESSED\n value: Error\nv2.9.0
Determines how to report objects that are not processed by any rule. By default, a warning is generated, however this behavior can be modified by this option.
The following preferences are available:
This option can be specified using:
# PowerShell: Using the ExecutionUnprocessedObject parameter\n$option = New-PSRuleOption -ExecutionUnprocessedObject 'Ignore';\n# PowerShell: Using the Execution.UnprocessedObject hashtable key\n$option = New-PSRuleOption -Option @{ 'Execution.UnprocessedObject' = 'Ignore' };\n# PowerShell: Using the ExecutionUnprocessedObject parameter to set YAML\nSet-PSRuleOption -ExecutionUnprocessedObject 'Ignore';\n# YAML: Using the execution/unprocessedObject property\nexecution:\n unprocessedObject: Ignore\n# Bash: Using environment variable\nexport PSRULE_EXECUTION_UNPROCESSEDOBJECT=Ignore\n# GitHub Actions: Using environment variable\nenv:\n PSRULE_EXECUTION_UNPROCESSEDOBJECT: Ignore\n
"},{"location":"concepts/PSRule/en-US/about_PSRule_Options/#includemodule","title":"Include.Module","text":"# Azure Pipelines: Using environment variable\nvariables:\n- name: PSRULE_EXECUTION_UNPROCESSEDOBJECT\n value: Ignore\nAutomatically include rules and resources from the specified module. To automatically import and include a module specify the module by name. The module must already be installed on the system.
When
$PSModuleAutoLoadingPreferenceis set to a value other thenAllthe module must be imported.This option is equivalent to using the
-Moduleparameter on PSRule cmdlets, with the following addition:This option can be specified using:
# PowerShell: Using the IncludeModule parameter\n$option = New-PSRuleOption -IncludeModule 'TestModule1', 'TestModule2';\n# PowerShell: Using the Include.Module hashtable key\n$option = New-PSRuleOption -Option @{ 'Include.Module' = 'TestModule1', 'TestModule2' };\n# PowerShell: Using the IncludeModule parameter to set YAML\nSet-PSRuleOption -IncludeModule 'TestModule1', 'TestModule2';\n# YAML: Using the include/module property\ninclude:\n module:\n - TestModule1\n# Bash: Using environment variable\nexport PSRULE_INCLUDE_MODULE=TestModule1;TestModule2\n# GitHub Actions: Using environment variable\nenv:\n PSRULE_INCLUDE_MODULE: TestModule1;TestModule2\n
"},{"location":"concepts/PSRule/en-US/about_PSRule_Options/#includepath","title":"Include.Path","text":"# Azure Pipelines: Using environment variable\nvariables:\n- name: PSRULE_INCLUDE_MODULE\n value: TestModule1;TestModule2\nAutomatically include rules and resources from the specified path. By default,
.ps-rule/is included.This option is equivalent to using the
-Pathparameter on PSRule cmdlets, with the following additions:This option can be specified using:
# PowerShell: Using the IncludePath parameter\n$option = New-PSRuleOption -IncludePath '.ps-rule/', 'custom-rules/';\n# PowerShell: Using the Include.Path hashtable key\n$option = New-PSRuleOption -Option @{ 'Include.Path' = '.ps-rule/', 'custom-rules/' };\n# PowerShell: Using the IncludePath parameter to set YAML\nSet-PSRuleOption -IncludePath '.ps-rule/', 'custom-rules/';\n# YAML: Using the include/path property\ninclude:\n path:\n - custom-rules/\n# Bash: Using environment variable\nexport PSRULE_INCLUDE_PATH=.ps-rule/;custom-rules/\n# GitHub Actions: Using environment variable\nenv:\n PSRULE_INCLUDE_PATH: .ps-rule/;custom-rules/\n
"},{"location":"concepts/PSRule/en-US/about_PSRule_Options/#inputformat","title":"Input.Format","text":"# Azure Pipelines: Using environment variable\nvariables:\n- name: PSRULE_INCLUDE_PATH\n value: .ps-rule/;custom-rules/\nConfigures the input format for when a string is passed in as a target object. This option determines if the target object is deserialized into an alternative form.
Use this option with
Assert-PSRule,Invoke-PSRuleorTest-PSRuleTarget. Set this option to eitherYaml,Json,Markdown,PowerShellDatato deserialize as a specific format. The-Formatparameter will override any value set in configuration.When the
-InputObjectparameter or pipeline input is used, strings are treated as plain text by default.FileInfoobjects for supported file formats will be deserialized based on file extension.When the
-InputPathparameter is used, supported file formats will be deserialized based on file extension. The-InputPathparameter can be used with a file path or URL.The following formats are available:
If the
Detectformat is used, the file extension will be used to automatically detect the format. When the file extension can not be determinedDetectis the same asNone.The
Markdownformat does not parse the whole markdown document. Specifically this format deserializes YAML front matter from the top of the document if any exists.The
Fileformat does not deserialize file contents. Each file is returned as an object. Files within.gitsub-directories are ignored. Path specs specified in.gitignoredirectly in the current working path are ignored. ARepositoryInfoobject is generated if the current working path if a.gitsub-directory is present. Additionally, PSRule performs automatic type binding for file objects, using the extension as the type. When files have no extension the whole file name is used.Detect uses the following file extensions:
This option can be specified using:
# PowerShell: Using the Format parameter\n$option = New-PSRuleOption -Format Yaml;\n# PowerShell: Using the Input.Format hashtable key\n$option = New-PSRuleOption -Option @{ 'Input.Format' = 'Yaml' };\n# PowerShell: Using the Format parameter to set YAML\nSet-PSRuleOption -Format Yaml;\n# YAML: Using the input/format property\ninput:\n format: Yaml\n# Bash: Using environment variable\nexport PSRULE_INPUT_FORMAT=Yaml\n# GitHub Actions: Using environment variable\nenv:\n PSRULE_INPUT_FORMAT: Yaml\n
"},{"location":"concepts/PSRule/en-US/about_PSRule_Options/#inputignoregitpath","title":"Input.IgnoreGitPath","text":"# Azure Pipelines: Using environment variable\nvariables:\n- name: PSRULE_INPUT_FORMAT\n value: Yaml\nWhen reading files from an input path, files within the
.gitsub-directory are ignored by default. Files stored within the.gitsub-directory are system repository files used by git. To read files stored within the.gitpath, set this option to$False.This option can be specified using:
# PowerShell: Using the InputIgnoreGitPath parameter\n$option = New-PSRuleOption -InputIgnoreGitPath $False;\n# PowerShell: Using the Input.IgnoreGitPath hashtable key\n$option = New-PSRuleOption -Option @{ 'Input.IgnoreGitPath' = $False };\n# PowerShell: Using the InputIgnoreGitPath parameter to set YAML\nSet-PSRuleOption -InputIgnoreGitPath $False;\n# YAML: Using the input/ignoreGitPath property\ninput:\n ignoreGitPath: false\n# Bash: Using environment variable\nexport PSRULE_INPUT_IGNOREGITPATH=false\n# GitHub Actions: Using environment variable\nenv:\n PSRULE_INPUT_IGNOREGITPATH: false\n
"},{"location":"concepts/PSRule/en-US/about_PSRule_Options/#inputignoreobjectsource","title":"Input.IgnoreObjectSource","text":"# Azure Pipelines: Using environment variable\nvariables:\n- name: PSRULE_INPUT_IGNOREGITPATH\n value: false\nBy default, objects read from file using
inputPathwill be skipped if the file path has been ignored. When set to true, additionally objects with a source path that has been ignored will be skipped. This will includeFileInfoobjects, and objects with a source set using the_PSRule.sourceproperty.File paths to ignore are set by
Input.PathIgnore,Input.IgnoreGitPath, andInput.IgnoreRepositoryCommon.This option can be specified using:
# PowerShell: Using the InputIgnoreObjectSource parameter\n$option = New-PSRuleOption -InputIgnoreObjectSource $True;\n# PowerShell: Using the Input.IgnoreObjectSource hashtable key\n$option = New-PSRuleOption -Option @{ 'Input.IgnoreObjectSource' = $True };\n# PowerShell: Using the InputIgnoreObjectSource parameter to set YAML\nSet-PSRuleOption -InputIgnoreObjectSource $True;\n# YAML: Using the input/ignoreObjectSource property\ninput:\n ignoreObjectSource: true\n# Bash: Using environment variable\nexport PSRULE_INPUT_IGNOREOBJECTSOURCE=true\n# GitHub Actions: Using environment variable\nenv:\n PSRULE_INPUT_IGNOREOBJECTSOURCE: true\n
"},{"location":"concepts/PSRule/en-US/about_PSRule_Options/#inputignorerepositorycommon","title":"Input.IgnoreRepositoryCommon","text":"# Azure Pipelines: Using environment variable\nvariables:\n- name: PSRULE_INPUT_IGNOREOBJECTSOURCE\n value: true\nWhen reading files from an input path, files are discovered recursively. A number of files are commonly found within a private and open-source repositories. In many cases these files are of no interest for analysis and should be ignored by rules. PSRule will ignore the following files by default:
To include these files, set this option to
$False. This option can be specified using:# PowerShell: Using the InputIgnoreRepositoryCommon parameter\n$option = New-PSRuleOption -InputIgnoreRepositoryCommon $False;\n# PowerShell: Using the Input.IgnoreRepositoryCommon hashtable key\n$option = New-PSRuleOption -Option @{ 'Input.IgnoreRepositoryCommon' = $False };\n# PowerShell: Using the InputIgnoreRepositoryCommon parameter to set YAML\nSet-PSRuleOption -InputIgnoreRepositoryCommon $False;\n# YAML: Using the input/ignoreRepositoryCommon property\ninput:\n ignoreRepositoryCommon: false\n# Bash: Using environment variable\nexport PSRULE_INPUT_IGNOREREPOSITORYCOMMON=false\n# GitHub Actions: Using environment variable\nenv:\n PSRULE_INPUT_IGNOREREPOSITORYCOMMON: false\n
"},{"location":"concepts/PSRule/en-US/about_PSRule_Options/#inputignoreunchangedpath","title":"Input.IgnoreUnchangedPath","text":"# Azure Pipelines: Using environment variable\nvariables:\n- name: PSRULE_INPUT_IGNOREREPOSITORYCOMMON\n value: false\nv2.5.0
By default, PSRule will process all files within an input path. For large repositories, this can result in a large number of files being processed. Additionally, for a pull request you may only be interested in files that have changed.
When set to
true, files that have not changed will be ignored. This option can be specified using:# PowerShell: Using the InputIgnoreUnchangedPath parameter\n$option = New-PSRuleOption -InputIgnoreUnchangedPath $True;\n# PowerShell: Using the Input.IgnoreUnchangedPath hashtable key\n$option = New-PSRuleOption -Option @{ 'Input.IgnoreUnchangedPath' = $True };\n# PowerShell: Using the InputIgnoreUnchangedPath parameter to set YAML\nSet-PSRuleOption -InputIgnoreUnchangedPath $True;\n# YAML: Using the input/ignoreUnchangedPath property\ninput:\n ignoreUnchangedPath: true\n# Bash: Using environment variable\nexport PSRULE_INPUT_IGNOREUNCHANGEDPATH=true\n# GitHub Actions: Using environment variable\nenv:\n PSRULE_INPUT_IGNOREUNCHANGEDPATH: true\n
"},{"location":"concepts/PSRule/en-US/about_PSRule_Options/#inputobjectpath","title":"Input.ObjectPath","text":"# Azure Pipelines: Using environment variable\nvariables:\n- name: PSRULE_INPUT_IGNOREUNCHANGEDPATH\n value: true\nThe object path to a property to use instead of the pipeline object.
By default, PSRule processes objects passed from the pipeline against selected rules. When this option is set, instead of evaluating the pipeline object, PSRule looks for a property of the pipeline object specified by
ObjectPathand uses that instead. If the property specified byObjectPathis a collection/ array, then each item is evaluated separately.If the property specified by
ObjectPathdoes not exist, PSRule skips the object.When using
Invoke-PSRule,Test-PSRuleTarget, andAssert-PSRulethe-ObjectPathparameter will override any value set in configuration.This option can be specified using:
# PowerShell: Using the ObjectPath parameter\n$option = New-PSRuleOption -ObjectPath 'items';\n# PowerShell: Using the Input.ObjectPath hashtable key\n$option = New-PSRuleOption -Option @{ 'Input.ObjectPath' = 'items' };\n# PowerShell: Using the ObjectPath parameter to set YAML\nSet-PSRuleOption -ObjectPath 'items';\n# YAML: Using the input/objectPath property\ninput:\n objectPath: items\n# Bash: Using environment variable\nexport PSRULE_INPUT_OBJECTPATH=items\n# GitHub Actions: Using environment variable\nenv:\n PSRULE_INPUT_OBJECTPATH: items\n
"},{"location":"concepts/PSRule/en-US/about_PSRule_Options/#inputpathignore","title":"Input.PathIgnore","text":"# Azure Pipelines: Using environment variable\nvariables:\n- name: PSRULE_INPUT_OBJECTPATH\n value: items\nIgnores input files that match the path spec when using
-InputPath. If specified, files that match the path spec will not be processed. By default, all files are processed.For example, ignoring file extensions:
input:\n pathIgnore:\n # Exclude files with these extensions\n - '*.md'\n - '*.png'\n # Exclude specific configuration files\n - 'bicepconfig.json'\nFor example, ignoring all files with exceptions:
input:\n pathIgnore:\n # Exclude all files\n - '*'\n # Only process deploy.bicep files\n - '!**/deploy.bicep'\nThis option can be specified using:
# PowerShell: Using the InputPathIgnore parameter\n$option = New-PSRuleOption -InputPathIgnore '*.Designer.cs';\n# PowerShell: Using the Input.PathIgnore hashtable key\n$option = New-PSRuleOption -Option @{ 'Input.PathIgnore' = '*.Designer.cs' };\n# PowerShell: Using the InputPathIgnore parameter to set YAML\nSet-PSRuleOption -InputPathIgnore '*.Designer.cs';\n# YAML: Using the input/pathIgnore property\ninput:\n pathIgnore:\n - '*.Designer.cs'\n# Bash: Using environment variable\nexport PSRULE_INPUT_PATHIGNORE=*.Designer.cs\n# GitHub Actions: Using environment variable\nenv:\n PSRULE_INPUT_PATHIGNORE: '*.Designer.cs'\n
"},{"location":"concepts/PSRule/en-US/about_PSRule_Options/#inputtargettype","title":"Input.TargetType","text":"# Azure Pipelines: Using environment variable\nvariables:\n- name: PSRULE_INPUT_PATHIGNORE\n value: '*.Designer.cs'\nFilters input objects by TargetType.
If specified, only objects with the specified TargetType are processed. Objects that do not match TargetType are ignored. If multiple values are specified, only one TargetType must match. This option is not case-sensitive.
By default, all objects are processed.
To change the field TargetType is bound to set the
Binding.TargetTypeoption.When using
Invoke-PSRule,Test-PSRuleTarget, andAssert-PSRulethe-TargetTypeparameter will override any value set in configuration.This option can be specified using:
# PowerShell: Using the InputTargetType parameter\n$option = New-PSRuleOption -InputTargetType 'virtualMachine', 'virtualNetwork';\n# PowerShell: Using the Input.TargetType hashtable key\n$option = New-PSRuleOption -Option @{ 'Input.TargetType' = 'virtualMachine', 'virtualNetwork' };\n# PowerShell: Using the InputTargetType parameter to set YAML\nSet-PSRuleOption -InputTargetType 'virtualMachine', 'virtualNetwork';\n# YAML: Using the input/targetType property\ninput:\n targetType:\n - virtualMachine\n# Bash: Using environment variable\nexport PSRULE_INPUT_TARGETTYPE=virtualMachine;virtualNetwork\n# GitHub Actions: Using environment variable\nenv:\n PSRULE_INPUT_TARGETTYPE: virtualMachine;virtualNetwork\n
"},{"location":"concepts/PSRule/en-US/about_PSRule_Options/#logginglimitdebug","title":"Logging.LimitDebug","text":"# Azure Pipelines: Using environment variable\nvariables:\n- name: PSRULE_INPUT_TARGETTYPE\n value: virtualMachine;virtualNetwork\nLimits debug messages to a list of named debug scopes.
When using the
-Debugswitch or preference variable, by default PSRule cmdlets log all debug output. When using debug output for debugging a specific rule, it may be helpful to limit debug message to a specific rule.To identify a rule to include in debug output use the rule name.
The following built-in scopes exist in addition to rule names:
This option can be specified using:
# PowerShell: Using the LoggingLimitDebug parameter\n$option = New-PSRuleOption -LoggingLimitDebug Rule1, Rule2;\n# PowerShell: Using the Logging.LimitDebug hashtable key\n$option = New-PSRuleOption -Option @{ 'Logging.LimitDebug' = Rule1, Rule2 };\n# PowerShell: Using the LoggingLimitDebug parameter to set YAML\nSet-PSRuleOption -LoggingLimitDebug Rule1, Rule2;\n
"},{"location":"concepts/PSRule/en-US/about_PSRule_Options/#logginglimitverbose","title":"Logging.LimitVerbose","text":"# YAML: Using the logging/limitDebug property\nlogging:\n limitDebug:\n - Rule1\n - Rule2\nLimits verbose messages to a list of named verbose scopes.
When using the
-Verboseswitch or preference variable, by default PSRule cmdlets log all verbose output. When using verbose output for troubleshooting a specific rule, it may be helpful to limit verbose messages to a specific rule.To identify a rule to include in verbose output use the rule name.
The following built-in scopes exist in addition to rule names:
This option can be specified using:
# PowerShell: Using the LoggingLimitVerbose parameter\n$option = New-PSRuleOption -LoggingLimitVerbose Rule1, Rule2;\n# PowerShell: Using the Logging.LimitVerbose hashtable key\n$option = New-PSRuleOption -Option @{ 'Logging.LimitVerbose' = Rule1, Rule2 };\n# PowerShell: Using the LoggingLimitVerbose parameter to set YAML\nSet-PSRuleOption -LoggingLimitVerbose Rule1, Rule2;\n
"},{"location":"concepts/PSRule/en-US/about_PSRule_Options/#loggingrulefail","title":"Logging.RuleFail","text":"# YAML: Using the logging/limitVerbose property\nlogging:\n limitVerbose:\n - Rule1\n - Rule2\nWhen an object fails a rule condition the results are written to output as a structured object marked with the outcome of Fail. If the rule executed successfully regardless of outcome no other informational messages are shown by default.
In some circumstances such as a continuous integration (CI) pipeline, it may be preferable to see informational messages or abort the CI process if one or more Fail outcomes are returned.
By settings this option, error, warning or information messages will be generated for each rule fail outcome in addition to structured output. By default, outcomes are not logged to an informational stream (i.e. None).
The following streams available:
This option can be specified using:
# PowerShell: Using the LoggingRuleFail parameter\n$option = New-PSRuleOption -LoggingRuleFail Error;\n# PowerShell: Using the Logging.RuleFail hashtable key\n$option = New-PSRuleOption -Option @{ 'Logging.RuleFail' = 'Error' };\n# PowerShell: Using the LoggingRuleFail parameter to set YAML\nSet-PSRuleOption -LoggingRuleFail Error;\n
"},{"location":"concepts/PSRule/en-US/about_PSRule_Options/#loggingrulepass","title":"Logging.RulePass","text":"# YAML: Using the logging/ruleFail property\nlogging:\n ruleFail: Error\nWhen an object passes a rule condition the results are written to output as a structured object marked with the outcome of Pass. If the rule executed successfully regardless of outcome no other informational messages are shown by default.
In some circumstances such as a continuous integration (CI) pipeline, it may be preferable to see informational messages.
By settings this option, error, warning or information messages will be generated for each rule pass outcome in addition to structured output. By default, outcomes are not logged to an informational stream (i.e. None).
The following streams available:
This option can be specified using:
# PowerShell: Using the LoggingRulePass parameter\n$option = New-PSRuleOption -LoggingRulePass Information;\n# PowerShell: Using the Logging.RulePass hashtable key\n$option = New-PSRuleOption -Option @{ 'Logging.RulePass' = 'Information' };\n# PowerShell: Using the LoggingRulePass parameter to set YAML\nSet-PSRuleOption -LoggingRulePass Information;\n
"},{"location":"concepts/PSRule/en-US/about_PSRule_Options/#outputas","title":"Output.As","text":"# YAML: Using the logging/rulePass property\nlogging:\n rulePass: Information\nConfigures the type of results to produce.
This option only applies to
Invoke-PSRuleandAssert-PSRule.Invoke-PSRuleandAssert-PSRulealso include a-Asparameter to set this option at runtime. If specified, the-Asparameter take precedence, over this option.The following options are available:
This option can be specified using:
# PowerShell: Using the OutputAs parameter\n$option = New-PSRuleOption -OutputAs Summary;\n# PowerShell: Using the Output.As hashtable key\n$option = New-PSRuleOption -Option @{ 'Output.As' = 'Summary' };\n# PowerShell: Using the OutputAs parameter to set YAML\nSet-PSRuleOption -OutputAs Summary;\n# YAML: Using the output/as property\noutput:\n as: Summary\n# Bash: Using environment variable\nexport PSRULE_OUTPUT_AS=Summary\n# GitHub Actions: Using environment variable\nenv:\n PSRULE_OUTPUT_AS: Summary\n
"},{"location":"concepts/PSRule/en-US/about_PSRule_Options/#outputbanner","title":"Output.Banner","text":"# Azure Pipelines: Using environment variable\nvariables:\n- name: PSRULE_OUTPUT_AS\n value: Summary\nThe information displayed for PSRule banner. This option is only applicable when using
Assert-PSRulecmdlet.The following information can be shown or hidden by configuring this option.
Additionally the following rollup options exist:
This option can be configured using one of the named values described above. Alternatively, this value can be configured by specifying a bit mask as an integer. For example
6would showSource, andSupportLinks.This option can be specified using:
# PowerShell: Using the OutputBanner parameter\n$option = New-PSRuleOption -OutputBanner Minimal;\n# PowerShell: Using the Output.Banner hashtable key\n$option = New-PSRuleOption -Option @{ 'Output.Banner' = 'Minimal' };\n# PowerShell: Using the OutputBanner parameter to set YAML\nSet-PSRuleOption -OutputBanner Minimal;\n# YAML: Using the output/banner property\noutput:\n banner: Minimal\n# Bash: Using environment variable\nexport PSRULE_OUTPUT_BANNER=Minimal\n# GitHub Actions: Using environment variable\nenv:\n PSRULE_OUTPUT_BANNER: Minimal\n
"},{"location":"concepts/PSRule/en-US/about_PSRule_Options/#outputculture","title":"Output.Culture","text":"# Azure Pipelines: Using environment variable\nvariables:\n- name: PSRULE_OUTPUT_BANNER\n value: Minimal\nSpecified the name of one or more cultures to use for generating output. When multiple cultures are specified, the first matching culture will be used. If a culture is not specified, PSRule will use the current PowerShell culture.
PSRule cmdlets also include a
-Cultureparameter to set this option at runtime. If specified, the-Cultureparameter take precedence, over this option.To get a list of cultures use the
Get-Culture -ListAvailablecmdlet.This option can be specified using:
# PowerShell: Using the OutputCulture parameter\n$option = New-PSRuleOption -OutputCulture 'en-AU';\n# PowerShell: Using the Output.Culture hashtable key\n$option = New-PSRuleOption -Option @{ 'Output.Culture' = 'en-AU' };\n# PowerShell: Using the OutputCulture parameter to set YAML\nSet-PSRuleOption -OutputCulture 'en-AU', 'en-US';\n# YAML: Using the output/culture property\noutput:\n culture: [ 'en-AU', 'en-US' ]\n# Bash: Using environment variable\nexport PSRULE_OUTPUT_CULTURE=en-AU;en-US\n# GitHub Actions: Using environment variable\nenv:\n PSRULE_OUTPUT_CULTURE: en-AU;en-US\n
"},{"location":"concepts/PSRule/en-US/about_PSRule_Options/#outputencoding","title":"Output.Encoding","text":"# Azure Pipelines: Using environment variable\nvariables:\n- name: PSRULE_OUTPUT_CULTURE\n value: en-AU;en-US\nConfigures the encoding used when output is written to file. This option has no affect when
Output.Pathis not set.The following encoding options are available:
This option can be specified using:
# PowerShell: Using the OutputEncoding parameter\n$option = New-PSRuleOption -OutputEncoding UTF8;\n# PowerShell: Using the Output.Format hashtable key\n$option = New-PSRuleOption -Option @{ 'Output.Encoding' = 'UTF8' };\n# PowerShell: Using the OutputEncoding parameter to set YAML\nSet-PSRuleOption -OutputEncoding UTF8;\n# YAML: Using the output/encoding property\noutput:\n encoding: UTF8\n# Bash: Using environment variable\nexport PSRULE_OUTPUT_ENCODING=UTF8\n# GitHub Actions: Using environment variable\nenv:\n PSRULE_OUTPUT_ENCODING: UTF8\n
"},{"location":"concepts/PSRule/en-US/about_PSRule_Options/#outputfooter","title":"Output.Footer","text":"# Azure Pipelines: Using environment variable\nvariables:\n- name: PSRULE_OUTPUT_ENCODING\n value: UTF8\nThe information displayed for PSRule footer. This option is only applicable when using
Assert-PSRulecmdlet.The following information can be shown or hidden by configuring this option.
Additionally the following rollup options exist:
This option can be configured using one of the named values described above. Alternatively, this value can be configured by specifying a bit mask as an integer. For example
3would showRunInfo, andRuleCount.This option can be specified using:
# PowerShell: Using the OutputFooter parameter\n$option = New-PSRuleOption -OutputFooter RuleCount;\n# PowerShell: Using the Output.Footer hashtable key\n$option = New-PSRuleOption -Option @{ 'Output.Footer' = 'RuleCount' };\n# PowerShell: Using the OutputFooter parameter to set YAML\nSet-PSRuleOption -OutputFooter RuleCount;\n# YAML: Using the output/footer property\noutput:\n footer: RuleCount\n# Bash: Using environment variable\nexport PSRULE_OUTPUT_FOOTER=RuleCount\n# GitHub Actions: Using environment variable\nenv:\n PSRULE_OUTPUT_FOOTER: RuleCount\n
"},{"location":"concepts/PSRule/en-US/about_PSRule_Options/#outputformat","title":"Output.Format","text":"# Azure Pipelines: Using environment variable\nvariables:\n- name: PSRULE_OUTPUT_FOOTER\n value: RuleCount\nConfigures the format that results will be presented in. This option applies to
Invoke-PSRule,Assert-PSRule,Get-PSRuleandGet-PSRuleBaseline. This options is ignored by other cmdlets.The following format options are available:
The Wide format is ignored by
Assert-PSRule.Get-PSRuleonly acceptsNone,Wide,YamlandJson. Usage of other formats are treated asNone.The
Get-PSRuleBaselinecmdlet only acceptsNoneorYaml. TheExport-PSRuleBaselinecmdlet only acceptsYaml.This option can be specified using:
# PowerShell: Using the OutputFormat parameter\n$option = New-PSRuleOption -OutputFormat Yaml;\n# PowerShell: Using the Output.Format hashtable key\n$option = New-PSRuleOption -Option @{ 'Output.Format' = 'Yaml' };\n# PowerShell: Using the OutputFormat parameter to set YAML\nSet-PSRuleOption -OutputFormat Yaml;\n# YAML: Using the output/format property\noutput:\n format: Yaml\n# Bash: Using environment variable\nexport PSRULE_OUTPUT_FORMAT=Yaml\n# GitHub Actions: Using environment variable\nenv:\n PSRULE_OUTPUT_FORMAT: Yaml\n
"},{"location":"concepts/PSRule/en-US/about_PSRule_Options/#outputoutcome","title":"Output.Outcome","text":"# Azure Pipelines: Using environment variable\nvariables:\n- name: PSRULE_OUTPUT_FORMAT\n value: Yaml\nFilters output to include results with the specified outcome. The following outcome options are available:
Additionally the following rollup options exist:
This option can be specified using:
# PowerShell: Using the OutputOutcome parameter\n$option = New-PSRuleOption -OutputOutcome Fail;\n# PowerShell: Using the Output.Outcome hashtable key\n$option = New-PSRuleOption -Option @{ 'Output.Outcome' = 'Fail' };\n# PowerShell: Using the OutputOutcome parameter to set YAML\nSet-PSRuleOption -OutputOutcome Fail;\n# YAML: Using the output/outcome property\noutput:\n outcome: 'Fail'\n# Bash: Using environment variable\nexport PSRULE_OUTPUT_OUTCOME=Fail\n# GitHub Actions: Using environment variable\nenv:\n PSRULE_OUTPUT_OUTCOME: Fail\n
"},{"location":"concepts/PSRule/en-US/about_PSRule_Options/#outputpath","title":"Output.Path","text":"# Azure Pipelines: Using environment variable\nvariables:\n- name: PSRULE_OUTPUT_OUTCOME\n value: Fail\nSpecifies the output file path to write results. Directories along the file path will automatically be created if they do not exist.
This option only applies to
Invoke-PSRule.Invoke-PSRulealso includes a parameter-OutputPathto set this option at runtime. If specified, the-OutputPathparameter take precedence, over this option.Syntax:
output:\n path: string\nDefault:
output:\n path: null\nThis option can be specified using:
# PowerShell: Using the OutputPath parameter\n$option = New-PSRuleOption -OutputPath 'out/results.yaml';\n# PowerShell: Using the Output.Path hashtable key\n$option = New-PSRuleOption -Option @{ 'Output.Path' = 'out/results.yaml' };\n# PowerShell: Using the OutputPath parameter to set YAML\nSet-PSRuleOption -OutputPath 'out/results.yaml';\n# YAML: Using the output/path property\noutput:\n path: 'out/results.yaml'\n# Bash: Using environment variable\nexport PSRULE_OUTPUT_PATH=out/results.yaml\n# GitHub Actions: Using environment variable\nenv:\n PSRULE_OUTPUT_PATH: out/results.yaml\n
"},{"location":"concepts/PSRule/en-US/about_PSRule_Options/#outputsarifproblemsonly","title":"Output.SarifProblemsOnly","text":"# Azure Pipelines: Using environment variable\nvariables:\n- name: PSRULE_OUTPUT_PATH\n value: out/results.yaml\nDetermines if SARIF output only includes rules with fail or error outcomes. By default, only rules with fail or error outcomes are included for compatibility with external tools. To include rules with pass outcomes, set this option to
false. This option only applies when the output format isSarif.Syntax:
output:\n sarifProblemsOnly: boolean\nDefault:
output:\n sarifProblemsOnly: true\nThis option can be specified using:
# PowerShell: Using the OutputSarifProblemsOnly parameter\n$option = New-PSRuleOption -OutputSarifProblemsOnly $False;\n# PowerShell: Using the Output.SarifProblemsOnly hashtable key\n$option = New-PSRuleOption -Option @{ 'Output.SarifProblemsOnly' = $False };\n# PowerShell: Using the OutputSarifProblemsOnly parameter to set YAML\nSet-PSRuleOption -OutputSarifProblemsOnly $False;\n# YAML: Using the output/sarifProblemsOnly property\noutput:\n sarifProblemsOnly: false\n# Bash: Using environment variable\nexport PSRULE_OUTPUT_SARIFPROBLEMSONLY=false\n# GitHub Actions: Using environment variable\nenv:\n PSRULE_OUTPUT_SARIFPROBLEMSONLY: false\n
"},{"location":"concepts/PSRule/en-US/about_PSRule_Options/#outputstyle","title":"Output.Style","text":"# Azure Pipelines: Using environment variable\nvariables:\n- name: PSRULE_OUTPUT_SARIFPROBLEMSONLY\n value: false\nConfigures the style that results will be presented in.
This option only applies to output generated from
Assert-PSRule.Assert-PSRulealso include a parameter-Styleto set this option at runtime. If specified, the-Styleparameter takes precedence, over this option.The following styles are available:
Detect uses the following logic:
Syntax:
output:\n style: string\nDefault:
output:\n style: Detect\nThis option can be specified using:
# PowerShell: Using the OutputStyle parameter\n$option = New-PSRuleOption -OutputStyle AzurePipelines;\n# PowerShell: Using the Output.Style hashtable key\n$option = New-PSRuleOption -Option @{ 'Output.Style' = 'AzurePipelines' };\n# PowerShell: Using the OutputStyle parameter to set YAML\nSet-PSRuleOption -OutputFormat AzurePipelines;\n# YAML: Using the output/style property\noutput:\n style: AzurePipelines\n# Bash: Using environment variable\nexport PSRULE_OUTPUT_STYLE=AzurePipelines\n# GitHub Actions: Using environment variable\nenv:\n PSRULE_OUTPUT_STYLE: AzurePipelines\n
"},{"location":"concepts/PSRule/en-US/about_PSRule_Options/#outputjobsummarypath","title":"Output.JobSummaryPath","text":"# Azure Pipelines: Using environment variable\nvariables:\n- name: PSRULE_OUTPUT_STYLE\n value: AzurePipelines\nv2.6.0
Configures the file path a job summary will be written to when using
Assert-PSRule. A job summary is a markdown file that summarizes the results of a job. When not specified, a job summary will not be generated.Syntax:
output:\n jobSummaryPath: string\nDefault:
output:\n jobSummaryPath: null\nThis option can be specified using:
# PowerShell: Using the OutputJobSummaryPath parameter\n$option = New-PSRuleOption -OutputJobSummaryPath 'reports/summary.md';\n# PowerShell: Using the Output.JobSummaryPath hashtable key\n$option = New-PSRuleOption -Option @{ 'Output.JobSummaryPath' = 'reports/summary.md' };\n# PowerShell: Using the OutputJobSummaryPath parameter to set YAML\nSet-PSRuleOption -OutputJobSummaryPath 'reports/summary.md';\n# YAML: Using the output/jobSummaryPath property\noutput:\n jobSummaryPath: 'reports/summary.md'\n# Bash: Using environment variable\nexport PSRULE_OUTPUT_JOBSUMMARYPATH='reports/summary.md'\n# PowerShell: Using environment variable\n$env:PSRULE_OUTPUT_JOBSUMMARYPATH = 'reports/summary.md';\n# GitHub Actions: Using environment variable\nenv:\n PSRULE_OUTPUT_JOBSUMMARYPATH: reports/summary.md\n
"},{"location":"concepts/PSRule/en-US/about_PSRule_Options/#outputjsonindent","title":"Output.JsonIndent","text":"# Azure Pipelines: Using environment variable\nvariables:\n- name: PSRULE_OUTPUT_JOBSUMMARYPATH\n value: reports/summary.md\nConfigures the number of spaces to indent JSON properties and elements. The default number of spaces is 0.
This option applies to output generated from
-OutputFormat JsonforGet-PSRuleandInvoke-PSRule. This option also applies to output generated from-OutputPathforAssert-PSRule.The range of indentation accepts a minimum of 0 (machine first) spaces and a maximum of 4 spaces.
This option can be specified using:
# PowerShell: Using the OutputJsonIndent parameter\n$option = New-PSRuleOption -OutputJsonIndent 2;\n# PowerShell: Using the Output.JsonIndent hashtable key\n$option = New-PSRuleOption -Option @{ 'Output.JsonIndent' = 2 };\n# PowerShell: Using the OutputJsonIndent parameter to set YAML\nSet-PSRuleOption -OutputJsonIndent 2;\n# YAML: Using the output/jsonIndent property\noutput:\n jsonIndent: 2\n# Bash: Using environment variable\nexport PSRULE_OUTPUT_JSONINDENT=2\n# PowerShell: Using environment variable\n$env:PSRULE_OUTPUT_JSONINDENT = 2;\n# GitHub Actions: Using environment variable\nenv:\n PSRULE_OUTPUT_JSONINDENT: 2\n
"},{"location":"concepts/PSRule/en-US/about_PSRule_Options/#repositorybaseref","title":"Repository.BaseRef","text":"# Azure Pipelines: Using environment variable\nvariables:\n- name: PSRULE_OUTPUT_JSONINDENT\n value: 2\nThis option is used for specify the base branch for pull requests. When evaluating changes files only PSRule uses this option for comparison with the current branch. By default, the base ref is detected from environment variables set by the build system.
This option can be specified using:
# PowerShell: Using the RepositoryBaseRef parameter\n$option = New-PSRuleOption -RepositoryBaseRef 'main';\n# PowerShell: Using the Repository.BaseRef hashtable key\n$option = New-PSRuleOption -Option @{ 'Repository.BaseRef' = 'main' };\n# PowerShell: Using the RepositoryBaseRef parameter to set YAML\nSet-PSRuleOption -RepositoryBaseRef 'main';\n# YAML: Using the repository/baseRef property\nrepository:\n baseRef: main\n# Bash: Using environment variable\nexport PSRULE_REPOSITORY_BASEREF='main'\n
"},{"location":"concepts/PSRule/en-US/about_PSRule_Options/#repositoryurl","title":"Repository.Url","text":"# PowerShell: Using environment variable\n$env:PSRULE_REPOSITORY_BASEREF = 'main';\nThis option can be configured to set the repository URL reported in output. By default, the repository URL is detected from environment variables set by the build system.
This option can be specified using:
# PowerShell: Using the RepositoryUrl parameter\n$option = New-PSRuleOption -RepositoryUrl 'https://github.com/microsoft/PSRule';\n# PowerShell: Using the Repository.Url hashtable key\n$option = New-PSRuleOption -Option @{ 'Repository.Url' = 'https://github.com/microsoft/PSRule' };\n# PowerShell: Using the RepositoryUrl parameter to set YAML\nSet-PSRuleOption -RepositoryUrl 'https://github.com/microsoft/PSRule';\n# YAML: Using the repository/url property\nrepository:\n url: 'https://github.com/microsoft/PSRule'\n# Bash: Using environment variable\nexport PSRULE_REPOSITORY_URL='https://github.com/microsoft/PSRule'\n
"},{"location":"concepts/PSRule/en-US/about_PSRule_Options/#requires","title":"Requires","text":"# PowerShell: Using environment variable\n$env:PSRULE_REPOSITORY_URL = 'https://github.com/microsoft/PSRule';\nSpecifies module version constraints for running PSRule. When set PSRule will error if a module version is used that does not satisfy the requirements. The format for version constraints are the same as the
Versionassertion method. See [about_PSRule_Assert] for more information.Module version constraints a not enforced prior to PSRule v0.19.0.
The version constraint for a rule module is enforced when the module is included with
-Module. A version constraint does not require a rule module to be included. Use theInclude.Moduleoption to automatically include a rule module.This option can be specified using:
# PowerShell: Using the Requires.module hashtable key\n$option = New-PSRuleOption -Option @{ 'Requires.PSRule' = '>=1.0.0' };\n# YAML: Using the requires property\nrequires:\n PSRule: '>=1.0.0' # Require v1.0.0 or greater.\n PSRule.Rules.Azure: '>=1.0.0' # Require v1.0.0 or greater.\n PSRule.Rules.CAF: '@pre >=0.1.0' # Require stable or pre-releases v0.1.0 or greater.\nThis option can be configured using environment variables. To specify a module version constraint, prefix the module name with
PSRULE_REQUIRES_. When the module name includes a dot (.) use an underscore (_) instead.# Bash: Using environment variable\nexport PSRULE_REQUIRES_PSRULE='>=1.0.0'\nexport PSRULE_REQUIRES_PSRULE_RULES_AZURE='>=1.0.0'\nexport PSRULE_REQUIRES_PSRULE_RULES_CAF='@pre >=0.1.0'\n# GitHub Actions: Using environment variable\nenv:\n PSRULE_REQUIRES_PSRULE: '>=1.0.0'\n PSRULE_REQUIRES_PSRULE_RULES_AZURE: '>=1.0.0'\n PSRULE_REQUIRES_PSRULE_RULES_CAF: '@pre >=0.1.0'\n
"},{"location":"concepts/PSRule/en-US/about_PSRule_Options/#rulebaseline","title":"Rule.Baseline","text":"# Azure Pipelines: Using environment variable\nvariables:\n- name: PSRULE_REQUIRES_PSRULE\n value: '>=1.0.0'\n- name: PSRULE_REQUIRES_PSRULE_RULES_AZURE\n value: '>=1.0.0'\n- name: PSRULE_REQUIRES_PSRULE_RULES_CAF\n value: '@pre >=0.1.0'\nThe name of a default baseline to use for the module. Currently this option can only be set within a module configuration resource.
For example:
"},{"location":"concepts/PSRule/en-US/about_PSRule_Options/#ruleinclude","title":"Rule.Include","text":"---\n# Synopsis: Example module configuration for Enterprise.Rules module.\napiVersion: github.com/microsoft/PSRule/v1\nkind: ModuleConfig\nmetadata:\n name: Enterprise.Rules\nspec:\n rule:\n baseline: Enterprise.Baseline1\nThe name of specific rules to evaluate. If this option is not specified all rules in search paths will be evaluated.
This option can be overridden at runtime by using the
-Namecmdlet parameter.This option can be specified using:
# PowerShell: Using the Rule.Include hashtable key\n$option = New-PSRuleOption -Option @{ 'Rule.Include' = 'Rule1','Rule2' };\n# YAML: Using the rule/include property\nrule:\n include:\n - Rule1\n - Rule2\n# Bash: Using environment variable\nexport PSRULE_RULE_INCLUDE='Rule1;Rule2'\n# GitHub Actions: Using environment variable\nenv:\n PSRULE_RULE_INCLUDE: 'Rule1;Rule2'\n
"},{"location":"concepts/PSRule/en-US/about_PSRule_Options/#ruleincludelocal","title":"Rule.IncludeLocal","text":"# Azure Pipelines: Using environment variable\nvariables:\n- name: PSRULE_RULE_INCLUDE\n value: 'Rule1;Rule2'\nAutomatically include all local rules in the search path unless they have been explicitly excluded. This option will include local rules even when they do not match
Rule.IncludeorRule.Tagfilters. By default, local rules will be filtered withRule.IncludeandRule.Tagfilters.This option is useful when you want to include local rules not included in a baseline.
This option can be specified using:
# PowerShell: Using the RuleIncludeLocal parameter\n$option = New-PSRuleOption -RuleIncludeLocal $True;\n# PowerShell: Using the Rule.IncludeLocal hashtable key\n$option = New-PSRuleOption -Option @{ 'Rule.IncludeLocal' = $True };\n# PowerShell: Using the RuleIncludeLocal parameter to set YAML\nSet-PSRuleOption -RuleIncludeLocal $True;\n# YAML: Using the rule/includeLocal property\nrule:\n includeLocal: true\n# Bash: Using environment variable\nexport PSRULE_RULE_INCLUDELOCAL=true\n# GitHub Actions: Using environment variable\nenv:\n PSRULE_RULE_INCLUDELOCAL: true\n
"},{"location":"concepts/PSRule/en-US/about_PSRule_Options/#ruleexclude","title":"Rule.Exclude","text":"# Azure Pipelines: Using environment variable\nvariables:\n- name: PSRULE_RULE_INCLUDELOCAL\n value: true\nThe name of specific rules to exclude from being evaluated. This will exclude rules specified by
Rule.Includeor discovered from a search path.This option can be specified using:
# PowerShell: Using the Rule.Exclude hashtable key\n$option = New-PSRuleOption -Option @{ 'Rule.Exclude' = 'Rule3','Rule4' };\n# YAML: Using the rule/exclude property\nrule:\n exclude:\n - Rule3\n - Rule4\n# Bash: Using environment variable\nexport PSRULE_RULE_EXCLUDE='Rule3;Rule4'\n# GitHub Actions: Using environment variable\nenv:\n PSRULE_RULE_EXCLUDE: 'Rule3;Rule4'\n
"},{"location":"concepts/PSRule/en-US/about_PSRule_Options/#ruletag","title":"Rule.Tag","text":"# Azure Pipelines: Using environment variable\nvariables:\n- name: PSRULE_RULE_EXCLUDE\n value: 'Rule3;Rule4'\nA set of required key value pairs (tags) that rules must have applied to them to be included.
Multiple values can be specified for the same tag. When multiple values are used, only one must match.
This option can be overridden at runtime by using the
-Tagcmdlet parameter.This option can be specified using:
# PowerShell: Using the Rule.Tag hashtable key\n$option = New-PSRuleOption -Option @{ 'Rule.Tag' = @{ severity = 'Critical','Warning' } };\n# YAML: Using the rule/tag property\nrule:\n tag:\n severity: Critical\n# YAML: Using the rule/tag property, with multiple values\nrule:\n tag:\n severity:\n - Critical\n - Warning\nIn the example above, rules must have a tag of
"},{"location":"concepts/PSRule/en-US/about_PSRule_Options/#suppression","title":"Suppression","text":"severityset to eitherCriticalorWarningto be included.In certain circumstances it may be necessary to exclude or suppress rules from processing objects that are in a known failed state.
PSRule allows objects to be suppressed for a rule by TargetName. Objects that are suppressed are not processed by the rule at all but will continue to be processed by other rules.
Rule suppression complements pre-filtering and pre-conditions.
This option can be specified using:
# PowerShell: Using the SuppressTargetName option with a hashtable\n$option = New-PSRuleOption -SuppressTargetName @{ 'storageAccounts.UseHttps' = 'TestObject1', 'TestObject3' };\n# YAML: Using the suppression property\nsuppression:\n storageAccounts.UseHttps:\n targetName:\n - TestObject1\n - TestObject3\nIn both of the above examples,
TestObject1andTestObject3have been suppressed from being processed by a rule namedstorageAccounts.UseHttps.When to use rule suppression:
When not to use rule suppression:
An example of pre-filtering:
# Define objects to validate\n$items = @();\n$items += [PSCustomObject]@{ Name = 'Fridge'; Type = 'Equipment'; Category = 'White goods'; };\n$items += [PSCustomObject]@{ Name = 'Apple'; Type = 'Food'; Category = 'Produce'; };\n$items += [PSCustomObject]@{ Name = 'Carrot'; Type = 'Food'; Category = 'Produce'; };\n\n# Example of pre-filtering, only food items are sent to Invoke-PSRule\n$items | Where-Object { $_.Type -eq 'Food' } | Invoke-PSRule;\nAn example of pre-conditions:
"},{"location":"concepts/PSRule/en-US/about_PSRule_Options/#examples","title":"Examples","text":""},{"location":"concepts/PSRule/en-US/about_PSRule_Options/#example-ps-ruleyaml","title":"Example ps-rule.yaml","text":"# A rule with a pre-condition to only process produce\nRule 'isFruit' -If { $TargetObject.Category -eq 'Produce' } {\n # Condition to determine if the object is fruit\n $TargetObject.Name -in 'Apple', 'Orange', 'Pear'\n}\n
"},{"location":"concepts/PSRule/en-US/about_PSRule_Options/#default-ps-ruleyaml","title":"Default ps-rule.yaml","text":"#\n# PSRule example configuration\n#\n\n# Configures the repository\nrepository:\n url: https://github.com/microsoft/PSRule\n baseRef: main\n\n# Configure required module versions\nrequires:\n PSRule.Rules.Azure: '>=1.1.0'\n\n# Configure convention options\nconvention:\n include:\n - 'Convention1'\n\n# Configure execution options\nexecution:\n hashAlgorithm: SHA256\n duplicateResourceId: Warn\n languageMode: ConstrainedLanguage\n suppressionGroupExpired: Error\n restrictScriptSource: ModuleOnly\n\n# Configure include options\ninclude:\n module:\n - 'PSRule.Rules.Azure'\n path: [ ]\n\n# Configures input options\ninput:\n format: Yaml\n ignoreGitPath: false\n ignoreObjectSource: true\n ignoreRepositoryCommon: false\n ignoreUnchangedPath: true\n objectPath: items\n pathIgnore:\n - '*.Designer.cs'\n targetType:\n - Microsoft.Compute/virtualMachines\n - Microsoft.Network/virtualNetworks\n\n# Configures outcome logging options\nlogging:\n limitDebug:\n - Rule1\n - Rule2\n limitVerbose:\n - Rule1\n - Rule2\n ruleFail: Error\n rulePass: Information\n\noutput:\n as: Summary\n banner: Minimal\n culture:\n - en-US\n encoding: UTF8\n footer: RuleCount\n format: Json\n jobSummaryPath: reports/summary.md\n outcome: Fail\n sarifProblemsOnly: false\n style: GitHubActions\n\n# Configure rule suppression\nsuppression:\n storageAccounts.UseHttps:\n targetName:\n - TestObject1\n - TestObject3\n\n# Configure baseline options\nbinding:\n field:\n id:\n - ResourceId\n - AlternativeId\n ignoreCase: false\n nameSeparator: '::'\n preferTargetInfo: true\n targetName:\n - ResourceName\n - AlternateName\n targetType:\n - ResourceType\n - kind\n useQualifiedName: true\n\nconfiguration:\n appServiceMinInstanceCount: 2\n\nrule:\n include:\n - rule1\n - rule2\n includeLocal: true\n exclude:\n - rule3\n - rule4\n tag:\n severity:\n - Critical\n - Warning\n
"},{"location":"concepts/PSRule/en-US/about_PSRule_Options/#links","title":"Links","text":"#\n# PSRule defaults\n#\n\n# Note: Only properties that differ from the default values need to be specified.\n\n# Configure required module versions\nrequires: { }\n\n# Configure convention options\nconvention:\n include: [ ]\n\n# Configure execution options\nexecution:\n hashAlgorithm: SHA512\n aliasReference: Warn\n duplicateResourceId: Error\n invariantCulture: Warn\n languageMode: FullLanguage\n initialSessionState: BuiltIn\n restrictScriptSource: Unrestricted\n ruleInconclusive: Warn\n ruleSuppressed: Warn\n suppressionGroupExpired: Warn\n unprocessedObject: Warn\n\n# Configure include options\ninclude:\n module: [ ]\n path:\n - '.ps-rule/'\n\n# Configures input options\ninput:\n format: Detect\n ignoreGitPath: true\n ignoreObjectSource: false\n ignoreRepositoryCommon: true\n ignoreUnchangedPath: false\n objectPath: null\n pathIgnore: [ ]\n targetType: [ ]\n\n# Configures outcome logging options\nlogging:\n limitDebug: [ ]\n limitVerbose: [ ]\n ruleFail: None\n rulePass: None\n\noutput:\n as: Detail\n banner: Default\n culture: [ ]\n encoding: Default\n footer: Default\n format: None\n jobSummaryPath: null\n outcome: Processed\n sarifProblemsOnly: true\n style: Detect\n\n# Configure rule suppression\nsuppression: { }\n\n# Configure baseline options\nbinding:\n field: { }\n ignoreCase: true\n nameSeparator: '/'\n preferTargetInfo: false\n targetName:\n - TargetName\n - Name\n targetType:\n - PSObject.TypeNames[0]\n useQualifiedName: false\n\nconfiguration: { }\n\nrule:\n include: [ ]\n includeLocal: false\n exclude: [ ]\n tag: { }\nDescribes PSRule rules including how to use and author them.
"},{"location":"concepts/PSRule/en-US/about_PSRule_Rules/#description","title":"Description","text":"PSRule executes rules to validate an object from input either from a file or PowerShell pipeline. The PowerShell pipeline only available when running PSRule directly. PSRule can also be run from a continuous integration (CI) pipeline or Visual Studio Code. When using these methods, the PowerShell pipeline is not available.
To evaluate an object PSRule can use rules defined in script or YAML.
When using script rules:
To learn more about assertion helpers see about_PSRule_Assert.
When using YAML rules:
To learn more about YAML-based expressions see about_PSRule_Expressions.
"},{"location":"concepts/PSRule/en-US/about_PSRule_Rules/#using-pre-conditions","title":"Using pre-conditions","text":"Pre-conditions are used to determine if a rule should be executed. While pre-conditions are not required for each rule, it is a good practice to define them. If a rule does not specify a pre-condition it may be executed against an object it does not expect.
Pre-conditions come in three forms:
Different forms of pre-conditions can be combined. When combining pre-conditions, different forms must be all true (logical AND). i.e. Script AND Type AND Selector must be all be true for the rule to be executed.
Multiple Type and Selector pre-conditions can be specified. If multiple Type and Selector pre-conditions are specified, only one must be true (logical OR).
For example:
# Synopsis: An example script rule with pre-conditions.\nRule 'ScriptRule' -If { $True } -Type 'CustomType1', 'CustomType2' -With 'Selector.1', 'Selector.2' {\n # Rule condition\n}\n---\n# Synopsis: An example YAML rule with pre-conditions.\napiVersion: github.com/microsoft/PSRule/v1\nkind: Rule\nmetadata:\n name: 'YamlRule'\nspec:\n type:\n - 'CustomType1'\n - 'CustomType2'\n with:\n - 'Selector.1'\n - 'Selector.2'\n condition: { }\n[\n {\n // Synopsis: An example YAML rule with pre-conditions.\n \"apiVersion\": \"github.com/microsoft/PSRule/v1\",\n \"kind\": \"Rule\",\n \"metadata\": {\n \"name\": \"YamlRule\"\n },\n \"spec\": {\n \"type\": [\n \"CustomType1\",\n \"CustomType2\"\n ],\n \"with\": [\n \"Selector.1\",\n \"Selector.2\"\n ],\n \"condition\": {}\n }\n }\n]\nPre-conditions are evaluated in the following order: Selector, Type, then Script.
"},{"location":"concepts/PSRule/en-US/about_PSRule_Rules/#defining-script-rules","title":"Defining script rules","text":"To define a script rule use the
Rulekeyword followed by a name and a pair of squiggly brackets{. Within the{ }one or more conditions can be used. Script rule must be defined within.Rule.ps1files. Multiple rules can be defined in a single file by creating multipleRuleblocks. Rule blocks can not be nested within each other.Within the
Ruleblock, define one or more conditions to determine pass or fail of the rule.Syntax:
Rule [-Name] <string> [-Tag <hashtable>] [-When <string[]>] [-Type <string[]>] [-If <scriptBlock>] [-DependsOn <string[]>] [-Configure <hashtable>] [-ErrorAction <ActionPreference>] [-Body] {\n ...\n}\nExample:
"},{"location":"concepts/PSRule/en-US/about_PSRule_Rules/#defining-yaml-rules","title":"Defining YAML rules","text":"# Synopsis: Use a Standard load-balancer with AKS clusters.\nRule 'Azure.AKS.StandardLB' -Type 'Microsoft.ContainerService/managedClusters' -Tag @{ release = 'GA'; ruleSet = '2020_06' } {\n $Assert.HasFieldValue($TargetObject, 'Properties.networkProfile.loadBalancerSku', 'standard');\n}\nTo define a YAML rule use the
Ruleresource in a YAML file. Each rule must be defined within a.Rule.yamlfile following a standard schema. Multiple rules can be defined in a single YAML file by separating each rule with a---.Within the
Ruleresource, theconditionproperty specifies conditions to pass or fail the rule.Syntax:
---\n# Synopsis: {{ Synopsis }}\napiVersion: github.com/microsoft/PSRule/v1\nkind: Rule\nmetadata:\n name: '{{ Name }}'\n tags: { }\nspec:\n type: [ ]\n with: [ ]\n condition: { }\nExample:
"},{"location":"concepts/PSRule/en-US/about_PSRule_Rules/#defining-json-rules","title":"Defining JSON rules","text":"---\n# Synopsis: Use a Standard load-balancer with AKS clusters.\napiVersion: github.com/microsoft/PSRule/v1\nkind: Rule\nmetadata:\n name: 'Azure.AKS.StandardLB'\n tags:\n release: 'GA'\n ruleSet: '2020_06'\nspec:\n type:\n - Microsoft.ContainerService/managedClusters\n condition:\n field: 'Properties.networkProfile.loadBalancerSku'\n equals: 'standard'\nTo define a JSON rule use the
Ruleresource in a JSON file. Each rule must be defined within a.Rule.jsoncfile following a standard schema. One or more rules can be defined in a single JSON array separating each rule in a JSON object.Within the
Ruleresource, theconditionproperty specifies conditions to pass or fail the rule.Rules can also be defined within
.jsonfiles. We recommend using.jsoncto view JSON with Comments in Visual Studio Code.Syntax:
[\n {\n // Synopsis: {{ Synopsis }}\n \"apiVersion\": \"github.com/microsoft/PSRule/v1\",\n \"kind\": \"Rule\",\n \"metadata\": {\n \"name\": \"{{ Name }}\",\n \"tags\": {}\n },\n \"spec\": {\n \"type\": [],\n \"with\": [],\n \"condition\": {}\n }\n }\n]\nExample:
"},{"location":"concepts/PSRule/en-US/about_PSRule_Rules/#links","title":"Links","text":"[\n {\n // Synopsis: Use a Standard load-balancer with AKS clusters.\n \"apiVersion\": \"github.com/microsoft/PSRule/v1\",\n \"kind\": \"Rule\",\n \"metadata\": {\n \"name\": \"Azure.AKS.StandardLB\",\n \"tags\": {\n \"release\": \"GA\",\n \"ruleSet\": \"2020_06\"\n }\n },\n \"spec\": {\n \"type\": [\n \"Microsoft.ContainerService/managedClusters\"\n ],\n \"condition\": {\n \"field\": \"Properties.networkProfile.loadBalancerSku\",\n \"equals\": \"standard\"\n }\n }\n }\n]\nDescribes PSRule Selectors including how to use and author them.
"},{"location":"concepts/PSRule/en-US/about_PSRule_Selectors/#description","title":"Description","text":"PSRule executes rules to validate an object from input. When evaluating an object from input, PSRule can use selectors to perform complex matches of an object.
The following conditions are available:
The following operators are available:
The following comparison properties are available:
To learn more about conditions, operators, and properties see about_PSRule_Expressions.
Currently the following limitations apply:
Selectors can be referenced by name as a rule pre-condition by using the
-Withparameter. For example:Rule 'RuleWithSelector' -With 'BasicSelector' {\n # Rule condition\n}\nSelector pre-conditions can be used together with type and script block pre-conditions. If one or more selector pre-conditions are used, they are evaluated before type or script block pre-conditions.
"},{"location":"concepts/PSRule/en-US/about_PSRule_Selectors/#defining-selectors","title":"Defining selectors","text":"Selectors can be defined with either YAML or JSON format, and can be included with a module or standalone
.Rule.yamlor.Rule.jsoncfile. In either case, define a selector within a file ending with the.Rule.yamlor.Rule.jsoncextension. A selector can be defined side-by-side with other resources such as baselines or module configurations.Selectors can also be defined within
.jsonfiles. We recommend using.jsoncto view JSON with Comments in Visual Studio Code.Use the following template to define a selector:
---\n# Synopsis: {{ Synopsis }}\napiVersion: github.com/microsoft/PSRule/v1\nkind: Selector\nmetadata:\n name: '{{ Name }}'\nspec:\n if: { }\n[\n {\n // Synopsis: {{ Synopsis }}\n \"apiVersion\": \"github.com/microsoft/PSRule/v1\",\n \"kind\": \"Selector\",\n \"metadata\": {\n \"name\": \"{{ Name }}\"\n },\n \"spec\": {\n \"if\": {}\n }\n }\n]\nWithin the
"},{"location":"concepts/PSRule/en-US/about_PSRule_Selectors/#examples","title":"Examples","text":""},{"location":"concepts/PSRule/en-US/about_PSRule_Selectors/#example-selectorsruleyaml","title":"Example Selectors.Rule.yaml","text":"ifobject, one or more conditions or logical operators can be used.
"},{"location":"concepts/PSRule/en-US/about_PSRule_Selectors/#example-selectorsrulejsonc","title":"Example Selectors.Rule.jsonc","text":"# Example Selectors.Rule.yaml\n---\n# Synopsis: Require the CustomValue field.\napiVersion: github.com/microsoft/PSRule/v1\nkind: Selector\nmetadata:\n name: RequireCustomValue\nspec:\n if:\n field: 'CustomValue'\n exists: true\n\n---\n# Synopsis: Require a Name or AlternativeName.\napiVersion: github.com/microsoft/PSRule/v1\nkind: Selector\nmetadata:\n name: RequireName\nspec:\n if:\n anyOf:\n - field: 'AlternateName'\n exists: true\n - field: 'Name'\n exists: true\n\n---\n# Synopsis: Require a specific CustomValue\napiVersion: github.com/microsoft/PSRule/v1\nkind: Selector\nmetadata:\n name: RequireSpecificCustomValue\nspec:\n if:\n field: 'CustomValue'\n in:\n - 'Value1'\n - 'Value2'\n
"},{"location":"concepts/PSRule/en-US/about_PSRule_Selectors/#links","title":"Links","text":"// Example Selectors.Rule.jsonc\n[\n {\n // Synopsis: Require the CustomValue field.\n \"apiVersion\": \"github.com/microsoft/PSRule/v1\",\n \"kind\": \"Selector\",\n \"metadata\": {\n \"name\": \"RequireCustomValue\"\n },\n \"spec\": {\n \"if\": {\n \"field\": \"CustomValue\",\n \"exists\": true\n }\n }\n },\n {\n // Synopsis: Require a Name or AlternativeName.\n \"apiVersion\": \"github.com/microsoft/PSRule/v1\",\n \"kind\": \"Selector\",\n \"metadata\": {\n \"name\": \"RequireName\"\n },\n \"spec\": {\n \"if\": {\n \"anyOf\": [\n {\n \"field\": \"AlternateName\",\n \"exists\": true\n },\n {\n \"field\": \"Name\",\n \"exists\": true\n }\n ]\n }\n }\n },\n {\n // Synopsis: Require a specific CustomValue\n \"apiVersion\": \"github.com/microsoft/PSRule/v1\",\n \"kind\": \"Selector\",\n \"metadata\": {\n \"name\": \"RequireSpecificCustomValue\"\n },\n \"spec\": {\n \"if\": {\n \"field\": \"CustomValue\",\n \"in\": [\n \"Value1\",\n \"Value2\"\n ]\n }\n }\n }\n]\nDescribes PSRule Suppression Groups including how to use and author them.
"},{"location":"concepts/PSRule/en-US/about_PSRule_SuppressionGroups/#description","title":"Description","text":"PSRule executes rules to validate an object from input. When an evaluating each object, PSRule can use suppression groups to suppress rules based on a condition. Suppression groups use a Selector to determine if the rule is suppressed.
"},{"location":"concepts/PSRule/en-US/about_PSRule_SuppressionGroups/#defining-suppression-groups","title":"Defining suppression groups","text":"Suppression groups can be defined using either YAML or JSON format. A suppression group can be in a standalone file or included in a module. Define suppression groups in
.Rule.yamlor.Rule.jsoncfiles. Each suppression group may be defined individually or side-by-side with resources such as rules or baselines.Suppression groups can also be defined within
.jsonfiles. We recommend using.jsoncto view JSON with Comments in Visual Studio Code.Use the following template to define a suppression group:
---\n# Synopsis: {{ Synopsis }}\napiVersion: github.com/microsoft/PSRule/v1\nkind: SuppressionGroup\nmetadata:\n name: '{{ Name }}'\nspec:\n expiresOn: null\n rule: []\n if: { }\n[\n {\n // Synopsis: {{ Synopsis }}\n \"apiVersion\": \"github.com/microsoft/PSRule/v1\",\n \"kind\": \"SuppressionGroup\",\n \"metadata\": {\n \"name\": \"{{ Name }}\"\n },\n \"spec\": {\n \"expiresOn\": null,\n \"rule\": [],\n \"if\": {}\n }\n }\n]\nSet the
synopsisto describe the justification for the suppression. Within therulearray, one or more rule names can be used. If no rules are specified, suppression will occur for all rules. Within theifobject, one or more conditions or logical operators can be used. When theifcondition istruethe object will be suppressed for the current rule.Optionally, an expiry can be set using the
"},{"location":"concepts/PSRule/en-US/about_PSRule_SuppressionGroups/#documentation","title":"Documentation","text":"expiresOnproperty. When the expiry date is reached, the suppression will no longer be applied. To configure an expiry, set a RFC3339 (ISO 8601) formatted date time using the formatyyyy-MM-ddTHH:mm:ssZ.Suppression groups can be configured with a synopsis. When set, the synopsis will be included in output for any suppression warnings that are shown. The synopsis helps provide justification for the suppression, in a short single line message. To set the synopsis, include a comment above the suppression group
apiVersionproperty.Alternatively, a localized synopsis can be provided in a separate markdown file. See about_PSRule_Docs for details.
Some examples of a suppression group synopsis include:
"},{"location":"concepts/PSRule/en-US/about_PSRule_SuppressionGroups/#example-suppressiongroupsrulejsonc","title":"Example SuppressionGroups.Rule.jsonc","text":"# Example SuppressionGroups.Rule.yaml\n\n---\n# Synopsis: Ignore test objects by name.\napiVersion: github.com/microsoft/PSRule/v1\nkind: SuppressionGroup\nmetadata:\n name: SuppressWithTargetName\nspec:\n rule:\n - 'FromFile1'\n - 'FromFile2'\n if:\n name: '.'\n in:\n - 'TestObject1'\n - 'TestObject2'\n\n---\n# Synopsis: Ignore test objects by type.\napiVersion: github.com/microsoft/PSRule/v1\nkind: SuppressionGroup\nmetadata:\n name: SuppressWithTestType\nspec:\n expiresOn: '2030-01-01T00:00:00Z'\n rule:\n - 'FromFile3'\n - 'FromFile5'\n if:\n type: '.'\n equals: 'TestType'\n
"},{"location":"concepts/PSRule/en-US/about_PSRule_SuppressionGroups/#links","title":"Links","text":"// Example SuppressionGroups.Rule.jsonc\n[\n {\n // Synopsis: Ignore test objects by name.\n \"apiVersion\": \"github.com/microsoft/PSRule/v1\",\n \"kind\": \"SuppressionGroup\",\n \"metadata\": {\n \"name\": \"SuppressWithTargetName\"\n },\n \"spec\": {\n \"rule\": [\n \"FromFile1\",\n \"FromFile2\"\n ],\n \"if\": {\n \"name\": \".\",\n \"in\": [\n \"TestObject1\",\n \"TestObject2\"\n ]\n }\n }\n },\n {\n // Synopsis: Ignore test objects by type.\n \"apiVersion\": \"github.com/microsoft/PSRule/v1\",\n \"kind\": \"SuppressionGroup\",\n \"metadata\": {\n \"name\": \"SuppressWithTestType\"\n },\n \"spec\": {\n \"expiresOn\": \"2030-01-01T00:00:00Z\",\n \"rule\": [\n \"FromFile3\",\n \"FromFile5\"\n ],\n \"if\": {\n \"type\": \".\",\n \"equals\": \"TestType\"\n }\n }\n }\n]\nDescribes the automatic variables that can be used within PSRule rule definitions.
"},{"location":"concepts/PSRule/en-US/about_PSRule_Variables/#description","title":"Description","text":"PSRule lets you define rules using PowerShell blocks. A rule is defined within script files by using the
rulekeyword.Within a rule definition, PSRule exposes a number of automatic variables that can be read to assist with rule execution. Overwriting these variables or variable properties is not supported.
These variables are only available while
Invoke-PSRuleis executing.The following variables are available for use:
An assertion helper with methods to evaluate objects. The
$Assertobject provides a set of built-in methods and provides a consistent variable for extension.Each
$Assertmethod returns anAssertResultobject that contains the result of the condition.The following built-in assertion methods are provided:
The
$Assertvariable can only be used within a rule definition block.For detailed information on the assertion helper see about_PSRule_Assert.
Syntax:
$Assert\nExamples:
"},{"location":"concepts/PSRule/en-US/about_PSRule_Variables/#configuration","title":"Configuration","text":"# Synopsis: Determine if $TargetObject is valid against the provided schema\nRule 'UseJsonSchema' {\n $Assert.JsonSchema($TargetObject, 'schemas/PSRule-options.schema.json')\n}\nA dynamic object with properties names that map to configuration values set in the baseline.
When accessing configuration:
The following helper methods are available:
Syntax:
$Configuration.<configurationKey>\n$Configuration.GetStringValues(<configurationKey>)\nExamples:
"},{"location":"concepts/PSRule/en-US/about_PSRule_Variables/#localizeddata","title":"LocalizedData","text":"# Synopsis: This rule uses a threshold stored as $Configuration.appServiceMinInstanceCount\nRule 'appServicePlan.MinInstanceCount' -If { $TargetObject.ResourceType -eq 'Microsoft.Web/serverfarms' } {\n $TargetObject.Sku.capacity -ge $Configuration.appServiceMinInstanceCount\n} -Configure @{ appServiceMinInstanceCount = 2 }\nA dynamic object with properties names that map to localized data messages in a
.psd1file.When using localized data, PSRule loads localized strings as a hashtable from
PSRule-rules.psd1.The following logic is used to locate
PSRule-rules.psd1:When accessing localized data:
Syntax:
$LocalizedData.<messageName>\nExamples:
# Data for rules stored in PSRule-rules.psd1\n@{\n WithLocalizedDataMessage = 'LocalizedMessage for en-ZZ. Format={0}.'\n}\n# Synopsis: Use -f to generate a formatted localized warning\nRule 'WithLocalizedData' {\n Write-Warning -Message ($LocalizedData.WithLocalizedDataMessage -f $TargetObject.Type)\n}\nThis rule returns a warning message similar to:
"},{"location":"concepts/PSRule/en-US/about_PSRule_Variables/#psrule","title":"PSRule","text":"LocalizedMessage for en-ZZ. Format=TestType.\nAn object representing the current context during execution.
The following properties are available for read access:
The following properties are available for read/ write access:
To bind fields that already exist on the target object use custom binding and
Binding.Field. Use custom data to store data that must be calculated during rule execution.The following helper methods are available:
The file format is detected based on the same file formats as the option
Input.Format. i.e. Yaml, Json, Markdown, and PowerShell Data.Syntax:
$PSRule\nExamples:
# Synopsis: This rule determines if the target object matches the naming convention\nRule 'NamingConvention' {\n $PSRule.TargetName.ToLower() -ceq $PSRule.TargetName\n}\n
"},{"location":"concepts/PSRule/en-US/about_PSRule_Variables/#rule","title":"Rule","text":"# Synopsis: Use allowed environment tags\nRule 'CustomData' {\n Recommend 'Environment must be set to an allowed value'\n Within 'Tags.environment' 'production', 'test', 'development'\n\n if ($TargetObject.Tags.environment -in 'prod') {\n $PSRule.Data['targetEnvironment'] = 'production'\n }\n elseif ($TargetObject.Tags.environment -in 'dev', 'develop') {\n $PSRule.Data['targetEnvironment'] = 'development'\n }\n elseif ($TargetObject.Tags.environment -in 'tst', 'testing') {\n $PSRule.Data['targetEnvironment'] = 'test'\n }\n}\nAn object representing the current rule during execution.
The following properties are available for read access:
Syntax:
$Rule\nExamples:
"},{"location":"concepts/PSRule/en-US/about_PSRule_Variables/#targetobject","title":"TargetObject","text":"# Synopsis: This rule determines if the target object matches the naming convention\nRule 'resource.NamingConvention' {\n $PSRule.TargetName.ToLower() -ceq $PSRule.TargetName\n}\nThe value of the pipeline object currently being processed.
$TargetObjectis set by using the-InputObjectparameter ofInvoke-PSRule.When more than one input object is set, each object will be processed sequentially.
Syntax:
$TargetObject\nExamples:
"},{"location":"concepts/PSRule/en-US/about_PSRule_Variables/#links","title":"Links","text":"# Synopsis: Check that sku capacity is set to at least 2\nRule 'HasMinInstances' {\n $TargetObject.Sku.capacity -ge 2\n}\nAbstract
PSRule provides a command-line interface (CLI) to run rules and analyze results. This article describes the commands available in the CLI.
For details on installing the PSRule CLI, see Install PSRule.
"},{"location":"concepts/cli/#commands","title":"Commands","text":"The following commands are available in the CLI:
--version","text":"Show the version information for PSRule.
For example:
"},{"location":"concepts/cli/#global-options","title":"Global options","text":"ps-rule --version\nThe following global options can be used with any command:
"},{"location":"concepts/cli/#-option","title":"--option","text":"Specifies the path to an options file. By default, the CLI will look for a file named
"},{"location":"concepts/cli/#-h-help","title":"ps-rule.yamlin the current directory.-?|-h|--help","text":"Display help and usage information for the PSRule CLI and commands. To display help for a specific command, use
--helpwith the command name.For example:
"},{"location":"concepts/cli/#-verbose","title":"ps-rule run --help\n--verbose","text":"Display verbose output for the selected command.
"},{"location":"concepts/cli/#-debug","title":"--debug","text":"Display debug output for the selected command.
"},{"location":"concepts/cli/module/","title":"ps-rule module","text":"Abstract
Use the
"},{"location":"concepts/cli/module/#usage","title":"Usage","text":"PSRule CLI command-linemodulecommand to manage or restore modules tracked by the module lock file and configured options. (ps-rule.lock.json). The module lock file, provides consistent module versions across multiple machines and environments. For more information, see Lock file.ps-rule module [subcommand] [options]\nTo use the
modulecommand, choose one of the available subcommands:module init","text":"Initialize a new lock file based on existing options. Using this command, the module lock file is created or updated.
If
ps-rule.yamloption are configured to included module (Include.Modules), these a automatically added to the lock file. Any required version constraints set by theRequiresoption are taken into consideration.Optional parameters:
For example:
PSRule CLI command-lineps-rule module init\nFor example, force the creation of a new lock file, even if one already exists:
PSRule CLI command-line
"},{"location":"concepts/cli/module/#module-list","title":"ps-rule module init --force\nmodule list","text":"List any module and the installed versions from the lock file.
"},{"location":"concepts/cli/module/#module-add","title":"module add","text":"Add one or more modules to the module lock file. If the lock file does not exist, it is created.
By default, the latest stable version of the module is added. Any required version constraints set by the
Requiresoption are taken into consideration.To use a specific module version, use the
--versionargument.Optional parameters:
For example:
PSRule CLI command-lineps-rule module add PSRule.Rules.Azure\nFor example, a specific version of the module is added:
PSRule CLI command-line
"},{"location":"concepts/cli/module/#module-remove","title":"ps-rule module add PSRule.Rules.Azure --version 1.32.1\nmodule remove","text":"Remove one or more modules from the lock file.
For example:
PSRule CLI command-line
"},{"location":"concepts/cli/module/#module-restore","title":"ps-rule module remove PSRule.Rules.Azure\nmodule restore","text":"Restore modules from the module lock file (
ps-rule.lock.json) and configured options.Optional parameters:
For example:
PSRule CLI command-lineps-rule module restore\nFor example, force restore of all modules:
PSRule CLI command-line
"},{"location":"concepts/cli/module/#module-upgrade","title":"ps-rule module restore --force\nmodule upgrade","text":"Upgrade to the latest versions any modules within the lock file.
For example:
PSRule CLI command-line
"},{"location":"concepts/cli/module/#next-steps","title":"Next steps","text":"ps-rule module upgrade\nFor more information on the module lock file, see Lock file.
To find out more about the commands available with the PSRule CLI, see PSRule CLI.
"},{"location":"concepts/cli/run/","title":"ps-rule run","text":"Abstract
Use the
"},{"location":"concepts/cli/run/#usage","title":"Usage","text":"PSRule CLI command-lineruncommand to run rules against an input path and output the results.
"},{"location":"concepts/cli/run/#options","title":"Options","text":""},{"location":"concepts/cli/run/#-input-path-f","title":"ps-rule run [options]\n--input-path|-f","text":"The file or directory path to search for input file to use during a run. By default, this is the current working path.
"},{"location":"concepts/cli/run/#-module-m","title":"--module|-m","text":"The name of one or more modules that contain rules or resources to use during a run.
"},{"location":"concepts/cli/run/#-baseline","title":"--baseline","text":"The name of a specific baseline to use. Currently, only a single baseline can be used during a run.
"},{"location":"concepts/cli/run/#-outcome","title":"--outcome","text":"Specifies the rule results to show in output. By default,
Pass/Fail/Errorresults are shown.Allows filtering of results by outcome. The supported values are:
To specify multiple values, specify the parameter multiple times. For example:
"},{"location":"concepts/cli/run/#-output-o","title":"--outcome Pass --Outcome Fail.--output|-o","text":"Specifies the format to use when outputting results.
"},{"location":"concepts/cli/run/#-output-path","title":"--output-path","text":"Specifies a path to write results to.
"},{"location":"concepts/cli/run/#next-steps","title":"Next steps","text":"To find out more about the commands available with the PSRule CLI, see PSRule CLI.
"},{"location":"expressions/functions/","title":"Functions","text":"Abstract
Functions are an advanced language feature specific to YAML and JSON expressions. That extend the language to allow for more complex use cases with expressions. Functions don't apply to script expressions because PowerShell already has rich support for complex manipulation.
Experimental
Functions are a work in progress and subject to change. We hope to add more functions, broader support, and more detailed documentation in the future. Join or start a discussion to let us know how we can improve this feature going forward.
Functions cover two (2) main scenarios:
It may be necessary to perform minor transformation before evaluating a condition.
Currently functions are only supported on a subset of conditions. The conditions that are supported are:
"},{"location":"expressions/functions/#recommended-content","title":"Recommended content","text":"---\n# Synopsis: An expression function example.\napiVersion: github.com/microsoft/PSRule/v1\nkind: Selector\nmetadata:\n name: Yaml.Fn.Example1\nspec:\n if:\n value:\n $:\n substring:\n path: name\n length: 7\n equals: TestObj\n\n---\n# Synopsis: An expression function example.\napiVersion: github.com/microsoft/PSRule/v1\nkind: Selector\nmetadata:\n name: Yaml.Fn.Example2\nspec:\n if:\n value:\n $:\n configuration: 'ConfigArray'\n count: 5\n\n---\n# Synopsis: An expression function example.\napiVersion: github.com/microsoft/PSRule/v1\nkind: Selector\nmetadata:\n name: Yaml.Fn.Example3\nspec:\n if:\n value:\n $:\n boolean: true\n equals: true\n\n---\n# Synopsis: An expression function example.\napiVersion: github.com/microsoft/PSRule/v1\nkind: Selector\nmetadata:\n name: Yaml.Fn.Example4\nspec:\n if:\n value:\n $:\n concat:\n - path: name\n - string: '-'\n - path: name\n equals: TestObject1-TestObject1\n\n---\n# Synopsis: An expression function example.\napiVersion: github.com/microsoft/PSRule/v1\nkind: Selector\nmetadata:\n name: Yaml.Fn.Example5\nspec:\n if:\n value:\n $:\n integer: 6\n greater: 5\n\n---\n# Synopsis: An expression function example.\napiVersion: github.com/microsoft/PSRule/v1\nkind: Selector\nmetadata:\n name: Yaml.Fn.Example6\nspec:\n if:\n value: TestObject1-TestObject1\n equals:\n $:\n concat:\n - path: name\n - string: '-'\n - path: name\nAbstract
This topic covers sub-selectors which are a PSRule language feature specific to YAML and JSON expressions. They are useful for filtering out objects that you do not want to evaluate. Sub-selectors don't apply to script expressions because PowerShell already has rich support for filtering.
Experimental
Sub-selectors are a work in progress and subject to change. We hope to add broader support, and more detailed documentation in the future. Join or start a discussion to let us know how we can improve this feature going forward.
Sub-selectors cover two (2) main scenarios:
PSRule can process many different types of objects. Rules however, are normally written to test a specific property or type of object. So it is important that rules only run on objects that you want to evaluate. Pre-condition sub-selectors are one way you can determine if a rule should be run.
To use a sub-selector as a pre-condition, use the
whereproperty, directly under thespec. The expressions in the sub-selector follow the same form that you can use in rules.For example:
YAMLJSON---\n# Synopsis: A rule with a sub-selector precondition.\napiVersion: github.com/microsoft/PSRule/v1\nkind: Rule\nmetadata:\n name: Yaml.Subselector.Precondition\nspec:\n where:\n field: 'kind'\n equals: 'api'\n condition:\n field: resources\n count: 10\n{\n // Synopsis: A rule with a sub-selector precondition.\n \"apiVersion\": \"github.com/microsoft/PSRule/v1\",\n \"kind\": \"Rule\",\n \"metadata\": {\n \"name\": \"Json.Subselector.Precondition\"\n },\n \"spec\": {\n \"where\": {\n \"field\": \"kind\",\n \"equals\": \"api\"\n },\n \"condition\": {\n \"field\": \"resources\",\n \"count\": 10\n }\n }\n}\nIn the example:
The rule does not run if the:
Tip
Other types of pre-conditions also exist that allow you to filter based on type or by a shared selector.
"},{"location":"expressions/sub-selectors/#object-filter","title":"Object filter","text":"When you are evaluating an object, you can use sub-selectors to limit the condition. This is helpful when dealing with properties that are a list of items. Properties that contain a list of items may contain a sub-set of items that you want to evaluate.
For example, the object may look like this:
YAMLJSONname: app1\ntype: Microsoft.Web/sites\nresources:\n- name: web\n type: Microsoft.Web/sites/config\n properties:\n detailedErrorLoggingEnabled: true\n{\n \"name\": \"app1\",\n \"type\": \"Microsoft.Web/sites\",\n \"resources\": [\n {\n \"name\": \"web\",\n \"type\": \"Microsoft.Web/sites/config\",\n \"properties\": {\n \"detailedErrorLoggingEnabled\": true\n }\n }\n ]\n}\nA rule to test if any sub-resources with the
YAMLJSONdetailedErrorLoggingEnabledset totrueexist might look like this:---\n# Synopsis: A rule with a sub-selector filter.\napiVersion: github.com/microsoft/PSRule/v1\nkind: Rule\nmetadata:\n name: Yaml.Subselector.Filter\nspec:\n condition:\n field: resources\n where:\n type: '.'\n equals: 'Microsoft.Web/sites/config'\n allOf:\n - field: properties.detailedErrorLoggingEnabled\n equals: true\n{\n // Synopsis: A rule with a sub-selector filter.\n \"apiVersion\": \"github.com/microsoft/PSRule/v1\",\n \"kind\": \"Rule\",\n \"metadata\": {\n \"name\": \"Json.Subselector.Filter\"\n },\n \"spec\": {\n \"condition\": {\n \"field\": \"resources\",\n \"where\": {\n \"type\": \".\",\n \"equals\": \"Microsoft.Web/sites/config\"\n },\n \"allOf\": [\n {\n \"field\": \"properties.detailedErrorLoggingEnabled\",\n \"equals\": true\n }\n ]\n }\n }\n}\nIn the example:
Given the example, is important to understand what happens by default if:
In either of these two cases, the sub-selector will return
falseand fail the rule. The rule fails because there is no secondary conditions that could be used instead.If this was not the desired behavior, you could:
For example:
YAMLJSON---\n# Synopsis: A rule with a sub-selector filter.\napiVersion: github.com/microsoft/PSRule/v1\nkind: Rule\nmetadata:\n name: Yaml.Subselector.FilterOr\nspec:\n condition:\n anyOf:\n\n - field: resources\n where:\n type: '.'\n equals: 'Microsoft.Web/sites/config'\n allOf:\n - field: properties.detailedErrorLoggingEnabled\n equals: true\n\n - field: resources\n exists: false\n{\n // Synopsis: A rule with a sub-selector filter.\n \"apiVersion\": \"github.com/microsoft/PSRule/v1\",\n \"kind\": \"Rule\",\n \"metadata\": {\n \"name\": \"Json.Subselector.FilterOr\"\n },\n \"spec\": {\n \"condition\": {\n \"anyOf\": [\n {\n \"field\": \"resources\",\n \"where\": {\n \"type\": \".\",\n \"equals\": \"Microsoft.Web/sites/config\"\n },\n \"allOf\": [\n {\n \"field\": \"properties.detailedErrorLoggingEnabled\",\n \"equals\": true\n }\n ]\n },\n {\n \"field\": \"resources\",\n \"exists\": false\n }\n ]\n }\n }\n}\nIn the example:
When iterating over a list of items, you may want to determine how many items must match. A quantifier determines how many items in the list match. Matching items must be:
Supported quantifiers are:
For example:
YAMLJSON---\n# Synopsis: A rule with a sub-selector quantifier.\napiVersion: github.com/microsoft/PSRule/v1\nkind: Rule\nmetadata:\n name: Yaml.Subselector.Quantifier\nspec:\n condition:\n field: resources\n where:\n type: '.'\n equals: 'Microsoft.Web/sites/config'\n greaterOrEqual: 1\n allOf:\n - field: properties.detailedErrorLoggingEnabled\n equals: true\n{\n // Synopsis: A rule with a sub-selector quantifier.\n \"apiVersion\": \"github.com/microsoft/PSRule/v1\",\n \"kind\": \"Rule\",\n \"metadata\": {\n \"name\": \"Json.Subselector.Quantifier\"\n },\n \"spec\": {\n \"condition\": {\n \"field\": \"resources\",\n \"where\": {\n \"type\": \".\",\n \"equals\": \"Microsoft.Web/sites/config\"\n },\n \"greaterOrEqual\": 1,\n \"allOf\": [\n {\n \"field\": \"properties.detailedErrorLoggingEnabled\",\n \"equals\": true\n }\n ]\n }\n }\n}\nIn the example:
Describes the language keywords that can be used within PSRule rule definitions.
"},{"location":"keywords/PSRule/en-US/about_PSRule_Keywords/#description","title":"Description","text":"PSRule lets you define rules using PowerShell blocks. To define a rule use the
Rulekeyword.The following are the built-in keywords that can be used within a rule definition:
A subset of built-in keywords can be used within script preconditions:
A
Ruledefinition describes an individual business rule that will be executed against each input object. Input objects can be passed on the PowerShell pipeline or supplied from file.To define a Rule use the
Rulekeyword followed by a name and a pair of squiggly brackets{. Within the{ }one or more conditions can be used.Conditions determine if the input object either Pass or Fail the rule.
Syntax:
Rule [-Name] <string> [-Ref <string>] [-Alias <string[]>] [-Tag <hashtable>] [-When <string[]>] [-Type <string[]>] [-If <scriptBlock>] [-DependsOn <string[]>] [-Configure <hashtable>] [-ErrorAction <ActionPreference>] [-Body] {\n ...\n}\nA condition is any valid PowerShell that return either
$Trueor$False. Optionally, PSRule keywords can be used to help build out conditions quickly. When a rule contains more then one condition, all must return$Truefor the rule to Pass. If any one condition returns$Falsethe rule has failed.The following restrictions apply:
Examples:
# Synopsis: This rule checks for the presence of a name field\nRule 'NameMustExist' {\n Exists 'Name'\n}\n# Synopsis: This rule checks that the title field is valid, when the rule NameMustExist is successful\nRule 'TitleIsValid' -DependsOn 'NameMustExist' {\n Within 'Title' 'Mr', 'Miss', 'Mrs', 'Ms'\n}\n# Synopsis: This rule uses a threshold stored as $Configuration.minInstanceCount\nRule 'HasMinInstances' {\n $TargetObject.Sku.capacity -ge $Configuration.minInstanceCount\n} -Configure @{ minInstanceCount = 2 }\n
"},{"location":"keywords/PSRule/en-US/about_PSRule_Keywords/#exists","title":"Exists","text":"# Synopsis: This rule still passes because errors are ignored\nRule 'WithRuleErrorActionIgnore' -ErrorAction Ignore {\n Write-Error 'Some error';\n $True;\n}\nThe
Existsassertion is used within aRuledefinition to assert that a field or property must exist on the pipeline object.Syntax:
Exists [-Field] <string[]> [-CaseSensitive] [-Not] [-All] [-Reason <string>] [-InputObject <PSObject>]\nExamples:
# Synopsis: Checks for the presence of a name property\nRule 'nameMustExist' {\n Exists 'Name'\n}\n# Synopsis: Checks for the presence of name nested under the metadata property\nRule 'nameMustExist' {\n Exists 'metadata.name'\n}\n# Synopsis: Checks for the presence of name nested under the metadata property\nRule 'nameMustExist' {\n $TargetObject.metadata | Exists 'name'\n}\n# Synopsis: Checks that the NotName property does not exist\nRule 'NotNameMustNotExist' {\n Exists -Not 'NotName'\n}\n# Synopsis: Checks one of Name or AlternativeName properties exist\nRule 'EitherMustExist' {\n Exists 'Name', 'AlternativeName'\n}\n# Synopsis: Checks that both Name and Type properties exist\nRule 'AllMustExist' {\n Exists 'Name', 'Type' -All\n}\nOutput:
If any the specified fields exists then
Existswill return$True, otherwise$False.If
-Notis used, then if any of the fields exist thenExistswill return$Falseotherwise$True.If
"},{"location":"keywords/PSRule/en-US/about_PSRule_Keywords/#match","title":"Match","text":"-Allis used, then then all of the fields must exist, or not with the-Notswitch. If all fields exist thenExistswill return$True, otherwise$False. If-Notis used with-All, if all of the fields existExistswill return$Falseotherwise$True.The
Matchassertion is used within aRuledefinition to assert that the value of a field or property from pipeline data must match one or more regular expressions. To optionally perform a case sensitive match use the-CaseSensitiveswitch, otherwise a case insensitive match will be used.Syntax:
Match [-Field] <string> [-Expression] <string[]> [-CaseSensitive] [-Not] [-Reason <string>] [-InputObject <PSObject>]\nExamples:
# Synopsis: Check that PhoneNumber is complete and formatted correctly\nRule 'validatePhoneNumber' {\n Match 'PhoneNumber' '^(\\+61|0)([0-9] {0,1}){8}[0-9]$'\n}\nOutput:
If any of the specified regular expressions match the field value then
Matchreturns$True, otherwise$False.When
"},{"location":"keywords/PSRule/en-US/about_PSRule_Keywords/#within","title":"Within","text":"-Notis used, if any of the regular expressions match the field value withMatchreturn$False, otherwise$True.The
Withinassertion is used within aRuledefinition to assert that the value of a field or property from pipeline data must equal an item from a supplied list of allowed values. To optionally perform a case sensitive match use the-CaseSensitiveswitch, otherwise a case insensitive match will be used.Syntax:
Within [-Field] <string> [-Not] [-Like] [-Value] <PSObject[]> [-CaseSensitive] [-Reason <string>] [-InputObject <PSObject>]\nExamples:
# Synopsis: Ensure that the title field has one of the allowed values\nRule 'validateTitle' {\n Within 'Title' 'Mr', 'Miss', 'Mrs', 'Ms'\n}\n# Synopsis: Ensure that the title field is not one of the specified values\nRule 'validateTitle' {\n Within 'Title' -Not 'Mr', 'Sir'\n}\n# Synopsis: Ensure that the title field has one of the allowed values\nRule 'validateTitle' {\n Within 'Title' -Like 'Mr', 'M*s'\n}\nOutput:
If any of the values match the field value then
Withinreturns$True, otherwise$False.When
-Notis used, if any of the values match the field value withWithinreturn$False, otherwise$True.When
"},{"location":"keywords/PSRule/en-US/about_PSRule_Keywords/#allof","title":"AllOf","text":"-Likeis used, the field value is matched against one or more wildcard expressions.The
AllOfassertion is used within aRuledefinition to aggregate the result of assertions within a pair of squiggly brackets{ }.AllOfis functionally equivalent to a binary and, where when all of the contained assertions return$True,AllOfwill return$True.Syntax:
AllOf [-Body] {\n <assertion>\n [<assertion>]\n ...\n}\nExamples:
# Synopsis: The Name field must exist and have a value of either John or Jane\nRule 'nameCheck' {\n AllOf {\n Exists 'Name'\n Within 'Name' 'John', 'Jane'\n }\n}\nOutput:
If all of the assertions return
"},{"location":"keywords/PSRule/en-US/about_PSRule_Keywords/#anyof","title":"AnyOf","text":"$TrueAllOf will return$True, otherwise$False.The
AnyOfassertion is used within aRuledefinition to aggregate the result of assertions within a pair of squiggly brackets{ }.AnyOfis functionally equivalent to a binary or, where if any of the contained assertions returns$True,AnyOfwill return$True.Syntax:
AnyOf [-Body] {\n <assertion>\n [<assertion>]\n ...\n}\nExamples:
# Synopsis: The Last or Surname field must exist\nRule 'personCheck' {\n AnyOf {\n Exists 'Last'\n Exists 'Surname'\n }\n}\nOutput:
If any of the assertions return
"},{"location":"keywords/PSRule/en-US/about_PSRule_Keywords/#typeof","title":"TypeOf","text":"$TrueAnyOf will return$True, otherwise$False.The
TypeOfassertion is used within aRuledefinition to evaluate if the pipeline object matches one or more of the supplied type names.Syntax:
TypeOf [-TypeName] <string[]> [-Reason <string>] [-InputObject <PSObject>]\nExamples:
# Synopsis: The object must be a hashtable\nRule 'objectType' {\n TypeOf 'System.Collections.Hashtable'\n}\nOutput:
If any the specified type names match the pipeline object then TypeOf will return
"},{"location":"keywords/PSRule/en-US/about_PSRule_Keywords/#reason","title":"Reason","text":"$True, otherwise$False.The
Reasonkeyword is used within aRuledefinition to provide a message that indicates the reason the rule failed. The reason is included in detailed results.A reason is only included when the rule fails or errors. The outcomes
PassandNonedo not include reason.Use this keyword when you want to implement custom logic. Built-in keywords including
Exists,Match,WithinandTypeOfautomatically include a reason when they fail.Syntax:
Reason [-Text] <string>\nExamples:
# Synopsis: Provide reason the rule failed\nRule 'objectRecommend' {\n Reason 'A minimum of two (2) instances are required'\n $TargetObject.count -ge 2\n}\nOutput:
None.
"},{"location":"keywords/PSRule/en-US/about_PSRule_Keywords/#recommend","title":"Recommend","text":"The
Recommendkeyword is used within aRuledefinition to provide a recommendation to resolve the issue and pass the rule. This may include manual steps to change that state of the object or the desired state accessed by the rule.The recommendation can only be set once per rule. Each object will use the same recommendation.
Syntax:
Recommend [-Text] <string>\nExamples:
# Synopsis: Provide recommendation to resolve the issue\nRule 'objectRecommend' {\n Recommend 'Use at least two (2) instances'\n $TargetObject.count -ge 2\n}\nOutput:
None.
"},{"location":"keywords/PSRule/en-US/about_PSRule_Keywords/#examples","title":"Examples","text":"
"},{"location":"keywords/PSRule/en-US/about_PSRule_Keywords/#links","title":"Links","text":"# Synopsis: App Service Plan has multiple instances\nRule 'appServicePlan.MinInstanceCount' -If { $TargetObject.ResourceType -eq 'Microsoft.Web/serverfarms' } {\n Recommend 'Use at least two (2) instances'\n\n $TargetObject.Sku.capacity -ge 2\n}\nYou can use PSRule to create tests for PowerShell objects piped to PSRule for validation. Each test is called a rule.
PSRule allows you to write rules using YAML, JSON, or PowerShell. Regardless of the format you choose, any combination of YAML, JSON, or PowerShell rules can be used together.
Abstract
This topic covers how to create a rule using YAML, JSON, and PowerShell by example. In this quickstart, will be using native PowerShell objects. For an example of reading objects from disk, continue reading Testing infrastructure.
"},{"location":"quickstart/standalone-rule/#prerequisites","title":"Prerequisites","text":"For this quickstart, PSRule must be installed locally on MacOS, Linux, or Windows. To install PSRule locally, open PowerShell and run the following
PowerShellInstall-Modulecommand. If you don't have PowerShell installed, complete Installing PowerShell first.Install-Module -Name 'PSRule' -Repository PSGallery -Scope CurrentUser\nTip
PowerShell is installed by default on Windows. If these instructions don't work for you, your administrator may have restricted how PowerShell can be used in your environment. You or your administrator may be able to install PSRule for all users as a local administrator. See Getting the modules for instructions on how to do this.
Tip
To make you editing experience even better, consider installing the Visual Studio Code extension.
"},{"location":"quickstart/standalone-rule/#scenario-test-for-image-files","title":"Scenario - Test for image files","text":"In our quickstart scenario, we have been tasked with creating a rule to test for image files. When a file ending with the
.jpgor.pngextension is found the rule should fail.We will be using the following PowerShell code to get a list of files.
PowerShell$pathToSearch = $Env:HOME;\n$files = Get-ChildItem -Path $pathToSearch -File -Recurse;\nInfo
The path to search
"},{"location":"quickstart/standalone-rule/#define-the-file-type-rule","title":"Define the file type rule","text":"$Env:HOMEdefaults to the current user's home directory. This directory is used so this quickstart works on Windows and Linux operating systems. Feel free to update this path to a more suitable directory on your local machine.Before an object can be tested with PSRule, one or more rules must be defined. Each rule is defined in a file named with the suffix
.Rule.yaml,.Rule.jsonc, or.Rule.ps1. Multiple rules can be defined in a single file.A rule that fail on files with
YAMLJSONPowerShell.jpgor.pngextensions is shown in YAML, JSON, and PowerShell formats. You only need to choose one format, however you can choose to create all three to try out each format.Create the
YAMLFileType.Rule.yamlfile with the following contents. This file can be created in Visual Studio Code or any text editor. Make a note of the location you saveFileType.Rule.yaml.---\n# Synopsis: Image files are not permitted.\napiVersion: github.com/microsoft/PSRule/v1\nkind: Rule\nmetadata:\n name: Yaml.FileType\nspec:\n type:\n - System.IO.FileInfo\n condition:\n field: Extension\n notIn:\n - .jpg\n - .png\nCreate the
JSONFileType.Rule.jsoncfile with the following contents. This file can be created in Visual Studio Code or any text editor. Make a note of the location you saveFileType.Rule.jsonc.[\n {\n // Synopsis: Image files are not permitted.\n \"apiVersion\": \"github.com/microsoft/PSRule/v1\",\n \"kind\": \"Rule\",\n \"metadata\": {\n \"name\": \"Json.FileType\"\n },\n \"spec\": {\n \"type\": [\n \"System.IO.FileInfo\"\n ],\n \"condition\": {\n \"field\": \"Extension\",\n \"notIn\": [\n \".jpg\",\n \".png\"\n ]\n }\n }\n }\n]\nCreate the
PowerShellFileType.Rule.ps1file with the following contents. This file can be created in Visual Studio Code, Windows PowerShell ISE, or any text editor. Make a note of the location you saveFileType.Rule.ps1.# Synopsis: Image files are not permitted.\nRule 'PS.FileType' -Type 'System.IO.FileInfo' {\n $Assert.NotIn($TargetObject, 'Extension', @('.jpg', '.png'))\n}\nYou can test the rule by using the
PowerShellInvoke-PSRulecommand. For example:$pathToSearch = $Env:HOME;\n$files = Get-ChildItem -Path $pathToSearch -File -Recurse;\n\n# The path to the rule file. Update this to the location of your saved file.\n$rulePath = 'C:\\temp\\FileType.Rule.ps1'\n# Or the directory can be used to find all rules in the path:\n# $rulePath = 'C:\\temp\\'\n\n# Test the rule\n$files | Invoke-PSRule -Path $rulePath\nAfter running
Invoke-PSRuleyou will get output which includes all files in the pathToSeach. Files with a.jpgor.pngextension should have the outcome ofFail. All other files should report an outcome ofPass.For example:
OutputTargetName: main.html\n\nRuleName Outcome Recommendation\n-------- ------- --------------\nYaml.FileType Pass Image files are not permitted.\n\n TargetName: favicon.png\n\nRuleName Outcome Recommendation\n-------- ------- --------------\nYaml.FileType Fail Image files are not permitted.\nTip
v2.0.0
In our quickstart scenario, we have been tasked to:
We will be using the following PowerShell code to get a list of local services.
PowerShell$services = Get-Service\nNote
This scenario is designed for Windows clients. The PowerShell cmdlet
"},{"location":"quickstart/standalone-rule/#define-a-selector","title":"Define a selector","text":"Get-Serviceis only available on Windows.A selector can be used to filter a list of all services to only services that are set to start automatically. Selectors use YAML or JSON expressions and are similar to rules in many ways. A selector determines if the rule will be run or skipped.
Create the
YAMLService.Rule.yamlfile with the following contents. This file can be created in Visual Studio Code or any text editor. Make a note of the location you saveService.Rule.yaml.---\n# Synopsis: Find services with an automatic start type.\napiVersion: github.com/microsoft/PSRule/v1\nkind: Selector\nmetadata:\n name: Yaml.IsAutomaticService\nspec:\n if:\n field: StartType\n startsWith: Automatic\n convert: true\nCreate the
JSONService.Rule.jsoncfile with the following contents. This file can be created in Visual Studio Code or any text editor. Make a note of the location you saveService.Rule.jsonc.[\n {\n // Synopsis: Find services with an automatic start type.\n \"apiVersion\": \"github.com/microsoft/PSRule/v1\",\n \"kind\": \"Selector\",\n \"metadata\": {\n \"name\": \"Json.IsAutomaticService\"\n },\n \"spec\": {\n \"if\": {\n \"field\": \"StartType\",\n \"startsWith\": \"Automatic\",\n \"convert\": true\n }\n }\n }\n]\nSimilar to the selector, the
YAMLJSONPowerShellStatusfield will be tested to determine if the service isRunning.Append the following contents to the existing
YAMLService.Rule.yamlfile.---\n# Synopsis: Automatic services should be running.\napiVersion: github.com/microsoft/PSRule/v1\nkind: Rule\nmetadata:\n name: Yaml.ServiceStarted\nspec:\n with:\n - Yaml.IsAutomaticService\n condition:\n field: Status\n equals: Running\n convert: true\nUpdate the contents of
JSONService.Rule.jsoncto the following.[\n {\n // Synopsis: Find services with an automatic start type.\n \"apiVersion\": \"github.com/microsoft/PSRule/v1\",\n \"kind\": \"Selector\",\n \"metadata\": {\n \"name\": \"Json.IsAutomaticService\"\n },\n \"spec\": {\n \"if\": {\n \"field\": \"StartType\",\n \"startsWith\": \"Automatic\",\n \"convert\": true\n }\n }\n },\n {\n // Synopsis: Automatic services should be running.\n \"apiVersion\": \"github.com/microsoft/PSRule/v1\",\n \"kind\": \"Rule\",\n \"metadata\": {\n \"name\": \"Json.ServiceStarted\"\n },\n \"spec\": {\n \"with\": [\n \"Json.IsAutomaticService\"\n ],\n \"condition\": {\n \"field\": \"Status\",\n \"equals\": \"Running\",\n \"convert\": true\n }\n }\n }\n]\nCreate the
PowerShellService.Rule.ps1file with the following contents. This file can be created in Visual Studio Code, Windows PowerShell ISE, or any text editor. Make a note of the location you saveService.Rule.ps1.# Synopsis: Automatic services should be running.\nRule 'PS.ServiceStarted' -With 'Yaml.IsAutomaticService' {\n $status = $TargetObject.Status.ToString()\n $Assert.HasFieldValue($status, '.', 'Running')\n}\nYou can test the rule with service object by using the
PowerShellInvoke-PSRulecommand. For example:$services = Get-Service\n\n# The directory path to the rule file. Update this to the location of your saved file.\n$rulePath = 'C:\\temp\\'\n\n# Test the rule\n$services | Invoke-PSRule -Path $rulePath\nAfter running
Invoke-PSRuleyou will get output which include for services that start automatically. Services that areRunningshould pass whereas other stopped services should fail. For manual or disabled services a warning will be generated indicating that no matching rules were found.For example:
OutputTargetName: edgeupdate\n\nRuleName Outcome Recommendation\n-------- ------- --------------\nPS.ServiceStarted Fail Automatic services should be running.\nYaml.ServiceStarted Fail Automatic services should be running.\nJson.ServiceStarted Fail Automatic services should be running.\n\n\n TargetName: EventLog\n\nRuleName Outcome Recommendation\n-------- ------- --------------\nPS.ServiceStarted Pass Automatic services should be running.\nYaml.ServiceStarted Pass Automatic services should be running.\nJson.ServiceStarted Pass Automatic services should be running.\n\nWARNING: Target object 'TermService' has not been processed because no matching rules were found.\nTip
You can disable the warning by setting Execution.UnprocessedObject option. Alternatively you can ignore all warnings by using the
"},{"location":"scenarios/","title":"Getting started with PSRule","text":""},{"location":"scenarios/#define-a-rule","title":"Define a rule","text":"-WarningAction SilentlyContinueparameter.To define a rule, use a
Ruleblock saved to a file with the.Rule.ps1extension.Rule 'NameOfRule' {\n # Rule conditions\n}\nWithin the body of the rule provide one or more conditions. A condition is valid PowerShell that results in
$Trueor$False.For example:
Rule 'isFruit' {\n # Condition to determine if the object is fruit\n $TargetObject.Name -in 'Apple', 'Orange', 'Pear'\n}\nAn optional result message can be added to by using the
Recommendkeyword.Rule 'isFruit' {\n # An recommendation to display in output\n Recommend 'Fruit is only Apple, Orange and Pear'\n\n # Condition to determine if the object is fruit\n $TargetObject.Name -in 'Apple', 'Orange', 'Pear'\n}\nThe rule is saved to a file named
"},{"location":"scenarios/#execute-a-rule","title":"Execute a rule","text":"isFruit.Rule.ps1file. One or more rules can be defined within a single file.To execute the rule use
Invoke-PSRule.For example:
# Define objects to validate\n$items = @();\n$items += [PSCustomObject]@{ Name = 'Fridge' };\n$items += [PSCustomObject]@{ Name = 'Apple' };\n\n# Validate each item using rules saved in current working path\n$items | Invoke-PSRule;\nThe output of this example is:
"},{"location":"scenarios/#additional-options","title":"Additional options","text":"TargetName: Fridge\n\nRuleName Outcome Recommendation\n-------- ------- --------------\nisFruit Fail Fruit is only Apple, Orange and Pear\n\n\n TargetName: Apple\n\nRuleName Outcome Recommendation\n-------- ------- --------------\nisFruit Pass Fruit is only Apple, Orange and Pear\nTo 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\n$items | Invoke-PSRule -Outcome Fail;\nFor a summary of results for each rule use
Invoke-PSRule -As Summary.For example:
# Show rule summary\n$items | Invoke-PSRule -As Summary;\nThe output of this example is:
RuleName Pass Fail Outcome\n-------- ---- ---- -------\nisFruit 1 1 Fail\nAn optional failure reason can be added to the rule block by using the
Reasonkeyword.Rule 'isFruit' {\n # An recommendation to display in output\n Recommend 'Fruit is only Apple, Orange and Pear'\n\n # An failure reason to display for non-fruit\n Reason \"$($PSRule.TargetName) is not fruit.\"\n\n # Condition to determine if the object is fruit\n $TargetObject.Name -in 'Apple', 'Orange', 'Pear'\n}\nTo include the reason with output use
Invoke-PSRule -OutputFormat Wide.For example:
# Show failure reason for failing results\n$items | Invoke-PSRule -OutputFormat Wide;\nThe output of this example is:
TargetName: Fridge\n\nRuleName Outcome Reason Recommendation\n-------- ------- ------ --------------\nisFruit Fail Fridge is not fruit. Fruit is only Apple, Orange and Pear\n\n\n TargetName: Apple\n\nRuleName Outcome Reason Recommendation\n-------- ------- ------ --------------\nisFruit Pass Fruit is only Apple, Orange and Pear\nThe final rule is saved to
"},{"location":"scenarios/#scenarios","title":"Scenarios","text":"isFruit.Rule.ps1.For walk through examples of PSRule usage see:
PSRule makes it easy to validate Infrastructure as Code (IaC) such as Azure resources. For example, Azure resources can be validated to match an internal standard or baseline.
Note
A pre-built module to validate Azure resources already exists. This scenario demonstrates the process and features of PSRule for illustration purposes.
Consider using or contributing these pre-built rule modules instead:
This scenario covers the following:
In this scenario we will use a JSON file:
To generate a similar
resources.jsonfile of your own, the use following command.# Get all resources using the Az modules. Alternatively use Get-AzureRmResource if using AzureRm modules.\n# This command also requires authentication with Connect-AzAccount or Connect-AzureRmAccount\nGet-AzResource -ExpandProperties | ConvertTo-Json -Depth 10 | Set-Content -path .\\resources.json;\nFor this example we ran this command:
"},{"location":"scenarios/azure-resources/azure-resources/#define-rules","title":"Define rules","text":"Get-AzResource -ExpandProperties | ConvertTo-Json -Depth 10 | Set-Content -path docs/scenarios/azure-resources/resources.json;\nTo validate our Azure resources we need to define some rules. Rules are defined by using the
Rulekeyword in a file ending with the.Rule.ps1extension.So start we are going to define a
storageAccounts.UseHttpsrule, which will validate that Azure Storage resources have a Secure Transfer Required enabled.In the example below:
"},{"location":"scenarios/azure-resources/azure-resources/#set-rule-condition","title":"Set rule condition","text":"# Synopsis: Configure storage accounts to only accept encrypted traffic i.e. HTTPS/SMB\nRule 'storageAccounts.UseHttps' {\n # Rule conditions go here\n}\nConditions can be any valid PowerShell expression that results in a
$Trueor$False, just like anIfstatement, but without specifically requiring theIfkeyword to be used.Several PSRule keywords such as
ExistsandAllOfcan supplement PowerShell to quickly build out rules that are easy to read.In
resources.jsonone of our example storage accounts has a propertyProperties.supportsHttpsTrafficOnlyas shown below, which will be how our rule will pass$Trueor fail$FalseAzure resources that we throw at it.{\n \"Name\": \"storage\",\n \"ResourceName\": \"storage\",\n \"ResourceType\": \"Microsoft.Storage/storageAccounts\",\n \"Kind\": \"Storage\",\n \"ResourceGroupName\": \"test-rg\",\n \"Location\": \"eastus2\",\n \"Properties\": {\n \"supportsHttpsTrafficOnly\": false\n }\n}\nIn the example below:
"},{"location":"scenarios/azure-resources/azure-resources/#add-rule-recommendation","title":"Add rule recommendation","text":"# Synopsis: Configure storage accounts to only accept encrypted traffic i.e. HTTPS/SMB\nRule 'storageAccounts.UseHttps' {\n # This property returns true or false, so nothing more needs to be done\n $TargetObject.Properties.supportsHttpsTrafficOnly\n\n # Alternatively this could be written as:\n # $TargetObject.Properties.supportsHttpsTrafficOnly -eq $True\n}\nAdditionally to provide feedback to the person or process running the rules, we can use the
Recommendkeyword to set a message that appears in results.If a recommend message is not provided the synopsis will be used instead.
In the example below:
"},{"location":"scenarios/azure-resources/azure-resources/#filter-with-preconditions","title":"Filter with preconditions","text":"# Synopsis: Configure storage accounts to only accept encrypted traffic i.e. HTTPS/SMB\nRule 'storageAccounts.UseHttps' {\n Recommend 'Storage accounts should only allow secure traffic'\n\n $TargetObject.Properties.supportsHttpsTrafficOnly\n}\nSo far our rule works for a Storage Account, but there are many type of resources that could be returned by calling
Get-AzResource. Most of these resources won't have theProperties.supportsHttpsTrafficOnlyproperty, and if it did, it may use different configuration options instead of justtrueandfalse. This is where preconditions help out.Preconditions can be specified by using the
-Ifparameter when defining a rule. When the rule is executed, if the precondition is$Truethen the rule is processed, otherwise it is skipped.In the example below:
# Synopsis: Configure storage accounts to only accept encrypted traffic i.e. HTTPS/SMB\nRule 'storageAccounts.UseHttps' -If { $TargetObject.ResourceType -eq 'Microsoft.Storage/storageAccounts' } {\n Recommend 'Storage accounts should only allow secure traffic'\n\n $TargetObject.Properties.supportsHttpsTrafficOnly\n}\nSkipped rules have the outcome
"},{"location":"scenarios/azure-resources/azure-resources/#execute-rules","title":"Execute rules","text":"Noneand are not included in output by default. To include skipped rules use the-Outcome Allparameter.With a rule defined, the next step is to execute it. To execute rules, pipe the target object to
Invoke-PSRule.For example:
# Read resources in from file\n$resources = Get-Content -Path .\\resources.json | ConvertFrom-Json;\n\n# Process resources\n$resources | Invoke-PSRule;\nPSRule natively supports reading from YAML and JSON files so this command-line can be simplified to:
Invoke-PSRule -InputPath .\\resources.json;\nYou will notice, we didn't specify the rule. By default PSRule will look for any
.Rule.ps1files in the current working path.Invoke-PSRulesupports-Path,-Nameand-Tagparameters that can be used to specify the path to look for rules in or filter rules if you want to run a subset of the rules.For this example we ran these commands:
Invoke-PSRule -Path docs/scenarios/azure-resources -InputPath docs/scenarios/azure-resources/resources.json;\nOur output looked like this:
TargetName: storage\n\nRuleName Outcome Recommendation\n-------- ------- --------------\nstorageAccounts.UseHttps Fail Storage accounts should only allow secure traffic\nIn our case
"},{"location":"scenarios/azure-resources/azure-resources/#define-helper-functions","title":"Define helper functions","text":"storageAccounts.UseHttpsreturns aFailoutcome because our storage account hassupportsHttpsTrafficOnly=false, which is exactly what should happen.Using helper functions is completely optional and not required in many cases. However, you may prefer to use helper functions when rule conditions or preconditions are complex and hard to understand.
To use helper functions use a
functionblock within a file with a.Rule.ps1extension. Any code within.Rule.ps1files called byInvoke-PSRulewill be executed, however to make it available for use within a rule, a global scope modifier must be used.For functions this is done by prefixing the function name with
global:.For example:
function global:NameOfFunction {\n # Function body\n}\nIn our example, we are going to define a
ResourceTypefunction in a file namedcommon.Rule.ps1. This function will be used by preconditions to check the type of Azure resource.# A custom function to filter by resource type\nfunction global:ResourceType {\n param (\n [String]$ResourceType\n )\n\n process {\n return $TargetObject.ResourceType -eq $ResourceType;\n }\n}\nUpdating our existing
storageAccounts.UseHttpsrule, our rule definition becomes:
"},{"location":"scenarios/azure-resources/azure-resources/#more-information","title":"More information","text":"# Synopsis: Configure storage accounts to only accept encrypted traffic i.e. HTTPS/SMB\nRule 'storageAccounts.UseHttps' -If { ResourceType 'Microsoft.Storage/storageAccounts' } {\n Recommend 'Storage accounts should only allow secure traffic'\n\n $TargetObject.Properties.supportsHttpsTrafficOnly\n}\nThis is an example of how PSRule can be used to validate tags on Azure resources to match an internal tagging standard.
This scenario covers the following:
In this scenario we will use a JSON file:
To generate a similar file of your own, the use following command.
# Get all resources using the Az modules. Alternatively use Get-AzureRmResource if using AzureRm modules.\n# This command also requires authentication with Connect-AzAccount or Connect-AzureRmAccount\nGet-AzResource -ExpandProperties | ConvertTo-Json -Depth 10 | Set-Content -Path .\\resources.json;\nFor this example, we ran this command:
"},{"location":"scenarios/azure-tags/azure-tags/#define-rules","title":"Define rules","text":"Get-AzResource -ExpandProperties | ConvertTo-Json -Depth 10 | Set-Content -Path docs/scenarios/azure-resources/resources.json;\nTo validate our Azure resources, we need to define some rules. Rules are defined by using the
Rulekeyword in a file ending with the.Rule.ps1extension.Our business rules for Azure resource tagging can be defined with the following dot points:
To start we are going to define an
environmentTagrule, which will ensure that the environment tag exists and that the value only uses allowed values.In the example below:
"},{"location":"scenarios/azure-tags/azure-tags/#check-that-tag-exists","title":"Check that tag exists","text":"# Synopsis: Resource must have environment tag\nRule 'environmentTag' {\n # Rule conditions go here\n}\nConditions can be any valid PowerShell expression that results in a
$Trueor$False, just like anIfstatement, but without specifically requiring theIfkeyword to be used.In
resources.jsonone of our example storage accounts has theTagsproperty as shown below, this is how Azure Resource Manager stores tags for a resource. We will use this property as the basis of our rules to determine if the resource is tagged and what the tag value is.{\n \"Name\": \"storage\",\n \"ResourceName\": \"storage\",\n \"ResourceType\": \"Microsoft.Storage/storageAccounts\",\n \"Tags\": {\n \"role\": \"deployment\",\n \"environment\": \"production\"\n }\n}\nPSRule also defines several additional keywords to supplement PowerShell. These additional keywords help to create readable rules that can be built out quickly.
In the example below:
"},{"location":"scenarios/azure-tags/azure-tags/#tag-uses-only-allowed-values","title":"Tag uses only allowed values","text":"# Synopsis: Resource must have environment tag\nRule 'environmentTag' {\n Exists 'Tags.environment' -CaseSensitive\n}\nIn our scenario, we have three environments that our environment tag could be set to. In the next example we will ensure that only allowed environment values are used.
In the example below:
# Synopsis: Resource must have environment tag\nRule 'environmentTag' {\n Exists 'Tags.environment' -CaseSensitive\n Within 'Tags.environment' 'production', 'test', 'development' -CaseSensitive\n}\nAlternatively, instead of using the
Withinkeyword the-cinoperator could be used.Withinprovides additional verbose logging, however either syntax is valid.In the example below:
"},{"location":"scenarios/azure-tags/azure-tags/#tag-value-matches-regular-expression","title":"Tag value matches regular expression","text":"# Synopsis: Resource must have environment tag\nRule 'environmentTag' {\n Exists 'Tags.environment' -CaseSensitive\n $TargetObject.Tags.environment -cin 'production', 'test', 'development'\n}\nFor our second rule (
costCentreTag), the costCentre tag value must be 5 numbers. We can validate this by using a regular expression.In the example below:
# Synopsis: Resource must have costCentre tag\nRule 'costCentreTag' {\n Exists 'Tags.costCentre' -CaseSensitive\n Match 'Tags.costCentre' '^([1-9][0-9]{4})$'\n}\nAn alternative way to write the rule would be to use the
-matchoperator instead of theMatchkeyword. Like theWithinkeyword, theMatchkeyword provides additional verbose logging that the-matchoperator does not provide.In the example below:
"},{"location":"scenarios/azure-tags/azure-tags/#use-business-unit-name-from-configuration","title":"Use business unit name from configuration","text":"# Synopsis: Resource must have costCentre tag\nRule 'costCentreTag' {\n Exists 'Tags.costCentre' -CaseSensitive\n $TargetObject.Tags.costCentre -match '^([1-9][0-9]{4})$'\n}\nFor our third rule (
businessUnitTag), the businessUnit must match a valid business unit. A list of business units will be referenced from configuration instead of hard coded in the rule.Configuration can be used within rule definitions by defining configuration in a YAML file then using the automatic variable
$Configuration.In the example below:
An extract from azureTags.Rule.ps1:
# Synopsis: Resource must have businessUnit tag\nRule 'businessUnitTag' {\n Exists 'Tags.businessUnit' -CaseSensitive\n Within 'Tags.businessUnit' $Configuration.allowedBusinessUnits\n}\nAn extract from ps-rule.yaml:
"},{"location":"scenarios/azure-tags/azure-tags/#execute-rules","title":"Execute rules","text":"# Configure business units that are allowed\nconfiguration:\n allowedBusinessUnits:\n - 'IT Operations'\n - 'Finance'\n - 'HR'\nWith a rule defined, the next step is to execute it. To execute rules, pipe the target object to
Invoke-PSRule.For example:
# Read resources in from file\n$resources = Get-Content -Path .\\resources.json | ConvertFrom-Json;\n\n# Evaluate each resource against tagging rules\n$resources | Invoke-PSRule -Option .\\ps-rule.yaml;\nThe
ps-rule.yamlwill automatically discovered if it exists in the current working path (i.e..\\ps-rule.yaml). Alternatively it can be specified with the-Optionparameter as show above.PSRule natively supports reading from YAML and JSON files so this command-line can be simplified to:
# Evaluate each resource against tagging rules\nInvoke-PSRule -InputPath .\\resources.json;\nYou will notice, we didn't specify the rule. By default PSRule will look for any
.Rule.ps1files in the current working path.Invoke-PSRulesupports-Path,-Nameand-Tagparameters that can be used to specify the path to look for rules in or filter rules if you want to run a subset of the rules.The
-Optionparameter allows us to specify a specific YAML configuration file to use.For this example, we ran these commands:
# Evaluate each resource against tagging rules\nInvoke-PSRule -Path docs/scenarios/azure-tags -InputPath docs/scenarios/azure-tags/resources.json -Outcome Fail -Option docs/scenarios/azure-tags/ps-rule.yaml;\nOur output looked like this:
TargetName: storage\n\nRuleName Outcome Recommendation\n-------- ------- --------------\ncostCentreTag Fail Resource must have costCentre tag\nbusinessUnitTag Fail Resource must have businessUnit tag\n\n\n TargetName: web-app\n\nRuleName Outcome Recommendation\n-------- ------- --------------\nenvironmentTag Fail Resource must have environment tag\ncostCentreTag Fail Resource must have costCentre tag\n\n\n TargetName: web-app/staging\n\nRuleName Outcome Recommendation\n-------- ------- --------------\nenvironmentTag Fail Resource must have environment tag\ncostCentreTag Fail Resource must have costCentre tag\nAny resources that don't follow the tagging standard are reported with an outcome of
"},{"location":"scenarios/azure-tags/azure-tags/#more-information","title":"More information","text":"Fail.
| Method | Mean | Error | StdDev | Median | Gen 0 | Gen 1 | Gen 2 | Allocated | |------------------------- |-----------:|----------:|----------:|-----------:|-----------:|------:|------:|------------:| | Invoke | 111.140 ms | 2.1935 ms | 4.5786 ms | 109.312 ms | 8200.0000 | - | - | 16839.42 KB | | InvokeIf | 117.141 ms | 2.2703 ms | 2.2298 ms | 116.398 ms | 9600.0000 | - | - | 19980.62 KB | | InvokeType | 108.648 ms | 0.7983 ms | 0.7467 ms | 108.584 ms | 8200.0000 | - | - | 16870.67 KB | | InvokeSummary | 107.300 ms | 0.8612 ms | 0.8056 ms | 107.115 ms | 8000.0000 | - | - | 16784.76 KB | | Get | 9.003 ms | 0.0643 ms | 0.0602 ms | 9.010 ms | 140.6250 | - | - | 307.96 KB | | GetHelp | 8.902 ms | 0.0831 ms | 0.0649 ms | 8.899 ms | 140.6250 | - | - | 306.34 KB | | Within | 179.522 ms | 1.5483 ms | 1.4483 ms | 179.981 ms | 15666.6667 | - | - | 32400.38 KB | | WithinBulk | 247.883 ms | 2.6279 ms | 2.1944 ms | 248.124 ms | 28500.0000 | - | - | 59306.73 KB | | WithinLike | 238.815 ms | 2.5538 ms | 1.9939 ms | 239.245 ms | 29333.3333 | - | - | 60580.58 KB | | DefaultTargetNameBinding | 2.124 ms | 0.0214 ms | 0.0200 ms | 2.129 ms | 85.9375 | - | - | 179.69 KB | | CustomTargetNameBinding | 2.463 ms | 0.0483 ms | 0.0452 ms | 2.458 ms | 179.6875 | - | - | 375 KB | | NestedTargetNameBinding | 2.433 ms | 0.0370 ms | 0.0328 ms | 2.420 ms | 179.6875 | - | - | 375 KB |"},{"location":"scenarios/benchmark/results-v0.19.0/","title":"Results v0.19.0","text":"BenchmarkDotNet=v0.12.1, OS=Windows 10.0.18363.778 (1909/November2018Update/19H2)\nIntel Core i7-6600U CPU 2.60GHz (Skylake), 1 CPU, 4 logical and 2 physical cores\n.NET Core SDK=3.1.201\n [Host] : .NET Core 2.1.17 (CoreCLR 4.6.28619.01, CoreFX 4.6.28619.01), X64 RyuJIT\n DefaultJob : .NET Core 2.1.17 (CoreCLR 4.6.28619.01, CoreFX 4.6.28619.01), X64 RyuJIT\n
| Method | Mean | Error | StdDev | Gen 0 | Gen 1 | Gen 2 | Allocated | |------------------------- |-------------:|------------:|------------:|-----------:|---------:|------:|------------:| | Invoke | 40,943.5 \u03bcs | 581.23 \u03bcs | 515.25 \u03bcs | 4000.0000 | 500.0000 | - | 16452.28 KB | | InvokeIf | 42,806.0 \u03bcs | 477.29 \u03bcs | 423.11 \u03bcs | 4500.0000 | 500.0000 | - | 18703.12 KB | | InvokeType | 40,470.1 \u03bcs | 484.16 \u03bcs | 429.19 \u03bcs | 4000.0000 | 538.4615 | - | 16452.27 KB | | InvokeSummary | 39,768.8 \u03bcs | 462.14 \u03bcs | 385.91 \u03bcs | 4000.0000 | 153.8462 | - | 16397.82 KB | | Get | 11,145.4 \u03bcs | 402.59 \u03bcs | 1,187.03 \u03bcs | 46.8750 | - | - | 252.11 KB | | GetHelp | 10,169.1 \u03bcs | 625.02 \u03bcs | 1,842.88 \u03bcs | 46.8750 | - | - | 250.51 KB | | Within | 78,993.5 \u03bcs | 799.51 \u03bcs | 667.63 \u03bcs | 8000.0000 | 400.0000 | - | 32791.83 KB | | WithinBulk | 118,800.8 \u03bcs | 1,637.36 \u03bcs | 1,531.59 \u03bcs | 14333.3333 | 333.3333 | - | 59817.29 KB | | WithinLike | 106,796.3 \u03bcs | 2,067.20 \u03bcs | 2,538.71 \u03bcs | 11333.3333 | - | - | 47311.07 KB | | DefaultTargetNameBinding | 698.2 \u03bcs | 7.51 \u03bcs | 7.02 \u03bcs | 38.0859 | - | - | 156.25 KB | | CustomTargetNameBinding | 884.7 \u03bcs | 7.11 \u03bcs | 6.65 \u03bcs | 85.9375 | - | - | 351.56 KB | | NestedTargetNameBinding | 883.9 \u03bcs | 14.44 \u03bcs | 12.80 \u03bcs | 85.9375 | - | - | 351.56 KB |"},{"location":"scenarios/benchmark/results-v0.20.0/","title":"Results v0.20.0","text":"BenchmarkDotNet=v0.12.1, OS=Windows 10.0.19041.450 (2004/?/20H1)\nIntel Core i7-1065G7 CPU 1.30GHz, 1 CPU, 8 logical and 4 physical cores\n.NET Core SDK=3.1.401\n [Host] : .NET Core 3.1.7 (CoreCLR 4.700.20.36602, CoreFX 4.700.20.37001), X64 RyuJIT\n DefaultJob : .NET Core 3.1.7 (CoreCLR 4.700.20.36602, CoreFX 4.700.20.37001), X64 RyuJIT\n
| Method | Mean | Error | StdDev | Gen 0 | Gen 1 | Gen 2 | Allocated | |------------------------- |-------------:|------------:|------------:|-----------:|----------:|------:|------------:| | Invoke | 42,162.8 \u03bcs | 827.36 \u03bcs | 1,263.47 \u03bcs | 3833.3333 | - | - | 15952 KB | | InvokeIf | 45,646.4 \u03bcs | 912.31 \u03bcs | 1,924.38 \u03bcs | 4416.6667 | 416.6667 | - | 18202.98 KB | | InvokeType | 41,825.5 \u03bcs | 810.73 \u03bcs | 901.12 \u03bcs | 3833.3333 | - | - | 15952 KB | | InvokeSummary | 41,133.3 \u03bcs | 777.97 \u03bcs | 895.91 \u03bcs | 3833.3333 | 500.0000 | - | 15897.56 KB | | Get | 10,054.3 \u03bcs | 396.83 \u03bcs | 1,170.07 \u03bcs | 46.8750 | - | - | 252.11 KB | | GetHelp | 10,581.4 \u03bcs | 448.15 \u03bcs | 1,321.38 \u03bcs | 46.8750 | - | - | 250.51 KB | | Within | 81,215.1 \u03bcs | 1,532.85 \u03bcs | 1,433.83 \u03bcs | 7750.0000 | 250.0000 | - | 32290.62 KB | | WithinBulk | 123,301.6 \u03bcs | 2,451.51 \u03bcs | 3,958.73 \u03bcs | 14000.0000 | 1000.0000 | - | 59317.29 KB | | WithinLike | 109,738.9 \u03bcs | 1,933.95 \u03bcs | 1,809.02 \u03bcs | 11333.3333 | 1000.0000 | - | 46811.07 KB | | DefaultTargetNameBinding | 696.0 \u03bcs | 12.06 \u03bcs | 10.69 \u03bcs | 38.0859 | - | - | 156.25 KB | | CustomTargetNameBinding | 845.6 \u03bcs | 11.75 \u03bcs | 10.42 \u03bcs | 85.9375 | - | - | 351.56 KB | | NestedTargetNameBinding | 856.0 \u03bcs | 12.29 \u03bcs | 10.90 \u03bcs | 85.9375 | - | - | 351.56 KB |"},{"location":"scenarios/benchmark/results-v0.21.0/","title":"Results v0.21.0","text":"BenchmarkDotNet=v0.12.1, OS=Windows 10.0.19041.450 (2004/?/20H1)\nIntel Core i7-1065G7 CPU 1.30GHz, 1 CPU, 8 logical and 4 physical cores\n.NET Core SDK=3.1.401\n [Host] : .NET Core 3.1.7 (CoreCLR 4.700.20.36602, CoreFX 4.700.20.37001), X64 RyuJIT\n DefaultJob : .NET Core 3.1.7 (CoreCLR 4.700.20.36602, CoreFX 4.700.20.37001), X64 RyuJIT\n
| Method | Mean | Error | StdDev | Gen 0 | Gen 1 | Gen 2 | Allocated | |------------------------- |-------------:|------------:|------------:|-----------:|---------:|------:|------------:| | Invoke | 41,409.3 \u03bcs | 743.11 \u03bcs | 1,089.24 \u03bcs | 3916.6667 | 500.0000 | - | 16124.02 KB | | InvokeIf | 43,138.3 \u03bcs | 510.44 \u03bcs | 426.24 \u03bcs | 4416.6667 | 83.3333 | - | 18374.86 KB | | InvokeType | 41,511.3 \u03bcs | 703.93 \u03bcs | 963.55 \u03bcs | 3923.0769 | 230.7692 | - | 16144.62 KB | | InvokeSummary | 40,319.9 \u03bcs | 795.95 \u03bcs | 705.59 \u03bcs | 3900.0000 | 500.0000 | - | 16124.26 KB | | Get | 9,873.7 \u03bcs | 392.08 \u03bcs | 1,149.89 \u03bcs | 46.8750 | - | - | 253.44 KB | | GetHelp | 9,943.1 \u03bcs | 406.36 \u03bcs | 1,198.17 \u03bcs | 46.8750 | - | - | 251.84 KB | | Within | 76,627.6 \u03bcs | 1,527.91 \u03bcs | 1,759.54 \u03bcs | 7800.0000 | - | - | 32460.47 KB | | WithinBulk | 115,374.0 \u03bcs | 2,279.41 \u03bcs | 3,269.07 \u03bcs | 14333.3333 | - | - | 59488.54 KB | | WithinLike | 102,684.3 \u03bcs | 1,482.11 \u03bcs | 1,313.85 \u03bcs | 11500.0000 | 750.0000 | - | 46983.1 KB | | DefaultTargetNameBinding | 673.8 \u03bcs | 4.27 \u03bcs | 3.79 \u03bcs | 38.0859 | - | - | 156.25 KB | | CustomTargetNameBinding | 888.9 \u03bcs | 15.31 \u03bcs | 12.78 \u03bcs | 85.9375 | - | - | 351.56 KB | | NestedTargetNameBinding | 901.3 \u03bcs | 9.04 \u03bcs | 8.01 \u03bcs | 85.9375 | - | - | 351.56 KB |"},{"location":"scenarios/benchmark/results-v0.22.0/","title":"Results v0.22.0","text":"BenchmarkDotNet=v0.12.1, OS=Windows 10.0.19042\nIntel Core i7-1065G7 CPU 1.30GHz, 1 CPU, 8 logical and 4 physical cores\n.NET Core SDK=3.1.403\n [Host] : .NET Core 3.1.9 (CoreCLR 4.700.20.47201, CoreFX 4.700.20.47203), X64 RyuJIT\n DefaultJob : .NET Core 3.1.9 (CoreCLR 4.700.20.47201, CoreFX 4.700.20.47203), X64 RyuJIT\n
| Method | Mean | Error | StdDev | Gen 0 | Gen 1 | Gen 2 | Allocated | |------------------------- |-------------:|------------:|------------:|-----------:|---------:|------:|------------:| | Invoke | 40,804.1 \u03bcs | 656.89 \u03bcs | 614.45 \u03bcs | 3916.6667 | 500.0000 | - | 16124.02 KB | | InvokeIf | 42,768.8 \u03bcs | 843.79 \u03bcs | 704.61 \u03bcs | 4461.5385 | 76.9231 | - | 18374.92 KB | | InvokeType | 40,487.0 \u03bcs | 609.33 \u03bcs | 1,034.69 \u03bcs | 3923.0769 | 538.4615 | - | 16124.02 KB | | InvokeSummary | 40,403.1 \u03bcs | 806.53 \u03bcs | 714.97 \u03bcs | 3923.0769 | 538.4615 | - | 16124.26 KB | | Assert | 41,551.0 \u03bcs | 684.23 \u03bcs | 640.03 \u03bcs | 4000.0000 | 153.8462 | - | 16538.36 KB | | Get | 10,180.9 \u03bcs | 402.29 \u03bcs | 1,186.17 \u03bcs | 46.8750 | - | - | 231.12 KB | | GetHelp | 9,941.1 \u03bcs | 409.65 \u03bcs | 1,207.87 \u03bcs | 46.8750 | - | - | 229.52 KB | | Within | 75,818.3 \u03bcs | 1,504.74 \u03bcs | 2,297.90 \u03bcs | 7800.0000 | 600.0000 | - | 32468.28 KB | | WithinBulk | 112,731.0 \u03bcs | 1,239.66 \u03bcs | 1,035.17 \u03bcs | 14333.3333 | 666.6667 | - | 59496.35 KB | | WithinLike | 101,227.7 \u03bcs | 1,990.03 \u03bcs | 2,854.05 \u03bcs | 11333.3333 | - | - | 46623.62 KB | | DefaultTargetNameBinding | 654.3 \u03bcs | 10.46 \u03bcs | 9.78 \u03bcs | 38.0859 | - | - | 156.25 KB | | CustomTargetNameBinding | 854.3 \u03bcs | 16.30 \u03bcs | 15.25 \u03bcs | 85.9375 | - | - | 351.56 KB | | NestedTargetNameBinding | 945.7 \u03bcs | 18.78 \u03bcs | 19.29 \u03bcs | 85.9375 | - | - | 351.57 KB | | AssertHasFieldValue | 1,036.2 \u03bcs | 13.63 \u03bcs | 12.08 \u03bcs | 121.0938 | - | - | 500 KB |"},{"location":"scenarios/benchmark/results-v0.3.0/","title":"Results v0.3.0","text":"BenchmarkDotNet=v0.12.1, OS=Windows 10.0.19042\nIntel Core i7-1065G7 CPU 1.30GHz, 1 CPU, 8 logical and 4 physical cores\n.NET Core SDK=3.1.403\n [Host] : .NET Core 3.1.9 (CoreCLR 4.700.20.47201, CoreFX 4.700.20.47203), X64 RyuJIT\n DefaultJob : .NET Core 3.1.9 (CoreCLR 4.700.20.47201, CoreFX 4.700.20.47203), X64 RyuJIT\n
| Method | Mean | Error | StdDev | Gen 0/1k Op | Gen 1/1k Op | Gen 2/1k Op | Allocated Memory/Op | |-------------- |-----------:|----------:|----------:|------------:|------------:|------------:|--------------------:| | Invoke | 117.257 ms | 2.1959 ms | 2.1567 ms | 8400.0000 | 400.0000 | - | 17355.83 KB | | InvokeIf | 128.418 ms | 3.0122 ms | 3.8095 ms | 9750.0000 | 500.0000 | - | 20301.73 KB | | InvokeSummary | 116.479 ms | 1.9241 ms | 1.7998 ms | 8400.0000 | - | - | 17301.03 KB | | Get | 8.921 ms | 0.0864 ms | 0.0766 ms | 93.7500 | - | - | 203.82 KB |"},{"location":"scenarios/benchmark/results-v1.0.1/","title":"Results v1.0.1","text":"BenchmarkDotNet=v0.11.3, OS=Windows 10.0.17763.195 (1809/October2018Update/Redstone5)\nIntel Core i7-6600U CPU 2.60GHz (Skylake), 1 CPU, 4 logical and 2 physical cores\n.NET Core SDK=2.2.100\n [Host] : .NET Core 2.1.6 (CoreCLR 4.6.27019.06, CoreFX 4.6.27019.05), 64bit RyuJIT\n DefaultJob : .NET Core 2.1.6 (CoreCLR 4.6.27019.06, CoreFX 4.6.27019.05), 64bit RyuJIT\n
| Method | Mean | Error | StdDev | Median | Gen 0 | Gen 1 | Gen 2 | Allocated | |------------------------- |-------------:|------------:|------------:|-------------:|-----------:|---------:|------:|------------:| | Invoke | 39,343.5 \u03bcs | 781.08 \u03bcs | 835.75 \u03bcs | 39,287.2 \u03bcs | 3923.0769 | 538.4615 | - | 16124.02 KB | | InvokeIf | 41,264.0 \u03bcs | 545.97 \u03bcs | 483.99 \u03bcs | 41,148.4 \u03bcs | 4461.5385 | 76.9231 | - | 18374.92 KB | | InvokeType | 39,514.4 \u03bcs | 755.90 \u03bcs | 670.09 \u03bcs | 39,343.8 \u03bcs | 3923.0769 | 538.4615 | - | 16124.02 KB | | InvokeSummary | 39,251.4 \u03bcs | 605.30 \u03bcs | 566.20 \u03bcs | 39,143.5 \u03bcs | 3916.6667 | 500.0000 | - | 16124.26 KB | | Assert | 40,662.2 \u03bcs | 776.24 \u03bcs | 688.12 \u03bcs | 40,589.9 \u03bcs | 4000.0000 | 333.3333 | - | 16538.53 KB | | Get | 8,570.8 \u03bcs | 429.97 \u03bcs | 1,267.78 \u03bcs | 8,872.7 \u03bcs | 46.8750 | - | - | 231.12 KB | | GetHelp | 9,235.4 \u03bcs | 295.56 \u03bcs | 871.45 \u03bcs | 9,238.7 \u03bcs | 46.8750 | - | - | 229.52 KB | | Within | 75,171.4 \u03bcs | 744.98 \u03bcs | 660.41 \u03bcs | 75,223.5 \u03bcs | 7750.0000 | 750.0000 | - | 32468.28 KB | | WithinBulk | 110,726.9 \u03bcs | 2,142.74 \u03bcs | 2,200.44 \u03bcs | 109,801.1 \u03bcs | 14500.0000 | 500.0000 | - | 59496.51 KB | | WithinLike | 101,989.2 \u03bcs | 2,007.91 \u03bcs | 4,056.09 \u03bcs | 100,288.9 \u03bcs | 11250.0000 | - | - | 46623.25 KB | | DefaultTargetNameBinding | 626.0 \u03bcs | 11.49 \u03bcs | 10.75 \u03bcs | 622.9 \u03bcs | 38.0859 | - | - | 156.25 KB | | CustomTargetNameBinding | 796.3 \u03bcs | 7.48 \u03bcs | 7.00 \u03bcs | 797.0 \u03bcs | 85.9375 | - | - | 351.56 KB | | NestedTargetNameBinding | 806.1 \u03bcs | 12.12 \u03bcs | 10.12 \u03bcs | 805.3 \u03bcs | 85.9375 | - | - | 351.56 KB | | AssertHasFieldValue | 900.6 \u03bcs | 14.51 \u03bcs | 12.87 \u03bcs | 901.2 \u03bcs | 122.0703 | - | - | 500 KB |"},{"location":"scenarios/benchmark/results-v1.1.0/","title":"Results v1.1.0","text":"BenchmarkDotNet=v0.12.1, OS=Windows 10.0.19042\nIntel Core i7-1065G7 CPU 1.30GHz, 1 CPU, 8 logical and 4 physical cores\n.NET Core SDK=5.0.102\n [Host] : .NET Core 3.1.11 (CoreCLR 4.700.20.56602, CoreFX 4.700.20.56604), X64 RyuJIT\n DefaultJob : .NET Core 3.1.11 (CoreCLR 4.700.20.56602, CoreFX 4.700.20.56604), X64 RyuJIT\n
| Method | Mean | Error | StdDev | Gen 0 | Gen 1 | Gen 2 | Allocated | |------------------------- |-------------:|------------:|------------:|-----------:|---------:|------:|------------:| | Invoke | 40,327.3 \u03bcs | 801.24 \u03bcs | 1,013.31 \u03bcs | 3923.0769 | 538.4615 | - | 16124.02 KB | | InvokeIf | 42,943.9 \u03bcs | 849.72 \u03bcs | 1,396.11 \u03bcs | 4461.5385 | 76.9231 | - | 18374.92 KB | | InvokeType | 40,880.7 \u03bcs | 783.51 \u03bcs | 1,452.28 \u03bcs | 3900.0000 | - | - | 16149.45 KB | | InvokeSummary | 39,101.4 \u03bcs | 431.56 \u03bcs | 336.93 \u03bcs | 3916.6667 | 500.0000 | - | 16124.26 KB | | Assert | 41,917.1 \u03bcs | 831.37 \u03bcs | 1,192.33 \u03bcs | 4076.9231 | 461.5385 | - | 16780.81 KB | | Get | 9,643.0 \u03bcs | 428.32 \u03bcs | 1,262.91 \u03bcs | 54.6875 | 7.8125 | - | 231.12 KB | | GetHelp | 9,271.5 \u03bcs | 372.94 \u03bcs | 1,099.63 \u03bcs | 46.8750 | - | - | 229.52 KB | | Within | 76,020.5 \u03bcs | 954.22 \u03bcs | 744.99 \u03bcs | 7800.0000 | 600.0000 | - | 32468.65 KB | | WithinBulk | 112,135.7 \u03bcs | 2,189.72 \u03bcs | 2,342.97 \u03bcs | 14500.0000 | 500.0000 | - | 59499.77 KB | | WithinLike | 101,928.4 \u03bcs | 1,952.97 \u03bcs | 2,398.43 \u03bcs | 11333.3333 | - | - | 46623.57 KB | | DefaultTargetNameBinding | 655.6 \u03bcs | 13.11 \u03bcs | 25.87 \u03bcs | 38.0859 | - | - | 156.25 KB | | CustomTargetNameBinding | 822.1 \u03bcs | 16.06 \u03bcs | 19.11 \u03bcs | 85.9375 | - | - | 351.56 KB | | NestedTargetNameBinding | 878.9 \u03bcs | 16.63 \u03bcs | 17.08 \u03bcs | 85.9375 | - | - | 351.56 KB | | AssertHasFieldValue | 923.2 \u03bcs | 17.81 \u03bcs | 19.05 \u03bcs | 122.0703 | 0.9766 | - | 500.26 KB |"},{"location":"scenarios/benchmark/results-v1.10.0/","title":"Results v1.10.0","text":"BenchmarkDotNet=v0.12.1, OS=Windows 10.0.19042\nIntel Core i7-1065G7 CPU 1.30GHz, 1 CPU, 8 logical and 4 physical cores\n.NET Core SDK=5.0.103\n [Host] : .NET Core 3.1.12 (CoreCLR 4.700.21.6504, CoreFX 4.700.21.6905), X64 RyuJIT\n DefaultJob : .NET Core 3.1.12 (CoreCLR 4.700.21.6504, CoreFX 4.700.21.6905), X64 RyuJIT\n
| Method | Mean | Error | StdDev | Gen 0 | Gen 1 | Allocated | |------------------------- |-------------:|------------:|------------:|-----------:|----------:|----------:| | Invoke | 50,742.5 \u03bcs | 908.47 \u03bcs | 709.27 \u03bcs | 4100.0000 | 400.0000 | 17,758 KB | | InvokeIf | 53,048.6 \u03bcs | 698.34 \u03bcs | 619.06 \u03bcs | 4500.0000 | 200.0000 | 20,008 KB | | InvokeType | 50,575.6 \u03bcs | 794.27 \u03bcs | 663.25 \u03bcs | 4000.0000 | 200.0000 | 17,760 KB | | InvokeSummary | 50,449.0 \u03bcs | 698.80 \u03bcs | 619.47 \u03bcs | 4100.0000 | 400.0000 | 17,758 KB | | Assert | 52,152.6 \u03bcs | 765.95 \u03bcs | 678.99 \u03bcs | 4200.0000 | 300.0000 | 18,462 KB | | Get | 5,793.8 \u03bcs | 86.70 \u03bcs | 81.10 \u03bcs | 78.1250 | - | 364 KB | | GetHelp | 5,799.6 \u03bcs | 76.72 \u03bcs | 71.77 \u03bcs | 85.9375 | 7.8125 | 364 KB | | Within | 89,538.2 \u03bcs | 1,754.26 \u03bcs | 1,555.11 \u03bcs | 8000.0000 | 1000.0000 | 34,102 KB | | WithinBulk | 128,126.9 \u03bcs | 1,928.80 \u03bcs | 1,709.83 \u03bcs | 14666.6667 | 1333.3333 | 61,131 KB | | WithinLike | 112,174.1 \u03bcs | 1,132.30 \u03bcs | 1,003.76 \u03bcs | 11666.6667 | 1666.6667 | 48,258 KB | | DefaultTargetNameBinding | 695.6 \u03bcs | 13.57 \u03bcs | 14.52 \u03bcs | 38.0859 | - | 156 KB | | CustomTargetNameBinding | 851.0 \u03bcs | 10.35 \u03bcs | 8.64 \u03bcs | 85.9375 | - | 352 KB | | NestedTargetNameBinding | 961.5 \u03bcs | 17.83 \u03bcs | 15.80 \u03bcs | 85.9375 | - | 352 KB | | AssertHasFieldValue | 3,033.5 \u03bcs | 60.15 \u03bcs | 66.85 \u03bcs | 253.9063 | 7.8125 | 1,040 KB |"},{"location":"scenarios/benchmark/results-v1.11.0/","title":"Results v1.11.0","text":"BenchmarkDotNet=v0.13.1, OS=Windows 10.0.22000\nIntel Core i7-1065G7 CPU 1.30GHz, 1 CPU, 8 logical and 4 physical cores\n.NET SDK=5.0.404\n [Host] : .NET Core 3.1.22 (CoreCLR 4.700.21.56803, CoreFX 4.700.21.57101), X64 RyuJIT\n DefaultJob : .NET Core 3.1.22 (CoreCLR 4.700.21.56803, CoreFX 4.700.21.57101), X64 RyuJIT\n
| Method | Mean | Error | StdDev | Gen 0 | Gen 1 | Allocated | |------------------------- |-------------:|------------:|------------:|-----------:|----------:|----------:| | Invoke | 50,529.4 \u03bcs | 1,006.40 \u03bcs | 941.38 \u03bcs | 4000.0000 | 444.4444 | 17,758 KB | | InvokeIf | 51,974.4 \u03bcs | 667.26 \u03bcs | 591.51 \u03bcs | 4500.0000 | 200.0000 | 20,008 KB | | InvokeType | 49,901.2 \u03bcs | 679.83 \u03bcs | 567.69 \u03bcs | 4000.0000 | 363.6364 | 17,758 KB | | InvokeSummary | 51,198.9 \u03bcs | 862.22 \u03bcs | 922.57 \u03bcs | 4000.0000 | 363.6364 | 17,758 KB | | Assert | 52,136.6 \u03bcs | 588.93 \u03bcs | 550.88 \u03bcs | 4100.0000 | 300.0000 | 18,461 KB | | Get | 5,710.0 \u03bcs | 111.69 \u03bcs | 104.47 \u03bcs | 85.9375 | 7.8125 | 364 KB | | GetHelp | 5,777.4 \u03bcs | 97.83 \u03bcs | 91.51 \u03bcs | 85.9375 | 7.8125 | 364 KB | | Within | 88,106.3 \u03bcs | 1,752.66 \u03bcs | 1,799.86 \u03bcs | 8000.0000 | 1000.0000 | 34,102 KB | | WithinBulk | 125,319.9 \u03bcs | 2,303.80 \u03bcs | 2,154.98 \u03bcs | 14666.6667 | 1000.0000 | 61,133 KB | | WithinLike | 115,376.3 \u03bcs | 1,866.04 \u03bcs | 1,654.20 \u03bcs | 11666.6667 | 1666.6667 | 48,258 KB | | DefaultTargetNameBinding | 669.5 \u03bcs | 6.52 \u03bcs | 6.10 \u03bcs | 38.0859 | - | 156 KB | | CustomTargetNameBinding | 837.6 \u03bcs | 6.70 \u03bcs | 6.27 \u03bcs | 85.9375 | - | 352 KB | | NestedTargetNameBinding | 854.1 \u03bcs | 9.50 \u03bcs | 7.42 \u03bcs | 85.9375 | - | 352 KB | | AssertHasFieldValue | 2,967.0 \u03bcs | 38.88 \u03bcs | 34.47 \u03bcs | 253.9063 | 7.8125 | 1,040 KB |"},{"location":"scenarios/benchmark/results-v2.0.0/","title":"Results v2.0.0","text":"BenchmarkDotNet=v0.13.1, OS=Windows 10.0.22000\nIntel Core i7-1065G7 CPU 1.30GHz, 1 CPU, 8 logical and 4 physical cores\n.NET SDK=5.0.404\n [Host] : .NET Core 3.1.22 (CoreCLR 4.700.21.56803, CoreFX 4.700.21.57101), X64 RyuJIT\n DefaultJob : .NET Core 3.1.22 (CoreCLR 4.700.21.56803, CoreFX 4.700.21.57101), X64 RyuJIT\n
| Method | Mean | Error | StdDev | Median | Gen 0 | Gen 1 | Allocated | |------------------------- |-----------------:|----------------:|-----------------:|-----------------:|-----------:|----------:|----------:| | Invoke | 71,586,583.6 ns | 4,077,161.43 ns | 11,957,608.68 ns | 71,526,200.0 ns | 4200.0000 | 600.0000 | 17,703 KB | | InvokeIf | 59,661,136.5 ns | 1,161,506.18 ns | 1,192,781.33 ns | 59,397,680.0 ns | 4400.0000 | 400.0000 | 19,954 KB | | InvokeType | 55,089,186.0 ns | 1,045,769.22 ns | 1,989,684.63 ns | 54,242,620.0 ns | 4300.0000 | 500.0000 | 17,703 KB | | InvokeSummary | 55,371,580.7 ns | 1,271,559.50 ns | 3,586,456.14 ns | 53,815,745.0 ns | 4300.0000 | 500.0000 | 17,704 KB | | Assert | 56,146,053.8 ns | 1,122,221.08 ns | 3,053,085.20 ns | 54,841,105.0 ns | 4500.0000 | 600.0000 | 18,407 KB | | Get | 5,701,341.2 ns | 110,332.76 ns | 158,235.95 ns | 5,665,673.8 ns | 78.1250 | 7.8125 | 365 KB | | GetHelp | 5,750,066.9 ns | 113,595.72 ns | 170,024.73 ns | 5,720,298.0 ns | 85.9375 | 7.8125 | 366 KB | | Within | 99,151,338.5 ns | 2,136,858.10 ns | 6,165,324.21 ns | 97,015,516.7 ns | 8333.3333 | 1333.3333 | 34,142 KB | | WithinBulk | 147,062,385.7 ns | 2,633,709.47 ns | 2,334,714.85 ns | 146,838,450.0 ns | 14000.0000 | 3000.0000 | 61,169 KB | | WithinLike | 120,988,346.7 ns | 2,099,294.17 ns | 1,963,681.06 ns | 120,963,000.0 ns | 11666.6667 | 1666.6667 | 48,297 KB | | DefaultTargetNameBinding | 731,969.9 ns | 13,918.54 ns | 36,422.40 ns | 714,067.8 ns | 38.0859 | - | 156 KB | | CustomTargetNameBinding | 1,052,297.9 ns | 44,284.38 ns | 125,627.41 ns | 1,022,416.2 ns | 85.9375 | - | 352 KB | | NestedTargetNameBinding | 916,580.7 ns | 24,378.48 ns | 71,497.85 ns | 903,449.3 ns | 85.9375 | - | 352 KB | | AssertHasFieldValue | 3,082,706.1 ns | 61,644.86 ns | 68,518.10 ns | 3,058,487.1 ns | 234.3750 | - | 962 KB | | PathTokenize | 846.6 ns | 16.52 ns | 23.69 ns | 842.4 ns | 0.2632 | - | 1 KB | | PathExpressionBuild | 548.3 ns | 10.14 ns | 11.68 ns | 547.1 ns | 0.3500 | - | 1 KB | | PathExpressionGet | 356,089.5 ns | 7,027.54 ns | 11,348.18 ns | 351,085.5 ns | 17.0898 | - | 70 KB |"},{"location":"scenarios/containers/container-execution/","title":"Using PSRule from a Container","text":"BenchmarkDotNet=v0.13.1, OS=Windows 10.0.22000\nIntel Core i7-1065G7 CPU 1.30GHz, 1 CPU, 8 logical and 4 physical cores\n.NET SDK=6.0.400\n [Host] : .NET Core 3.1.28 (CoreCLR 4.700.22.36202, CoreFX 4.700.22.36301), X64 RyuJIT\n DefaultJob : .NET Core 3.1.28 (CoreCLR 4.700.22.36202, CoreFX 4.700.22.36301), X64 RyuJIT\nDepending on your development or CI/CD process for your environment you may desire to use PSRules to validate your Infrastructure as Code (IaC) from a container. This document shows how you can use a simple container based on the mcr.microsoft.com/powershell image from Microsoft.
In this tutorial we are going to use a simple Ubuntu based PowerShell image to validate an ARM template. We will do this by creating a dockerfile to describe and create a container image that we can then run. When we run the container we will use a volume mount to share our ARM template and test code for the container to then execute the PSRule for Azure against our ARM template and output the results.
"},{"location":"scenarios/containers/container-execution/#creating-the-image","title":"Creating the image","text":"Creating an image ready to run PSRules first requires a dockerfile. The below example will use the latest PowerShell image released and install the
DockerfilePSRuleandPSRule.Rules.Azuremodules.# Copyright (c) Microsoft Corporation.\n# Licensed under the MIT License.\n\nFROM mcr.microsoft.com/powershell:7.2-ubuntu-22.04\nSHELL [\"pwsh\", \"-command\"]\n\nRUN Install-Module -Name 'PSRule','PSRule.Rules.Azure' -Force\nThe below docker command can be used to create the image locally.
docker build --tag psrule:latest .\nNote
While fine for an example, it is common to always reference a container by a version number and not the
"},{"location":"scenarios/containers/container-execution/#create-your-test-script","title":"Create your test script","text":"latesttag. Using thelatesttag may lead to unexpected behavior as version changes occur.Create a new directory and add a new file named
validate-files.ps1. This file will run the PSRule test for us on our new container image. Add the below code to the file.# Copyright (c) Microsoft Corporation.\n# Licensed under the MIT License.\n\n<#\n .SYNOPSIS\n Create a PSRule AzRuleTemplate data file and run the PSRule.Rules.Azure module rules against the output.\n#>\n\nGet-AzRuleTemplateLink \"$PSScriptRoot/template\" | Export-AzRuleTemplateData -OutputPath \"$PSScriptRoot/out\"\n\nAssert-PSRule -InputPath \"$PSScriptRoot/out/\" -Module 'PSRule.Rules.Azure' -As Summary\nAlso, within the new directory add another directory named
template. Add any ARM template you would like to test in this directory. For a starting point you can get a template from Azure Quickstart Templates.Your directory should now look like the below.
"},{"location":"scenarios/containers/container-execution/#run-psrules-in-the-container","title":"Run PSRules in the container","text":"- Directory \n |--> validate-files.ps1\n |--> template\n |--> ARM template...\nNow we are ready to go! Run the below docker command to test the ARM template.
docker run -it --rm -v $PWD/:/src psrule:latest pwsh -file /src/validate-files.ps1\nThis command runs the container and the PSRule tests by mounting the directory to the
/srcpath and then executing thevalidate-files.ps1script.Note
The volume mount option expects your current working directory to be the new directory created. You can change this to an absolute or relative path if desired.
"},{"location":"scenarios/containers/container-execution/#clean-up","title":"Clean up","text":"When you are ready to clean up the container image you can do so with the below command.
"},{"location":"scenarios/kubernetes-resources/kubernetes-resources/","title":"Kubernetes resource validation example","text":"docker image rm psrule\nThis is an example of how PSRule can be used to validate Kubernetes resources to match an internal metadata and configuration standard.
Note
A pre-built module to validate Kubernetes resources already exists. This scenario demonstrates the process and features of PSRule for illustration purposes.
Consider using or contributing these pre-built rule modules instead:
This scenario covers the following:
In this scenario we will use a YAML file:
To validate our Kubernetes resources, we need to define some rules. Rules are defined by using the
Rulekeyword in a file ending with the.Rule.ps1extension.Our business rules for configuration Kubernetes resources can be defined with the following dot points:
In the example below:
"},{"location":"scenarios/kubernetes-resources/kubernetes-resources/#check-that-the-label-exists","title":"Check that the label exists","text":"# Synopsis: Must have the app.kubernetes.io/name label\nRule 'metadata.Name' {\n # Rule conditions go here\n}\nIn the next step, we define one or more conditions.
Conditions can be:
PSRule includes several convenience keywords such as
AllOf,AnyOf,Exists,Match,TypeOfandWithinthat make conditions faster to define, easier to understand and troubleshoot. However, use of these keywords is optional.In the example below:
# Synopsis: Must have the app.kubernetes.io/name label\nRule 'metadata.Name' {\n Exists \"metadata.labels.'app.kubernetes.io/name'\"\n}\nWe have also defined something similar for the version and component labels.
In the example below:
"},{"location":"scenarios/kubernetes-resources/kubernetes-resources/#use-custom-binding","title":"Use custom binding","text":"# Synopsis: Must have the app.kubernetes.io/version label\nRule 'metadata.Version' {\n Exists 'metadata.labels.''app.kubernetes.io/version'''\n}\n\n# Synopsis: Must have the app.kubernetes.io/component label\nRule 'metadata.Component' {\n Exists 'metadata.labels.''app.kubernetes.io/component'''\n Within 'metadata.labels.''app.kubernetes.io/component''' 'web', 'api', 'database', 'gateway' -CaseSensitive\n}\nBefore processing rules, PSRule binds
TargetNameandTargetTypeproperties to the pipeline object. These properties are used for filtering and displaying results.The default properties that PSRule binds are different from how Kubernetes resources are structured. Kubernetes uses:
The default bindings can be updated by providing custom property names or a custom script. To change binding property names set the
Binding.TargetNameandBinding.TargetTypeconfiguration options.The following example shows how to set the options using a YAML configuration file:
binding:\n targetName:\n - metadata.name\n targetType:\n - kind\nThese options can be set in the file
.\\ps-rule.yamlto be automatically loaded at when PSRule cmdlets are called. To set these configuration options either edit the file manually or use the following command.# Set options in ps-rule.yaml\nSet-PSRuleOption -TargetName 'metadata.Name' -TargetType 'kind';\nAlternatively, these options can be set at runtime using the hashtable syntax.
# Save options to a variable\n$option = New-PSRuleOption -TargetName 'metadata.Name' -TargetType 'kind';\nThese options will be passed to
"},{"location":"scenarios/kubernetes-resources/kubernetes-resources/#define-preconditions","title":"Define preconditions","text":"Invoke-PSRuleusing the-Optionparameter in a later step.Currently the
metadata.Namerule defined in a previous step will be executed for any type of object. Kubernetes has many types of built-in resource such as Services, Deployments, Namespaces, Pods and ClusterRoles.By defining a precondition, we can ensure that the rule is only processed for Services or Deployments to match our business rules.
PSRule supports two types of preconditions, either type (
-Type) or script block (-If).Preconditions are evaluated once per rule for each object.
In the example below:
# Synopsis: Must have the app.kubernetes.io/name label\nRule 'metadata.Name' -Type 'Deployment', 'Service' {\n Exists \"metadata.labels.'app.kubernetes.io/name'\"\n}\nUsing a type precondition satisfies our business rules and will deliver faster performance then using a script block. An example using a script block precondition is also shown below.
"},{"location":"scenarios/kubernetes-resources/kubernetes-resources/#complete-remaining-rules","title":"Complete remaining rules","text":"# Synopsis: Must have the app.kubernetes.io/name label\nRule 'metadata.Name' -If { $TargetObject.kind -eq 'Deployment' -or $TargetObject.kind -eq 'Service' } {\n Exists \"metadata.labels.'app.kubernetes.io/name'\"\n}\nThe remaining rule definitions from our defined business rules are included below. Each follows a similar pattern and builds on the previous sections.
In the example below:
"},{"location":"scenarios/kubernetes-resources/kubernetes-resources/#execute-rules","title":"Execute rules","text":"# Synopsis: Deployments use a minimum of 2 replicas\nRule 'deployment.HasMinimumReplicas' -Type 'Deployment' {\n Exists 'spec.replicas'\n $TargetObject.spec.replicas -ge 2\n}\n\n# Synopsis: Deployments use specific tags\nRule 'deployment.NotLatestImage' -Type 'Deployment' {\n foreach ($container in $TargetObject.spec.template.spec.containers) {\n $container.image -like '*:*' -and\n $container.image -notlike '*:latest'\n }\n}\n\n# Synopsis: Resource requirements are set for each container\nRule 'deployment.ResourcesSet' -Type 'Deployment' {\n foreach ($container in $TargetObject.spec.template.spec.containers) {\n $container | Exists 'resources.requests.cpu'\n $container | Exists 'resources.requests.memory'\n $container | Exists 'resources.limits.cpu'\n $container | Exists 'resources.limits.memory'\n }\n}\nWith some rules defined, the next step is to execute them. For this example, we'll use
Invoke-PSRuleto get the result for each rule. TheTest-PSRuleTargetcmdlet can be used if only a true or false is required.In our example we are using the YAML format to store Kubernetes resources. PSRule has built-in support for YAML so we can import these files directly from disk or process output from a command such as
kubectl.In the examples below:
# Validate resources from file\nInvoke-PSRule -InputPath resources.yaml;\n# Validate resources directly from kubectl output\nkubectl get services -o yaml | Out-String | Invoke-PSRule -Format Yaml -ObjectPath items;\nFor this example, we limited the output to failed results with the following command:
# Validate resources from file\nInvoke-PSRule -Path docs/scenarios/kubernetes-resources -InputPath docs/scenarios/kubernetes-resources/resources.yaml -Option docs/scenarios/kubernetes-resources/ps-rule.yaml -Outcome Fail;\nThe resulting output is:
"},{"location":"scenarios/kubernetes-resources/kubernetes-resources/#more-information","title":"More information","text":"TargetName: app1-cache\n\nRuleName Outcome Recommendation\n-------- ------- --------------\ndeployment.HasMinimumReplicas Fail Deployments use a minimum of 2 replicas\ndeployment.NotLatestImage Fail Deployments use specific tags\ndeployment.ResourcesSet Fail Resource requirements are set for each container\n\n\n TargetName: app1-cache-service\n\nRuleName Outcome Recommendation\n-------- ------- --------------\nmetadata.Name Fail Must have the app.kubernetes.io/name label\nmetadata.Version Fail Must have the app.kubernetes.io/version label\nmetadata.Component Fail Must have the app.kubernetes.io/component label\n\n\n TargetName: app1-ui\n\nRuleName Outcome Recommendation\n-------- ------- --------------\nmetadata.Version Fail Must have the app.kubernetes.io/version label\nPSRule supports several features that make it easy to a continuous integration (CI) pipeline. When added to a pipeline, PSRule can validate files, template and objects dynamically.
This scenario covers the following:
Typically, PSRule is not pre-installed on CI worker nodes and must be installed. If your CI pipeline runs on a persistent virtual machine that you control, consider pre-installing PSRule. The following examples focus on installing PSRule dynamically during execution of the pipeline. Which is suitable for cloud-based CI worker nodes.
To install PSRule within a CI pipeline execute the
Install-ModulePowerShell cmdlet.In the example below:
Install-Module -Name PSRule -Scope CurrentUser -Force;\nIn some cases, installing NuGet and PowerShellGet may be required to connect to the PowerShell Gallery. The NuGet package provider can be installed using the
Install-PackageProviderPowerShell cmdlet.Install-PackageProvider -Name NuGet -Scope CurrentUser -Force;\nInstall-Module PowerShellGet -MinimumVersion '2.2.1' -Scope CurrentUser -Force -AllowClobber;\nThe example below includes both steps together with checks:
if ($Null -eq (Get-PackageProvider -Name NuGet -ErrorAction SilentlyContinue)) {\n Install-PackageProvider -Name NuGet -Scope CurrentUser -Force;\n}\n\nif ($Null -eq (Get-InstalledModule -Name PowerShellGet -MinimumVersion '2.2.1' -ErrorAction Ignore)) {\n Install-Module PowerShellGet -MinimumVersion '2.2.1' -Scope CurrentUser -Force -AllowClobber;\n}\nif ($Null -eq (Get-InstalledModule -Name PSRule -MinimumVersion '2.1.0' -ErrorAction SilentlyContinue)) {\n Install-Module -Name PSRule -Scope CurrentUser -MinimumVersion '2.1.0' -Force;\n}\nSee the change log for the latest version.
"},{"location":"scenarios/validation-pipeline/validation-pipeline/#validating-objects","title":"Validating objects","text":"To validate objects use
Invoke-PSRule,Assert-PSRuleorTest-PSRuleTarget. In a CI pipeline,Assert-PSRuleis recommended.Assert-PSRuleoutputs preformatted results ideal for use within a CI pipeline.For rules within the same source control repository, put rules in the
.ps-ruledirectory. A directory.ps-rulein the repository root, is used by convention.In the following example, objects are validated against rules from the
./.ps-rule/directory:$items | Assert-PSRule -Path './.ps-rule/'\nExample output:
-> ObjectFromFile.psd1 : System.IO.FileInfo\n\n [PASS] File.Header\n [PASS] File.Encoding\n [WARN] Target object 'ObjectFromFile.yaml' has not been processed because no matching rules were found.\n [WARN] Target object 'ObjectFromNestedFile.yaml' has not been processed because no matching rules were found.\n [WARN] Target object 'Baseline.Rule.yaml' has not been processed because no matching rules were found.\n\n -> FromFile.Rule.ps1 : System.IO.FileInfo\n\n [FAIL] File.Header\n [PASS] File.Encoding\nIn the next example, objects from file are validated against pre-defined rules from a module:
"},{"location":"scenarios/validation-pipeline/validation-pipeline/#formatting-output","title":"Formatting output","text":"Assert-PSRule -InputPath .\\resources-*.json -Module PSRule.Rules.Azure;\nWhen executing a CI pipeline, feedback on any validation failures is important. The
Assert-PSRulecmdlet provides easy to read formatted output instead of PowerShell objects.Additionally,
Assert-PSRulesupports styling formatted output for Azure Pipelines and GitHub Actions. Use the-Style AzurePipelinesor-Style GitHubActionsparameter to style output.For example:
"},{"location":"scenarios/validation-pipeline/validation-pipeline/#failing-the-pipeline","title":"Failing the pipeline","text":"$items | Assert-PSRule -Path './.ps-rule/' -Style AzurePipelines;\nWhen using PSRule within a CI pipeline, a failed rule should stop the pipeline. When using
Assert-PSRuleif any rules fail, an error will be generated.Assert-PSRule : One or more rules reported failure.\nAt line:1 char:10\n+ $items | Assert-PSRule -Path ./.ps-rule/\n+ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n+ CategoryInfo : InvalidData: (:) [Assert-PSRule], FailPipelineException\n+ FullyQualifiedErrorId : PSRule.Fail,Assert-PSRule\nA single PowerShell error is typically enough to stop a CI pipeline. If you are using a different configuration additionally
-ErrorAction Stopcan be used.For example:
$items | Assert-PSRule -Path './.ps-rule/' -ErrorAction Stop;\nUsing
-ErrorAction Stopwill stop the current script and return an exit code of 1.To continue running the current script but return an exit code, use:
"},{"location":"scenarios/validation-pipeline/validation-pipeline/#generating-nunit-output","title":"Generating NUnit output","text":"try {\n $items | Assert-PSRule -Path './.ps-rule/' -ErrorAction Stop;\n}\ncatch {\n $Host.SetShouldExit(1);\n}\nNUnit is a popular unit test framework for .NET. NUnit generates a test report format that is widely interpreted by CI systems. While PSRule does not use NUnit directly, it support outputting validation results in the NUnit3 format. Using a common format allows integration with any system that supports the NUnit3 for publishing test results.
To generate an NUnit report:
$items | Assert-PSRule -Path './.ps-rule/' -OutputFormat NUnit3 -OutputPath reports/rule-report.xml;\nThe output path will be created if it does not exist.
"},{"location":"scenarios/validation-pipeline/validation-pipeline/#publishing-nunit-report-with-azure-devops","title":"Publishing NUnit report with Azure DevOps","text":"With Azure DevOps, an NUnit report can be published using Publish Test Results task.
An example YAML snippet is included below:
"},{"location":"scenarios/validation-pipeline/validation-pipeline/#complete-example","title":"Complete example","text":"# PSRule results\n- task: PublishTestResults@2\n displayName: 'Publish PSRule results'\n inputs:\n testRunTitle: 'PSRule'\n testRunner: NUnit\n testResultsFiles: 'reports/rule-report.xml'\n mergeTestResults: true\n publishRunAttachments: true\n condition: succeededOrFailed()\nPutting each of these steps together.
"},{"location":"scenarios/validation-pipeline/validation-pipeline/#install-dependencies","title":"Install dependencies","text":"
"},{"location":"scenarios/validation-pipeline/validation-pipeline/#validate-files","title":"Validate files","text":"# Install dependencies for connecting to PowerShell Gallery\nif ($Null -eq (Get-PackageProvider -Name NuGet -ErrorAction SilentlyContinue)) {\n Install-PackageProvider -Name NuGet -Force -Scope CurrentUser;\n}\n\nif ($Null -eq (Get-InstalledModule -Name PowerShellGet -MinimumVersion '2.2.1' -ErrorAction SilentlyContinue)) {\n Install-Module PowerShellGet -MinimumVersion '2.2.1' -Scope CurrentUser -Force -AllowClobber;\n}\n
"},{"location":"scenarios/validation-pipeline/validation-pipeline/#azure-devops-pipeline","title":"Azure DevOps Pipeline","text":"# Install PSRule module\nif ($Null -eq (Get-InstalledModule -Name PSRule -MinimumVersion '2.1.0' -ErrorAction SilentlyContinue)) {\n Install-Module -Name PSRule -Scope CurrentUser -MinimumVersion '2.1.0' -Force;\n}\n\n# Validate files\n$assertParams = @{\n Path = './.ps-rule/'\n Style = 'AzurePipelines'\n OutputFormat = 'NUnit3'\n OutputPath = 'reports/rule-report.xml'\n}\n$items = Get-ChildItem -Recurse -Path .\\src\\,.\\tests\\ -Include *.ps1,*.psd1,*.psm1,*.yaml;\n$items | Assert-PSRule $assertParams -ErrorAction Stop;\n
"},{"location":"scenarios/validation-pipeline/validation-pipeline/#additional-options","title":"Additional options","text":""},{"location":"scenarios/validation-pipeline/validation-pipeline/#using-invoke-build","title":"Using Invoke-Build","text":"steps:\n\n# Install dependencies\n- powershell: ./pipeline-deps.ps1\n displayName: 'Install dependencies'\n\n# Validate templates\n- powershell: ./validate-files.ps1\n displayName: 'Validate files'\n\n# Publish pipeline results\n- task: PublishTestResults@2\n displayName: 'Publish PSRule results'\n inputs:\n testRunTitle: 'PSRule'\n testRunner: NUnit\n testResultsFiles: 'reports/rule-report.xml'\n mergeTestResults: true\n publishRunAttachments: true\n condition: succeededOrFailed()\nInvoke-Build is a build automation cmdlet that can be installed from the PowerShell Gallery by installing the InvokeBuild module. Within Invoke-Build, each build process is broken into tasks.
The following example shows an example of using PSRule with Invoke-Build tasks.
# Synopsis: Install PSRule\ntask PSRule {\n if ($Null -eq (Get-InstalledModule -Name PSRule -MinimumVersion '2.1.0' -ErrorAction SilentlyContinue)) {\n Install-Module -Name PSRule -Scope CurrentUser -MinimumVersion '2.1.0' -Force;\n }\n}\n\n# Synopsis: Validate files\ntask ValidateFiles PSRule, {\n $assertParams = @{\n Path = './.ps-rule/'\n Style = 'AzurePipelines'\n OutputFormat = 'NUnit3'\n OutputPath = 'reports/rule-report.xml'\n }\n $items = Get-ChildItem -Recurse -Path .\\src\\,.\\tests\\ -Include *.ps1,*.psd1,*.psm1,*.yaml;\n $items | Assert-PSRule @assertParams -ErrorAction Stop;\n}\n\n# Synopsis: Run all build tasks\ntask Build ValidateFiles\n
"},{"location":"scenarios/validation-pipeline/validation-pipeline/#calling-from-pester","title":"Calling from Pester","text":"Invoke-Build Build;\nPester is a unit test framework for PowerShell that can be installed from the PowerShell Gallery.
Typically, Pester unit tests are built for a particular pipeline. PSRule can complement Pester unit tests by providing dynamic and sharable rules that are easy to reuse. By using
-Ifor-Typepre-conditions, rules can dynamically provide validation for a range of use cases.When calling PSRule from Pester use
Invoke-PSRuleinstead ofAssert-PSRule.Invoke-PSRulereturns validation result objects that can be tested by PesterShouldconditions.Additionally, the
Logging.RuleFailoption can be included to generate an error message for each failing rule.For example:
"},{"location":"scenarios/validation-pipeline/validation-pipeline/#more-information","title":"More information","text":"Describe 'Azure' {\n Context 'Resource templates' {\n It 'Use content rules' {\n $invokeParams = @{\n Path = './.ps-rule/'\n OutputFormat = 'NUnit3'\n OutputPath = 'reports/rule-report.xml'\n }\n $items = Get-ChildItem -Recurse -Path .\\src\\,.\\tests\\ -Include *.ps1,*.psd1,*.psm1,*.yaml;\n Invoke-PSRule @invokeParams -Outcome Fail,Error | Should -BeNullOrEmpty;\n }\n }\n}\nThis document is intended as a working technical specification for PSRule.
"},{"location":"specs/design-spec/#what-is-psrule","title":"What is PSRule?","text":"PSRule is an engine, shipped as a PowerShell module designed to validate infrastructure as code (IaC). Additionally, PSRule can validate any PowerShell object, allowing almost any custom scenario to be supported.
PSRule natively supports common infrastructure code artifacts with the following file formats:
While some infrastructure as code languages implement their own custom language, many support output into a standard artifact format. i.e.
"},{"location":"specs/design-spec/#project-objectives","title":"Project objectives","text":"terraform show -jsonPSRule is rooted in PowerShell. This provides significant benefits and flexibility including:
To ensure these benefits remain, the following must be true:
PowerShell offers complete flexibility to build simple to complex rules. However, rule authors may be unfamiliar with PowerShell. Authoring rules in YAML or JSON with a defined schema will allow additional options for basic rules.
"},{"location":"specs/design-spec/#concepts","title":"Concepts","text":""},{"location":"specs/design-spec/#rule-definitions","title":"Rule definitions","text":"Rule definitions or rules are defined using PowerShell. Rules can be created in a PowerShell script file with the
.Rule.ps1extension. Rule files can be created and used individually or bundled as a module.Each rule:
For example:
Rule 'NameOfRule' {\n # <Rule conditions>\n}\n
"},{"location":"specs/design-spec/#psrule-engine","title":"PSRule engine","text":"# Synopsis: Configure storage accounts to only accept encrypted traffic i.e. HTTPS/SMB\nRule 'StorageAccounts.UseHttps' -Type 'Microsoft.Storage/storageAccounts' {\n $TargetObject.Properties.supportsHttpsTrafficOnly -eq $True\n}\nDistributed as a PowerShell module, all source code is included within this repository. This included cmdlets and an execution sandbox where rules are evaluated. PSRule is designed to be self contained, requiring only PowerShell to run.
By itself PSRule doesn't implement any specific rules. Custom rules can be defined and evaluated from PowerShell script files. Reusable rules can be distributed using PowerShell modules. Use PowerShellGet to install modules from public and private sources.
PSRule extends PowerShell with domain specific language (DSL) keywords, cmdlets, and automatic variables. These language features are only available within the sandbox. Stubs are exported from PSRule module to provide command completion during authoring.
In additional to rules, a number of resources can be used within PSRule. Resources are defined in YAML files with the
.Rule.yamlfile extension. You can create one or many resource within a single.Rule.yamlfile.PSRule supports the following resources:
A special
"},{"location":"specs/design-spec/#keywords-and-variables","title":"Keywords and variables","text":"ModuleConfigresource can also be defined to configure defaults for a module.TBA
"},{"location":"specs/design-spec/#baselines","title":"Baselines","text":"A baseline is a resource defined in YAML that determines which rules to run for a given scenario. One or more baselines can be included in a
.Rule.yamlfile. Baselines can be created individually or bundled in a module.Common use cases where baselines are helpful include:
Execution within PSRule occurs within a pipeline. The PSRule pipeline is similar to PowerShell and contains a
begin,process, andendstage.Three execution pipelines exist,
Invoke,Assert, orTest. Differences between each of these pipeline is minimal and mostly deals with how output is presented.The execution sandbox is implemented using PowerShell runspaces. Runspaces are a PowerShell feature which enable partial isolation within a PowerShell process.
PSRule uses two discrete runspaces:
Input and output are proxied between the two discrete runspaces to maintain runspace separation. This separation allows rules to be executed without polluting the state of the parent runspace.
"},{"location":"specs/design-spec/#rule-evaluation","title":"Rule evaluation","text":"TBA
"},{"location":"specs/design-spec/#configuration","title":"Configuration","text":"PSRule has built-in support for configuration of the engine and rules. Configuration can be set by:
Configuration of the PSRule engine is referred to as options. Each option changes the default that PSRule uses during execution. The supported options that can be configured for PSRule are described in the about_PSRule_Options topic.
"},{"location":"specs/design-spec/#rule-configuration","title":"Rule configuration","text":"Separately, rules can optionally define configuration that can skip or change the rule conditions. Rule configuration is a key/ value pair.
"},{"location":"specs/design-spec/#integration","title":"Integration","text":"TBA
"},{"location":"specs/function-spec/","title":"PSRule function expressions spec (draft)","text":"This is a spec for implementing function expressions in PSRule v2.
"},{"location":"specs/function-spec/#synopsis","title":"Synopsis","text":"Functions are available to handle complex conditions within YAML and JSON expressions.
"},{"location":"specs/function-spec/#schema-driven","title":"Schema driven","text":"While functions allow handing for complex use cases, they should still remain schema driven. A schema driven design allows auto-completion and validation during authoring in a broad set of tools.
"},{"location":"specs/function-spec/#syntax","title":"Syntax","text":"Functions can be used within YAML and JSON expressions by using the
$object property. For example:
"},{"location":"specs/option-spec/","title":"PSRule options spec (draft)","text":"---\n# Synopsis: An expression function example.\napiVersion: github.com/microsoft/PSRule/v1\nkind: Selector\nmetadata:\n name: Yaml.Fn.Example1\nspec:\n if:\n value:\n $:\n substring:\n path: name\n length: 3\n equals: abc\nThis is a spec for implementing options in PSRule v2.
"},{"location":"specs/option-spec/#synopsis","title":"Synopsis","text":"When executing resources options is often required to control the specific behaviour. In additional, many of these cases are scoped to the module being used.
The following scopes exist:
See upgrade notes for helpful information when upgrading from previous versions.
Attention
PSRule v0 is a prior release. For more information see v2 release notes. Please check out our upgrade notes to get prepared for upgrading to the latest version.
"},{"location":"CHANGELOG-v0/#v0220","title":"v0.22.0","text":"What's changed since v0.21.0:
What's changed since pre-release v0.22.0-B2010014:
What's changed since v0.21.0:
What's changed since v0.20.0:
What's changed since pre-release v0.21.0-B2010010:
What's changed since pre-release v0.21.0-B2010003:
What's changed since pre-release v0.21.0-B2009016:
What's changed since pre-release v0.21.0-B2009006:
What's changed since v0.20.0:
What's changed since v0.19.0:
What's changed since pre-release v0.20.0-B2009013:
What's changed since pre-release v0.20.0-B2009007:
What's changed since pre-release v0.20.0-B2008010:
What's changed since pre-release v0.20.0-B2008002:
What's changed since v0.19.0:
What's changed since v0.18.1:
What's changed since pre-release v0.19.0-B2007030:
What's changed since v0.18.0:
What's changed since v0.17.0:
What's changed since pre-release v0.18.0-B2005015:
What's changed since v0.16.0:
What's changed since pre-release v0.17.0-B2005010:
What's changed since v0.15.0:
What's changed since pre-release v0.16.0-B2003027:
What's changed since v0.14.0:
What's changed since pre-release v0.15.0-B2002031:
What's changed since v0.13.0:
What's changed since pre-release v0.14.0-B2002003:
What's changed since v0.12.0:
What's changed since pre-release v0.13.0-B2001013:
What's changed since v0.11.0:
What's changed since pre-release v0.12.0-B1912007:
What's changed since v0.10.0:
What's changed since pre-release v0.11.0-B1911002:
What's changed since v0.9.0:
What's changed since pre-release v0.10.0-B1910036:
What's changed since v0.8.0:
What's changed since pre-release v0.9.0-B190905:
What's changed since v0.7.0:
What's changed since pre-release v0.8.0-B190806:
What's changed since v0.6.0:
What's changed since pre-release v0.7.0-B190664:
What's changed since v0.5.0:
What's changed since pre-release v0.6.0-B190627:
What's changed since v0.4.0:
What's changed since pre-release v0.5.0-B190423:
What's changed since v0.3.0:
What's changed since pre-release v0.4.0-B190328:
What's changed since v0.2.0:
What's changed since pre-release v0.3.0-B190231:
What's changed since v0.1.0:
What's changed since pre-release v0.2.0-B190121:
What's changed since pre-release v0.1.0-B181235:
See upgrade notes for helpful information when upgrading from previous versions.
Important notes:
Attention
PSRule v1 is a prior release. For more information see v2 release notes. Please check out our upgrade notes to get prepared for upgrading to the latest version.
"},{"location":"CHANGELOG-v1/#v1111","title":"v1.11.1","text":"What's changed since v1.11.1:
What's changed since v1.10.0:
What's changed since pre-release v1.11.0-B2112016:
What's changed since v1.10.0:
What's changed since v1.9.0:
What's changed since pre-release v1.10.0-B2112002:
What's changed since pre-release v1.10.0-B2111024:
What's changed since v1.9.0:
What's changed since v1.8.0:
What's changed since pre-release v1.9.0-B2111024:
What's changed since pre-release v1.9.0-B2111009:
What's changed since pre-release v1.9.0-B2110027:
What's changed since pre-release v1.9.0-B2110015:
What's changed since v1.8.0:
What's changed since v1.7.2:
What's changed since pre-release v1.8.0-B2110030:
What's changed since pre-release v1.8.0-B2110020:
What's changed since pre-release v1.8.0-B2110006:
What's changed since pre-release v1.8.0-B2109022:
What's changed since pre-release v1.8.0-B2109015:
What's changed since v1.7.2:
What's changed since v1.7.1:
What's changed since v1.7.0:
What's changed since v1.6.0:
What's changed since pre-release v1.7.0-B2109002:
What's changed since pre-release v1.7.0-B2108032:
What's changed since pre-release v1.7.0-B2108021:
What's changed since pre-release v1.7.0-B2108016:
What's changed since v1.6.0:
What's changed since v1.6.0:
What's changed since v1.5.0:
What's changed since pre-release v1.6.0-B2108009:
What's changed since pre-release v1.6.0-B2108003:
What's changed since pre-release v1.6.0-B2107008:
What's changed since v1.5.0:
What's changed since v1.4.0:
What's changed since pre-release v1.5.0-B2107009:
What's changed since pre-release v1.5.0-B2106006:
What's changed since v1.4.0:
What's changed since v1.3.0:
What's changed since pre-release v1.4.0-B2105041:
What's changed since pre-release v1.4.0-B2105032:
What's changed since pre-release v1.4.0-B2105019:
What's changed since pre-release v1.4.0-B2105004:
What's changed since v1.3.0:
What's changed since v1.2.0:
What's changed since pre-release v1.3.0-B2105004:
What's changed since pre-release v1.3.0-B2104042:
What's changed since pre-release v1.3.0-B2104030:
What's changed since pre-release v1.3.0-B2104021:
What's changed since v1.2.0:
What's changed since v1.1.0:
What's changed since pre-release v1.2.0-B2103043:
What's changed since pre-release v1.2.0-B2103031:
What's changed since pre-release v1.2.0-B2103023:
What's changed since pre-release v1.2.0-B2103016:
What's changed since pre-release v1.2.0-B2103008:
What's changed since v1.1.0:
What's changed since v1.0.3:
What's changed since pre-release v1.1.0-B2102029:
What's changed since pre-release v1.1.0-B2102024:
What's changed since pre-release v1.1.0-B2102019:
What's changed since v1.0.3:
What's changed since v1.0.2:
What's changed since v1.0.1:
What's changed since v1.0.0:
What's changed since v0.22.0:
What's changed since pre-release v1.0.0-B2011028:
What's changed since v0.22.0:
See upgrade notes for helpful information when upgrading from previous versions.
Important notes:
Experimental features:
Attention
We are currently working towards the next release of PSRule. For more information see v3 release notes. Please check out our upgrade notes to get prepared for upgrading to the latest version.
"},{"location":"CHANGELOG-v2/#v290","title":"v2.9.0","text":"What's changed since release v2.8.1:
What's changed since pre-release v2.9.0-B0068:
What's changed since pre-release v2.9.0-B0033:
What's changed since pre-release v2.9.0-B0013:
What's changed since release v2.8.1:
What's changed since release v2.8.0:
What's changed since release v2.7.0:
What's changed since pre-release v2.8.0-B0171:
What's changed since pre-release v2.8.0-B0121:
What's changed since pre-release v2.8.0-B0076:
What's changed since pre-release v2.8.0-B0034:
What's changed since v2.7.0:
What's changed since v2.6.0:
What's changed since pre-release v2.7.0-B0126:
What's changed since pre-release v2.7.0-B0097:
What's changed since pre-release v2.7.0-B0070:
What's changed since pre-release v2.7.0-B0049:
What's changed since pre-release v2.7.0-B0031:
What's changed since pre-release v2.7.0-B0016:
What's changed since pre-release v2.7.0-B0006:
What's changed since pre-release v2.7.0-B0001:
What's changed since v2.6.0:
What's changed since v2.5.3:
What's changed since pre-release v2.6.0-B0034:
What's changed since pre-release v2.6.0-B0013:
What's changed since v2.5.3:
What's changed since v2.5.2:
What's changed since v2.5.1:
What's changed since v2.5.0:
What's changed since v2.4.2:
What's changed since pre-release v2.5.0-B0080:
What's changed since pre-release v2.5.0-B0045:
What's changed since pre-release v2.5.0-B0015:
What's changed since pre-release v2.5.0-B0004:
What's changed since v2.4.0:
What's changed since v2.4.1:
What's changed since v2.4.0:
What's changed since v2.3.2:
What's changed since pre-release v2.4.0-B0091:
What's changed since pre-release v2.4.0-B0063:
What's changed since pre-release v2.4.0-B0039:
What's changed since pre-release v2.4.0-B0022:
What's changed since pre-release v2.4.0-B0009:
What's changed since v2.3.2:
What's changed since v2.3.1:
What's changed since v2.3.0:
What's changed since v2.2.0:
What's changed since pre-release v2.3.0-B0163:
What's changed since pre-release v2.3.0-B0130:
What's changed since pre-release v2.3.0-B0100:
What's changed since pre-release v2.3.0-B0074:
What's changed since pre-release v2.3.0-B0051:
What's changed since pre-release v2.3.0-B0030:
What's changed since pre-release v2.3.0-B0015:
What's changed since pre-release v2.3.0-B0006:
What's changed since pre-release v2.3.0-B0001:
What's changed since v2.2.0:
What's changed since v2.1.0:
What's changed since pre-release v2.2.0-B0175:
What's changed since pre-release v2.2.0-B0131:
What's changed since pre-release v2.2.0-B0089:
What's changed since pre-release v2.2.0-B0052:
What's changed since pre-release v2.2.0-B0021:
What's changed since v2.1.0:
What's changed since v2.0.1:
What's changed since pre-release v2.1.0-B0069:
What's changed since pre-release v2.1.0-B0040:
What's changed since pre-release v2.1.0-B0015:
What's changed since v2.0.1:
What's changed since v2.0.0:
What's changed since v1.11.1:
What's changed since pre-release v2.0.0-B2203045:
What's changed since pre-release v2.0.0-B2203033:
What's changed since pre-release v2.0.0-B2203019:
What's changed since pre-release v2.0.0-B2202072:
What's changed since pre-release v2.0.0-B2202065:
What's changed since pre-release v2.0.0-B2202056:
What's changed since pre-release v2.0.0-B2202024:
What's changed since pre-release v2.0.0-B2202017:
What's changed since pre-release v2.0.0-B2202006:
What's changed since pre-release v2.0.0-B2201161:
What's changed since pre-release v2.0.0-B2201146:
What's changed since pre-release v2.0.0-B2201135:
What's changed since pre-release v2.0.0-B2201117:
What's changed since pre-release v2.0.0-B2201093:
What's changed since pre-release v2.0.0-B2201075:
What's changed since pre-release v2.0.0-B2201054:
What's changed since v1.11.0:
See upgrade notes for helpful information when upgrading from previous versions.
Experimental features:
What's changed since pre-release v3.0.0-B0153:
What's changed since pre-release v3.0.0-B0151:
What's changed since pre-release v3.0.0-B0141:
What's changed since pre-release v3.0.0-B0137:
What's changed since pre-release v3.0.0-B0122:
What's changed since pre-release v3.0.0-B0093:
What's changed since pre-release v3.0.0-B0084:
What's changed since release v2.9.0:
PSRule is a rules engine geared towards testing Infrastructure as Code (IaC). Rules you write or import perform static analysis on IaC artifacts such as: templates, manifests, pipelines, and workflows.
"},{"location":"about/#why-use-psrule","title":"Why use PSRule?","text":"PSRule aims to provide a rich experience for building and running static analysis tests on IaC. While this has some similarities to traditional testing frameworks it extends on the following:
You can send rule results to Azure Monitor using
"},{"location":"addon-modules/#pre-built-rules","title":"Pre-built rules","text":"PSRule.Monitor.The following modules contain pre-built rules that can be plugged into your pipeline.
Module Description Version / downloads PSRule.Rules.Azure A suite of rules to validate Azure resources and infrastructure as code (IaC) using PSRule. PSRule.Rules.Kubernetes A suite of rules to validate Kubernetes resources using PSRule. PSRule.Rules.CAF A suite of rules to validate Azure resources against the Cloud Adoption Framework (CAF) using PSRule. PSRule.Rules.GitHub A suite of rules to validate GitHub repositories using PSRule. PSRule.Rules.MSFT.OSS A suite of rules to validate repositories against Microsoft Open Source Software (OSS) requirements. PSRule.Monitor Log PSRule analysis results to Azure Monitor."},{"location":"analysis-output/","title":"Analysis output","text":"PSRule supports generating and saving output in a number of different formats.
Abstract
This topic covers the supported formats and options for presenting output from a PSRule run.
"},{"location":"analysis-output/#setting-the-output-format","title":"Setting the output format","text":"The output format can be configuring by setting the
Output.Formatoption to one the following:Tip
To write output to a file, also set the
GitHub ActionsAzure PipelinesPowerShellOptions fileOutput.Pathoption to the file path to save.# Analyze and save results\n- name: Analyze repository\n uses: microsoft/ps-rule@v2.9.0\n with:\n outputFormat: Sarif\n outputPath: reports/ps-rule-results.sarif\n
Invoke-PSRule# Analyze and save results\n- task: ps-rule-assert@2\n displayName: Analyze repository\n inputs:\n inputType: repository\n outputFormat: Sarif\n outputPath: reports/ps-rule-results.sarif\n
Assert-PSRuleInvoke-PSRule -OutputFormat Sarif -OutputPath reports/ps-rule-results.sarif\n
ps-rule.yamlAssert-PSRule -OutputFormat Sarif -OutputPath reports/ps-rule-results.sarif\n
"},{"location":"analysis-output/#formatting-as-yaml","title":"Formatting as YAML","text":"output:\n format: 'Sarif'\n path: reports/ps-rule-results.sarif\nWhen using the YAML output format, results a serialized as YAML. Two spaces are used to indent properties of objects.
Example output
"},{"location":"analysis-output/#formatting-as-json","title":"Formatting as JSON","text":"- data: {}\n info:\n displayName: Local.PS.RequireTLS\n name: Local.PS.RequireTLS\n synopsis: An example rule to require TLS.\n level: Error\n outcome: Fail\n outcomeReason: Processed\n reason:\n - The field 'configure.supportsHttpsTrafficOnly' is set to 'False'.\n - The field 'configure.minTLSVersion' does not exist.\n ruleName: Local.PS.RequireTLS\n runId: 16b0534165ffb5279beeb1672a251fc1ff3124b6\n source:\n - file: C:\\Dev\\Workspace\\PSRule\\docs\\authoring\\writing-rules\\settings.json\n line: 2\n position: 11\n type: File\n targetName: 1fe7c0f476b11301402d5017d87424c36ff085a8\n targetType: app1\n time: 0\nWhen using the JSON output format, results are serialized as JSON. By default, no indentation is used.
Example output
"},{"location":"analysis-output/#configuring-json-indentation","title":"Configuring JSON indentation","text":"[{\"data\":{},\"info\":{\"displayName\":\"Local.PS.RequireTLS\",\"name\":\"Local.PS.RequireTLS\",\"synopsis\":\"An example rule to require TLS.\"},\"level\":1,\"outcome\":\"Fail\",\"outcomeReason\":\"Processed\",\"reason\":[\"The field 'configure.supportsHttpsTrafficOnly' is set to 'False'.\",\"The field 'configure.minTLSVersion' does not exist.\"],\"ruleName\":\"Local.PS.RequireTLS\",\"runId\":\"df662aad3ae7adee6f35b9733c7aaa53dc4d6b96\",\"source\":[{\"file\":\"C:\\\\Dev\\\\Workspace\\\\PSRule\\\\docs\\\\authoring\\\\writing-rules\\\\settings.json\",\"line\":2,\"position\":11,\"type\":\"File\"}],\"targetName\":\"1fe7c0f476b11301402d5017d87424c36ff085a8\",\"targetType\":\"app1\",\"time\":0}]\nv1.8.0
The number of spaces used to indent properties and elements is configurable between
Example output with 2 spaces0to4spaces. By default, no indentation is used.
"},{"location":"analysis-output/#formatting-as-csv","title":"Formatting as CSV","text":"[\n {\n \"data\": {},\n \"info\": {\n \"displayName\": \"Local.PS.RequireTLS\",\n \"name\": \"Local.PS.RequireTLS\",\n \"synopsis\": \"An example rule to require TLS.\"\n },\n \"level\": 1,\n \"outcome\": \"Fail\",\n \"outcomeReason\": \"Processed\",\n \"reason\": [\n \"The field 'configure.supportsHttpsTrafficOnly' is set to 'False'.\",\n \"The field 'configure.minTLSVersion' does not exist.\"\n ],\n \"ruleName\": \"Local.PS.RequireTLS\",\n \"runId\": \"3afadfed32e57f5283ad71c1aa496da822ff0c84\",\n \"source\": [\n {\n \"file\": \"C:\\\\Dev\\\\Workspace\\\\PSRule\\\\docs\\\\authoring\\\\writing-rules\\\\settings.json\",\n \"line\": 2,\n \"position\": 11,\n \"type\": \"File\"\n }\n ],\n \"targetName\": \"1fe7c0f476b11301402d5017d87424c36ff085a8\",\n \"targetType\": \"app1\",\n \"time\": 0\n }\n]\nThe output from analysis can be formatted as comma-separated values (CSV). Formatting as CSV may be useful when manipulating output results by hand. Output of CSV format varies depending on if detailed or summary output is used.
For detailed output, the following columns are added to CSV output for each processed object:
Column DescriptionRuleNameThe name of the rule.TargetNameThe name of the object that was analyzed.TargetTypeThe type of the object that was analyzed.OutcomeThe outcome of the analysis, such asPassorFail.OutcomeReasonAn additional reason for the outcome such asInconclusive.SynopsisA short description of the rule.RecommendationThe recommendation of the rule.For summary output, the following columns are used:
Column DescriptionRuleNameThe name of the rule.PassThe number of objects that passed.FailThe number of objects that failed.OutcomeThe worst case outcome of the analysis, such asPassorFail.SynopsisA short description of the rule.RecommendationThe recommendation of the rule. Example output
"},{"location":"analysis-output/#formatting-as-sarif","title":"Formatting as SARIF","text":"RuleName,TargetName,TargetType,Outcome,OutcomeReason,Synopsis,Recommendation\n\"Local.PS.RequireTLS\",\"1fe7c0f476b11301402d5017d87424c36ff085a8\",\"app1\",\"Fail\",\"Processed\",\"An example rule to require TLS.\",\n\"Local.YAML.RequireTLS\",\"1fe7c0f476b11301402d5017d87424c36ff085a8\",\"app1\",\"Fail\",\"Processed\",\"An example rule to require TLS.\",\n\"Local.JSON.RequireTLS\",\"1fe7c0f476b11301402d5017d87424c36ff085a8\",\"app1\",\"Fail\",\"Processed\",\"An example rule to require TLS.\",\nv2.0.0
Static Analysis Results Interchange Format (SARIF) is a standard output format for static analysis tools. It enables various unrelated tools to consume analysis results from PSRule. You can use SARIF to perform Static Analysis Security Testing (SAST) in DevOps environments at-scale.
"},{"location":"analysis-output/#github-code-scanning-alerts","title":"GitHub code scanning alerts","text":"SARIF results from PSRule can be uploaded to GitHub to create code scanning alerts against a repository. You can see these results in your repository visible under Security > Code scanning alerts.
Tip
Code scanning is available for all public repositories, and for private repositories owned by organizations where GitHub Advanced Security is enabled. For more information, see About GitHub Advanced Security.
To configure GitHub Actions, perform the following steps:
Example
.github/workflows/analyze.yaml
"},{"location":"analysis-output/#azure-devops-scans-tab","title":"Azure DevOps scans tab","text":"name: Analyze\non:\n push:\n branches: [ main ]\n schedule:\n - cron: '24 22 * * 0' # At 10:24 PM, on Sunday each week\n workflow_dispatch:\n\njobs:\n oss:\n name: Analyze with PSRule\n runs-on: ubuntu-latest\n permissions:\n contents: read\n security-events: write\n steps:\n\n - name: Checkout\n uses: actions/checkout@v4\n\n - name: Run PSRule analysis\n uses: microsoft/ps-rule@v2.9.0\n with:\n outputFormat: Sarif\n outputPath: reports/ps-rule-results.sarif\n\n - name: Upload results to security tab\n uses: github/codeql-action/upload-sarif@v3\n with:\n sarif_file: reports/ps-rule-results.sarif\nSARIF results from PSRule can be uploaded and viewed within Azure DevOps. To add the scans tab to build results the SARIF SAST Scans Tab extension needs to be installed.
"},{"location":"analysis-output/#verifying-configuration","title":"Verifying configuration","text":"v3.0.0
The configuration used to run PSRule is included in properties of the run. This can be used to verify the configuration used to run PSRule.
"},{"location":"creating-your-pipeline/","title":"Creating your pipeline","text":"You can use PSRule to test Infrastructure as Code (IaC) artifacts throughout their lifecycle. By using validation within a continuous integration (CI) pipeline, any issues provide fast feedback.
Within the root directory of your IaC repository:
GitHub ActionsAzure PipelinesGeneric with PowerShellCreate a new GitHub Actions workflow by creating
.github/workflows/analyze-arm.yaml.name: Analyze templates\non:\n- pull_request\njobs:\n analyze_arm:\n name: Analyze templates\n runs-on: ubuntu-latest\n steps:\n\n - name: Checkout\n uses: actions/checkout@v4\n\n # Analyze Azure resources using PSRule for Azure\n - name: Analyze Azure template files\n uses: microsoft/ps-rule@v2.9.0\n with:\n modules: 'PSRule.Rules.Azure'\nThis will automatically install compatible versions of all dependencies.
Create a new Azure DevOps YAML pipeline by creating
.azure-pipelines/analyze-arm.yaml.steps:\n\n# Analyze Azure resources using PSRule for Azure\n- task: ps-rule-assert@2\n displayName: Analyze Azure template files\n inputs:\n inputType: repository\n modules: 'PSRule.Rules.Azure'\nThis will automatically install compatible versions of all dependencies.
Create a pipeline in any CI environment by using PowerShell.
$modules = @('PSRule.Rules.Azure')\nInstall-Module -Name $modules -Scope CurrentUser -Force -ErrorAction Stop;\nAssert-PSRule -InputPath '.' -Module $modules -Format File -ErrorAction Stop;\nTip
This example demonstrates using PSRule for Azure, a populate module for testing Azure IaC. Instead, you can write your own module or use one of our pre-built modules.
"},{"location":"creating-your-pipeline/#configuration","title":"Configuration","text":"Configuration options for PSRule are set within the
"},{"location":"creating-your-pipeline/#ignoring-rules","title":"Ignoring rules","text":"ps-rule.yamlfile.To prevent a rule executing you can either:
To exclude a rule, set
Rule.Excludeoption within theps-rule.yamlfile.[ Docs][3]
ps-rule.yamlrule:\n exclude:\n # Ignore the following rules for all objects\n - Azure.VM.UseHybridUseBenefit\n - Azure.VM.Standalone\nTo suppress an individual rule, set
Suppressionoption within theps-rule.yamlfile.[ Docs][4]
ps-rule.yamlsuppression:\n Azure.AKS.AuthorizedIPs:\n # Exclude the following externally managed AKS clusters\n - aks-cluster-prod-eus-001\n Azure.Storage.SoftDelete:\n # Exclude the following non-production storage accounts\n - storagedeveus6jo36t\n - storagedeveus1df278\nTo suppress an rules by condition, create a suppression group.
[ Docs][5]
---\n# Synopsis: Ignore test objects by name.\napiVersion: github.com/microsoft/PSRule/v1\nkind: SuppressionGroup\nmetadata:\n name: SuppressWithTargetName\nspec:\n rule:\n - 'FromFile1'\n - 'FromFile2'\n if:\n name: '.'\n in:\n - 'TestObject1'\n - 'TestObject2'\nTip
Use comments within
"},{"location":"creating-your-pipeline/#processing-changed-files-only","title":"Processing changed files only","text":"ps-rule.yamlto describe the reason why rules are excluded or suppressed. Meaningful comments help during peer review within a Pull Request (PR). Also consider including a date if the exclusions or suppressions are temporary.v2.5.0 \u00b7 Docs
To only process files that have changed within a pull request, set the
GitHub ActionsAzure PipelinesGeneric with PowerShellInput.IgnoreUnchangedPathoption.Update your GitHub Actions workflow by setting the
.github/workflows/analyze-arm.yamlPSRULE_INPUT_IGNOREUNCHANGEDPATHenvironment variable.name: Analyze templates\non:\n- pull_request\njobs:\n analyze_arm:\n name: Analyze templates\n runs-on: ubuntu-latest\n steps:\n\n - name: Checkout\n uses: actions/checkout@v4\n\n # Analyze Azure resources using PSRule for Azure\n - name: Analyze Azure template files\n uses: microsoft/ps-rule@v2.9.0\n with:\n modules: 'PSRule.Rules.Azure'\n env:\n PSRULE_INPUT_IGNOREUNCHANGEDPATH: true\nUpdate your Azure DevOps YAML pipeline by setting the
.azure-pipelines/analyze-arm.yamlPSRULE_INPUT_IGNOREUNCHANGEDPATHenvironment variable.steps:\n\n# Analyze Azure resources using PSRule for Azure\n- task: ps-rule-assert@2\n displayName: Analyze Azure template files\n inputs:\n inputType: repository\n modules: 'PSRule.Rules.Azure'\n env:\n PSRULE_INPUT_IGNOREUNCHANGEDPATH: true\nUpdate your PowerShell command-line to include the
PowerShellInput.IgnoreUnchangedPathoption.$modules = @('PSRule.Rules.Azure')\n$options = @{\n 'Input.IgnoreUnchangedPath' = $True\n}\nInstall-Module -Name $modules -Scope CurrentUser -Force -ErrorAction Stop;\nAssert-PSRule -Options $options -InputPath '.' -Module $modules -Format File -ErrorAction Stop;\nTip
In some cases it may be necessary to set
"},{"location":"deprecations/","title":"Deprecations","text":""},{"location":"deprecations/#deprecations-for-v3","title":"Deprecations for v3","text":""},{"location":"deprecations/#execution-options","title":"Execution options","text":"Repository.BaseRefto the default branch of your repository. By default, PSRule will detect the default branch of the repository from the build system environment variables.PSRule provides a number of execution options that control logging of certain events. In many cases these options turn a warning on or off.
These options are deprecated but replaced to provide more choice to when configuring logging options. Now you can configure the following:
The following execution options have been deprecated and will be removed from v3.
Tip
You do not need to configure both options. If you have the deprecated option configured, switch to the new option.
"},{"location":"deprecations/#rule-output-object","title":"Rule output object","text":"Several properties of the rule object have been renamed to improve consistency with other objects. Previously rules returned by
Get-PSRulereturned a rule object which included the following properties:These have been replaced with the following properties:
The changes apply from v2.1.0, however the old properties are still available for backwards compatibility. From v3 these properties will be removed. These changes do not affect normal usage of PSRule. Supporting scripts that directly use the old names may not work correctly until you update these names.
"},{"location":"deprecations/#language-block-interface","title":"Language block interface","text":"Several properties of Baselines and Selectors have been renamed to improve consistency.
These have been replaced with the following properties:
The changes apply from v2.1.0, however the old properties are still available for backwards compatibility. From v3 these properties will be removed. These changes do not affect normal usage of PSRule. Supporting scripts that directly use the old names may not work correctly until you update these names.
"},{"location":"deprecations/#deprecations-for-v2","title":"Deprecations for v2","text":""},{"location":"deprecations/#default-baseline-by-module-manifest","title":"Default baseline by module manifest","text":"When packaging baselines in a module, you may want to specify a default baseline. PSRule v1.9.0 added support for setting the default baseline in a module configuration.
Previously a default baseline could be set by specifying the baseline in the module manifest. From v1.9.0 this is deprecated and will be removed from v2.
For details on how to migrate to the new default baseline option, continue reading the upgrade notes.
"},{"location":"deprecations/#resources-without-an-api-version","title":"Resources without an API version","text":"When creating YAML and JSON resources you define a resource by specifying the
apiVersionandkind. To allow new schema versions for resources to be introduced in the future, anapiVersionwas introduced. For backwards compatibility, resources without anapiVersiondeprecated but supported. From v2 resources without anapiVersionwill be ignored.For details on how to add an
"},{"location":"faq/","title":"Frequently Asked Questions (FAQ)","text":""},{"location":"faq/#how-is-psrule-different-to-pester","title":"How is PSRule different to Pester?","text":"apiVersionto a resource, continue reading the upgrade notes.PSRule is a framework for testing infrastructure as code (IaC) and objects using rules. Rules can be written in PowerShell, YAML, or JSON. Some features include:
These features make PSRule ideal for validating:
If you want to test PowerShell code, consider using Pester, we do!
"},{"location":"faq/#what-pre-built-modules-are-available-for-psrule","title":"What pre-built modules are available for PSRule?","text":"PSRule rules modules can be found on the PowerShell Gallery using the tag
"},{"location":"faq/#how-do-i-configure-psrule","title":"How do I configure PSRule?","text":"PSRule-rules.PSRule and rules can be configured by:
For example:
# With cmdlet\n$option = New-PSRuleOption -OutputAs Summary -OutputCulture 'en-AU' -ExecutionUnprocessedObject 'Ignore' -Configuration @{\n CUSTOM_VALUE = 'example'\n}\n$items | Assert-PSRule -Option $option\n\n# With hashtable\n$items | Assert-PSRule -Option @{\n 'Output.As' = 'Summary'\n 'Output.Culture' = 'en-AU'\n 'Execution.UnprocessedObject' = 'Ignore'\n 'Configuration.CUSTOM_VALUE' = 'Example'\n}\n# With YAML\noutput:\n as: Summary\n culture: [ 'en-AU' ]\n\nexecution:\n unprocessedObject: Ignore\n\nconfiguration:\n CUSTOM_VALUE: Example\n# With environment variable in bash\nexport PSRULE_EXECUTION_UNPROCESSEDOBJECT=Ignore\nexport PSRULE_OUTPUT_AS=Summary\nexport PSRULE_OUTPUT_CULTURE=en-AU\nexport PSRULE_CONFIGURATION_CUSTOM_VALUE=Example\nFor a list of configuration options and usage see about_PSRule_Options.
"},{"location":"faq/#how-do-i-ignore-a-rule","title":"How do I ignore a rule?","text":"To prevent a rule executing you can either:
To exclude a rule use the
Rule.Excludeoption. To do this in YAML, add the following to theps-rule.yamloptions file.# YAML: Using the rule/exclude property\nrule:\n exclude:\n - 'My.FirstRule' # The name of the first rule to exclude.\n - 'My.SecondRule' # The name of the second rule to exclude.\nTo suppress a rule use the
Suppressionoption. To do this in YAML, add the following to theps-rule.yamloptions file.# YAML: Using the suppression property\nsuppression:\n My.FirstRule: # The name of the rule being suppressed\n - TestObject1 # The name of the first object to suppress\n - TestObject3 # The name of the second object to suppress\n My.SecondRule: # An additional rule to suppress\n - TestObject2\nThe name of the object is reported by PSRule in output results.
See about_PSRule_Options for additional usage for both of these options.
"},{"location":"faq/#how-do-exclude-or-ignore-files-from-being-processed","title":"How do exclude or ignore files from being processed?","text":"To exclude or ignore files from being processed, configure the Input.PathIgnore option. This option allows you to ignore files using a path spec.
For example:
input:\n pathIgnore:\n # Exclude files with these extensions\n - '*.md'\n - '*.png'\n # Exclude specific configuration files\n - 'bicepconfig.json'\nOr:
"},{"location":"faq/#how-do-i-disable-or-suppress-the-not-processed-warning","title":"How do I disable or suppress the not processed warning?","text":"input:\n pathIgnore:\n # Exclude all files\n - '*'\n # Only process deploy.bicep files\n - '!**/deploy.bicep'\nYou may receive a warning message suggesting a file or object has not been processed. If there are no rules that apply to the file or object this warning will be displayed.
Note
This warning is intended as a verification so that you are able to confirm your configuration is correct.
After you have tuned your configuration, you may wish to disable this warning to reduce output noise. To do this you have two options:
PSRule allows rules from modules and standalone (loose) rules to be run together.
To run rules from a standalone path use:
# Note: .ps-rule/ is a standard path to include standalone rules.\n\n# With input from the pipeline\n$items | Assert-PSRule -Path '.ps-rule/'\n\n# With input from file\nAssert-PSRule -Path '.ps-rule/' -InputPath 'src/'\nTo run rules from an installed module use:
# With input from the pipeline\n$items | Assert-PSRule -Module 'PSRule.Rules.Azure'\n\n# With input from file\nAssert-PSRule -Module 'PSRule.Rules.Azure' -InputPath 'src/'\nCombining both:
"},{"location":"faq/#why-should-i-use-psrule-keywords-and-assertions","title":"Why should I use PSRule keywords and assertions?","text":"Assert-PSRule -Module 'PSRule.Rules.Azure', 'PSRule.Rules.CAF' -Path '.ps-rule/' -InputPath 'src/'\nExcept for the
Rulekeyword, using the built-in language features are optional.The built-in keywords and assertions accelerate rule creation. They do this by providing a condition and a set of reasons in a single command.
Reasons are also optional; however, they provide additional context as to why the rule failed. Alternatively, you can provide your own reasons to complement standard PowerShell with the
"},{"location":"faq/#collection-of-telemetry","title":"Collection of telemetry","text":"Reasonkeyword.PSRule currently does not collect any telemetry during installation or execution.
PowerShell (used by PSRule) does collect basic telemetry by default. Collection of telemetry in PowerShell and how to opt-out is explained in about_Telemetry.
"},{"location":"features/","title":"Features","text":""},{"location":"features/#devops","title":"DevOps","text":"PSRule allows you to quickly plug-in Infrastructure as Code (IaC) controls into your DevOps pipeline.
Run on MacOS, Linux, and Windows or anywhere PowerShell is supported. Native support for popular continuous integration (CI) systems includes:
Import pre-built rules or define your own using YAML, JSON, or PowerShell format. Regardless of the format you choose, any combination of YAML, JSON, or PowerShell rules can be used together.
Rules can be authored using any text editor, but we provide a native extension for Visual Studio Code. Use the extension to quickly author rules or run tests locally before you commit your IaC.
"},{"location":"features/#reusable","title":"Reusable","text":"Typically unit tests in traditional testing frameworks are written for a specific case. This makes it hard invest in tests that are not easily reusable between projects. Several features of PSRule make it easier to reuse and share rules across teams or organizations.
The following built-in features improve portability:
PSRule supports running within continuous integration (CI) systems or locally. It is shipped as a PowerShell module which makes it easy to install and distribute updates.
Task Options Run tests within CI pipelines With GitHub Actions or Azure Pipelines or CLI or PowerShell Run tests locally during development With Visual Studio Code and CLI / PowerShell Create custom tests for your organization With Visual Studio Code and CLI / PowerShellTip
PSRule provides native integration to popular CI systems such as GitHub Actions and Azure Pipelines. If you are using a different CI system you can use the local install to run on MacOS, Linux, and Windows worker nodes.
"},{"location":"install/#with-github-actions","title":"With GitHub Actions","text":"GitHub Action
Install and use PSRule with GitHub Actions by referencing the
Specific versionLatest stable v2Latest stable GitHub Actionsmicrosoft/ps-ruleaction.
GitHub Actions- name: Analyze with PSRule\n uses: microsoft/ps-rule@v2.9.0\n
GitHub Actions- name: Analyze with PSRule\n uses: microsoft/ps-rule@v2\n- name: Analyze with PSRule\n uses: microsoft/ps-rule@latest\nThis will automatically install compatible versions of all dependencies.
Tip
The recommended approach is to pin to the latest specific version. Pinning to a specific version reduces the risk of new versions breaking your pipeline. You can easily update to the latest version by changing the version number. At such time, you can test the new version in a feature branch before merging to main.
"},{"location":"install/#working-with-dependabot","title":"Working with Dependabot","text":"You can use Dependabot to automatically upgrade your PSRule action if you use a specific version. When new versions a released Dependabot will automatically add a pull request (PR) for you to review and merge.
.github/dependabot.yaml
"},{"location":"install/#with-azure-pipelines","title":"With Azure Pipelines","text":"#\n# Dependabot configuration\n#\nversion: 2\nupdates:\n\n # Maintain GitHub Actions\n - package-ecosystem: github-actions\n directory: \"/\"\n schedule:\n interval: daily\nExtension
Install and use PSRule with Azure Pipeline by using extension tasks. Install the extension from the marketplace, then use the
ps-rule-asserttask in pipeline steps.- task: ps-rule-assert@2\n displayName: Analyze Azure template files\n inputs:\n inputType: repository\nThis will automatically install compatible versions of all dependencies.
"},{"location":"install/#with-visual-studio-code","title":"With Visual Studio Code","text":"Extension
An extension for Visual Studio Code is available for an integrated experience using PSRule. The Visual Studio Code extension includes a built-in tasks and configuration schemas for working with PSRule.
"},{"location":"install/#with-cli","title":"With CLI","text":"PSRule can be installed from NuGet.org using the .NET CLI where the .NET 8.0 SDK is available. You can use this option to install on CI workers that are not natively supported.
To install PSRule as a global tool use the following command line:
dotnet tool install -g Microsoft.PSRule.Tool\nTo install a specific version use the following command line:
dotnet tool install -g Microsoft.PSRule.Tool --version 3.0.0-B0151\nFor a list of commands supported by the CLI, see PSRule CLI.
"},{"location":"install/#with-powershell","title":"With PowerShell","text":"PSRule can be installed locally from the PowerShell Gallery using PowerShell. You can use this option to install on CI workers that are not natively supported.
"},{"location":"install/#prerequisites","title":"Prerequisites","text":"Operating System Tool Installation Link Windows Windows PowerShell 5.1 with .NET Framework 4.7.2 or greater. link Windows, MacOS, Linux PowerShell version 7.4.x or greater. linkNote
If you are using Windows PowerShell you may need to bootstrap NuGet before you can install modules. The NuGet package provider is not installed in Windows PowerShell be default. For instructions see Bootstrapping NuGet.
"},{"location":"install/#installing-powershell","title":"Installing PowerShell","text":"PowerShell 7.x can be installed on MacOS, Linux, and Windows but is not installed by default. For a list of platforms that PowerShell 7.4 is supported on and install instructions see Get PowerShell.
"},{"location":"install/#getting-the-modules","title":"Getting the modules","text":"Module
PSRule can be installed or updated from the PowerShell Gallery. Use the following command line examples from a PowerShell terminal to install or update PSRule.
For the current userFor all usersTo install PSRule for the current user use:
Install-Module -Name 'PSRule' -Repository PSGallery -Scope CurrentUser\nTo update PSRule for the current user use:
Update-Module -Name 'PSRule' -Scope CurrentUser\nOpen PowerShell with Run as administrator on Windows or
sudo pwshon Linux.To install PSRule for all users (requires admin/ root permissions) use:
Install-Module -Name 'PSRule' -Repository PSGallery -Scope AllUsers\nTo update PSRule for all users (requires admin/ root permissions) use:
"},{"location":"install/#pre-release-versions","title":"Pre-release versions","text":"Update-Module -Name 'PSRule' -Scope AllUsers\nTo use a pre-release version of PSRule add the
-AllowPrereleaseswitch when callingInstall-Module,Update-Module, orSave-Modulecmdlets.Tip
To install pre-release module versions, the latest version of PowerShellGet may be required.
For the current userFor all users# Install the latest PowerShellGet version\nInstall-Module -Name PowerShellGet -Repository PSGallery -Scope CurrentUser -Force\nTo install PSRule for the current user use:
Install-Module -Name PowerShellGet -Repository PSGallery -Scope CurrentUser -Force\nInstall-Module -Name 'PSRule' -Repository PSGallery -Scope CurrentUser -AllowPrerelease\nOpen PowerShell with Run as administrator on Windows or
sudo pwshon Linux.To install PSRule for all users (requires admin/ root permissions) use:
"},{"location":"install/#building-from-source","title":"Building from source","text":"Install-Module -Name PowerShellGet -Repository PSGallery -Scope CurrentUser -Force\nInstall-Module -Name 'PSRule' -Repository PSGallery -Scope AllUsers -AllowPrerelease\nSource
PSRule is provided as open source on GitHub. To build PSRule from source code:
This build script will compile the module and documentation then output the result into
"},{"location":"install/#development-dependencies","title":"Development dependencies","text":"out/modules/PSRule.The following PowerShell modules will be automatically install if the required versions are not present:
These additional modules are only required for building PSRule.
Additionally .NET SDK v8 is required. .NET will not be automatically downloaded and installed. To download and install the latest SDK see Download .NET 8.0.
"},{"location":"install/#limited-access-networks","title":"Limited access networks","text":"If you are on a network that does not permit Internet access to the PowerShell Gallery, download the required PowerShell modules on an alternative device that has access. PowerShell provides the
Save-Modulecmdlet that can be run from a PowerShell terminal to do this.The following command lines can be used to download the required modules using a PowerShell terminal. After downloading the modules, copy the module directories to devices with restricted Internet access.
Runtime modulesDevelopment modulesTo save PSRule for offline use:
Save-Module -Name 'PSRule' -Path '.\\modules'\nThis will save PSRule into the
modulessub-directory.To save PSRule development module dependencies for offline use:
$modules = @('PlatyPS', 'Pester', 'PSScriptAnalyzer', 'PowerShellGet',\n'PackageManagement', 'InvokeBuild')\nSave-Module -Name $modules -Repository PSGallery -Path '.\\modules';\nThis will save required developments dependencies into the
modulessub-directory.Tip
If you use additional rules modules such as PSRule for Azure you should also save these for offline use.
Note
If you are using Windows PowerShell you may need to bootstrap NuGet before you can install modules. The NuGet package provider is not installed in Windows PowerShell be default. For instructions see Bootstrapping NuGet.
"},{"location":"license-contributing/","title":"License and contributing","text":"PSRule is licensed with an MIT License, which means it's free to use and modify. But please check out the details.
We open source at Microsoft.
In addition to our team, we hope you will think about contributing too. Here is how you can get started:
The PSRule project is distributed across multiple repositories. You can find out more by visiting each repository.
Name Description ps-rule GitHub continuous integration using GitHub Actions. PSRule-pipelines Azure DevOps continuous integration using Azure Pipelines. PSRule-vscode Support for running and authoring rules within Visual Studio Code. PSRule.Monitor Support for logging PSRule analysis results to Azure Monitor. PSRule.Rules.Azure Rules to validate Azure resources and infrastructure as code (IaC) using PSRule. PSRule.Rules.Azure-quickstart Sample code you can use to quickly start using PSRule for Azure. PSRule.Rules.CAF A suite of rules to validate Azure resources against the Cloud Adoption Framework (CAF) using PSRule. PSRule.Rules.GitHub A suite of rules to validate GitHub repositories using PSRule. PSRule.Rules.Kubernetes A suite of rules to validate Kubernetes resources using PSRule. PSRule.Rules.MSFT.OSS A suite of rules to validate repositories against Microsoft Open Source Software (OSS) requirements."},{"location":"related-projects/#community-modules","title":"Community modules","text":"The following third-party modules are created, maintained, supported, and licensed by their respective authors. Before consuming these module, double check they meet your organization's support, security, and licensing expectations.
Author Name Description cloudyspells PSRule.Rules.AzureDevOps A suite of rules to validate Azure DevOps projects using PSRule."},{"location":"support/","title":"Support","text":"This project uses GitHub Issues to track bugs and feature requests.
Please search the existing issues before filing new issues to avoid duplicates.
Support for this project/ product is limited to the resources listed above.
"},{"location":"troubleshooting/","title":"Troubleshooting","text":"Abstract
This article provides troubleshooting instructions for common errors generic to PSRule or core functionality.
Tip
See troubleshooting specific to PSRule for Azure for common errors when testing Azure resources using the
"},{"location":"troubleshooting/#custom-rules-are-not-running","title":"Custom rules are not running","text":"PSRule.Rules.Azuremodule.There is a few common causes of this issue including:
Tip
You may be able to use
"},{"location":"troubleshooting/#windows-powershell-is-in-noninteractive-mode","title":"Windows PowerShell is in NonInteractive mode","text":"git mvto change the case of a file if it is committed to the repository incorrectly.When running PSRule on a Windows self-hosted agent/ private runner you may encounter an error similar to the following:
Error
Exception calling \"ShouldContinue\" with \"2\" argument(s): \"Windows PowerShell is in NonInteractive mode. Read and Prompt functionality is not available.\"
This error may be caused by the PowerShell NuGet package provider not being installed. By default, Windows PowerShell does not have these components installed. These components are required for installing and checking versions of PSRule modules.
To resolve this issue, install the NuGet package provider during setup the agent/ runner by using the following script:
if ($Null -eq (Get-PackageProvider -Name NuGet -ErrorAction Ignore)) {\n Install-PackageProvider -Name NuGet -Force -Scope CurrentUser;\n}\nAdditionally consider installing the latest version of
PowerShellGetby using the following script:
"},{"location":"troubleshooting/#format-default-error-when-running-invoke-psrule","title":"Format-Default error when running Invoke-PSRule","text":"if ($Null -eq (Get-InstalledModule -Name PowerShellGet -MinimumVersion 2.2.1 -ErrorAction Ignore)) {\n Install-Module PowerShellGet -MinimumVersion 2.2.1 -Scope CurrentUser -Force -AllowClobber;\n}\nWhen running PSRule you may encounter an error similar to the following:
Error
Format-Default: Cannot process argument because the value of argument \"name\" is not valid. Change the value of the \"name\" argument and run the operation again.
This error is caused by a known issue in PowerShell 7.4.0 and 7.4.1. To resolve this issue, upgrade to PowerShell 7.4.2 or later.
For more details see #1723.
"},{"location":"troubleshooting/#psr0001-unable-to-read-options-file","title":"PSR0001 - Unable to read options file","text":"When running PSRule you may encounter an error similar to the following:
Error
PSR0001: Unable to read options file 'ps-rule.yaml'.
This error typically indicates a problem with the YAML syntax in the
ps-rule.yamlfile. Double check the file for incorrect indentation or missing punctuation such as-and:characters.If you still have an issue, try re-saving the file as UTF-8 in an editor such as Visual Studio Code.
"},{"location":"troubleshooting/#psr0002-summary-results-are-not-supported-with-job-summaries","title":"PSR0002 - Summary results are not supported with Job Summaries","text":"Error
PSR0002: Summary results are not supported with Job Summaries.
Currently using the
Output.Aswith theSummaryoption is not supported with job summaries. Choose to use one or the other.If you have a specific use case your would like to enable, please start a discussion.
"},{"location":"troubleshooting/#psr0003-the-specified-baseline-group-is-not-known","title":"PSR0003 - The specified baseline group is not known","text":"Error
PSR0003: The specified baseline group 'latest' is not known.
This error is caused by attempting to reference a baseline group which has not been defined. To define a baseline group, see Baseline.Group option.
"},{"location":"troubleshooting/#psr0004-the-specified-resource-is-not-known","title":"PSR0004 - The specified resource is not known","text":"Error
PSR0004: The specified Baseline resource 'TestModule4\\Module4' is not known.
This error is caused when you attempt to reference a resource such as a baseline, rule, or selector which has not been defined.
"},{"location":"upgrade-notes/","title":"Upgrade notes","text":"This document contains notes to help upgrade from previous versions of PSRule.
"},{"location":"upgrade-notes/#upgrading-to-v300","title":"Upgrading to v3.0.0","text":""},{"location":"upgrade-notes/#unbound-object-names","title":"Unbound object names","text":"When an object is processed by PSRule, it is assigned a name. This name is used to identify the object in the output and to suppress the object from future processing.
Prior to v3.0.0, the name was generated using a SHA-1 hash of the object. The SHA-1 algorithm is no longer considered secure and has been replaced with SHA-512.
From v3.0.0, if the name of an object can not be determined, the SHA-512 hash of the object will be used. Any objects that have previously been suppressed with a name based on a SHA-1 hash will no longer be suppressed.
To resolve any issue caused by this change, you can:
From v3.0.0, PSRule requires:
Support for Windows PowerShell 5.1 is deprecated and will be removed in a future release of PSRule (v4). We recommend upgrading to PowerShell 7.3 or later.
At the time of writing, PowerShell 7.3 is the most recent version of PowerShell. PowerShell 7.4 is expected, and PSRule v4 will aim to support the latest version of PowerShell as the minimum requirement.
"},{"location":"upgrade-notes/#changes-to-cli-commands","title":"Changes to CLI commands","text":"From v3.0.0, the CLI command names have been renamed to simplify usage. The following changes have been made:
The
runcommand provides similar output to theAssert-PSRulecmdlet in PowerShell.Previously the
restorecommand installed modules based on the configuration of the Requires option. From v3.0.0, themodule restorecommand installs modules based on:When naming resources such as rules or selectors, the following restrictions apply:
Prior to v2.0.0, there was no specific naming restriction for resources. However functionally PSRule and downstream components could not support all resource names. To avoid confusion, we have decided to restrict resource names to a specific set of characters.
From v2.0.0, resource names that do not meet the naming restrictions will generate an error.
Regular expression for valid resource names
"},{"location":"upgrade-notes/#setting-default-module-baseline","title":"Setting default module baseline","text":"^[^<>:/\\\\|?*\"'`+@._\\-\\x00-\\x1F][^<>:/\\\\|?*\"'`+@\\x00-\\x1F]{1,126}[^<>:/\\\\|?*\"'`+@._\\-\\x00-\\x1F]$\nWhen packaging rules in a module, you can set the default baseline. The default baseline from the module will be automatically used unless overridden.
Prior to v1.9.0 the default baseline was set by configuring the module manifest
.psd1file. From v1.9.0 the default baseline can be configured by within a module configuration. Using module configuration is the recommended method. Setting the default baseline from module manifest and has been removed from v2.0.0.A module configuration can be defined in YAML.
Example
"},{"location":"upgrade-notes/#setting-resource-api-version","title":"Setting resource API version","text":"---\n# Synopsis: Example module configuration for Enterprise.Rules module.\napiVersion: github.com/microsoft/PSRule/v1\nkind: ModuleConfig\nmetadata:\n name: Enterprise.Rules\nspec:\n rule:\n baseline: Enterprise.Default\nWhen creating YAML and JSON resources you define a resource by specifying the
apiVersionandkind. AnapiVersionwas added as a requirement from v1.2.0. For compatibility, resources without anapiVersionwere supported however deprecated for removal. This has now been removed from v2.0.0.When defining resource specify an
YAMLJSONapiVersion. Currently this must be set togithub.com/microsoft/PSRule/v1.---\n# Synopsis: An example rule to require TLS.\napiVersion: github.com/microsoft/PSRule/v1\nkind: Rule\nmetadata:\n name: 'Local.YAML.RequireTLS'\nspec:\n condition:\n field: 'configure.supportsHttpsTrafficOnly'\n equals: true\n
"},{"location":"upgrade-notes/#change-in-source-file-discovery-for-get-psrulehelp","title":"Change in source file discovery for Get-PSRuleHelp","text":"[\n {\n // Synopsis: An example rule to require TLS.\n \"apiVersion\": \"github.com/microsoft/PSRule/v1\",\n \"kind\": \"Rule\",\n \"metadata\": {\n \"name\": \"Local.JSON.RequireTLS\"\n },\n \"spec\": {\n \"condition\": {\n \"field\": \"configure.supportsHttpsTrafficOnly\",\n \"equals\": true\n }\n }\n }\n]\nPreviously in PSRule v1.11.0 and prior versions, rules would show up twice when running
Get-PSRuleHelpin the context of a module and in the same working directory of the module. This behavior has now been removed from v2.0.0.Module files are now preferred over loose files, and rules are only shown once in the output. Any duplicate rule names from loose files are outputted as a warning instead.
The old behavior:
Name ModuleName Synopsis\n---- ---------- --------\nM1.Rule1 This is the default\nM1.Rule2 This is the default\nM1.Rule1 TestModule Synopsis en-AU.\nM1.Rule2 TestModule This is the default\nThe new behavior:
"},{"location":"upgrade-notes/#require-source-discovery-from-current-working-directory-to-be-explicitly-included","title":"Require source discovery from current working directory to be explicitly included","text":"WARNING: A rule with the same name 'M1.Rule1' already exists.\nWARNING: A rule with the same name 'M1.Rule2' already exists.\n\nName ModuleName Synopsis\n---- ---------- --------\nM1.Rule1 TestModule Synopsis en-AU.\nM1.Rule2 TestModule This is the default\nPreviously in PSRule v1.11.0 and prior versions, rule sources from the current working directory without the
-Pathand-Moduleparameters were automatically included. This behavior has now been removed from v2.0.0.Rules sources in the current working directory are only included if
-Path .or-Path $PWDis specified.The old behavior:
PowerShellSet-Location docs\\scenarios\\azure-resources\nGet-PSRule\n\nRuleName ModuleName Synopsis\n-------- ---------- --------\nappServicePlan.MinInstanceCount App Service Plan has multiple instances\nappServicePlan.MinPlan Use at least a Standard App Service Plan\nappServiceApp.ARRAffinity Disable client affinity for stateless services\nappServiceApp.UseHTTPS Use HTTPS only\nstorageAccounts.UseHttps Configure storage accounts to only accept encrypted traffic i.e. HTTPS/SMB\nstorageAccounts.UseEncryption Use at-rest storage encryption\nThe new behavior:
PowerShell
"},{"location":"upgrade-notes/#upgrading-to-v140","title":"Upgrading to v1.4.0","text":"Set-Location docs\\scenarios\\azure-resources\nGet-PSRule\n\n# No output, need to specify -Path explicitly\n\nGet-PSRule -Path $PWD\n\nRuleName ModuleName Synopsis\n-------- ---------- --------\nappServicePlan.MinInstanceCount App Service Plan has multiple instances\nappServicePlan.MinPlan Use at least a Standard App Service Plan\nappServiceApp.ARRAffinity Disable client affinity for stateless services\nappServiceApp.UseHTTPS Use HTTPS only\nstorageAccounts.UseHttps Configure storage accounts to only accept encrypted traffic i.e. HTTPS/SMB\nstorageAccounts.UseEncryption \nFollow these notes to upgrade to PSRule v1.4.0 from previous versions.
"},{"location":"upgrade-notes/#change-in-default-output-styles","title":"Change in default output styles","text":"Previously in PSRule v1.3.0 and prior the default style when using
Assert-PSRulewasClient. From v1.4.0 PSRule now defaults toDetect.The
Detectoutput style falls back toClienthowever may detect one of the following styles instead:Detect uses the following logic:
To force usage of the
ps-rule.yamlClientoutput style set theOutput.Styleoption. For example:# YAML: Using the output/style property\noutput:\n style: Client\n
GitHub Actions# Bash: Using environment variable\nexport PSRULE_OUTPUT_STYLE=Client\n
Azure Pipelines# GitHub Actions: Using environment variable\nenv:\n PSRULE_OUTPUT_STYLE: Client\n
"},{"location":"upgrade-notes/#upgrading-to-v100","title":"Upgrading to v1.0.0","text":"# Azure Pipelines: Using environment variable\nvariables:\n- name: PSRULE_OUTPUT_STYLE\n value: Client\nFollow these notes to upgrade to PSRule v1.0.0 from previous versions.
"},{"location":"upgrade-notes/#replaced-rule-target-properties","title":"Replaced $Rule target properties","text":"Previously in PSRule v0.22.0 and prior the
$Ruleautomatic variable had the following properties:For example:
PowerShell rulesRule 'Rule1' {\n $Rule.TargetName -eq 'Name1';\n $Rule.TargetType -eq '.json';\n $Rule.TargetObject.someProperty -eq 1;\n}\nIn v1.0.0 these properties have been removed after being deprecated in v0.12.0. These properties are instead available on the
$PSRulevariable. Rules referencing the deprecated properties of$Rulemust be updated.For example:
PowerShell rules
"},{"location":"validating-locally/","title":"Validating locally","text":"Rule 'Rule1' {\n $PSRule.TargetName -eq 'Name1';\n $PSRule.TargetType -eq '.json';\n $PSRule.TargetObject.someProperty -eq 1;\n}\nPSRule can be installed locally on MacOS, Linux, and Windows for local validation. This allows you to test Infrastructure as Code (IaC) artifacts before pushing changes to a repository.
Tip
If you haven't already, follow the instructions on installing locally before continuing.
"},{"location":"validating-locally/#with-visual-studio-code","title":"With Visual Studio Code","text":"Extension
An extension for Visual Studio Code is available for an integrated experience using PSRule. The Visual Studio Code extension includes a built-in task PSRule: Run analysis task.
Info
To learn about tasks in Visual Studio Code see Integrate with External Tools via Tasks.
"},{"location":"validating-locally/#customizing-the-task","title":"Customizing the task","text":"The PSRule: Run analysis task will be available automatically after you install the PSRule extension. You can customize the defaults of the task by editing or inserting the task into
JSON.vscode/tasks.jsonwithin your workspace.{\n \"type\": \"PSRule\",\n \"problemMatcher\": [\n \"$PSRule\"\n ],\n \"label\": \"PSRule: Run analysis\",\n \"modules\": [\n \"PSRule.Rules.Azure\"\n ],\n \"presentation\": {\n \"clear\": true,\n \"panel\": \"dedicated\"\n }\n}\nExample
A complete
.vscode/tasks.json.vscode/tasks.jsonmight look like the following:
"},{"location":"versioning/","title":"Changes and versioning","text":"{\n \"version\": \"2.0.0\",\n \"tasks\": [\n {\n \"type\": \"PSRule\",\n \"problemMatcher\": [\n \"$PSRule\"\n ],\n \"label\": \"PSRule: Run analysis\",\n \"modules\": [\n \"PSRule.Rules.Azure\"\n ],\n \"presentation\": {\n \"clear\": true,\n \"panel\": \"dedicated\"\n }\n }\n ]\n}\nPSRule uses semantic versioning to declare breaking changes. The latest module version can be installed from the PowerShell Gallery. For a list of module changes please see the change log.
"},{"location":"versioning/#pre-releases","title":"Pre-releases","text":"Pre-release module versions are created on major commits and can be installed from the PowerShell Gallery. Module versions and change log details for pre-releases will be removed as stable releases are made available.
Important
Pre-release versions should be considered work in progress. These releases should not be used in production. We may introduce breaking changes between a pre-release as we work towards a stable version release.
"},{"location":"versioning/#experimental-features","title":"Experimental features","text":"From time to time we may ship experiential features. These features are generally marked experiential in the change log as these features ship. Experimental features may ship in stable releases, however to use them you may need to:
Important
Experimental features should be considered work in progress. These features may be incomplete and should not be used in production. We may introduce breaking changes for experimental features as we work towards a general release for the feature.
"},{"location":"versioning/#reporting-bugs","title":"Reporting bugs","text":"If you experience an issue with an pre-release or experimental feature please let us know by logging an issue as a bug.
"},{"location":"authoring/packaging-rules/","title":"Packaging rules in a module","text":"PSRule supports distribution of rules within modules. Using a module, rules can be published and installed using standard PowerShell cmdlets.
You should consider packaging rules into a module to:
This scenario covers the following:
When creating a PowerShell module, a module manifest is an optional file that stores module metadata. Module manifests use the
"},{"location":"authoring/packaging-rules/#creating-the-manifest-file","title":"Creating the manifest file","text":".psd1file extension. When packaging rules in a module, a module manifest is required for PSRule discover the module.A module manifest can be created from PowerShell using the
New-ModuleManifestcmdlet. Additionally, Visual Studio Code and many other tools also include snippets for creating a module manifest.For example:
# Create a directory for the module\nmd ./Enterprise.Rules;\n\n# Create the manifest\nNew-ModuleManifest -Path ./Enterprise.Rules/Enterprise.Rules.psd1 -Tags 'PSRule-rules';\nThe example above creates a module manifest for a module named Enterprise.Rules tagged with
"},{"location":"authoring/packaging-rules/#setting-module-tags","title":"Setting module tags","text":"PSRule-rules. The use of thePSRule-rulestag is explained in the following section.When PSRule cmdlets are used with the
-Moduleparameter, PSRule discovers rule modules. If the module is already imported, that module is used. If the module is not imported, PSRule will import the highest version of the module automatically.For a module to be discovered by PSRule, tag the module with
PSRule-rules. To tag modules, find theTagssection thePSDatahashtable in the module manifest and addPSRule-rules.An updated module manifest may look like this:
"},{"location":"authoring/packaging-rules/#including-rules-and-baselines","title":"Including rules and baselines","text":"# Private data to pass to the module specified in RootModule/ModuleToProcess. This may also contain a PSData hashtable with additional module metadata used by PowerShell.\nPrivateData = @{\n PSData = @{\n # Tags applied to this module. These help with module discovery in online galleries.\n Tags = @('PSRule-rules')\n }\n}\nRules and baselines can be included anywhere within the module directory structure. Such as in the root directory of the module or in a nested sub-directory.
By convention, consider including rules and baselines within a
rulessub-directory within the module.For example:
For PSRule to find rules included in a module, rule file names must end with the
.Rule.ps1suffix. We recommend using the exact case.Rule.ps1. This is because some file systems are case-sensitive. For example, on LinuxStandards.rule.ps1would be ignored by PSRule.Similarly, when including baselines within a module use the
"},{"location":"authoring/packaging-rules/#defining-a-module-configuration","title":"Defining a module configuration","text":".Rule.yamlsuffix.A module configuration that sets options defaults and can be optionally packaged with a module. To set a module configuration, define a
ModuleConfigresource within an included.Rule.yamlfile. A module configuration.Rule.yamlfile must be distributed within the module directory structure.PSRule only supports a single
ModuleConfigresource. The name of theModuleConfigmust match the name of the module. AdditionalModuleConfigresources or with an alternative name are ignored. PSRule does not support module configurations distributed outside of a module.Example
---\n# Synopsis: Example module configuration for Enterprise.Rules module.\napiVersion: github.com/microsoft/PSRule/v1\nkind: ModuleConfig\nmetadata:\n name: Enterprise.Rules\nspec:\n binding:\n targetName:\n - ResourceName\n - FullName\n - name\n targetType:\n - ResourceType\n - type\n - Extension\n field:\n resourceId: [ 'ResourceId' ]\n subscriptionId: [ 'SubscriptionId' ]\n resourceGroupName: [ 'ResourceGroupName' ]\n rule:\n baseline: Enterprise.Default\nThe following options are allowed within a
ModuleConfig:Optionally, baselines can be included in rule modules. If a baseline contains configuration or binding options then setting a default baseline is often desirable. When a default baseline is set, PSRule will use the named baseline automatically when processing rules from that module. This feature removes the need for users to specify it manually.
To set a default baseline, set the
Rule.Baselineproperty of theModuleConfigresource.Example
---\n# Synopsis: Example module configuration for Enterprise.Rules module.\napiVersion: github.com/microsoft/PSRule/v1\nkind: ModuleConfig\nmetadata:\n name: Enterprise.Rules\nspec:\n binding:\n targetName:\n - ResourceName\n - FullName\n - name\n targetType:\n - ResourceType\n - type\n - Extension\n field:\n resourceId: [ 'ResourceId' ]\n subscriptionId: [ 'SubscriptionId' ]\n resourceGroupName: [ 'ResourceGroupName' ]\n rule:\n baseline: Enterprise.Default\nThis examples set the default baseline to
"},{"location":"authoring/packaging-rules/#including-documentation","title":"Including documentation","text":"Enterprise.Default. The default baseline must be included in file ending with.Rule.yamlwithin the module directory structure.PSRule supports write and packaging rule modules with markdown documentation. Markdown documentation is automatically interpreted by PSRule and included in output.
When including markdown, files are copied into a directory structure based on the target culture.
For example, store documentation targeted to the culture
en-USin a directory nameden-US. Similarly, documentation for cultures such asen-AU,en-GBandfr-FRwould be in separate directories.If a directory for the exact culture
en-USdoesn't exist, PSRule will attempt to find the parent culture. For example, documentation would be read from a directory nameden.When naming directories for their culture, use exact case. This is because some file systems are case-sensitive. For example on Linux
en-uswould not match.For example:
Rules are stored in one or more files and each file can contain one or many rules. Additionally, rules can be grouped into a module and distributed.
Abstract
This topic covers recommendations for naming and storing rules.
"},{"location":"authoring/storing-rules/#using-a-standard-file-path","title":"Using a standard file path","text":"Rules can be standalone or packaged within a module. Standalone rules are ideal for a single project such as an Infrastructure as Code (IaC) repository. To reuse rules across multiple projects consider packaging these as a module.
The instructions for packaging rules in a module can be found here:
To store standalone rules we recommend that you:
Note
Build pipelines are often case-sensitive or run on Linux-based systems. Using the casing rule above reduces confusion latter when you configure continuous integration (CI).
"},{"location":"authoring/storing-rules/#naming-rules","title":"Naming rules","text":"When running PSRule, rule names must be unique. For example, PSRule for Azure uses the name prefix of
Azure.for rules included in the module.Example
The following names are examples of rules included within PSRule for Azure:
In addition, names for rules and other resources must meet the following requirements:
^[^<>:/\\\\|?*\"'`+@._\\-\\x00-\\x1F][^<>:/\\\\|?*\"'`+@\\x00-\\x1F]{1,126}[^<>:/\\\\|?*\"'`+@._\\-\\x00-\\x1F]$\nWhen naming rules we recommend that you:
You can use PSRule to create tests for Infrastructure as Code (IaC). Each test is called a rule.
PSRule allows you to write rules using YAML, JSON, or PowerShell. Regardless of the format you choose, any combination of YAML, JSON, or PowerShell rules can be used together.
Abstract
This topic covers how to create a rule using YAML, JSON, and PowerShell by example. This example, while fictitious is indicative of common testing and validation scenarios for IaC.
"},{"location":"authoring/testing-infrastructure/#sample-data","title":"Sample data","text":"To get started authoring a rule, we will be working with a sample file
settings.json. This sample configuration file configures an application.For the purpose of this example, one configuration setting
supportsHttpsTrafficOnlyis set. This configuration setting can be eithertrueorfalse. When set totrue, Transport Layer Security (TLS) is enforced. When set tofalse, the application permits insecure communication with HTTP.Contents of
settings.jsonCreate a
settings.jsonfile in the root of your repository with the following contents.
"},{"location":"authoring/testing-infrastructure/#define-a-rule","title":"Define a rule","text":"{\n \"type\": \"app1\",\n \"version\": 1,\n \"configure\": {\n \"supportsHttpsTrafficOnly\": false\n }\n}\nTo meet the requirements of our organization we want to write a rule to:
In this section the same rule will be authored using YAML, JSON, and PowerShell.
Tip
To make you editing experience even better, consider installing the Visual Studio Code extension.
YAMLJSONPowerShellCreate a
.ps-rule/Local.Rule.yamlfile in your repository with the following contents.---\n# Synopsis: An example rule to require TLS.\napiVersion: github.com/microsoft/PSRule/v1\nkind: Rule\nmetadata:\n name: 'Local.YAML.RequireTLS'\nspec:\n condition:\n field: 'configure.supportsHttpsTrafficOnly'\n equals: true\nCreate a
.ps-rule/Local.Rule.jsoncfile in your repository with the following contents.[\n {\n // Synopsis: An example rule to require TLS.\n \"apiVersion\": \"github.com/microsoft/PSRule/v1\",\n \"kind\": \"Rule\",\n \"metadata\": {\n \"name\": \"Local.JSON.RequireTLS\"\n },\n \"spec\": {\n \"condition\": {\n \"field\": \"configure.supportsHttpsTrafficOnly\",\n \"equals\": true\n }\n }\n }\n]\nCreate a
.ps-rule/Local.Rule.ps1file in your repository with the following contents.# Synopsis: An example rule to require TLS.\nRule 'Local.PS.RequireTLS' {\n $Assert.HasFieldValue($TargetObject, 'configure.supportsHttpsTrafficOnly', $True)\n}\nTip
To learn more about recommended file and naming conventions for rules, continue reading Storing and naming rules.
"},{"location":"authoring/testing-infrastructure/#using-multiple-conditions","title":"Using multiple conditions","text":"Each rule must have at least one condition. Additional conditions can be combined to check multiple test cases.
In the example a
YAMLJSONPowerShellminTLSVersionconfiguration setting does not exist and is not set.Update
.ps-rule/Local.Rule.yamlin your repository with the following contents.---\n# Synopsis: An example rule to require TLS.\napiVersion: github.com/microsoft/PSRule/v1\nkind: Rule\nmetadata:\n name: 'Local.YAML.RequireTLS'\nspec:\n condition:\n allOf:\n - field: 'configure.supportsHttpsTrafficOnly'\n equals: true\n - field: 'configure.minTLSVersion'\n equals: '1.2'\nUpdate
.ps-rule/Local.Rule.jsoncin your repository with the following contents.[\n {\n // Synopsis: An example rule to require TLS.\n \"apiVersion\": \"github.com/microsoft/PSRule/v1\",\n \"kind\": \"Rule\",\n \"metadata\": {\n \"name\": \"Local.JSON.RequireTLS\"\n },\n \"spec\": {\n \"condition\": {\n \"allOf\": [\n {\n \"field\": \"configure.supportsHttpsTrafficOnly\",\n \"equals\": true\n },\n {\n \"field\": \"configure.minTLSVersion\",\n \"equals\": \"1.2\"\n }\n ]\n }\n }\n }\n]\nUpdate
.ps-rule/Local.Rule.ps1in your repository with the following contents.# Synopsis: An example rule to require TLS.\nRule 'Local.PS.RequireTLS' {\n $Assert.HasFieldValue($TargetObject, 'configure.supportsHttpsTrafficOnly', $True)\n $Assert.HasFieldValue($TargetObject, 'configure.minTLSVersion', '1.2')\n}\nTo test the rule manually, run the following command.
"},{"location":"authoring/testing-infrastructure/#advanced-usage","title":"Advanced usage","text":""},{"location":"authoring/testing-infrastructure/#severity-level","title":"Severity level","text":"Assert-PSRule -f ./settings.json\nv2.0.0
When defining a rule, you can specify a severity level. The severity level is used if the rule fails. By default, the severity level for a rule is
Error.In a continuous integration (CI) pipeline, severity level is particularly important. If any rule fails with a severity level of
Errorthe pipeline will fail. This helps prevent serious problems from being introduced into the code base or deployed.The following example shows how to set the severity level to
YAMLJSONPowerShellWarning.---\n# Synopsis: An example rule to require TLS.\napiVersion: github.com/microsoft/PSRule/v1\nkind: Rule\nmetadata:\n name: 'Local.YAML.RequireTLS'\nspec:\n level: Warning\n condition:\n allOf:\n - field: 'configure.supportsHttpsTrafficOnly'\n equals: true\n - field: 'configure.minTLSVersion'\n equals: '1.2'\n[\n {\n // Synopsis: An example rule to require TLS.\n \"apiVersion\": \"github.com/microsoft/PSRule/v1\",\n \"kind\": \"Rule\",\n \"metadata\": {\n \"name\": \"Local.JSON.RequireTLS\"\n },\n \"spec\": {\n \"level\": \"Warning\",\n \"condition\": {\n \"allOf\": [\n {\n \"field\": \"configure.supportsHttpsTrafficOnly\",\n \"equals\": true\n },\n {\n \"field\": \"configure.minTLSVersion\",\n \"equals\": \"1.2\"\n }\n ]\n }\n }\n }\n]\nUpdate
.ps-rule/Local.Rule.ps1in your repository with the following contents.
"},{"location":"authoring/using-expressions/","title":"Using expressions","text":"# Synopsis: An example rule to require TLS.\nRule 'Local.PS.RequireTLS' -Level Warning {\n $Assert.HasFieldValue($TargetObject, 'configure.supportsHttpsTrafficOnly', $True)\n $Assert.HasFieldValue($TargetObject, 'configure.minTLSVersion', '1.2')\n}\nPSRule allows you to write rules using YAML, JSON, or PowerShell. This offers a lot of flexibility to use PSRule for a variety of use cases. Some examples of use cases for each format include:
Abstract
This topic covers the differences and limitations between authoring rules using YAML, JSON, and PowerShell. For an example of authoring rules see Writing rules or Testing infrastructure topics.
"},{"location":"authoring/using-expressions/#language-comparison","title":"Language comparison","text":"Expressions and assertion methods can be used to build similar conditions.
In most cases expressions and assertion method names match. There are some cases where these names do not directly align. This lookup table provides a quick reference for expressions and their assertion method counterpart.
Expression Assertion method Contains Contains Count Count Equals 1 n/a EndsWith EndsWith Exists HasField Greater Greater GreaterOrEquals GreaterOrEqual HasDefault HasDefaultValue HasSchema HasJsonSchema HasValue 1 n/a In In IsLower IsLower IsString IsString IsUpper IsUpper Less Less LessOrEquals LessOrEqual Match Match NotEquals n/a NotIn NotIn NotMatch NotMatch SetOf SetOf StartsWith StartsWith Subset Subset Version Version n/a FileHeader n/a FilePath n/a HasFields n/a HasFieldValue 1 IsArray IsArray IsBoolean IsBoolean IsDateTime IsDateTime IsInteger IsInteger IsNumeric IsNumeric n/a JsonSchema Exists NotHasField n/a NotNull NotWithinPath NotWithinPath n/a Null n/a NullOrEmpty n/a TypeOf WithinPath WithinPathPSRule has built-in support for help. Documentation can optionally be added for each rule to provide detailed information or remediation steps.
This scenario covers the following:
With authoring rules in YAML and JSON, PSRule provides the following syntax features:
Specify the synopsis of the rule with the
YAMLJSONSynopsiscomment above the rule properties.---\n# Synopsis: An example rule to require TLS.\napiVersion: github.com/microsoft/PSRule/v1\nkind: Rule\nmetadata:\n name: 'Local.YAML.RequireTLS'\nspec:\n condition:\n field: 'configure.supportsHttpsTrafficOnly'\n equals: true\n[\n {\n // Synopsis: An example rule to require TLS.\n \"apiVersion\": \"github.com/microsoft/PSRule/v1\",\n \"kind\": \"Rule\",\n \"metadata\": {\n \"name\": \"Local.JSON.RequireTLS\"\n },\n \"spec\": {\n \"condition\": {\n \"field\": \"configure.supportsHttpsTrafficOnly\",\n \"equals\": true\n }\n }\n }\n]\nNote
The resource comment is not localized. Use markdown documentation for a localized synopsis.
"},{"location":"authoring/writing-rule-help/#display-name-property","title":"Display name property","text":"Specify the display name of the rule with the
YAMLJSONmetadata.displayNameproperty.---\n# Synopsis: An example rule to require TLS.\napiVersion: github.com/microsoft/PSRule/v1\nkind: Rule\nmetadata:\n name: 'Local.YAML.RequireTLS'\n displayName: Require TLS\nspec:\n condition:\n field: 'configure.supportsHttpsTrafficOnly'\n equals: true\n[\n {\n // Synopsis: An example rule to require TLS.\n \"apiVersion\": \"github.com/microsoft/PSRule/v1\",\n \"kind\": \"Rule\",\n \"metadata\": {\n \"name\": \"Local.JSON.RequireTLS\",\n \"displayName\": \"Require TLS\"\n },\n \"spec\": {\n \"condition\": {\n \"field\": \"configure.supportsHttpsTrafficOnly\",\n \"equals\": true\n }\n }\n }\n]\nNote
This property is not localized. Use markdown documentation for a localized display name.
"},{"location":"authoring/writing-rule-help/#description-property","title":"Description property","text":"Specify the description of the rule with the
YAMLJSONmetadata.descriptionproperty.---\n# Synopsis: An example rule to require TLS.\napiVersion: github.com/microsoft/PSRule/v1\nkind: Rule\nmetadata:\n name: 'Local.YAML.RequireTLS'\n description: The resource should only use TLS.\nspec:\n condition:\n field: 'configure.supportsHttpsTrafficOnly'\n equals: true\n[\n {\n // Synopsis: An example rule to require TLS.\n \"apiVersion\": \"github.com/microsoft/PSRule/v1\",\n \"kind\": \"Rule\",\n \"metadata\": {\n \"name\": \"Local.JSON.RequireTLS\",\n \"description\": \"The resource should only use TLS.\"\n },\n \"spec\": {\n \"condition\": {\n \"field\": \"configure.supportsHttpsTrafficOnly\",\n \"equals\": true\n }\n }\n }\n]\nNote
This property is not localized. Use markdown documentation for a localized description.
"},{"location":"authoring/writing-rule-help/#link-property","title":"Link property","text":"Specify the online help URL of the rule with the
YAMLJSONmetadata.linkproperty.---\n# Synopsis: An example rule to require TLS.\napiVersion: github.com/microsoft/PSRule/v1\nkind: Rule\nmetadata:\n name: 'Local.YAML.RequireTLS'\n link: https://aka.ms/ps-rule\nspec:\n condition:\n field: 'configure.supportsHttpsTrafficOnly'\n equals: true\n[\n {\n // Synopsis: An example rule to require TLS.\n \"apiVersion\": \"github.com/microsoft/PSRule/v1\",\n \"kind\": \"Rule\",\n \"metadata\": {\n \"name\": \"Local.JSON.RequireTLS\",\n \"link\": \"https://aka.ms/ps-rule\"\n },\n \"spec\": {\n \"condition\": {\n \"field\": \"configure.supportsHttpsTrafficOnly\",\n \"equals\": true\n }\n }\n }\n]\nNote
This property is not localized. Use markdown documentation for a localized online help URL.
"},{"location":"authoring/writing-rule-help/#recommend-property","title":"Recommend property","text":"Specify the rule recommendation with the
YAMLJSONspec.recommendproperty.---\n# Synopsis: An example rule to require TLS.\napiVersion: github.com/microsoft/PSRule/v1\nkind: Rule\nmetadata:\n name: 'Local.YAML.RequireTLS'\nspec:\n recommend: The resource should only use TLS.\n condition:\n field: 'configure.supportsHttpsTrafficOnly'\n equals: true\n[\n {\n // Synopsis: An example rule to require TLS.\n \"apiVersion\": \"github.com/microsoft/PSRule/v1\",\n \"kind\": \"Rule\",\n \"metadata\": {\n \"name\": \"Local.JSON.RequireTLS\"\n },\n \"spec\": {\n \"recommend\": \"\",\n \"condition\": {\n \"field\": \"configure.supportsHttpsTrafficOnly\",\n \"equals\": true\n }\n }\n }\n]\nNote
This property is not localized. Use markdown documentation for a localized recommendation.
"},{"location":"authoring/writing-rule-help/#inline-help-with-powershell","title":"Inline help with PowerShell","text":"When authoring rules in PowerShell, PSRule provides the following syntax features:
These features are each describe in detail in the following sections.
"},{"location":"authoring/writing-rule-help/#synopsis-script-comment","title":"Synopsis script comment","text":"Comment metadata can be included directly above a rule block by using the syntax
# Synopsis: <text>. This is only supported for populating a rule synopsis.For example:
PowerShell# Synopsis: Must have the app.kubernetes.io/name label\nRule 'metadata.Name' -Type 'Deployment', 'Service' {\n Exists \"metadata.labels.'app.kubernetes.io/name'\"\n}\nThis example above would set the synopsis to
Must have the app.kubernetes.io/name label.Including comment metadata improves authoring by indicating the rules purpose. Only a single line is supported. A rule synopsis is displayed when using
Get-PSRuleandGet-PSRuleHelp. The synopsis can not break over multiple lines.The key limitation of only using comment metadata is that it can not be localized for multiple languages. Consider using comment metadata and also using markdown documentation for a multi-language experience.
Note
The script comment is not localized. Use markdown documentation for a localized synopsis.
"},{"location":"authoring/writing-rule-help/#recommend-keyword","title":"Recommend keyword","text":"The
Recommendkeyword sets the recommendation for a rule. Use the keyword with a text recommendation at the top of your rule body.Using the
Recommendkeyword is recommended for rules that are not packaged in a module. When packaging rules in a module consider using markdown help instead.For example:
PowerShell# Synopsis: Must have the app.kubernetes.io/name label\nRule 'metadata.Name' -Type 'Deployment', 'Service' {\n Recommend 'Consider setting the recommended label ''app.kubernetes.io/name'' on deployment and service resources.'\n Exists \"metadata.labels.'app.kubernetes.io/name'\"\n}\nA rule recommendation is displayed when using
Invoke-PSRuleorGet-PSRuleHelp.Only use the
Recommendkeyword once to set the recommendation text and avoid formatting with variables. Recommendations are cached the first time they are used. Supplying a unique recommendation within a rule based on conditions/ logic is not supported. To return a custom unique reason for why the rule failed, use theReasonkeyword.Localized recommendations can set by using the
$LocalizedData.For example:
PowerShell
"},{"location":"authoring/writing-rule-help/#reason-keyword","title":"Reason keyword","text":"# Synopsis: Must have the app.kubernetes.io/name label\nRule 'metadata.Name' -Type 'Deployment', 'Service' {\n Recommend $LocalizedData.RecommendNameLabel\n Exists \"metadata.labels.'app.kubernetes.io/name'\"\n}\nThe
Reasonkeyword sets the reason the rule failed when usingInvoke-PSRuleandAssert-PSRule. The reason is only included in detailed output if the rule did not pass. If the rule passed, then reason is empty it returned output.Reasons are not included in the default view when using
Invoke-PSRule. Use-OutputFormat Wideto display reason messages.To set a reason use the
PowerShellReasonkeyword followed by the reason. For example:# Synopsis: Must have the app.kubernetes.io/name label\nRule 'metadata.Name' -Type 'Deployment', 'Service' {\n Recommend $LocalizedData.RecommendNameLabel\n Exists \"metadata.labels.'app.kubernetes.io/name'\"\n\n Reason 'The standard name label is not set.'\n}\nThe
Reasonkeyword can be used multiple times within conditional logic to return a list of reasons the rule failed. Additionally the reason messages can be localized by using the$LocalizedDatavariable.For example:
PowerShell
"},{"location":"authoring/writing-rule-help/#writing-markdown-documentation","title":"Writing markdown documentation","text":"# Synopsis: Must have the app.kubernetes.io/name label\nRule 'metadata.Name' -Type 'Deployment', 'Service' {\n Recommend $LocalizedData.RecommendNameLabel\n Exists \"metadata.labels.'app.kubernetes.io/name'\"\n\n # $LocalizedData.ReasonLabelMissing is set to 'The standard {0} label is not set.'.\n Reason ($LocalizedData.ReasonLabelMissing -f 'name')\n}\nIn addition to inline help, documentation can be written in markdown to provide online and offline help. Extended documentation is generally easier to author using markdown. Additionally markdown documentation is easily localized.
Markdown documentation is authored by creating one or more
.mdfiles, one for each rule. PSRule uses a naming convention with a file name the same as the rule to match rule to markdown.For example,
metadata.Name.mdwould be used for a rule namedmetadata.Name.We recommend matching the rule name case exactly when naming markdown files. This is because some file systems are case-sensitive. For example on Linux
Metadata.Name.mdwould not match.Within each markdown file a number of predefined sections are automatically interpreted by PSRule. While it is possible to have additional sections, they will be ignored by the help system.
The basic structure of markdown help is as follows:
---\n{{ Annotations }}\n---\n\n# {{ Name of rule }}\n\n## SYNOPSIS\n\n{{ A brief summary of the rule }}\n\n## DESCRIPTION\n\n{{ A detailed description of the rule }}\n\n## RECOMMENDATION\n\n{{ A detailed explanation of the steps required to pass the rule }}\n\n## NOTES\n\n{{ Additional information or configuration options }}\n\n## LINKS\n\n{{ Links to external references }}\nThe PSRule Visual Studio Code extension includes snippets for writing markdown documentation.
"},{"location":"authoring/writing-rule-help/#annotations","title":"Annotations","text":"The annotation front matter at the top of the markdown document, is a set of key value pairs. Front matter follows YAML conventions and must start on the first line of the markdown document.
A
---on a separate line indicates the start and end of the front matter block. Within the front matter block, all key value pairs are treated as annotations by PSRule.Annotations are optional metadata that are associated with the rule. Any annotations associated with a rule are included in output. Some examples of annotations include;
severity,category,author.Annotations differ from tags in two key ways:
The following reserved annotation exists:
---\nonline version: https://github.com/microsoft/PSRule/blob/main/docs/scenarios/rule-docs/rule-docs.md\n---\nThe front matter start and end
"},{"location":"authoring/writing-rule-help/#display-name","title":"Display name","text":"---are not required and can be removed if no annotations are defined.The document title, indicated by a level one heading
#is the display name of the rule. The rule display name is shown when usingGet-PSRuleHelpand is included in output.Specify the display name on a single line. Wrapping the display name across multiple lines is not supported.
For example:
"},{"location":"authoring/writing-rule-help/#synopsis-section","title":"Synopsis section","text":"# Use recommended name label\nThe synopsis section is indicated by the heading
## SYNOPSIS. Any text following the heading is interpreted by PSRule and included in output. The synopsis is displayed when usingGet-PSRuleandGet-PSRuleHelpcmdlets.The synopsis is intended to be a brief description of the rule, over a single line. A good synopsis should convey the purpose of the rule. A more verbose description can be included in the description section.
For example:
"},{"location":"authoring/writing-rule-help/#description-section","title":"Description section","text":"## SYNOPSIS\n\nDeployments and services must use the app.kubernetes.io/name label.\nThe description section is indicated by the heading
## DESCRIPTION. Any text following the heading is interpreted by PSRule and included in output. The description is displayed when using theGet-PSRuleHelpcmdlet.The description is intended to be a verbose description of the rule. If your rule documentation needs to include background information include it here.
PSRule supports semantic line breaks, and will automatically run together lines into a single paragraph. Use a blank line to separate paragraphs.
For example:
"},{"location":"authoring/writing-rule-help/#recommendation-section","title":"Recommendation section","text":"## DESCRIPTION\n\nKubernetes defines a common set of labels that are recommended for tool interoperability.\nThese labels should be used to consistently apply standard metadata.\n\nThe `app.kubernetes.io/name` label should be used to specify the name of the application.\nThe recommendation section is indicated by the heading
## RECOMMENDATION. Any text following the heading is interpreted by PSRule and included in output. The recommendation is displayed when using theInvoke-PSRuleandGet-PSRuleHelpcmdlets.The recommendation is intended to identify corrective actions that can be taken to address any failures. Avoid using URLs within the recommendation. Use the links section to include references to external sources.
PSRule supports semantic line breaks, and will automatically run together lines into a single paragraph. Use a blank line to separate paragraphs.
For example:
"},{"location":"authoring/writing-rule-help/#notes-section","title":"Notes section","text":"## RECOMMENDATION\n\nConsider setting the recommended label `app.kubernetes.io/name` on deployment and service resources.\nThe notes section is indicated by the heading
## NOTES. Any text following the heading is interpreted by PSRule and included in pipeline output. Notes are excluded when formatting output as YAML and JSON.To view any included notes use the
Get-PSRuleHelpcmdlet with the-Fullswitch.Use notes to include additional information such configuration options.
PSRule supports semantic line breaks, and will automatically run together lines into a single paragraph. Use a blank line to separate paragraphs.
For example:
"},{"location":"authoring/writing-rule-help/#links-section","title":"Links section","text":"## NOTES\n\nThe Kubernetes recommended labels include:\n\n- `app.kubernetes.io/name`\n- `app.kubernetes.io/instance`\n- `app.kubernetes.io/version`\n- `app.kubernetes.io/component`\n- `app.kubernetes.io/part-of`\n- `app.kubernetes.io/managed-by`\nThe links section is indicated by the heading
## LINKS. Any markdown links following the heading are interpreted by PSRule and included in pipeline output. Links are excluded when formatting output as YAML and JSON.To view any included links use the
Get-PSRuleHelpcmdlet with the-Fullswitch.Use links to reference external sources with a URL.
To specify links, use the markdown syntax
[display name](url). Include each link on a separate line. To improve display in web rendered markdown, use a list of links by prefixing the line with-.Additional text such as
See additional information:is useful for web rendered views, but ignored by PSRule.For example:
"},{"location":"authoring/writing-rule-help/#localizing-documentation-files","title":"Localizing documentation files","text":"## LINKS\n\n- [Recommended Labels](https://kubernetes.io/docs/concepts/overview/working-with-objects/common-labels/)\nWhen distributing rules, you may need to provide rule help in different languages. PSRule builds on the culture system in PowerShell.
"},{"location":"authoring/writing-rule-help/#using-cultures","title":"Using cultures","text":"A directory structure is used to identify the markdown documentation that should be used for each culture.
To get a list of cultures in PowerShell the use cmdlet
Get-Culture -ListAvailable.For example, store documentation targeted to the culture
en-USin a directory nameden-US. Similarly, documentation for cultures such asen-AU,en-GBandfr-FRwould be in separate directories.If a directory for the exact culture
en-USdoesn't exist, PSRule will attempt to find the parent culture. For example, documentation would be read from a directory nameden.When naming directories for their culture, use exact case. This is because some file systems are case-sensitive. For example on Linux
"},{"location":"authoring/writing-rule-help/#culture-directory-search-path","title":"Culture directory search path","text":"en-uswould not match.The path that PSRule looks for a culture directory in varies depending on how the rule is redistributed. Rules can be redistributed individually (loose) or included in a module.
The following logic is used to locate the culture directory.
For example, loose file structure:
Module file structure:
Each resource must be tagged with mandatory tags.
"},{"location":"authoring/packaging-rules/Enterprise.Rules/en/Org.Az.Resource.Tagging/#description","title":"DESCRIPTION","text":"Azure resources can be tagged with additional metadata. Our enterprise standard requires that the following tags are used:
Consider tagging Azure resource with mandatory tags.
"},{"location":"authoring/packaging-rules/Enterprise.Rules/en/Org.Az.Resource.Tagging/#links","title":"LINKS","text":"Storage accounts should only accept encrypted connections.
"},{"location":"authoring/packaging-rules/Enterprise.Rules/en/Org.Az.Storage.UseHttps/#description","title":"DESCRIPTION","text":"An Azure Storage Account is configured to allow unencrypted connections. This does not indicate that unencrypted connections are being used.
Unencrypted communication to storage accounts could allow disclosure of information to an untrusted party.
Storage Accounts can be configured to require encrypted connections, by setting the Secure transfer required option. If secure transfer required is not enabled (the default), unencrypted and encrypted connections are permitted.
When secure transfer required is enabled, attempts to connect to storage using HTTP or unencrypted SMB connections are rejected.
"},{"location":"authoring/packaging-rules/Enterprise.Rules/en/Org.Az.Storage.UseHttps/#recommendation","title":"RECOMMENDATION","text":"Storage accounts should only accept secure traffic. Consider setting secure transfer required if there is no requirement to access storage over unencrypted connections. Also consider using Azure Policy to audit or enforce this configuration.
"},{"location":"authoring/packaging-rules/Enterprise.Rules/en/Org.Az.Storage.UseHttps/#links","title":"LINKS","text":"Deployments and services must use the app.kubernetes.io/name label.
"},{"location":"authoring/writing-rule-help/en-US/metadata.Name/#description","title":"DESCRIPTION","text":"Kubernetes defines a common set of labels that are recommended for tool interoperability. These labels should be used to consistently apply standard metadata.
The
"},{"location":"authoring/writing-rule-help/en-US/metadata.Name/#recommendation","title":"RECOMMENDATION","text":"app.kubernetes.io/namelabel should be used to specify the name of the application.Consider setting the recommended label
"},{"location":"authoring/writing-rule-help/en-US/metadata.Name/#notes","title":"NOTES","text":"app.kubernetes.io/nameon deployment and service resources.The Kubernetes recommended labels include:
Evaluate objects against matching rules and assert any failures.
"},{"location":"commands/PSRule/en-US/Assert-PSRule/#syntax","title":"SYNTAX","text":""},{"location":"commands/PSRule/en-US/Assert-PSRule/#input-default","title":"Input (Default)","text":"
"},{"location":"commands/PSRule/en-US/Assert-PSRule/#inputpath","title":"InputPath","text":"Assert-PSRule [-Module <String[]>] [-Format <InputFormat>] [-Baseline <BaselineOption>]\n [-Convention <String[]>] [-Style <OutputStyle>] [-Outcome <RuleOutcome>] [-As <ResultFormat>]\n [[-Path] <String[]>] [-Name <String[]>] [-Tag <Hashtable>] [-OutputPath <String>]\n [-OutputFormat <OutputFormat>] [-Option <PSRuleOption>] [-ObjectPath <String>] [-TargetType <String[]>]\n [-Culture <String[]>] -InputObject <PSObject> [-ResultVariable <String>] [-WhatIf] [-Confirm]\n [<CommonParameters>]\n
"},{"location":"commands/PSRule/en-US/Assert-PSRule/#description","title":"DESCRIPTION","text":"Assert-PSRule -InputPath <String[]> [-Module <String[]>] [-Format <InputFormat>] [-Baseline <BaselineOption>]\n [-Convention <String[]>] [-Style <OutputStyle>] [-Outcome <RuleOutcome>] [-As <ResultFormat>]\n [[-Path] <String[]>] [-Name <String[]>] [-Tag <Hashtable>] [-OutputPath <String>]\n [-OutputFormat <OutputFormat>] [-Option <PSRuleOption>] [-ObjectPath <String>] [-TargetType <String[]>]\n [-Culture <String[]>] [-ResultVariable <String>] [-WhatIf] [-Confirm] [<CommonParameters>]\nEvaluate objects against matching rules and assert any failures. Objects can be specified directly from the pipeline or provided from file.
The commands
Invoke-PSRuleandAssert-PSRuleprovide similar functionality, as differ as follows:@{ Name = 'Item 1' } | Assert-PSRule;\nEvaluate a simple hashtable on the pipeline against rules loaded from the current working path.
"},{"location":"commands/PSRule/en-US/Assert-PSRule/#example-2","title":"Example 2","text":"# Define objects to validate\n$items = @();\n$items += [PSCustomObject]@{ Name = 'Fridge' };\n$items += [PSCustomObject]@{ Name = 'Apple' };\n\n# Validate each item using rules saved in current working path\n$items | Assert-PSRule -Path .\\docs\\scenarios\\fruit\\\n-> Fridge : System.Management.Automation.PSCustomObject\n\n [FAIL] isFruit\n\n-> Apple : System.Management.Automation.PSCustomObject\n\n [PASS] isFruit\n\nAssert-PSRule : One or more rules reported failure.\nAt line:1 char:10\n+ $items | Assert-PSRule -Path .\\docs\\scenarios\\fruit\\\n+ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n+ CategoryInfo : InvalidData: (:) [Assert-PSRule], FailPipelineException\n+ FullyQualifiedErrorId : PSRule.Fail,Assert-PSRule\nEvaluate an array of objects on the pipeline against rules loaded a specified relative path.
"},{"location":"commands/PSRule/en-US/Assert-PSRule/#example-3","title":"Example 3","text":"$items | Assert-PSRule -Module PSRule.Rules.Azure -o NUnit3 -OutputPath .\\reports\\results.xml\nEvaluate items from a pre-installed rules module PSRule.Rules.Azure. Additionally save the results as a NUnit report.
"},{"location":"commands/PSRule/en-US/Assert-PSRule/#example-4","title":"Example 4","text":"$items | Assert-PSRule -Path .\\docs\\scenarios\\fruit\\ -ResultVariable resultRecords;\nEvaluate items and additionally save the results into a variable
"},{"location":"commands/PSRule/en-US/Assert-PSRule/#parameters","title":"PARAMETERS","text":""},{"location":"commands/PSRule/en-US/Assert-PSRule/#-inputpath","title":"-InputPath","text":"resultRecords.Instead of processing objects from the pipeline, import objects file the specified file paths.
"},{"location":"commands/PSRule/en-US/Assert-PSRule/#-format","title":"-Format","text":"Type: String[]\nParameter Sets: InputPath\nAliases: f\n\nRequired: True\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nConfigures the input format for when a string is passed in as a target object.
When the
-InputObjectparameter or pipeline input is used, strings are treated as plain text by default. Set this option to eitherYaml,Json,Markdown,PowerShellDatato have PSRule deserialize the object.When the
-InputPathparameter is used with a file path or URL. If theDetectformat is used, the file extension will be used to automatically detect the format. When-InputPathis not used,Detectis the same asNone.When this option is set to
FilePSRule scans the path and subdirectories specified by-InputPath. Files are treated as objects instead of being deserialized. Additional, PSRule uses the file extension as the object type. When files have no extension the whole file name is used.See
about_PSRule_Optionsfor details.This parameter takes precedence over the
Input.Formatoption if set.
"},{"location":"commands/PSRule/en-US/Assert-PSRule/#-baseline","title":"-Baseline","text":"Type: InputFormat\nParameter Sets: (All)\nAliases:\nAccepted values: None, Yaml, Json, Markdown, PowerShellData, File, Detect\n\nRequired: False\nPosition: Named\nDefault value: Detect\nAccept pipeline input: False\nAccept wildcard characters: False\nSpecifies an explicit baseline by name to use for evaluating rules. Baselines can contain filters and custom configuration that overrides the defaults.
"},{"location":"commands/PSRule/en-US/Assert-PSRule/#-convention","title":"-Convention","text":"Type: BaselineOption\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nSpecifies conventions by name to execute in the pipeline when processing objects.
"},{"location":"commands/PSRule/en-US/Assert-PSRule/#-culture","title":"-Culture","text":"Type: String[]\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nSpecifies the culture to use for rule documentation and messages. By default, the culture of PowerShell is used.
This option does not affect the culture used for the PSRule engine, which always uses the culture of PowerShell.
The PowerShell cmdlet
Get-Cultureshows the current culture of PowerShell.
"},{"location":"commands/PSRule/en-US/Assert-PSRule/#-module","title":"-Module","text":"Type: String[]\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nSearch for rule definitions within a module. If no sources are specified by
-Path,-Module, or options, the current working directory is used.
"},{"location":"commands/PSRule/en-US/Assert-PSRule/#-name","title":"-Name","text":"Type: String[]\nParameter Sets: (All)\nAliases: m\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nThe name of a specific rule to evaluate. If this parameter is not specified all rules in search paths will be evaluated.
"},{"location":"commands/PSRule/en-US/Assert-PSRule/#-objectpath","title":"-ObjectPath","text":"Type: String[]\nParameter Sets: (All)\nAliases: n\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nThe name of a property to use instead of the pipeline object. If the property specified by
ObjectPathis a collection or an array, then each item in evaluated separately.
"},{"location":"commands/PSRule/en-US/Assert-PSRule/#-targettype","title":"-TargetType","text":"Type: String\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nFilters input objects by TargetType.
If specified, only objects with the specified TargetType are processed. Objects that do not match TargetType are ignored. If multiple values are specified, only one TargetType must match. This parameter is not case-sensitive.
By default, all objects are processed.
This parameter if set, overrides the
Input.TargetTypeoption.To change the field TargetType is bound to set the
Binding.TargetTypeoption. For details see the about_PSRule_Options help topic.
"},{"location":"commands/PSRule/en-US/Assert-PSRule/#-option","title":"-Option","text":"Type: String[]\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nAdditional options that configure execution. A
PSRuleOptioncan be created by using theNew-PSRuleOptioncmdlet. Alternatively, a hashtable or path to YAML file can be specified with options.For more information on PSRule options see about_PSRule_Options.
"},{"location":"commands/PSRule/en-US/Assert-PSRule/#-outputpath","title":"-OutputPath","text":"Type: PSRuleOption\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nSpecifies the output file path to write results. Directories along the file path will automatically be created if they do not exist.
"},{"location":"commands/PSRule/en-US/Assert-PSRule/#-outputformat","title":"-OutputFormat","text":"Type: String\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nConfigures the format that output is written. This parameter has no affect when
-OutputPathis not specified.The following format options are available:
The
Wideformat is not applicable toAssert-PSRule.
"},{"location":"commands/PSRule/en-US/Assert-PSRule/#-style","title":"-Style","text":"Type: OutputFormat\nParameter Sets: (All)\nAliases: o\nAccepted values: None, Yaml, Json, Markdown, NUnit3, Csv, Sarif\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nConfigures the style that results will be presented in.
The following styles are available:
Detect uses the following logic:
Each of these styles outputs to the host. To capture output as a string redirect the information stream. For example:
6>&1
"},{"location":"commands/PSRule/en-US/Assert-PSRule/#-as","title":"-As","text":"Type: OutputStyle\nParameter Sets: (All)\nAliases:\nAccepted values: Client, Plain, AzurePipelines, GitHubActions, VisualStudioCode, Detect\n\nRequired: False\nPosition: Named\nDefault value: Client\nAccept pipeline input: False\nAccept wildcard characters: False\nThe type of results to produce. Detailed results are generated by default.
The following result formats are available:
"},{"location":"commands/PSRule/en-US/Assert-PSRule/#-outcome","title":"-Outcome","text":"Type: ResultFormat\nParameter Sets: (All)\nAliases:\nAccepted values: Detail, Summary\n\nRequired: False\nPosition: Named\nDefault value: Detail\nAccept pipeline input: False\nAccept wildcard characters: False\nFilter output to only show rule results with a specific outcome.
"},{"location":"commands/PSRule/en-US/Assert-PSRule/#-path","title":"-Path","text":"Type: RuleOutcome\nParameter Sets: (All)\nAliases:\nAccepted values: Pass, Fail, Error, None, Processed, All\n\nRequired: False\nPosition: Named\nDefault value: Pass, Fail, Error\nAccept pipeline input: False\nAccept wildcard characters: False\nOne or more paths to search for rule definitions within.
"},{"location":"commands/PSRule/en-US/Assert-PSRule/#-tag","title":"-Tag","text":"Type: String[]\nParameter Sets: (All)\nAliases: p\n\nRequired: False\nPosition: 0\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nOnly get rules with the specified tags set. If this parameter is not specified all rules in search paths will be returned.
When more than one tag is used, all tags must match. Tags are not case sensitive. A tag value of
*may be used to filter rules to any rule with the tag set, regardless of tag value.An array of tag values can be used to match a rule with either value. i.e.
severity = important, criticalmatches rules with a category of eitherimportantorcritical.
"},{"location":"commands/PSRule/en-US/Assert-PSRule/#-inputobject","title":"-InputObject","text":"Type: Hashtable\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nThe pipeline object to process rules for.
"},{"location":"commands/PSRule/en-US/Assert-PSRule/#-resultvariable","title":"-ResultVariable","text":"Type: PSObject\nParameter Sets: Input\nAliases: TargetObject\n\nRequired: True\nPosition: Named\nDefault value: None\nAccept pipeline input: True (ByValue)\nAccept wildcard characters: False\nStores output result objects in the specified variable.
"},{"location":"commands/PSRule/en-US/Assert-PSRule/#-whatif","title":"-WhatIf","text":"Type: String\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nShows what would happen if the cmdlet runs. The cmdlet is not run.
"},{"location":"commands/PSRule/en-US/Assert-PSRule/#-confirm","title":"-Confirm","text":"Type: SwitchParameter\nParameter Sets: (All)\nAliases: wi\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nPrompts you for confirmation before running the cmdlet.
"},{"location":"commands/PSRule/en-US/Assert-PSRule/#commonparameters","title":"CommonParameters","text":"Type: SwitchParameter\nParameter Sets: (All)\nAliases: cf\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nThis cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters.
"},{"location":"commands/PSRule/en-US/Assert-PSRule/#inputs","title":"INPUTS","text":""},{"location":"commands/PSRule/en-US/Assert-PSRule/#systemmanagementautomationpsobject","title":"System.Management.Automation.PSObject","text":"You can pipe any object to Assert-PSRule.
"},{"location":"commands/PSRule/en-US/Assert-PSRule/#outputs","title":"OUTPUTS","text":""},{"location":"commands/PSRule/en-US/Assert-PSRule/#systemstring","title":"System.String","text":""},{"location":"commands/PSRule/en-US/Assert-PSRule/#notes","title":"NOTES","text":""},{"location":"commands/PSRule/en-US/Assert-PSRule/#related-links","title":"RELATED LINKS","text":"Get-PSRule
Invoke-PSRule
Test-PSRuleTarget
"},{"location":"commands/PSRule/en-US/Export-PSRuleBaseline/","title":"Export-PSRuleBaseline","text":""},{"location":"commands/PSRule/en-US/Export-PSRuleBaseline/#synopsis","title":"SYNOPSIS","text":"Exports a list of baselines.
"},{"location":"commands/PSRule/en-US/Export-PSRuleBaseline/#syntax","title":"SYNTAX","text":"
"},{"location":"commands/PSRule/en-US/Export-PSRuleBaseline/#description","title":"DESCRIPTION","text":"Export-PSRuleBaseline [-Module <String[]>] [[-Path] <String[]>] [-Name <String[]>] [-Option <PSRuleOption>]\n [-Culture <String>] [-OutputFormat <OutputFormat>] -OutputPath <String> [-OutputEncoding <OutputEncoding>]\n [-WhatIf] [-Confirm] [<CommonParameters>]\nExports a list of baselines to a file.
"},{"location":"commands/PSRule/en-US/Export-PSRuleBaseline/#examples","title":"EXAMPLES","text":""},{"location":"commands/PSRule/en-US/Export-PSRuleBaseline/#example-1","title":"Example 1","text":"Export-PSRuleBaseline -Module PSRule.Rules.Azure -OutputFormat Yaml -OutputPath Baseline.Rule.yml\nExports list of baselines from
"},{"location":"commands/PSRule/en-US/Export-PSRuleBaseline/#parameters","title":"PARAMETERS","text":""},{"location":"commands/PSRule/en-US/Export-PSRuleBaseline/#-module","title":"-Module","text":"PSRule.Rules.Azuremodule to fileBaseline.Rule.ymlin YAML output format.Search for baselines definitions within a module. If no sources are specified by
-Path,-Module, or options, the current working directory is used.
"},{"location":"commands/PSRule/en-US/Export-PSRuleBaseline/#-path","title":"-Path","text":"Type: String[]\nParameter Sets: (All)\nAliases: m\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nOne or more paths to search for baselines within.
"},{"location":"commands/PSRule/en-US/Export-PSRuleBaseline/#-name","title":"-Name","text":"Type: String[]\nParameter Sets: (All)\nAliases: p\n\nRequired: False\nPosition: 1\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nThe name of a specific baseline to list. If this parameter is not specified all baselines in search paths will be listed.
"},{"location":"commands/PSRule/en-US/Export-PSRuleBaseline/#-option","title":"-Option","text":"Type: String[]\nParameter Sets: (All)\nAliases: n\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: True\nAdditional options that configure execution. A
PSRuleOptioncan be created by using theNew-PSRuleOptioncmdlet. Alternatively a hashtable or path to YAML file can be specified with options.For more information on PSRule options see about_PSRule_Options.
"},{"location":"commands/PSRule/en-US/Export-PSRuleBaseline/#-culture","title":"-Culture","text":"Type: PSRuleOption\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nSpecifies the culture to use for documentation and messages. By default, the culture of PowerShell is used.
This option does not affect the culture used for the PSRule engine, which always uses the culture of PowerShell.
The PowerShell cmdlet
Get-Cultureshows the current culture of PowerShell.
"},{"location":"commands/PSRule/en-US/Export-PSRuleBaseline/#-outputformat","title":"-OutputFormat","text":"Type: String\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nConfigures the format that output is presented in.
The following format options are available:
"},{"location":"commands/PSRule/en-US/Export-PSRuleBaseline/#-outputencoding","title":"-OutputEncoding","text":"Type: OutputFormat\nParameter Sets: (All)\nAliases: o\nAccepted values: Yaml, Json\n\nRequired: False\nPosition: Named\nDefault value: Yaml\nAccept pipeline input: False\nAccept wildcard characters: False\nSets the option
Output.Encoding. TheOutput.Encodingoption configured the encoding used to write results to file.
"},{"location":"commands/PSRule/en-US/Export-PSRuleBaseline/#-outputpath","title":"-OutputPath","text":"Type: OutputEncoding\nParameter Sets: (All)\nAliases:\nAccepted values: Default, UTF8, UTF7, Unicode, UTF32, ASCII\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nSets the option
Output.Path. TheOutput.Pathoption configures the output path the results are written to.
"},{"location":"commands/PSRule/en-US/Export-PSRuleBaseline/#-whatif","title":"-WhatIf","text":"Type: String\nParameter Sets: (All)\nAliases:\n\nRequired: True\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nShows what would happen if the cmdlet runs. The cmdlet is not run.
"},{"location":"commands/PSRule/en-US/Export-PSRuleBaseline/#-confirm","title":"-Confirm","text":"Type: SwitchParameter\nParameter Sets: (All)\nAliases: wi\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nPrompts you for confirmation before running the cmdlet.
"},{"location":"commands/PSRule/en-US/Export-PSRuleBaseline/#commonparameters","title":"CommonParameters","text":"Type: SwitchParameter\nParameter Sets: (All)\nAliases: cf\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nThis cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters.
"},{"location":"commands/PSRule/en-US/Export-PSRuleBaseline/#inputs","title":"INPUTS","text":""},{"location":"commands/PSRule/en-US/Export-PSRuleBaseline/#outputs","title":"OUTPUTS","text":""},{"location":"commands/PSRule/en-US/Export-PSRuleBaseline/#notes","title":"NOTES","text":""},{"location":"commands/PSRule/en-US/Export-PSRuleBaseline/#related-links","title":"RELATED LINKS","text":"Get-PSRuleBaseline
"},{"location":"commands/PSRule/en-US/Get-PSRule/","title":"Get-PSRule","text":""},{"location":"commands/PSRule/en-US/Get-PSRule/#synopsis","title":"SYNOPSIS","text":"Get a list of rule definitions.
"},{"location":"commands/PSRule/en-US/Get-PSRule/#syntax","title":"SYNTAX","text":"
"},{"location":"commands/PSRule/en-US/Get-PSRule/#description","title":"DESCRIPTION","text":"Get-PSRule [-Module <String[]>] [-ListAvailable] [-OutputFormat <OutputFormat>] [-Baseline <BaselineOption>]\n [[-Path] <String[]>] [-Name <String[]>] [-Tag <Hashtable>] [-Option <PSRuleOption>] [-Culture <String>]\n [-IncludeDependencies] [<CommonParameters>]\nGet a list of matching rule definitions within the search path.
"},{"location":"commands/PSRule/en-US/Get-PSRule/#examples","title":"EXAMPLES","text":""},{"location":"commands/PSRule/en-US/Get-PSRule/#example-1","title":"Example 1","text":"Get-PSRule;\nRuleName ModuleName Synopsis\n-------- ---------- --------\nisFruit An example rule\nGet a list of rule definitions from the current working path.
"},{"location":"commands/PSRule/en-US/Get-PSRule/#example-2","title":"Example 2","text":"Get-PSRule -Module PSRule.Rules.Azure;\nRuleName ModuleName Synopsis\n-------- ---------- --------\nAzure.ACR.AdminUser PSRule.Rules.Azure Use Azure AD accounts instead of using the registry adm\u2026\nAzure.ACR.MinSku PSRule.Rules.Azure ACR should use the Premium or Standard SKU for producti\u2026\nAzure.AKS.MinNodeCount PSRule.Rules.Azure AKS clusters should have minimum number of nodes for fa\u2026\nAzure.AKS.Version PSRule.Rules.Azure AKS clusters should meet the minimum version.\nAzure.AKS.UseRBAC PSRule.Rules.Azure AKS cluster should use role-based access control (RBAC).\nGet a list of rule definitions included in the module
"},{"location":"commands/PSRule/en-US/Get-PSRule/#example-3","title":"Example 3","text":"PSRule.Rules.Azure.Get-PSRule -Module PSRule.Rules.Azure -OutputFormat Wide;\nRuleName ModuleName Synopsis Tag\n-------- ---------- -------- ---\nAzure.ACR.AdminUser PSRule.Rules.Azure Use Azure AD accounts severity='Critical'\n instead of using the category='Security\n registry admin user. configuration'\nAzure.ACR.MinSku PSRule.Rules.Azure ACR should use the Premium severity='Important'\n or Standard SKU for category='Performance'\n production deployments.\nAzure.AKS.MinNodeCount PSRule.Rules.Azure AKS clusters should have severity='Important'\n minimum number of nodes for category='Reliability'\n failover and updates.\nAzure.AKS.Version PSRule.Rules.Azure AKS clusters should meet severity='Important'\n the minimum version. category='Operations\n management'\nAzure.AKS.UseRBAC PSRule.Rules.Azure AKS cluster should use severity='Important'\n role-based access control category='Security\n (RBAC). configuration'\nGet a list of rule definitions included in the module
"},{"location":"commands/PSRule/en-US/Get-PSRule/#parameters","title":"PARAMETERS","text":""},{"location":"commands/PSRule/en-US/Get-PSRule/#-name","title":"-Name","text":"PSRule.Rules.Azureincluding tags with line wrapping.The name of a specific rule to list. If this parameter is not specified all rules in search paths will be listed.
"},{"location":"commands/PSRule/en-US/Get-PSRule/#-path","title":"-Path","text":"Type: String[]\nParameter Sets: (All)\nAliases: n\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nOne or more paths to search for rule definitions within.
"},{"location":"commands/PSRule/en-US/Get-PSRule/#-tag","title":"-Tag","text":"Type: String[]\nParameter Sets: (All)\nAliases: p\n\nRequired: False\nPosition: 0\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nOnly get rules with the specified tags set. If this parameter is not specified all rules in search paths will be returned.
When more than one tag is used, all tags must match. Tags are not case sensitive. A tag value of
*may be used to filter rules to any rule with the tag set, regardless of tag value.An array of tag values can be used to match a rule with either value. i.e.
severity = important, criticalmatches rules with a category of eitherimportantorcritical.
"},{"location":"commands/PSRule/en-US/Get-PSRule/#-option","title":"-Option","text":"Type: Hashtable\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nAdditional options that configure execution. A
PSRuleOptioncan be created by using theNew-PSRuleOptioncmdlet. Alternatively a hashtable or path to YAML file can be specified with options.For more information on PSRule options see about_PSRule_Options.
"},{"location":"commands/PSRule/en-US/Get-PSRule/#-listavailable","title":"-ListAvailable","text":"Type: PSRuleOption\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nLook for modules containing rule definitions including modules that are currently not imported.
This switch is used with the
-Moduleparameter.
"},{"location":"commands/PSRule/en-US/Get-PSRule/#-module","title":"-Module","text":"Type: SwitchParameter\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nSearch for rule definitions within a module. If no sources are specified by
-Path,-Module, or options, the current working directory is used.
"},{"location":"commands/PSRule/en-US/Get-PSRule/#-culture","title":"-Culture","text":"Type: String[]\nParameter Sets: (All)\nAliases: m\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nSpecifies the culture to use for documentation and messages. By default, the culture of PowerShell is used.
This option does not affect the culture used for the PSRule engine, which always uses the culture of PowerShell.
The PowerShell cmdlet
Get-Cultureshows the current culture of PowerShell.
"},{"location":"commands/PSRule/en-US/Get-PSRule/#-outputformat","title":"-OutputFormat","text":"Type: String\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nConfigures the format that output is presented in.
The following format options are available:
"},{"location":"commands/PSRule/en-US/Get-PSRule/#-includedependencies","title":"-IncludeDependencies","text":"Type: OutputFormat\nParameter Sets: (All)\nAliases: o\nAccepted values: None, Wide, Yaml, Json\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nWhen this switch is specified, dependencies of the rules that meet the
-Nameand-Tagfilters are included even if they would normally be excluded.This switch has no affect when getting an unfiltered list of rules.
"},{"location":"commands/PSRule/en-US/Get-PSRule/#-baseline","title":"-Baseline","text":"Type: SwitchParameter\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nWhen specified, rules are filtered so that only rules that are included in the baselines are returned.
"},{"location":"commands/PSRule/en-US/Get-PSRule/#commonparameters","title":"CommonParameters","text":"Type: BaselineOption\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nThis cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters.
"},{"location":"commands/PSRule/en-US/Get-PSRule/#inputs","title":"INPUTS","text":""},{"location":"commands/PSRule/en-US/Get-PSRule/#none","title":"None","text":""},{"location":"commands/PSRule/en-US/Get-PSRule/#outputs","title":"OUTPUTS","text":""},{"location":"commands/PSRule/en-US/Get-PSRule/#psruledefinitionsrulesirulev1","title":"PSRule.Definitions.Rules.IRuleV1","text":""},{"location":"commands/PSRule/en-US/Get-PSRule/#notes","title":"NOTES","text":""},{"location":"commands/PSRule/en-US/Get-PSRule/#related-links","title":"RELATED LINKS","text":"Invoke-PSRule
"},{"location":"commands/PSRule/en-US/Get-PSRuleBaseline/","title":"Get-PSRuleBaseline","text":""},{"location":"commands/PSRule/en-US/Get-PSRuleBaseline/#synopsis","title":"SYNOPSIS","text":"Get a list of baselines.
"},{"location":"commands/PSRule/en-US/Get-PSRuleBaseline/#syntax","title":"SYNTAX","text":"
"},{"location":"commands/PSRule/en-US/Get-PSRuleBaseline/#description","title":"DESCRIPTION","text":"Get-PSRuleBaseline [-Module <String[]>] [-ListAvailable] [[-Path] <String[]>] [-Name <String[]>]\n [-Option <PSRuleOption>] [-Culture <String>] [-OutputFormat <OutputFormat>] [<CommonParameters>]\nGet a list of matching baselines within the search path.
"},{"location":"commands/PSRule/en-US/Get-PSRuleBaseline/#examples","title":"EXAMPLES","text":""},{"location":"commands/PSRule/en-US/Get-PSRuleBaseline/#example-1","title":"Example 1","text":"Get-PSRuleBaseline;\nGet a list of baselines from the current working path.
"},{"location":"commands/PSRule/en-US/Get-PSRuleBaseline/#parameters","title":"PARAMETERS","text":""},{"location":"commands/PSRule/en-US/Get-PSRuleBaseline/#-module","title":"-Module","text":"Search for baselines definitions within a module. If no sources are specified by
-Path,-Module, or options, the current working directory is used.
"},{"location":"commands/PSRule/en-US/Get-PSRuleBaseline/#-listavailable","title":"-ListAvailable","text":"Type: String[]\nParameter Sets: (All)\nAliases: m\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nLook for modules containing baselines including modules that are currently not imported.
This switch is used with the
-Moduleparameter.
"},{"location":"commands/PSRule/en-US/Get-PSRuleBaseline/#-path","title":"-Path","text":"Type: SwitchParameter\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: False\nAccept pipeline input: False\nAccept wildcard characters: False\nOne or more paths to search for baselines within.
"},{"location":"commands/PSRule/en-US/Get-PSRuleBaseline/#-name","title":"-Name","text":"Type: String[]\nParameter Sets: (All)\nAliases: p\n\nRequired: False\nPosition: 1\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nThe name of a specific baseline to list. If this parameter is not specified all baselines in search paths will be listed.
"},{"location":"commands/PSRule/en-US/Get-PSRuleBaseline/#-option","title":"-Option","text":"Type: String[]\nParameter Sets: (All)\nAliases: n\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: True\nAdditional options that configure execution. A
PSRuleOptioncan be created by using theNew-PSRuleOptioncmdlet. Alternatively a hashtable or path to YAML file can be specified with options.For more information on PSRule options see about_PSRule_Options.
"},{"location":"commands/PSRule/en-US/Get-PSRuleBaseline/#-culture","title":"-Culture","text":"Type: PSRuleOption\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nSpecifies the culture to use for documentation and messages. By default, the culture of PowerShell is used.
This option does not affect the culture used for the PSRule engine, which always uses the culture of PowerShell.
The PowerShell cmdlet
Get-Cultureshows the current culture of PowerShell.
"},{"location":"commands/PSRule/en-US/Get-PSRuleBaseline/#-outputformat","title":"-OutputFormat","text":"Type: String\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nConfigures the format that output is presented in.
The following format options are available:
"},{"location":"commands/PSRule/en-US/Get-PSRuleBaseline/#commonparameters","title":"CommonParameters","text":"Type: OutputFormat\nParameter Sets: (All)\nAliases: o\nAccepted values: None, Yaml, Json\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nThis cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters.
"},{"location":"commands/PSRule/en-US/Get-PSRuleBaseline/#inputs","title":"INPUTS","text":""},{"location":"commands/PSRule/en-US/Get-PSRuleBaseline/#outputs","title":"OUTPUTS","text":""},{"location":"commands/PSRule/en-US/Get-PSRuleBaseline/#psruledefinitionsbaseline","title":"PSRule.Definitions.Baseline","text":"This is the default.
"},{"location":"commands/PSRule/en-US/Get-PSRuleBaseline/#systemstring","title":"System.String","text":"When you use
"},{"location":"commands/PSRule/en-US/Get-PSRuleBaseline/#notes","title":"NOTES","text":""},{"location":"commands/PSRule/en-US/Get-PSRuleBaseline/#related-links","title":"RELATED LINKS","text":"-OutputFormat Yamlor-OutputFormat Json.Get-PSRule
"},{"location":"commands/PSRule/en-US/Get-PSRuleHelp/","title":"Get-PSRuleHelp","text":""},{"location":"commands/PSRule/en-US/Get-PSRuleHelp/#synopsis","title":"SYNOPSIS","text":"Displays information about a rule.
"},{"location":"commands/PSRule/en-US/Get-PSRuleHelp/#syntax","title":"SYNTAX","text":"
"},{"location":"commands/PSRule/en-US/Get-PSRuleHelp/#description","title":"DESCRIPTION","text":"Get-PSRuleHelp [-Module <String>] [-Online] [-Full] [[-Name] <String[]>] [-Path <String>]\n [-Option <PSRuleOption>] [-Culture <String>] [<CommonParameters>]\nThe
Get-PSRuleHelpcmdlet display information about a rule.By default, this cmdlet will look for rules in the current path and loaded modules. To get help for a specific rule or module use the
-Nameor-Moduleparameters.If the rule has an online version of the documentation, use the
"},{"location":"commands/PSRule/en-US/Get-PSRuleHelp/#examples","title":"EXAMPLES","text":""},{"location":"commands/PSRule/en-US/Get-PSRuleHelp/#example-1","title":"Example 1","text":"-Onlineparameter to view it in your default web browser.Get-PSRuleHelp;\nGet a list of rule help within the current path or loaded modules.
"},{"location":"commands/PSRule/en-US/Get-PSRuleHelp/#example-2","title":"Example 2","text":"Get-PSRuleHelp Azure.ACR.AdminUser;\nGet rule documentation for the rule
"},{"location":"commands/PSRule/en-US/Get-PSRuleHelp/#example-3","title":"Example 3","text":"Azure.ACR.AdminUser.Get-PSRuleHelp Azure.ACR.AdminUser -Online;\nBrowse to the online version of documentation for
"},{"location":"commands/PSRule/en-US/Get-PSRuleHelp/#parameters","title":"PARAMETERS","text":""},{"location":"commands/PSRule/en-US/Get-PSRuleHelp/#-name","title":"-Name","text":"Azure.ACR.AdminUserusing the default web browser.The name of the rule to get documentation for.
"},{"location":"commands/PSRule/en-US/Get-PSRuleHelp/#-path","title":"-Path","text":"Type: String[]\nParameter Sets: (All)\nAliases: n\n\nRequired: False\nPosition: 1\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: True\nA path to check documentation for. By default, help from the current working path and loaded modules is listed. Results can be filtered by using
-Name,-Pathor-Module.
"},{"location":"commands/PSRule/en-US/Get-PSRuleHelp/#-module","title":"-Module","text":"Type: String\nParameter Sets: (All)\nAliases: p\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nLimit returned information to rules in the specified module. By default, help from the current working path and loaded modules is listed. Results can be filtered by using
-Name,-Pathor-Module.
"},{"location":"commands/PSRule/en-US/Get-PSRuleHelp/#-culture","title":"-Culture","text":"Type: String\nParameter Sets: (All)\nAliases: m\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nSpecifies the culture to use for rule documentation and messages. By default, the culture of PowerShell is used.
This option does not affect the culture used for the PSRule engine, which always uses the culture of PowerShell.
The PowerShell cmdlet
Get-Cultureshows the current culture of PowerShell.
"},{"location":"commands/PSRule/en-US/Get-PSRuleHelp/#-online","title":"-Online","text":"Type: String\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nInstead of displaying documentation within PowerShell, browse to the online version using the default web browser.
"},{"location":"commands/PSRule/en-US/Get-PSRuleHelp/#-full","title":"-Full","text":"Type: SwitchParameter\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: False\nAccept pipeline input: False\nAccept wildcard characters: False\nDisplay additional information such as notes and links.
"},{"location":"commands/PSRule/en-US/Get-PSRuleHelp/#-option","title":"-Option","text":"Type: SwitchParameter\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nAdditional options that configure execution. A
PSRuleOptioncan be created by using theNew-PSRuleOptioncmdlet. Alternatively a hashtable or path to YAML file can be specified with options.For more information on PSRule options see about_PSRule_Options.
"},{"location":"commands/PSRule/en-US/Get-PSRuleHelp/#commonparameters","title":"CommonParameters","text":"Type: PSRuleOption\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nThis cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters.
"},{"location":"commands/PSRule/en-US/Get-PSRuleHelp/#inputs","title":"INPUTS","text":""},{"location":"commands/PSRule/en-US/Get-PSRuleHelp/#none","title":"None","text":""},{"location":"commands/PSRule/en-US/Get-PSRuleHelp/#outputs","title":"OUTPUTS","text":""},{"location":"commands/PSRule/en-US/Get-PSRuleHelp/#psrulerulesrulehelpinfo","title":"PSRule.Rules.RuleHelpInfo","text":""},{"location":"commands/PSRule/en-US/Get-PSRuleHelp/#notes","title":"NOTES","text":""},{"location":"commands/PSRule/en-US/Get-PSRuleHelp/#related-links","title":"RELATED LINKS","text":""},{"location":"commands/PSRule/en-US/Get-PSRuleTarget/","title":"Get-PSRuleTarget","text":""},{"location":"commands/PSRule/en-US/Get-PSRuleTarget/#synopsis","title":"SYNOPSIS","text":"Get a list of target objects.
"},{"location":"commands/PSRule/en-US/Get-PSRuleTarget/#syntax","title":"SYNTAX","text":""},{"location":"commands/PSRule/en-US/Get-PSRuleTarget/#input-default","title":"Input (Default)","text":"
"},{"location":"commands/PSRule/en-US/Get-PSRuleTarget/#inputpath","title":"InputPath","text":"Get-PSRuleTarget [-Format <InputFormat>] [-Option <PSRuleOption>] [-ObjectPath <String>]\n -InputObject <PSObject> [-WhatIf] [-Confirm] [<CommonParameters>]\n
"},{"location":"commands/PSRule/en-US/Get-PSRuleTarget/#description","title":"DESCRIPTION","text":"Get-PSRuleTarget -InputPath <String[]> [-Format <InputFormat>] [-Option <PSRuleOption>] [-ObjectPath <String>]\n [-WhatIf] [-Confirm] [<CommonParameters>]\nGet a list of target objects from input.
"},{"location":"commands/PSRule/en-US/Get-PSRuleTarget/#examples","title":"EXAMPLES","text":""},{"location":"commands/PSRule/en-US/Get-PSRuleTarget/#example-1","title":"Example 1","text":"Get-PSRuleTarget -InputPath .\\resources.json;\nGet target objects from
"},{"location":"commands/PSRule/en-US/Get-PSRuleTarget/#parameters","title":"PARAMETERS","text":""},{"location":"commands/PSRule/en-US/Get-PSRuleTarget/#-inputpath","title":"-InputPath","text":"resources.json.Instead of processing objects from the pipeline, import objects file the specified file paths.
"},{"location":"commands/PSRule/en-US/Get-PSRuleTarget/#-format","title":"-Format","text":"Type: String[]\nParameter Sets: InputPath\nAliases: f\n\nRequired: True\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nConfigures the input format for when a string is passed in as a target object.
When the
-InputObjectparameter or pipeline input is used, strings are treated as plain text by default. Set this option to eitherYaml,Json,Markdown,PowerShellDatato have PSRule deserialize the object.When the
-InputPathparameter is used with a file path or URL. If theDetectformat is used, the file extension will be used to automatically detect the format. When-InputPathis not used,Detectis the same asNone.See
about_PSRule_Optionsfor details.This parameter takes precedence over the
Input.Formatoption if set.
"},{"location":"commands/PSRule/en-US/Get-PSRuleTarget/#-option","title":"-Option","text":"Type: InputFormat\nParameter Sets: (All)\nAliases:\nAccepted values: None, Yaml, Json, Markdown, PowerShellData, File, Detect\n\nRequired: False\nPosition: Named\nDefault value: Detect\nAccept pipeline input: False\nAccept wildcard characters: False\nAdditional options that configure execution. A
PSRuleOptioncan be created by using theNew-PSRuleOptioncmdlet. Alternatively, a hashtable or path to YAML file can be specified with options.For more information on PSRule options see about_PSRule_Options.
"},{"location":"commands/PSRule/en-US/Get-PSRuleTarget/#-objectpath","title":"-ObjectPath","text":"Type: PSRuleOption\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nThe name of a property to use instead of the pipeline object. If the property specified by
ObjectPathis a collection or an array, then each item in evaluated separately.
"},{"location":"commands/PSRule/en-US/Get-PSRuleTarget/#-inputobject","title":"-InputObject","text":"Type: String\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nThe pipeline object to process rules for.
"},{"location":"commands/PSRule/en-US/Get-PSRuleTarget/#-whatif","title":"-WhatIf","text":"Type: PSObject\nParameter Sets: Input\nAliases: TargetObject\n\nRequired: True\nPosition: Named\nDefault value: None\nAccept pipeline input: True (ByValue)\nAccept wildcard characters: False\nShows what would happen if the cmdlet runs. The cmdlet is not run.
"},{"location":"commands/PSRule/en-US/Get-PSRuleTarget/#-confirm","title":"-Confirm","text":"Type: SwitchParameter\nParameter Sets: (All)\nAliases: wi\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nPrompts you for confirmation before running the cmdlet.
"},{"location":"commands/PSRule/en-US/Get-PSRuleTarget/#commonparameters","title":"CommonParameters","text":"Type: SwitchParameter\nParameter Sets: (All)\nAliases: cf\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nThis cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters.
"},{"location":"commands/PSRule/en-US/Get-PSRuleTarget/#inputs","title":"INPUTS","text":""},{"location":"commands/PSRule/en-US/Get-PSRuleTarget/#outputs","title":"OUTPUTS","text":""},{"location":"commands/PSRule/en-US/Get-PSRuleTarget/#systemmanagementautomationpsobject","title":"System.Management.Automation.PSObject","text":""},{"location":"commands/PSRule/en-US/Get-PSRuleTarget/#notes","title":"NOTES","text":""},{"location":"commands/PSRule/en-US/Get-PSRuleTarget/#related-links","title":"RELATED LINKS","text":""},{"location":"commands/PSRule/en-US/Invoke-PSRule/","title":"Invoke-PSRule","text":""},{"location":"commands/PSRule/en-US/Invoke-PSRule/#synopsis","title":"SYNOPSIS","text":"Evaluate objects against matching rules and output the results.
"},{"location":"commands/PSRule/en-US/Invoke-PSRule/#syntax","title":"SYNTAX","text":""},{"location":"commands/PSRule/en-US/Invoke-PSRule/#input-default","title":"Input (Default)","text":"
"},{"location":"commands/PSRule/en-US/Invoke-PSRule/#inputpath","title":"InputPath","text":"Invoke-PSRule [-Module <String[]>] [-Outcome <RuleOutcome>] [-As <ResultFormat>] [-Format <InputFormat>]\n [-OutputPath <String>] [-OutputFormat <OutputFormat>] [-Baseline <BaselineOption>] [-Convention <String[]>]\n [[-Path] <String[]>] [-Name <String[]>] [-Tag <Hashtable>] [-Option <PSRuleOption>] [-ObjectPath <String>]\n [-TargetType <String[]>] [-Culture <String[]>] -InputObject <PSObject> [-WhatIf] [-Confirm]\n [<CommonParameters>]\n
"},{"location":"commands/PSRule/en-US/Invoke-PSRule/#description","title":"DESCRIPTION","text":"Invoke-PSRule -InputPath <String[]> [-Module <String[]>] [-Outcome <RuleOutcome>] [-As <ResultFormat>]\n [-Format <InputFormat>] [-OutputPath <String>] [-OutputFormat <OutputFormat>] [-Baseline <BaselineOption>]\n [-Convention <String[]>] [[-Path] <String[]>] [-Name <String[]>] [-Tag <Hashtable>] [-Option <PSRuleOption>]\n [-ObjectPath <String>] [-TargetType <String[]>] [-Culture <String[]>] [-WhatIf] [-Confirm]\n [<CommonParameters>]\nEvaluate objects against matching rules and output the results. Objects can be specified directly from the pipeline or provided from file.
The commands
Invoke-PSRuleandAssert-PSRuleprovide similar functionality, as differ as follows:@{ Name = 'Item 1' } | Invoke-PSRule;\nEvaluate a simple hashtable on the pipeline against rules loaded from the current working path.
"},{"location":"commands/PSRule/en-US/Invoke-PSRule/#example-2","title":"Example 2","text":"# Define objects to validate\n$items = @();\n$items += [PSCustomObject]@{ Name = 'Fridge' };\n$items += [PSCustomObject]@{ Name = 'Apple' };\n\n# Validate each item using rules saved in current working path\n$items | Invoke-PSRule;\nTargetName: Fridge\n\nRuleName Outcome Recommendation\n-------- ------- --------------\nisFruit Fail Fruit is only Apple, Orange and Pear\n\n\n TargetName: Apple\n\nRuleName Outcome Recommendation\n-------- ------- --------------\nisFruit Pass Fruit is only Apple, Orange and Pear\nEvaluate an array of objects on the pipeline against rules loaded from the current working path.
"},{"location":"commands/PSRule/en-US/Invoke-PSRule/#example-3","title":"Example 3","text":"# Define objects to validate\n$items = @();\n$items += [PSCustomObject]@{ Name = 'Fridge' };\n$items += [PSCustomObject]@{ Name = 'Apple' };\n\n# Validate each item and only return failing results\n$items | Invoke-PSRule -Outcome Fail;\nTargetName: Fridge\n\nRuleName Outcome Recommendation\n-------- ------- --------------\nisFruit Fail Fruit is only Apple, Orange and Pear\nEvaluate an array of objects, only failing object results are returned.
"},{"location":"commands/PSRule/en-US/Invoke-PSRule/#example-4","title":"Example 4","text":"# Define objects to validate\n$items = @();\n$items += [PSCustomObject]@{ Name = 'Fridge' };\n$items += [PSCustomObject]@{ Name = 'Apple' };\n\n# Validate each item and show rule summary\n$items | Invoke-PSRule -As Summary;\nRuleName Pass Fail Outcome\n-------- ---- ---- -------\nisFruit 1 1 Fail\nEvaluate an array of objects. The results for each rule is returned as a summary. Outcome is represented as the worst outcome.
"},{"location":"commands/PSRule/en-US/Invoke-PSRule/#parameters","title":"PARAMETERS","text":""},{"location":"commands/PSRule/en-US/Invoke-PSRule/#-name","title":"-Name","text":"The name of a specific rule to evaluate. If this parameter is not specified all rules in search paths will be evaluated.
"},{"location":"commands/PSRule/en-US/Invoke-PSRule/#-path","title":"-Path","text":"Type: String[]\nParameter Sets: (All)\nAliases: n\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nOne or more paths to search for rule definitions within.
"},{"location":"commands/PSRule/en-US/Invoke-PSRule/#-outcome","title":"-Outcome","text":"Type: String[]\nParameter Sets: (All)\nAliases: p\n\nRequired: False\nPosition: 0\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nFilter output to only show rule results with a specific outcome.
"},{"location":"commands/PSRule/en-US/Invoke-PSRule/#-tag","title":"-Tag","text":"Type: RuleOutcome\nParameter Sets: (All)\nAliases:\nAccepted values: Pass, Fail, Error, None, Processed, All\n\nRequired: False\nPosition: Named\nDefault value: Pass, Fail, Error\nAccept pipeline input: False\nAccept wildcard characters: False\nOnly get rules with the specified tags set. If this parameter is not specified all rules in search paths will be returned.
When more than one tag is used, all tags must match. Tags are not case sensitive. A tag value of
*may be used to filter rules to any rule with the tag set, regardless of tag value.An array of tag values can be used to match a rule with either value. i.e.
severity = important, criticalmatches rules with a category of eitherimportantorcritical.
"},{"location":"commands/PSRule/en-US/Invoke-PSRule/#-inputobject","title":"-InputObject","text":"Type: Hashtable\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nThe pipeline object to process rules for.
"},{"location":"commands/PSRule/en-US/Invoke-PSRule/#-option","title":"-Option","text":"Type: PSObject\nParameter Sets: Input\nAliases: TargetObject\n\nRequired: True\nPosition: Named\nDefault value: None\nAccept pipeline input: True (ByValue)\nAccept wildcard characters: False\nAdditional options that configure execution. A
PSRuleOptioncan be created by using theNew-PSRuleOptioncmdlet. Alternatively, a hashtable or path to YAML file can be specified with options.For more information on PSRule options see about_PSRule_Options.
"},{"location":"commands/PSRule/en-US/Invoke-PSRule/#-as","title":"-As","text":"Type: PSRuleOption\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nThe type of results to produce. Detailed results are generated by default.
The following result formats are available:
"},{"location":"commands/PSRule/en-US/Invoke-PSRule/#-format","title":"-Format","text":"Type: ResultFormat\nParameter Sets: (All)\nAliases:\nAccepted values: Detail, Summary\n\nRequired: False\nPosition: Named\nDefault value: Detail\nAccept pipeline input: False\nAccept wildcard characters: False\nConfigures the input format for when a string is passed in as a target object.
When the
-InputObjectparameter or pipeline input is used, strings are treated as plain text by default. Set this option to eitherYaml,Json,Markdown,PowerShellDatato have PSRule deserialize the object.When the
-InputPathparameter is used with a file path or URL. If theDetectformat is used, the file extension will be used to automatically detect the format. When-InputPathis not used,Detectis the same asNone.When this option is set to
FilePSRule scans the path and subdirectories specified by-InputPath. Files are treated as objects instead of being deserialized. Additional, PSRule uses the file extension as the object type. When files have no extension the whole file name is used.See
about_PSRule_Optionsfor details.This parameter takes precedence over the
Input.Formatoption if set.
"},{"location":"commands/PSRule/en-US/Invoke-PSRule/#-baseline","title":"-Baseline","text":"Type: InputFormat\nParameter Sets: (All)\nAliases:\nAccepted values: None, Yaml, Json, Markdown, PowerShellData, File, Detect\n\nRequired: False\nPosition: Named\nDefault value: Detect\nAccept pipeline input: False\nAccept wildcard characters: False\nSpecifies an explicit baseline by name to use for evaluating rules. Baselines can contain filters and custom configuration that overrides the defaults.
"},{"location":"commands/PSRule/en-US/Invoke-PSRule/#-convention","title":"-Convention","text":"Type: BaselineOption\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nSpecifies conventions by name to execute in the pipeline when processing objects.
"},{"location":"commands/PSRule/en-US/Invoke-PSRule/#-culture","title":"-Culture","text":"Type: String[]\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nSpecifies the culture to use for rule documentation and messages. By default, the culture of PowerShell is used.
This option does not affect the culture used for the PSRule engine, which always uses the culture of PowerShell.
The PowerShell cmdlet
Get-Cultureshows the current culture of PowerShell.
"},{"location":"commands/PSRule/en-US/Invoke-PSRule/#-objectpath","title":"-ObjectPath","text":"Type: String[]\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nThe name of a property to use instead of the pipeline object. If the property specified by
ObjectPathis a collection or an array, then each item in evaluated separately.
"},{"location":"commands/PSRule/en-US/Invoke-PSRule/#-targettype","title":"-TargetType","text":"Type: String\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nFilters input objects by TargetType.
If specified, only objects with the specified TargetType are processed. Objects that do not match TargetType are ignored. If multiple values are specified, only one TargetType must match. This parameter is not case-sensitive.
By default, all objects are processed.
This parameter if set, overrides the
Input.TargetTypeoption.To change the field TargetType is bound to set the
Binding.TargetTypeoption. For details see the about_PSRule_Options help topic.
"},{"location":"commands/PSRule/en-US/Invoke-PSRule/#-module","title":"-Module","text":"Type: String[]\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nSearch for rule definitions within a module. If no sources are specified by
-Path,-Module, or options, the current working directory is used.
"},{"location":"commands/PSRule/en-US/Invoke-PSRule/#-inputpath","title":"-InputPath","text":"Type: String[]\nParameter Sets: (All)\nAliases: m\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nInstead of processing objects from the pipeline, import objects file the specified file paths.
"},{"location":"commands/PSRule/en-US/Invoke-PSRule/#-outputpath","title":"-OutputPath","text":"Type: String[]\nParameter Sets: InputPath\nAliases: f\n\nRequired: True\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nSpecifies the output file path to write results. Directories along the file path will automatically be created if they do not exist.
"},{"location":"commands/PSRule/en-US/Invoke-PSRule/#-outputformat","title":"-OutputFormat","text":"Type: String\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nConfigures the format that output is presented in.
The following format options are available:
"},{"location":"commands/PSRule/en-US/Invoke-PSRule/#-confirm","title":"-Confirm","text":"Type: OutputFormat\nParameter Sets: (All)\nAliases: o\nAccepted values: None, Yaml, Json, Markdown, NUnit3, Csv, Wide, Sarif\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nPrompts you for confirmation before running the cmdlet.
"},{"location":"commands/PSRule/en-US/Invoke-PSRule/#-whatif","title":"-WhatIf","text":"Type: SwitchParameter\nParameter Sets: (All)\nAliases: cf\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nShows what would happen if the cmdlet runs. The cmdlet is not run.
"},{"location":"commands/PSRule/en-US/Invoke-PSRule/#commonparameters","title":"CommonParameters","text":"Type: SwitchParameter\nParameter Sets: (All)\nAliases: wi\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nThis cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters.
"},{"location":"commands/PSRule/en-US/Invoke-PSRule/#inputs","title":"INPUTS","text":""},{"location":"commands/PSRule/en-US/Invoke-PSRule/#systemmanagementautomationpsobject","title":"System.Management.Automation.PSObject","text":"You can pipe any object to Invoke-PSRule.
"},{"location":"commands/PSRule/en-US/Invoke-PSRule/#outputs","title":"OUTPUTS","text":""},{"location":"commands/PSRule/en-US/Invoke-PSRule/#psrulerulesrulerecord","title":"PSRule.Rules.RuleRecord","text":"This is the default.
"},{"location":"commands/PSRule/en-US/Invoke-PSRule/#psrulerulesrulesummaryrecord","title":"PSRule.Rules.RuleSummaryRecord","text":"When you use the
"},{"location":"commands/PSRule/en-US/Invoke-PSRule/#notes","title":"NOTES","text":""},{"location":"commands/PSRule/en-US/Invoke-PSRule/#related-links","title":"RELATED LINKS","text":"-As Summary. Otherwise, it returns aRuleRecordobject.Get-PSRule
Assert-PSRule
Test-PSRuleTarget
"},{"location":"commands/PSRule/en-US/New-PSRuleOption/","title":"New-PSRuleOption","text":""},{"location":"commands/PSRule/en-US/New-PSRuleOption/#synopsis","title":"SYNOPSIS","text":"Create options to configure PSRule execution.
"},{"location":"commands/PSRule/en-US/New-PSRuleOption/#syntax","title":"SYNTAX","text":""},{"location":"commands/PSRule/en-US/New-PSRuleOption/#frompath-default","title":"FromPath (Default)","text":"
"},{"location":"commands/PSRule/en-US/New-PSRuleOption/#fromoption","title":"FromOption","text":"New-PSRuleOption [[-Path] <String>] [-Configuration <ConfigurationOption>]\n [-SuppressTargetName <SuppressionOption>] [-BindTargetName <BindTargetName[]>]\n [-BindTargetType <BindTargetName[]>] [-BaselineGroup <Hashtable>] [-BindingIgnoreCase <Boolean>]\n [-BindingField <Hashtable>] [-BindingNameSeparator <String>] [-BindingPreferTargetInfo <Boolean>]\n [-TargetName <String[]>] [-TargetType <String[]>] [-BindingUseQualifiedName <Boolean>]\n [-Convention <String[]>] [-DuplicateResourceId <ExecutionActionPreference>]\n [-InitialSessionState <SessionState>] [-SuppressionGroupExpired <ExecutionActionPreference>]\n [-ExecutionRuleExcluded <ExecutionActionPreference>] [-ExecutionRuleSuppressed <ExecutionActionPreference>]\n [-ExecutionAliasReference <ExecutionActionPreference>]\n [-ExecutionRuleInconclusive <ExecutionActionPreference>]\n [-ExecutionInvariantCulture <ExecutionActionPreference>]\n [-ExecutionUnprocessedObject <ExecutionActionPreference>] [-IncludeModule <String[]>]\n [-IncludePath <String[]>] [-Format <InputFormat>] [-InputIgnoreGitPath <Boolean>]\n [-InputIgnoreRepositoryCommon <Boolean>] [-InputIgnoreObjectSource <Boolean>]\n [-InputIgnoreUnchangedPath <Boolean>] [-ObjectPath <String>] [-InputTargetType <String[]>]\n [-InputPathIgnore <String[]>] [-LoggingLimitDebug <String[]>] [-LoggingLimitVerbose <String[]>]\n [-LoggingRuleFail <OutcomeLogStream>] [-LoggingRulePass <OutcomeLogStream>] [-OutputAs <ResultFormat>]\n [-OutputBanner <BannerFormat>] [-OutputCulture <String[]>] [-OutputEncoding <OutputEncoding>]\n [-OutputFooter <FooterFormat>] [-OutputFormat <OutputFormat>] [-OutputJobSummaryPath <String>]\n [-OutputJsonIndent <Int32>] [-OutputOutcome <RuleOutcome>] [-OutputPath <String>]\n [-OutputSarifProblemsOnly <Boolean>] [-OutputStyle <OutputStyle>] [-RepositoryBaseRef <String>]\n [-RepositoryUrl <String>] [-RuleIncludeLocal <Boolean>] [<CommonParameters>]\n
"},{"location":"commands/PSRule/en-US/New-PSRuleOption/#fromdefault","title":"FromDefault","text":"New-PSRuleOption [-Option] <PSRuleOption> [-Configuration <ConfigurationOption>]\n [-SuppressTargetName <SuppressionOption>] [-BindTargetName <BindTargetName[]>]\n [-BindTargetType <BindTargetName[]>] [-BaselineGroup <Hashtable>] [-BindingIgnoreCase <Boolean>]\n [-BindingField <Hashtable>] [-BindingNameSeparator <String>] [-BindingPreferTargetInfo <Boolean>]\n [-TargetName <String[]>] [-TargetType <String[]>] [-BindingUseQualifiedName <Boolean>]\n [-Convention <String[]>] [-DuplicateResourceId <ExecutionActionPreference>]\n [-InitialSessionState <SessionState>] [-SuppressionGroupExpired <ExecutionActionPreference>]\n [-ExecutionRuleExcluded <ExecutionActionPreference>] [-ExecutionRuleSuppressed <ExecutionActionPreference>]\n [-ExecutionAliasReference <ExecutionActionPreference>]\n [-ExecutionRuleInconclusive <ExecutionActionPreference>]\n [-ExecutionInvariantCulture <ExecutionActionPreference>]\n [-ExecutionUnprocessedObject <ExecutionActionPreference>] [-IncludeModule <String[]>]\n [-IncludePath <String[]>] [-Format <InputFormat>] [-InputIgnoreGitPath <Boolean>]\n [-InputIgnoreRepositoryCommon <Boolean>] [-InputIgnoreObjectSource <Boolean>]\n [-InputIgnoreUnchangedPath <Boolean>] [-ObjectPath <String>] [-InputTargetType <String[]>]\n [-InputPathIgnore <String[]>] [-LoggingLimitDebug <String[]>] [-LoggingLimitVerbose <String[]>]\n [-LoggingRuleFail <OutcomeLogStream>] [-LoggingRulePass <OutcomeLogStream>] [-OutputAs <ResultFormat>]\n [-OutputBanner <BannerFormat>] [-OutputCulture <String[]>] [-OutputEncoding <OutputEncoding>]\n [-OutputFooter <FooterFormat>] [-OutputFormat <OutputFormat>] [-OutputJobSummaryPath <String>]\n [-OutputJsonIndent <Int32>] [-OutputOutcome <RuleOutcome>] [-OutputPath <String>]\n [-OutputSarifProblemsOnly <Boolean>] [-OutputStyle <OutputStyle>] [-RepositoryBaseRef <String>]\n [-RepositoryUrl <String>] [-RuleIncludeLocal <Boolean>] [<CommonParameters>]\n
"},{"location":"commands/PSRule/en-US/New-PSRuleOption/#description","title":"DESCRIPTION","text":"New-PSRuleOption [-Default] [-Configuration <ConfigurationOption>] [-SuppressTargetName <SuppressionOption>]\n [-BindTargetName <BindTargetName[]>] [-BindTargetType <BindTargetName[]>] [-BaselineGroup <Hashtable>]\n [-BindingIgnoreCase <Boolean>] [-BindingField <Hashtable>] [-BindingNameSeparator <String>]\n [-BindingPreferTargetInfo <Boolean>] [-TargetName <String[]>] [-TargetType <String[]>]\n [-BindingUseQualifiedName <Boolean>] [-Convention <String[]>]\n [-DuplicateResourceId <ExecutionActionPreference>] [-InitialSessionState <SessionState>]\n [-SuppressionGroupExpired <ExecutionActionPreference>] [-ExecutionRuleExcluded <ExecutionActionPreference>]\n [-ExecutionRuleSuppressed <ExecutionActionPreference>] [-ExecutionAliasReference <ExecutionActionPreference>]\n [-ExecutionRuleInconclusive <ExecutionActionPreference>]\n [-ExecutionInvariantCulture <ExecutionActionPreference>]\n [-ExecutionUnprocessedObject <ExecutionActionPreference>] [-IncludeModule <String[]>]\n [-IncludePath <String[]>] [-Format <InputFormat>] [-InputIgnoreGitPath <Boolean>]\n [-InputIgnoreRepositoryCommon <Boolean>] [-InputIgnoreObjectSource <Boolean>]\n [-InputIgnoreUnchangedPath <Boolean>] [-ObjectPath <String>] [-InputTargetType <String[]>]\n [-InputPathIgnore <String[]>] [-LoggingLimitDebug <String[]>] [-LoggingLimitVerbose <String[]>]\n [-LoggingRuleFail <OutcomeLogStream>] [-LoggingRulePass <OutcomeLogStream>] [-OutputAs <ResultFormat>]\n [-OutputBanner <BannerFormat>] [-OutputCulture <String[]>] [-OutputEncoding <OutputEncoding>]\n [-OutputFooter <FooterFormat>] [-OutputFormat <OutputFormat>] [-OutputJobSummaryPath <String>]\n [-OutputJsonIndent <Int32>] [-OutputOutcome <RuleOutcome>] [-OutputPath <String>]\n [-OutputSarifProblemsOnly <Boolean>] [-OutputStyle <OutputStyle>] [-RepositoryBaseRef <String>]\n [-RepositoryUrl <String>] [-RuleIncludeLocal <Boolean>] [<CommonParameters>]\nThe New-PSRuleOption cmdlet creates an options object that can be passed to PSRule cmdlets to configure execution.
"},{"location":"commands/PSRule/en-US/New-PSRuleOption/#examples","title":"EXAMPLES","text":""},{"location":"commands/PSRule/en-US/New-PSRuleOption/#example-1","title":"Example 1","text":"$option = New-PSRuleOption -Option @{ 'execution.mode' = 'ConstrainedLanguage' }\n@{ Name = 'Item 1' } | Invoke-PSRule -Option $option\nCreate an options object and run rules in constrained mode.
"},{"location":"commands/PSRule/en-US/New-PSRuleOption/#example-2","title":"Example 2","text":"$option = New-PSRuleOption -SuppressTargetName @{ 'storageAccounts.UseHttps' = 'TestObject1', 'TestObject3' };\nCreate an options object that suppresses
"},{"location":"commands/PSRule/en-US/New-PSRuleOption/#example-3","title":"Example 3","text":"TestObject1andTestObject3for a rule namedstorageAccounts.UseHttps.# Create a custom function that returns a TargetName string\n$bindFn = {\n param ($TargetObject)\n\n $otherName = $TargetObject.PSObject.Properties['OtherName'];\n\n if ($otherName -eq $Null) {\n return $Null\n }\n\n return $otherName.Value;\n}\n\n# Specify the binding function script block code to execute\n$option = New-PSRuleOption -BindTargetName $bindFn;\nCreates an options object that uses a custom function to bind the TargetName of an object.
"},{"location":"commands/PSRule/en-US/New-PSRuleOption/#example-4","title":"Example 4","text":"$option = New-PSRuleOption -Configuration @{ 'appServiceMinInstanceCount' = 2 };\nCreate an options object that sets the
"},{"location":"commands/PSRule/en-US/New-PSRuleOption/#parameters","title":"PARAMETERS","text":""},{"location":"commands/PSRule/en-US/New-PSRuleOption/#-option","title":"-Option","text":"appServiceMinInstanceCountbaseline configuration option to2.Additional options that configure execution. Option also accepts a hashtable to configure options. See about_PSRule_Options for more information.
"},{"location":"commands/PSRule/en-US/New-PSRuleOption/#-path","title":"-Path","text":"Type: PSRuleOption\nParameter Sets: FromOption\nAliases:\n\nRequired: True\nPosition: 0\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nThe path to a YAML file containing options.
Either a directory or file path can be specified. When a directory is used,
ps-rule.yamlwill be used as the file name.If the
-Pathparameter is specified and the file does not exist, an exception will be generated.
"},{"location":"commands/PSRule/en-US/New-PSRuleOption/#-default","title":"-Default","text":"Type: String\nParameter Sets: FromPath\nAliases:\n\nRequired: False\nPosition: 1\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nWhen specified, defaults are used for any options not overridden.
"},{"location":"commands/PSRule/en-US/New-PSRuleOption/#-suppresstargetname","title":"-SuppressTargetName","text":"Type: SwitchParameter\nParameter Sets: FromDefault\nAliases:\n\nRequired: True\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nConfigures suppression for a list of objects by TargetName. SuppressTargetName also accepts a hashtable to configure rule suppression. See about_PSRule_Options for more information.
"},{"location":"commands/PSRule/en-US/New-PSRuleOption/#-bindtargetname","title":"-BindTargetName","text":"Type: SuppressionOption\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nConfigures a custom function to use to bind TargetName of an object. See about_PSRule_Options for more information.
"},{"location":"commands/PSRule/en-US/New-PSRuleOption/#-configuration","title":"-Configuration","text":"Type: BindTargetName[]\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nConfigures a set of baseline configuration values that can be used in rule definitions instead of using hard coded values. Configuration also accepts a hashtable of configuration values as key/ value pairs. See about_PSRule_Options for more information.
"},{"location":"commands/PSRule/en-US/New-PSRuleOption/#-baselinegroup","title":"-BaselineGroup","text":"Type: ConfigurationOption\nParameter Sets: (All)\nAliases: BaselineConfiguration\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nSets the option
Baseline.Group. The optionBaseline.Groupallows a named group of baselines to be defined and later referenced. See about_PSRule_Options for more information.
"},{"location":"commands/PSRule/en-US/New-PSRuleOption/#-bindtargettype","title":"-BindTargetType","text":"Type: Hashtable\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nConfigures a custom function to use to bind TargetType of an object. See about_PSRule_Options for more information.
"},{"location":"commands/PSRule/en-US/New-PSRuleOption/#-bindingignorecase","title":"-BindingIgnoreCase","text":"Type: BindTargetName[]\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nSets the option
Binding.IgnoreCase. The optionBinding.IgnoreCasedetermines if binding operations are case-sensitive or not. See about_PSRule_Options for more information.
"},{"location":"commands/PSRule/en-US/New-PSRuleOption/#-bindingfield","title":"-BindingField","text":"Type: Boolean\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: True\nAccept pipeline input: False\nAccept wildcard characters: False\nSets the option
Binding.Field. The option specified one or more custom field bindings. See about_PSRule_Options for more information.
"},{"location":"commands/PSRule/en-US/New-PSRuleOption/#-bindingnameseparator","title":"-BindingNameSeparator","text":"Type: Hashtable\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nSets the option
Binding.NameSeparator. This option specifies the separator to use for qualified names. See about_PSRule_Options for more information.
"},{"location":"commands/PSRule/en-US/New-PSRuleOption/#-bindingprefertargetinfo","title":"-BindingPreferTargetInfo","text":"Type: String\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nSets the option
Binding.PreferTargetInfo. This option specifies if automatic binding is preferred over configured binding options. See about_PSRule_Options for more information.
"},{"location":"commands/PSRule/en-US/New-PSRuleOption/#-convention","title":"-Convention","text":"Type: Boolean\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: False\nAccept pipeline input: False\nAccept wildcard characters: False\nSets the
Option.ConventionIncludeoption. This option specifies the name of conventions to execute in the pipeline when processing objects. See about_PSRule_Options for more information.
"},{"location":"commands/PSRule/en-US/New-PSRuleOption/#-targetname","title":"-TargetName","text":"Type: String[]\nParameter Sets: (All)\nAliases: ConventionInclude\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nSets the option
Binding.TargetName. This option specifies one or more properties of TargetObject to use to bind TargetName to. See about_PSRule_Options for more information.
"},{"location":"commands/PSRule/en-US/New-PSRuleOption/#-targettype","title":"-TargetType","text":"Type: String[]\nParameter Sets: (All)\nAliases: BindingTargetName\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nSets the option
Binding.TargetType. This option specifies one or more properties of TargetObject to use to bind TargetType to. See about_PSRule_Options for more information.
"},{"location":"commands/PSRule/en-US/New-PSRuleOption/#-bindingusequalifiedname","title":"-BindingUseQualifiedName","text":"Type: String[]\nParameter Sets: (All)\nAliases: BindingTargetType\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nSets the option
Binding.UseQualifiedName. This option specifies is qualified target names are used. See about_PSRule_Options for more information.
"},{"location":"commands/PSRule/en-US/New-PSRuleOption/#-executionaliasreference","title":"-ExecutionAliasReference","text":"Type: Boolean\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nSets the
Execution.AliasReferenceoption. Determines how to handle when an alias to a resource is used. See about_PSRule_Options for more information.
"},{"location":"commands/PSRule/en-US/New-PSRuleOption/#-executioninvariantculture","title":"-ExecutionInvariantCulture","text":"Type: ExecutionActionPreference\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nSets the
Execution.InvariantCultureoption. Determines how to report when an invariant culture is used. See about_PSRule_Options for more information.
"},{"location":"commands/PSRule/en-US/New-PSRuleOption/#-executionruleinconclusive","title":"-ExecutionRuleInconclusive","text":"Type: ExecutionActionPreference\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nSets the
Execution.RuleInconclusiveoption. Determines how to handle rules that generate inconclusive results. See about_PSRule_Options for more information.
"},{"location":"commands/PSRule/en-US/New-PSRuleOption/#-executionunprocessedobject","title":"-ExecutionUnprocessedObject","text":"Type: ExecutionActionPreference\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nSets the
Execution.UnprocessedObjectoption. Determines how to report objects that are not processed by any rule. See about_PSRule_Options for more information.
"},{"location":"commands/PSRule/en-US/New-PSRuleOption/#-includemodule","title":"-IncludeModule","text":"Type: ExecutionActionPreference\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nSets the
Include.Moduleoption to include additional module sources. See about_PSRule_Options for more information.
"},{"location":"commands/PSRule/en-US/New-PSRuleOption/#-includepath","title":"-IncludePath","text":"Type: String[]\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nSets the
Include.Pathoption to include additional standalone sources. See about_PSRule_Options for more information.
"},{"location":"commands/PSRule/en-US/New-PSRuleOption/#-format","title":"-Format","text":"Type: String[]\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nSets the
Input.Formatoption to configure the input format for when a string is passed in as a target object. See about_PSRule_Options for more information.
"},{"location":"commands/PSRule/en-US/New-PSRuleOption/#-inputignoregitpath","title":"-InputIgnoreGitPath","text":"Type: InputFormat\nParameter Sets: (All)\nAliases: InputFormat\nAccepted values: None, Yaml, Json, Markdown, PowerShellData, File, Detect\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nSets the
Input.IgnoreGitPathoption to determine if files within the .git path are ignored. See about_PSRule_Options for more information.
"},{"location":"commands/PSRule/en-US/New-PSRuleOption/#-inputignorerepositorycommon","title":"-InputIgnoreRepositoryCommon","text":"Type: Boolean\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: True\nAccept pipeline input: False\nAccept wildcard characters: False\nSets the
Input.IgnoreRepositoryCommonoption to determine if files common repository files are ignored. See about_PSRule_Options for more information.
"},{"location":"commands/PSRule/en-US/New-PSRuleOption/#-inputignoreunchangedpath","title":"-InputIgnoreUnchangedPath","text":"Type: Boolean\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nSets the option
Input.IgnoreUnchangedPath. TheInput.IgnoreUnchangedPathoption determine if unchanged files are ignored.
"},{"location":"commands/PSRule/en-US/New-PSRuleOption/#-objectpath","title":"-ObjectPath","text":"Type: Boolean\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nSets the
Input.ObjectPathoption to use an object path to use instead of the pipeline object. See about_PSRule_Options for more information.
"},{"location":"commands/PSRule/en-US/New-PSRuleOption/#-inputpathignore","title":"-InputPathIgnore","text":"Type: String\nParameter Sets: (All)\nAliases: InputObjectPath\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nSets the
Input.PathIgnoreoption. If specified, files that match the path spec will not be processed. See about_PSRule_Options for more information.
"},{"location":"commands/PSRule/en-US/New-PSRuleOption/#-inputtargettype","title":"-InputTargetType","text":"Type: String[]\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nSets the
Input.TargetTypeoption to only process objects with the specified TargetType. See about_PSRule_Options for more information.
"},{"location":"commands/PSRule/en-US/New-PSRuleOption/#-inputignoreobjectsource","title":"-InputIgnoreObjectSource","text":"Type: String[]\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nSets the option
Input.IgnoreObjectSource. TheInput.IgnoreObjectSourceoption determines if objects will be skipped if the source path has been ignored.
"},{"location":"commands/PSRule/en-US/New-PSRuleOption/#-logginglimitdebug","title":"-LoggingLimitDebug","text":"Type: Boolean\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nSets the
Logging.LimitDebugoption to limit debug messages to a list of named debug scopes. See about_PSRule_Options for more information.
"},{"location":"commands/PSRule/en-US/New-PSRuleOption/#-logginglimitverbose","title":"-LoggingLimitVerbose","text":"Type: String[]\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nSets the
Logging.LimitVerboseoption to limit verbose messages to a list of named verbose scopes. See about_PSRule_Options for more information.
"},{"location":"commands/PSRule/en-US/New-PSRuleOption/#-loggingrulefail","title":"-LoggingRuleFail","text":"Type: String[]\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nSets the
Logging.RuleFailoption to generate an informational message for each rule fail. See about_PSRule_Options for more information.
"},{"location":"commands/PSRule/en-US/New-PSRuleOption/#-loggingrulepass","title":"-LoggingRulePass","text":"Type: OutcomeLogStream\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nSets the
Logging.RulePassoption to generate an informational message for each rule pass. See about_PSRule_Options for more information.
"},{"location":"commands/PSRule/en-US/New-PSRuleOption/#-outputas","title":"-OutputAs","text":"Type: OutcomeLogStream\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nSets the option
Output.As. TheOutput.Asoption configures the type of results to produce, either detail or summary.
"},{"location":"commands/PSRule/en-US/New-PSRuleOption/#-outputbanner","title":"-OutputBanner","text":"Type: ResultFormat\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nSets the option
Output.Banner. TheOutput.Banneroption configure information displayed with PSRule banner. This option is only applicable when usingAssert-PSRulecmdlet.
"},{"location":"commands/PSRule/en-US/New-PSRuleOption/#-outputculture","title":"-OutputCulture","text":"Type: BannerFormat\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: Default\nAccept pipeline input: False\nAccept wildcard characters: False\nSets the option
Output.Culture. TheOutput.Cultureoption configures the culture used to generated output. When multiple cultures are specified, the first matching culture will be used. See about_PSRule_Options for more information.
"},{"location":"commands/PSRule/en-US/New-PSRuleOption/#-outputencoding","title":"-OutputEncoding","text":"Type: String[]\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nSets the option
Output.Encoding. TheOutput.Encodingoption configured the encoding used to write results to file.
"},{"location":"commands/PSRule/en-US/New-PSRuleOption/#-outputfooter","title":"-OutputFooter","text":"Type: OutputEncoding\nParameter Sets: (All)\nAliases:\nAccepted values: Default, UTF8, UTF7, Unicode, UTF32, ASCII\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nSets the option
Output.Footer. TheOutput.Footeroption configures the information displayed for PSRule footer. See about_PSRule_Options for more information.
"},{"location":"commands/PSRule/en-US/New-PSRuleOption/#-outputformat","title":"-OutputFormat","text":"Type: FooterFormat\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: Default\nAccept pipeline input: False\nAccept wildcard characters: False\nSets the option
Output.Format. TheOutput.Formatoption configures the format that results will be presented in. See about_PSRule_Options for more information.
"},{"location":"commands/PSRule/en-US/New-PSRuleOption/#-outputjobsummarypath","title":"-OutputJobSummaryPath","text":"Type: OutputFormat\nParameter Sets: (All)\nAliases:\nAccepted values: None, Yaml, Json, Markdown, NUnit3, Csv, Wide, Sarif\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nSet the option
Output.JobSummaryPath. TheOutput.JobSummaryPathoption configures the path to a job summary output file.
"},{"location":"commands/PSRule/en-US/New-PSRuleOption/#-outputjsonindent","title":"-OutputJsonIndent","text":"Type: String\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nSets the option
Output.JsonIndent. TheOutput.JsonIndentoption configures indentation for JSON output.This option only applies to
Get-PSRule,Invoke-PSRuleandAssert-PSRulecmdlets.
"},{"location":"commands/PSRule/en-US/New-PSRuleOption/#-outputoutcome","title":"-OutputOutcome","text":"Type: Int32\nParameter Sets: (All)\nAliases: JsonIndent\nAccepted values: 0, 1, 2, 3, 4\n\nRequired: False\nPosition: Named\nDefault value: 0\nAccept pipeline input: False\nAccept wildcard characters: False\nSets the
Output.Outcomeoption. This option can be set to include or exclude output results. See about_PSRule_Options for more information.
"},{"location":"commands/PSRule/en-US/New-PSRuleOption/#-outputpath","title":"-OutputPath","text":"Type: RuleOutcome\nParameter Sets: (All)\nAliases: Outcome\n\nRequired: False\nPosition: Named\nDefault value: Processed\nAccept pipeline input: False\nAccept wildcard characters: False\nSets the option
Output.Path. TheOutput.Pathoption configures an output file path to write results.
"},{"location":"commands/PSRule/en-US/New-PSRuleOption/#-outputsarifproblemsonly","title":"-OutputSarifProblemsOnly","text":"Type: String\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nSets the option
Option.SarifProblemsOnly. TheOutput.SarifProblemsOnlyoption determines if SARIF output only includes fail and error outcomes.
"},{"location":"commands/PSRule/en-US/New-PSRuleOption/#-outputstyle","title":"-OutputStyle","text":"Type: Boolean\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: True\nAccept pipeline input: False\nAccept wildcard characters: False\nSets the option
Option.Style. TheOutput.Styleoption configures the style that results will be presented in.This option only applies to
Assert-PSRule.
"},{"location":"commands/PSRule/en-US/New-PSRuleOption/#-repositorybaseref","title":"-RepositoryBaseRef","text":"Type: OutputStyle\nParameter Sets: (All)\nAliases:\nAccepted values: Client, Plain, AzurePipelines, GitHubActions\n\nRequired: False\nPosition: Named\nDefault value: Client\nAccept pipeline input: False\nAccept wildcard characters: False\nSets the option
Repository.BaseRef. TheRepository.BaseRefoption sets the repository base ref used for comparisons of changed files.
"},{"location":"commands/PSRule/en-US/New-PSRuleOption/#-repositoryurl","title":"-RepositoryUrl","text":"Type: String\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nSets the option
Repository.Url. TheRepository.Urloption sets the repository URL reported in output.
"},{"location":"commands/PSRule/en-US/New-PSRuleOption/#-ruleincludelocal","title":"-RuleIncludeLocal","text":"Type: String\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nSets the option
Rule.IncludeLocal. TheRule.IncludeLocaloption configures if local rules are automatically included. See about_PSRule_Options for more information.
"},{"location":"commands/PSRule/en-US/New-PSRuleOption/#-duplicateresourceid","title":"-DuplicateResourceId","text":"Type: Boolean\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: False\nAccept pipeline input: False\nAccept wildcard characters: False\nSets the option
Execution.DuplicateResourceId. TheExecution.DuplicateResourceIdoption determines how to handle duplicate resources identifiers during execution.
"},{"location":"commands/PSRule/en-US/New-PSRuleOption/#-initialsessionstate","title":"-InitialSessionState","text":"Type: ExecutionActionPreference\nParameter Sets: (All)\nAliases: ExecutionDuplicateResourceId\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nSets the option
Execution.InitialSessionState. TheExecution.InitialSessionStateoption determines how the initial session state for executing PowerShell code is created.
"},{"location":"commands/PSRule/en-US/New-PSRuleOption/#-executionruleexcluded","title":"-ExecutionRuleExcluded","text":"Type: SessionState\nParameter Sets: (All)\nAliases: ExecutionInitialSessionState\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nSets the option
Execution.RuleExcluded. TheExecution.RuleExcludedoption determines how to handle excluded rules.
"},{"location":"commands/PSRule/en-US/New-PSRuleOption/#-executionrulesuppressed","title":"-ExecutionRuleSuppressed","text":"Type: ExecutionActionPreference\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nSets the option
Execution.RuleSuppressed. TheExecution.RuleSuppressedoption determines how to handle suppressed rules.
"},{"location":"commands/PSRule/en-US/New-PSRuleOption/#-suppressiongroupexpired","title":"-SuppressionGroupExpired","text":"Type: ExecutionActionPreference\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nSets the option
Execution.SuppressionGroupExpired. TheExecution.SuppressionGroupExpiredoption determines how to handle expired suppression groups.
"},{"location":"commands/PSRule/en-US/New-PSRuleOption/#commonparameters","title":"CommonParameters","text":"Type: ExecutionActionPreference\nParameter Sets: (All)\nAliases: ExecutionSuppressionGroupExpired\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nThis cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters.
"},{"location":"commands/PSRule/en-US/New-PSRuleOption/#inputs","title":"INPUTS","text":""},{"location":"commands/PSRule/en-US/New-PSRuleOption/#none","title":"None","text":""},{"location":"commands/PSRule/en-US/New-PSRuleOption/#outputs","title":"OUTPUTS","text":""},{"location":"commands/PSRule/en-US/New-PSRuleOption/#psruleconfigurationpsruleoption","title":"PSRule.Configuration.PSRuleOption","text":""},{"location":"commands/PSRule/en-US/New-PSRuleOption/#notes","title":"NOTES","text":""},{"location":"commands/PSRule/en-US/New-PSRuleOption/#related-links","title":"RELATED LINKS","text":"Invoke-PSRule
Set-PSRuleOption
"},{"location":"commands/PSRule/en-US/PSRule/","title":"PSRule Module","text":""},{"location":"commands/PSRule/en-US/PSRule/#description","title":"Description","text":"A PowerShell rules engine.
"},{"location":"commands/PSRule/en-US/PSRule/#psrule-cmdlets","title":"PSRule Cmdlets","text":""},{"location":"commands/PSRule/en-US/PSRule/#assert-psrule","title":"Assert-PSRule","text":"Evaluate objects against matching rules and assert any failures.
"},{"location":"commands/PSRule/en-US/PSRule/#export-psrulebaseline","title":"Export-PSRuleBaseline","text":"Exports a list of baselines to a file.
"},{"location":"commands/PSRule/en-US/PSRule/#get-psrule","title":"Get-PSRule","text":"Get a list of matching rule definitions within the search path.
"},{"location":"commands/PSRule/en-US/PSRule/#get-psrulebaseline","title":"Get-PSRuleBaseline","text":"Get a list of matching baselines within the search path.
"},{"location":"commands/PSRule/en-US/PSRule/#get-psrulehelp","title":"Get-PSRuleHelp","text":"Get documentation for a rule.
"},{"location":"commands/PSRule/en-US/PSRule/#get-psruletarget","title":"Get-PSRuleTarget","text":"Get a list of target object.
"},{"location":"commands/PSRule/en-US/PSRule/#invoke-psrule","title":"Invoke-PSRule","text":"Evaluate objects against matching rules and output the results.
"},{"location":"commands/PSRule/en-US/PSRule/#new-psruleoption","title":"New-PSRuleOption","text":"Create options to configure PSRule execution.
"},{"location":"commands/PSRule/en-US/PSRule/#set-psruleoption","title":"Set-PSRuleOption","text":"Set options to configure PSRule execution.
"},{"location":"commands/PSRule/en-US/PSRule/#test-psruletarget","title":"Test-PSRuleTarget","text":"Evaluate pipeline objects against matching rules.
"},{"location":"commands/PSRule/en-US/Set-PSRuleOption/","title":"Set-PSRuleOption","text":""},{"location":"commands/PSRule/en-US/Set-PSRuleOption/#synopsis","title":"SYNOPSIS","text":"Sets options that configure PSRule execution.
"},{"location":"commands/PSRule/en-US/Set-PSRuleOption/#syntax","title":"SYNTAX","text":"
"},{"location":"commands/PSRule/en-US/Set-PSRuleOption/#description","title":"DESCRIPTION","text":"Set-PSRuleOption [[-Path] <String>] [-Option <PSRuleOption>] [-PassThru] [-Force] [-AllowClobber]\n [-BaselineGroup <Hashtable>] [-BindingIgnoreCase <Boolean>] [-BindingField <Hashtable>]\n [-BindingNameSeparator <String>] [-BindingPreferTargetInfo <Boolean>] [-TargetName <String[]>]\n [-TargetType <String[]>] [-BindingUseQualifiedName <Boolean>] [-Convention <String[]>]\n [-DuplicateResourceId <ExecutionActionPreference>] [-InitialSessionState <SessionState>]\n [-SuppressionGroupExpired <ExecutionActionPreference>] [-ExecutionRuleExcluded <ExecutionActionPreference>]\n [-ExecutionRuleSuppressed <ExecutionActionPreference>] [-ExecutionAliasReference <ExecutionActionPreference>]\n [-ExecutionRuleInconclusive <ExecutionActionPreference>]\n [-ExecutionInvariantCulture <ExecutionActionPreference>]\n [-ExecutionUnprocessedObject <ExecutionActionPreference>] [-IncludeModule <String[]>]\n [-IncludePath <String[]>] [-Format <InputFormat>] [-InputIgnoreGitPath <Boolean>]\n [-InputIgnoreObjectSource <Boolean>] [-InputIgnoreRepositoryCommon <Boolean>]\n [-InputIgnoreUnchangedPath <Boolean>] [-ObjectPath <String>] [-InputPathIgnore <String[]>]\n [-InputTargetType <String[]>] [-LoggingLimitDebug <String[]>] [-LoggingLimitVerbose <String[]>]\n [-LoggingRuleFail <OutcomeLogStream>] [-LoggingRulePass <OutcomeLogStream>] [-OutputAs <ResultFormat>]\n [-OutputBanner <BannerFormat>] [-OutputCulture <String[]>] [-OutputEncoding <OutputEncoding>]\n [-OutputFooter <FooterFormat>] [-OutputFormat <OutputFormat>] [-OutputJobSummaryPath <String>]\n [-OutputJsonIndent <Int32>] [-OutputOutcome <RuleOutcome>] [-OutputPath <String>]\n [-OutputSarifProblemsOnly <Boolean>] [-OutputStyle <OutputStyle>] [-RepositoryBaseRef <String>]\n [-RepositoryUrl <String>] [-RuleIncludeLocal <Boolean>] [-WhatIf] [-Confirm] [<CommonParameters>]\nSets options that configure PSRule execution.
"},{"location":"commands/PSRule/en-US/Set-PSRuleOption/#examples","title":"EXAMPLES","text":""},{"location":"commands/PSRule/en-US/Set-PSRuleOption/#example-1","title":"Example 1","text":"PS C:\\> Set-PSRuleOption -OutputFormat Yaml;\nSets the
"},{"location":"commands/PSRule/en-US/Set-PSRuleOption/#example-2","title":"Example 2","text":"Output.FormattoYamlforps-rule.yamlin the current working path. If theps-rule.yamlfile exists, it is merged with the existing file and overwritten. If the file does not exist, a new file is created.PS C:\\> Set-PSRuleOption -OutputFormat Yaml -Path .\\project-options.yaml;\nSets the
"},{"location":"commands/PSRule/en-US/Set-PSRuleOption/#parameters","title":"PARAMETERS","text":""},{"location":"commands/PSRule/en-US/Set-PSRuleOption/#-path","title":"-Path","text":"Output.FormattoYamlforproject-options.yamlin the current working path. If theproject-options.yamlfile exists, it is merged with the existing file and overwritten. If the file does not exist, a new file is created.The path to a YAML file where options will be set.
Either a directory or file path can be specified. When a directory is used,
ps-rule.yamlwill be used as the file name.The file will be created if it does not exist. If the file already exists it will be merged with the existing options and overwritten.
If the directory does not exist an error will be generated. To force the creation of the directory path use the
-Forceswitch.
"},{"location":"commands/PSRule/en-US/Set-PSRuleOption/#-option","title":"-Option","text":"Type: String\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: 1\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nAn options object to use.
"},{"location":"commands/PSRule/en-US/Set-PSRuleOption/#-passthru","title":"-PassThru","text":"Type: PSRuleOption\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: True (ByValue)\nAccept wildcard characters: False\nUse this option to return the options object to the pipeline instead of saving to disk.
"},{"location":"commands/PSRule/en-US/Set-PSRuleOption/#-force","title":"-Force","text":"Type: SwitchParameter\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: False\nAccept pipeline input: False\nAccept wildcard characters: False\nForce creation of directory path for Path parameter, when the directory does not already exist.
"},{"location":"commands/PSRule/en-US/Set-PSRuleOption/#-allowclobber","title":"-AllowClobber","text":"Type: SwitchParameter\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nOverwrite YAML files that contain comments.
"},{"location":"commands/PSRule/en-US/Set-PSRuleOption/#-baselinegroup","title":"-BaselineGroup","text":"Type: SwitchParameter\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nSets the option
Baseline.Group. The optionBaseline.Groupallows a named group of baselines to be defined and later referenced. See about_PSRule_Options for more information.
"},{"location":"commands/PSRule/en-US/Set-PSRuleOption/#-bindingignorecase","title":"-BindingIgnoreCase","text":"Type: Hashtable\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nSets the option
Binding.IgnoreCase. The optionBinding.IgnoreCasedetermines if binding operations are case-sensitive or not. See about_PSRule_Options for more information.
"},{"location":"commands/PSRule/en-US/Set-PSRuleOption/#-bindingfield","title":"-BindingField","text":"Type: Boolean\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: True\nAccept pipeline input: False\nAccept wildcard characters: False\nSets the option
Binding.Field. The option specified one or more custom field bindings. See about_PSRule_Options for more information.
"},{"location":"commands/PSRule/en-US/Set-PSRuleOption/#-bindingnameseparator","title":"-BindingNameSeparator","text":"Type: Hashtable\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nSets the option
Binding.NameSeparator. This option specifies the separator to use for qualified names. See about_PSRule_Options for more information.
"},{"location":"commands/PSRule/en-US/Set-PSRuleOption/#-bindingprefertargetinfo","title":"-BindingPreferTargetInfo","text":"Type: String\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nSets the option
Binding.PreferTargetInfo. This option specifies if automatic binding is preferred over configured binding options. See about_PSRule_Options for more information.
"},{"location":"commands/PSRule/en-US/Set-PSRuleOption/#-convention","title":"-Convention","text":"Type: Boolean\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: False\nAccept pipeline input: False\nAccept wildcard characters: False\nSets the
Option.ConventionIncludeoption. This option specifies the name of conventions to execute in the pipeline when processing objects. See about_PSRule_Options for more information.
"},{"location":"commands/PSRule/en-US/Set-PSRuleOption/#-targetname","title":"-TargetName","text":"Type: String[]\nParameter Sets: (All)\nAliases: ConventionInclude\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nSets the option
Binding.TargetName. This option specifies one or more properties of TargetObject to use to bind TargetName to. See about_PSRule_Options for more information.
"},{"location":"commands/PSRule/en-US/Set-PSRuleOption/#-targettype","title":"-TargetType","text":"Type: String[]\nParameter Sets: (All)\nAliases: BindingTargetName\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nSets the option
Binding.TargetType. This option specifies one or more properties of TargetObject to use to bind TargetType to. See about_PSRule_Options for more information.
"},{"location":"commands/PSRule/en-US/Set-PSRuleOption/#-bindingusequalifiedname","title":"-BindingUseQualifiedName","text":"Type: String[]\nParameter Sets: (All)\nAliases: BindingTargetType\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nSets the option
Binding.UseQualifiedName. This option specifies is qualified target names are used. See about_PSRule_Options for more information.
"},{"location":"commands/PSRule/en-US/Set-PSRuleOption/#-executionaliasreference","title":"-ExecutionAliasReference","text":"Type: Boolean\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nSets the
Execution.AliasReferenceoption. Determines how to handle when an alias to a resource is used. See about_PSRule_Options for more information.
"},{"location":"commands/PSRule/en-US/Set-PSRuleOption/#-executioninvariantculture","title":"-ExecutionInvariantCulture","text":"Type: ExecutionActionPreference\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nSets the
Execution.InvariantCultureoption. Determines how to report when an invariant culture is used. See about_PSRule_Options for more information.
"},{"location":"commands/PSRule/en-US/Set-PSRuleOption/#-executionruleinconclusive","title":"-ExecutionRuleInconclusive","text":"Type: ExecutionActionPreference\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nSets the
Execution.RuleInconclusiveoption. Determines how to handle rules that generate inconclusive results. See about_PSRule_Options for more information.
"},{"location":"commands/PSRule/en-US/Set-PSRuleOption/#-executionunprocessedobject","title":"-ExecutionUnprocessedObject","text":"Type: ExecutionActionPreference\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nSets the
Execution.UnprocessedObjectoption. Determines how to report objects that are not processed by any rule. See about_PSRule_Options for more information.
"},{"location":"commands/PSRule/en-US/Set-PSRuleOption/#-includemodule","title":"-IncludeModule","text":"Type: ExecutionActionPreference\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nSets the
Include.Moduleoption to include additional module sources. See about_PSRule_Options for more information.
"},{"location":"commands/PSRule/en-US/Set-PSRuleOption/#-includepath","title":"-IncludePath","text":"Type: String[]\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nSets the
Include.Pathoption to include additional standalone sources. See about_PSRule_Options for more information.
"},{"location":"commands/PSRule/en-US/Set-PSRuleOption/#-format","title":"-Format","text":"Type: String[]\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nSets the
Input.Formatoption to configure the input format for when a string is passed in as a target object. See about_PSRule_Options for more information.
"},{"location":"commands/PSRule/en-US/Set-PSRuleOption/#-inputignoregitpath","title":"-InputIgnoreGitPath","text":"Type: InputFormat\nParameter Sets: (All)\nAliases: InputFormat\nAccepted values: None, Yaml, Json, Markdown, PowerShellData, File, Detect\n\nRequired: False\nPosition: Named\nDefault value: Detect\nAccept pipeline input: False\nAccept wildcard characters: False\nSets the
Input.IgnoreGitPathoption to determine if files within the .git path are ignored. See about_PSRule_Options for more information.
"},{"location":"commands/PSRule/en-US/Set-PSRuleOption/#-inputignorerepositorycommon","title":"-InputIgnoreRepositoryCommon","text":"Type: Boolean\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: True\nAccept pipeline input: False\nAccept wildcard characters: False\nSets the
Input.IgnoreRepositoryCommonoption to determine if files common repository files are ignored. See about_PSRule_Options for more information.
"},{"location":"commands/PSRule/en-US/Set-PSRuleOption/#-inputignoreunchangedpath","title":"-InputIgnoreUnchangedPath","text":"Type: Boolean\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nSets the option
Input.IgnoreUnchangedPath. TheInput.IgnoreUnchangedPathoption determine if unchanged files are ignored.
"},{"location":"commands/PSRule/en-US/Set-PSRuleOption/#-objectpath","title":"-ObjectPath","text":"Type: Boolean\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nSets the
Input.ObjectPathoption to use an object path to use instead of the pipeline object. See about_PSRule_Options for more information.
"},{"location":"commands/PSRule/en-US/Set-PSRuleOption/#-inputpathignore","title":"-InputPathIgnore","text":"Type: String\nParameter Sets: (All)\nAliases: InputObjectPath\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nSets the
Input.PathIgnoreoption. If specified, files that match the path spec will not be processed. See about_PSRule_Options for more information.
"},{"location":"commands/PSRule/en-US/Set-PSRuleOption/#-inputtargettype","title":"-InputTargetType","text":"Type: String[]\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nSets the
Input.TargetTypeoption to only process objects with the specified TargetType.
"},{"location":"commands/PSRule/en-US/Set-PSRuleOption/#-inputignoreobjectsource","title":"-InputIgnoreObjectSource","text":"Type: String[]\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nSets the option
Input.IgnoreObjectSource. TheInput.IgnoreObjectSourceoption determines if objects will be skipped if the source path has been ignored.
"},{"location":"commands/PSRule/en-US/Set-PSRuleOption/#-logginglimitdebug","title":"-LoggingLimitDebug","text":"Type: Boolean\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nSets the
Logging.LimitDebugoption to limit debug messages to a list of named debug scopes.
"},{"location":"commands/PSRule/en-US/Set-PSRuleOption/#-logginglimitverbose","title":"-LoggingLimitVerbose","text":"Type: String[]\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nSets the
Logging.LimitVerboseoption to limit verbose messages to a list of named verbose scopes.
"},{"location":"commands/PSRule/en-US/Set-PSRuleOption/#-loggingrulefail","title":"-LoggingRuleFail","text":"Type: String[]\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nSets the
Logging.RuleFailoption to generate an informational message for each rule fail.
"},{"location":"commands/PSRule/en-US/Set-PSRuleOption/#-loggingrulepass","title":"-LoggingRulePass","text":"Type: OutcomeLogStream\nParameter Sets: (All)\nAliases:\nAccepted values: None, Error, Warning, Information\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nSets the
Logging.RulePassoption to generate an informational message for each rule pass.
"},{"location":"commands/PSRule/en-US/Set-PSRuleOption/#-outputas","title":"-OutputAs","text":"Type: OutcomeLogStream\nParameter Sets: (All)\nAliases:\nAccepted values: None, Error, Warning, Information\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nSets the option
Output.As. TheOutput.Asoption configures the type of results to produce, either detail or summary.
"},{"location":"commands/PSRule/en-US/Set-PSRuleOption/#-outputbanner","title":"-OutputBanner","text":"Type: ResultFormat\nParameter Sets: (All)\nAliases:\nAccepted values: Detail, Summary\n\nRequired: False\nPosition: Named\nDefault value: Detail\nAccept pipeline input: False\nAccept wildcard characters: False\nSets the option
Output.Banner. TheOutput.Banneroption configure information displayed with PSRule banner. This option is only applicable when usingAssert-PSRulecmdlet.
"},{"location":"commands/PSRule/en-US/Set-PSRuleOption/#-outputculture","title":"-OutputCulture","text":"Type: BannerFormat\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: Default\nAccept pipeline input: False\nAccept wildcard characters: False\nSets the option
Output.Culture. TheOutput.Cultureoption configures the culture used to generated output. When multiple cultures are specified, the first matching culture will be used.
"},{"location":"commands/PSRule/en-US/Set-PSRuleOption/#-outputencoding","title":"-OutputEncoding","text":"Type: String[]\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nSets the option
Output.Encoding. TheOutput.Encodingoption configured the encoding used to write results to file.
"},{"location":"commands/PSRule/en-US/Set-PSRuleOption/#-outputfooter","title":"-OutputFooter","text":"Type: OutputEncoding\nParameter Sets: (All)\nAliases:\nAccepted values: Default, UTF8, UTF7, Unicode, UTF32, ASCII\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nSets the option
Output.Footer. TheOutput.Footeroption configures the information displayed for PSRule footer. See about_PSRule_Options for more information.
"},{"location":"commands/PSRule/en-US/Set-PSRuleOption/#-outputformat","title":"-OutputFormat","text":"Type: FooterFormat\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: Default\nAccept pipeline input: False\nAccept wildcard characters: False\nSets the option
Output.Format. TheOutput.Formatoption configures the format that results will be presented in.
"},{"location":"commands/PSRule/en-US/Set-PSRuleOption/#-outputjobsummarypath","title":"-OutputJobSummaryPath","text":"Type: OutputFormat\nParameter Sets: (All)\nAliases:\nAccepted values: None, Yaml, Json, Markdown, NUnit3, Csv, Wide, Sarif\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nSet the option
Output.JobSummaryPath. TheOutput.JobSummaryPathoption configures the path to a job summary output file.
"},{"location":"commands/PSRule/en-US/Set-PSRuleOption/#-outputjsonindent","title":"-OutputJsonIndent","text":"Type: String\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nSets the option
Output.JsonIndent. TheOutput.JsonIndentoption configures indentation for JSON output.This option only applies to
Get-PSRule,Invoke-PSRuleandAssert-PSRulecmdlets.
"},{"location":"commands/PSRule/en-US/Set-PSRuleOption/#-outputoutcome","title":"-OutputOutcome","text":"Type: Int32\nParameter Sets: (All)\nAliases: JsonIndent\nAccepted values: 0, 1, 2, 3, 4\n\nRequired: False\nPosition: Named\nDefault value: 0\nAccept pipeline input: False\nAccept wildcard characters: False\nSets the
Output.Outcomeoption. This option can be set to include or exclude output results. See about_PSRule_Options for more information.
"},{"location":"commands/PSRule/en-US/Set-PSRuleOption/#-outputpath","title":"-OutputPath","text":"Type: RuleOutcome\nParameter Sets: (All)\nAliases: Outcome\n\nRequired: False\nPosition: Named\nDefault value: Processed\nAccept pipeline input: False\nAccept wildcard characters: False\nSets the option
Output.Path. TheOutput.Pathoption configures an output file path to write results.
"},{"location":"commands/PSRule/en-US/Set-PSRuleOption/#-outputsarifproblemsonly","title":"-OutputSarifProblemsOnly","text":"Type: String\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nSets the option
Option.SarifProblemsOnly. TheOutput.SarifProblemsOnlyoption determines if SARIF output only includes fail and error outcomes.
"},{"location":"commands/PSRule/en-US/Set-PSRuleOption/#-outputstyle","title":"-OutputStyle","text":"Type: Boolean\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: True\nAccept pipeline input: False\nAccept wildcard characters: False\nSets the option
Option.Style. TheOutput.Styleoption configures the style that results will be presented in.This option only applies to
Assert-PSRule.
"},{"location":"commands/PSRule/en-US/Set-PSRuleOption/#-whatif","title":"-WhatIf","text":"Type: OutputStyle\nParameter Sets: (All)\nAliases:\nAccepted values: Client, Plain, AzurePipelines, GitHubActions\n\nRequired: False\nPosition: Named\nDefault value: Client\nAccept pipeline input: False\nAccept wildcard characters: False\nShows what would happen if the cmdlet runs. The cmdlet is not run.
"},{"location":"commands/PSRule/en-US/Set-PSRuleOption/#-confirm","title":"-Confirm","text":"Type: SwitchParameter\nParameter Sets: (All)\nAliases: wi\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nPrompts you for confirmation before running the cmdlet.
"},{"location":"commands/PSRule/en-US/Set-PSRuleOption/#-repositorybaseref","title":"-RepositoryBaseRef","text":"Type: SwitchParameter\nParameter Sets: (All)\nAliases: cf\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nSets the option
Repository.BaseRef. TheRepository.BaseRefoption sets the repository base ref used for comparisons of changed files.
"},{"location":"commands/PSRule/en-US/Set-PSRuleOption/#-repositoryurl","title":"-RepositoryUrl","text":"Type: String\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nSets the option
Repository.Url. TheRepository.Urloption sets the repository URL reported in output.
"},{"location":"commands/PSRule/en-US/Set-PSRuleOption/#-ruleincludelocal","title":"-RuleIncludeLocal","text":"Type: String\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nSets the option
Rule.IncludeLocal. TheRule.IncludeLocaloption configures if local rules are automatically included. See about_PSRule_Options for more information.
"},{"location":"commands/PSRule/en-US/Set-PSRuleOption/#-duplicateresourceid","title":"-DuplicateResourceId","text":"Type: Boolean\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: False\nAccept pipeline input: False\nAccept wildcard characters: False\nSets the option
Execution.DuplicateResourceId. TheExecution.DuplicateResourceIdoption determines how to handle duplicate resources identifiers during execution.
"},{"location":"commands/PSRule/en-US/Set-PSRuleOption/#-initialsessionstate","title":"-InitialSessionState","text":"Type: ExecutionActionPreference\nParameter Sets: (All)\nAliases: ExecutionDuplicateResourceId\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nSets the option
Execution.InitialSessionState. TheExecution.InitialSessionStateoption determines how the initial session state for executing PowerShell code is created.
"},{"location":"commands/PSRule/en-US/Set-PSRuleOption/#-executionruleexcluded","title":"-ExecutionRuleExcluded","text":"Type: SessionState\nParameter Sets: (All)\nAliases: ExecutionInitialSessionState\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nSets the option
Execution.RuleExcluded. TheExecution.RuleExcludedoption determines how to handle excluded rules.
"},{"location":"commands/PSRule/en-US/Set-PSRuleOption/#-executionrulesuppressed","title":"-ExecutionRuleSuppressed","text":"Type: ExecutionActionPreference\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nSets the option
Execution.RuleSuppressed. TheExecution.RuleSuppressedoption determines how to handle suppressed rules.
"},{"location":"commands/PSRule/en-US/Set-PSRuleOption/#-suppressiongroupexpired","title":"-SuppressionGroupExpired","text":"Type: ExecutionActionPreference\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nSets the option
Execution.SuppressionGroupExpired. TheExecution.SuppressionGroupExpiredoption determines how to handle expired suppression groups.
"},{"location":"commands/PSRule/en-US/Set-PSRuleOption/#commonparameters","title":"CommonParameters","text":"Type: ExecutionActionPreference\nParameter Sets: (All)\nAliases: ExecutionSuppressionGroupExpired\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nThis cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters.
"},{"location":"commands/PSRule/en-US/Set-PSRuleOption/#inputs","title":"INPUTS","text":""},{"location":"commands/PSRule/en-US/Set-PSRuleOption/#outputs","title":"OUTPUTS","text":""},{"location":"commands/PSRule/en-US/Set-PSRuleOption/#psruleconfigurationpsruleoption","title":"PSRule.Configuration.PSRuleOption","text":"When you use the
"},{"location":"commands/PSRule/en-US/Set-PSRuleOption/#notes","title":"NOTES","text":""},{"location":"commands/PSRule/en-US/Set-PSRuleOption/#related-links","title":"RELATED LINKS","text":"-PassThruswitch, an options object is returned to the pipeline.New-PSRuleOption
"},{"location":"commands/PSRule/en-US/Test-PSRuleTarget/","title":"Test-PSRuleTarget","text":""},{"location":"commands/PSRule/en-US/Test-PSRuleTarget/#synopsis","title":"SYNOPSIS","text":"Pass or fail objects against matching rules.
"},{"location":"commands/PSRule/en-US/Test-PSRuleTarget/#syntax","title":"SYNTAX","text":""},{"location":"commands/PSRule/en-US/Test-PSRuleTarget/#input-default","title":"Input (Default)","text":"
"},{"location":"commands/PSRule/en-US/Test-PSRuleTarget/#inputpath","title":"InputPath","text":"Test-PSRuleTarget [-Module <String[]>] [-Outcome <RuleOutcome>] [-Format <InputFormat>]\n [-Convention <String[]>] [[-Path] <String[]>] [-Name <String[]>] [-Tag <Hashtable>] -InputObject <PSObject>\n [-Option <PSRuleOption>] [-ObjectPath <String>] [-TargetType <String[]>] [-Culture <String>]\n [<CommonParameters>]\n
"},{"location":"commands/PSRule/en-US/Test-PSRuleTarget/#description","title":"DESCRIPTION","text":"Test-PSRuleTarget -InputPath <String[]> [-Module <String[]>] [-Outcome <RuleOutcome>] [-Format <InputFormat>]\n [-Convention <String[]>] [[-Path] <String[]>] [-Name <String[]>] [-Tag <Hashtable>] [-Option <PSRuleOption>]\n [-ObjectPath <String>] [-TargetType <String[]>] [-Culture <String>] [<CommonParameters>]\nEvaluate objects against matching rules and return an overall pass or fail for the object as
$True(pass) or$False(fail).PSRule uses the following logic to determine overall pass or fail for an object:
By default, objects that do match any rules are not returned in results. To return
"},{"location":"commands/PSRule/en-US/Test-PSRuleTarget/#examples","title":"EXAMPLES","text":""},{"location":"commands/PSRule/en-US/Test-PSRuleTarget/#example-1","title":"Example 1","text":"$Truefor these objects, use-Outcome All.@{ Name = 'Item 1' } | Test-PSRuleTarget;\nEvaluate a simple hashtable on the pipeline against rules loaded from the current working path.
"},{"location":"commands/PSRule/en-US/Test-PSRuleTarget/#parameters","title":"PARAMETERS","text":""},{"location":"commands/PSRule/en-US/Test-PSRuleTarget/#-path","title":"-Path","text":"One or more paths to search for rule definitions within.
If the
-Moduleparameter is used, rule definitions from the currently working path will not be included by default.
"},{"location":"commands/PSRule/en-US/Test-PSRuleTarget/#-name","title":"-Name","text":"Type: String[]\nParameter Sets: (All)\nAliases: p\n\nRequired: False\nPosition: 1\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nThe name of a specific rule to evaluate. If this parameter is not specified all rules in search paths will be evaluated.
"},{"location":"commands/PSRule/en-US/Test-PSRuleTarget/#-outcome","title":"-Outcome","text":"Type: String[]\nParameter Sets: (All)\nAliases: n\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nFilter output to only show pipeline objects with a specific outcome.
"},{"location":"commands/PSRule/en-US/Test-PSRuleTarget/#-tag","title":"-Tag","text":"Type: RuleOutcome\nParameter Sets: (All)\nAliases:\nAccepted values: Pass, Fail, Error, None, Processed, All\n\nRequired: False\nPosition: Named\nDefault value: Pass, Fail, Error\nAccept pipeline input: False\nAccept wildcard characters: False\nOnly get rules with the specified tags set. If this parameter is not specified all rules in search paths will be returned.
When more than one tag is used, all tags must match. Tags are not case sensitive. A tag value of
*may be used to filter rules to any rule with the tag set, regardless of tag value.An array of tag values can be used to match a rule with either value. i.e.
severity = important, criticalmatches rules with a category of eitherimportantorcritical.
"},{"location":"commands/PSRule/en-US/Test-PSRuleTarget/#-inputobject","title":"-InputObject","text":"Type: Hashtable\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nThe pipeline object to process rules for.
"},{"location":"commands/PSRule/en-US/Test-PSRuleTarget/#-option","title":"-Option","text":"Type: PSObject\nParameter Sets: Input\nAliases: TargetObject\n\nRequired: True\nPosition: Named\nDefault value: None\nAccept pipeline input: True (ByValue)\nAccept wildcard characters: False\nAdditional options that configure execution. A
PSRuleOptioncan be created by using theNew-PSRuleOptioncmdlet. Alternatively, a hashtable or path to YAML file can be specified with options.For more information on PSRule options see about_PSRule_Options.
"},{"location":"commands/PSRule/en-US/Test-PSRuleTarget/#-format","title":"-Format","text":"Type: PSRuleOption\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nConfigures the input format for when a string is passed in as a target object.
When the
-InputObjectparameter or pipeline input is used, strings are treated as plain text by default. Set this option to eitherYaml,Json,Markdown,PowerShellDatato have PSRule deserialize the object.When the
-InputPathparameter is used with a file path or URL. If theDetectformat is used, the file extension will be used to automatically detect the format. When-InputPathis not used,Detectis the same asNone.When this option is set to
FilePSRule scans the path and subdirectories specified by-InputPath. Files are treated as objects instead of being deserialized. Additional, PSRule uses the file extension as the object type. When files have no extension the whole file name is used.See
about_PSRule_Optionsfor details.This parameter takes precedence over the
Input.Formatoption if set.
"},{"location":"commands/PSRule/en-US/Test-PSRuleTarget/#-convention","title":"-Convention","text":"Type: InputFormat\nParameter Sets: (All)\nAliases:\nAccepted values: None, Yaml, Json, Markdown, PowerShellData, Repository, Detect\n\nRequired: False\nPosition: Named\nDefault value: Detect\nAccept pipeline input: False\nAccept wildcard characters: False\nSpecifies conventions by name to execute in the pipeline when processing objects.
"},{"location":"commands/PSRule/en-US/Test-PSRuleTarget/#-culture","title":"-Culture","text":"Type: String[]\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nSpecifies the culture to use for rule documentation and messages. By default, the culture of PowerShell is used.
This option does not affect the culture used for the PSRule engine, which always uses the culture of PowerShell.
The PowerShell cmdlet
Get-Cultureshows the current culture of PowerShell.
"},{"location":"commands/PSRule/en-US/Test-PSRuleTarget/#-objectpath","title":"-ObjectPath","text":"Type: String\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nThe name of a property to use instead of the pipeline object. If the property specified by
ObjectPathis a collection or an array, then each item in evaluated separately.
"},{"location":"commands/PSRule/en-US/Test-PSRuleTarget/#-targettype","title":"-TargetType","text":"Type: String\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nFilters input objects by TargetType.
If specified, only objects with the specified TargetType are processed. Objects that do not match TargetType are ignored. If multiple values are specified, only one TargetType must match. This parameter is not case-sensitive.
By default, all objects are processed.
This parameter if set, overrides the
Input.TargetTypeoption.To change the field TargetType is bound to set the
Binding.TargetTypeoption. For details see the about_PSRule_Options help topic.
"},{"location":"commands/PSRule/en-US/Test-PSRuleTarget/#-module","title":"-Module","text":"Type: String[]\nParameter Sets: (All)\nAliases:\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nSearch for rule definitions within a module. When specified without the
-Pathparameter, only rule definitions in the module will be discovered.When both
-Pathand-Moduleare specified, rule definitions from both are discovered.
"},{"location":"commands/PSRule/en-US/Test-PSRuleTarget/#-inputpath","title":"-InputPath","text":"Type: String[]\nParameter Sets: (All)\nAliases: m\n\nRequired: False\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nInstead of processing objects from the pipeline, import objects file the specified file paths.
"},{"location":"commands/PSRule/en-US/Test-PSRuleTarget/#commonparameters","title":"CommonParameters","text":"Type: String[]\nParameter Sets: InputPath\nAliases: f\n\nRequired: True\nPosition: Named\nDefault value: None\nAccept pipeline input: False\nAccept wildcard characters: False\nThis cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters.
"},{"location":"commands/PSRule/en-US/Test-PSRuleTarget/#inputs","title":"INPUTS","text":""},{"location":"commands/PSRule/en-US/Test-PSRuleTarget/#systemmanagementautomationpsobject","title":"System.Management.Automation.PSObject","text":"You can pipe any object to Test-PSRuleTarget.
"},{"location":"commands/PSRule/en-US/Test-PSRuleTarget/#outputs","title":"OUTPUTS","text":""},{"location":"commands/PSRule/en-US/Test-PSRuleTarget/#systemboolean","title":"System.Boolean","text":"Returns
"},{"location":"commands/PSRule/en-US/Test-PSRuleTarget/#notes","title":"NOTES","text":""},{"location":"commands/PSRule/en-US/Test-PSRuleTarget/#related-links","title":"RELATED LINKS","text":"$Truewhen the object passes and$Falsewhen the object fails.Invoke-PSRule
Assert-PSRule
Get-PSRule
"},{"location":"concepts/baselines/","title":"Baselines","text":"Abstract
A baseline is a set of rules and configuration options. You can define a named baseline to run a set of rules for a specific use case.
Baselines cover two (2) main scenarios:
A baseline is defined as a resource within YAML or JSON. Baselines can be defined side-by-side with rules you create or included separately as a custom baseline.
Continue reading baseline reference.
"},{"location":"concepts/baselines/#baseline-groups","title":"Baseline groups","text":"v2.9.0
In addition to regular baselines, you can use a baseline group to provide a friendly name to an existing baseline. A baseline groups are set by configuring the Baseline.Group option.
Experimental
Baseline groups are a work in progress and subject to change. Currently, baseline groups allow only a single baseline to be referenced. Join or start a discussion to let us know how we can improve this feature going forward.
Tip
You can use baseline groups to reference a baseline. If a new baseline is made available in the future, update your baseline group in one place to start using the new baseline.
In the following example, two baseline groups
ps-rule.yamllatestandprevieware defined:baseline:\n group:\n latest: PSRule.Rules.Azure\\Azure.GA_2023_03\n preview: PSRule.Rules.Azure\\Azure.Preview_2023_03\nTo use the baseline group, prefix the group name with
GitHub ActionsAzure PipelinesGeneric with PowerShell@when running PSRule. For example:- name: Run PSRule\n uses: microsoft/ps-rule@v2.9.0\n with:\n modules: 'PSRule.Rules.Azure'\n baseline: '@latest'\n- task: ps-rule-assert@2\n displayName: Run PSRule\n inputs:\n modules: 'PSRule.Rules.Azure'\n baseline: '@latest'\n
"},{"location":"concepts/grouping-rules/","title":"Grouping rules","text":"Assert-PSRule -InputPath '.' -Baseline '@latest' -Module PSRule.Rules.Azure -Format File;\nAbstract
Labels are additional metadata that can be used to classify rules. Together with tags they can be used to group or filter rules.
"},{"location":"concepts/grouping-rules/#using-labels","title":"Using labels","text":"When defining a rule you can specify labels to classify or link rules using a framework or standard. A single rule can be can linked to multiple labels. For example:
To specify labels in YAML, use the
labelsproperty:---\n# Synopsis: A rule with labels defined.\napiVersion: github.com/microsoft/PSRule/v1\nkind: Rule\nmetadata:\n name: WithLabels\n labels:\n Azure.WAF/pillar: Security\n Azure.ASB.v3/control: [ 'ID-1', 'ID-2' ]\nspec: { }\nTo specify labels in JSON, use the
labelsproperty:{\n // Synopsis: A rule with labels defined.\n \"apiVersion\": \"github.com/microsoft/PSRule/v1\",\n \"kind\": \"Rule\",\n \"metadata\": {\n \"name\": \"WithLabels\",\n \"labels\": {\n \"Azure.WAF/pillar\": \"Security\",\n \"Azure.ASB.v3/control\": [ \"ID-1\", \"ID-2\" ]\n }\n },\n \"spec\": { }\n}\nTo specify labels in PowerShell, use the
-Labelsparameter:
"},{"location":"concepts/grouping-rules/#filtering-with-labels","title":"Filtering with labels","text":"# Synopsis: A rule with labels defined.\nRule 'WithLabels' -Labels @{ 'Azure.WAF/pillar' = 'Security'; 'Azure.ASB.v3/control' = @('ID-1', 'ID-2') } {\n # Define conditions here\n} \nA reason for assigning labels to rules is to perform filtering of rules to a specific subset. This can be accomplished using baselines and the
spec.rule.labelsproperty. For example:
"},{"location":"concepts/lockfile/","title":"Lock file","text":"---\n# Synopsis: A baseline which returns only security rules.\napiVersion: github.com/microsoft/PSRule/v1\nkind: Baseline\nmetadata:\n name: TestBaseline6\nspec:\n rule:\n labels:\n Azure.WAF/pillar: [ 'Security' ]\n\n---\n# Synopsis: A baseline which returns any rules that are classified to Azure.WAF/pillar.\napiVersion: github.com/microsoft/PSRule/v1\nkind: Baseline\nmetadata:\n name: TestBaseline6\nspec:\n rule:\n labels:\n Azure.WAF/pillar: '*'\nAbstract
PSRule v3 and later uses a lock file to define the modules and versions used to run analysis. This article describes the lock file and how to manage it.
An optional lock file can be used to define the modules and versions used to run analysis. Using the lock file ensures that the same modules and versions are used across multiple machines, improving consistency.
Important
The lock file only applies to PSRule outside of PowerShell. When using PSRule as a PowerShell module, the lock file is ignored.
"},{"location":"concepts/lockfile/#restoring-modules","title":"Restoring modules","text":"When the lock file is present, PSRule will restore the modules and versions defined in the lock file.
"},{"location":"concepts/PSRule/en-US/about_PSRule_Assert/","title":"Assertion methods","text":"Describes the assertion helper that can be used within PSRule rule definitions.
","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Assert/#description","title":"Description","text":"PSRule includes an assertion helper exposed as a built-in variable
$Assert. The$Assertobject provides a consistent set of methods to evaluate objects.Each
$Assertmethod returns anAssertResultobject that contains the result of the assertion.The following built-in assertion methods are provided:
The
","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Assert/#using-assertion-methods","title":"Using assertion methods","text":"$Assertvariable can only be used within a rule definition block or script pre-conditions.An assertion method can be used like other methods in PowerShell. i.e.
$Assert.methodName(parameters).Assertion methods use the following standard pattern:
Some assertion methods may overlap or provide similar functionality to built-in keywords. Where you have the choice, use built-in keywords. Use assertion methods for advanced cases or increased flexibility.
In the following example,
Assert.HasFieldValueasserts that$TargetObjectshould have a field namedTypewith a non-empty value.Rule 'Assert.HasTypeField' {\n $Assert.HasFieldValue($TargetObject, 'Type')\n}\nTo find perform multiple assertions use.
","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Assert/#field-names","title":"Field names","text":"Rule 'Assert.HasRequiredFields' {\n $Assert.HasFieldValue($TargetObject, 'Name')\n $Assert.HasFieldValue($TargetObject, 'Type')\n $Assert.HasFieldValue($TargetObject, 'Value')\n}\nMany of the built-in assertion methods accept an object path or field name. An object path is an expression that traverses object properties, keys or indexes of the input object. The syntax for an object path is inspired by JSONPath which is current an IETF Internet-Draft.
The object path expression can contain:
For example:
Notable differences between object paths and JSONPath are:
The
APIVersionassertion method checks the field value is a valid date version. A constraint can optionally be provided to require the date version to be within a range.A date version uses the format
yyyy-MM-dd(2015-10-01). Additionally an optional string prerelease identifier can be usedyyyy-MM-dd-prerelease(2015-10-01-preview.1).The following parameters are accepted:
The following are supported constraints:
An empty, null or
*constraint matches all valid date versions.Multiple constraints can be joined together:
By example:
Handling for prerelease versions:
Reasons include:
Examples:
","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Assert/#contains","title":"Contains","text":"Rule 'ValidAPIVersion' {\n $Assert.APIVersion($TargetObject, 'apiVersion')\n}\n\nRule 'MinimumAPIVersion' {\n $Assert.APIVersion($TargetObject, 'apiVersion', '>=2015-10-01')\n}\n\nRule 'MinimumAPIVersionWithPrerelease' {\n $Assert.APIVersion($TargetObject, 'apiVersion', '>=2015-10-01-0', $True)\n}\n\nRule 'MinimumAPIVersionWithFlag' {\n $Assert.APIVersion($TargetObject, 'apiVersion', '@pre >=2015-10-01-0')\n}\nThe
Containsassertion method checks the operand contains the specified string. If the operand is an array of strings, only one string must contain the specified string. Optionally a case-sensitive compare can be used, however case is ignored by default.The following parameters are accepted:
Reasons include:
Examples:
","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Assert/#count","title":"Count","text":"Rule 'Contains' {\n $Assert.Contains($TargetObject, 'ResourceGroupName', 'prod')\n $Assert.Contains($TargetObject, 'Name', @('prod', 'test'), $True)\n}\nThe
Countassertion method checks the field value contains the specified number of items. The field value must be an array or collection.The following parameters are accepted:
Reasons include:
Examples:
","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Assert/#endswith","title":"EndsWith","text":"Rule 'Count' {\n $Assert.Count($TargetObject, 'items', 2)\n}\nThe
EndsWithassertion method checks the operand ends with the specified suffix. If the operand is an array of strings, only one string must end with the specified suffix. Optionally a case-sensitive compare can be used, however case is ignored by default.The following parameters are accepted:
Reasons include:
Examples:
","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Assert/#fileheader","title":"FileHeader","text":"Rule 'EndsWith' {\n $Assert.EndsWith($TargetObject, 'ResourceGroupName', 'eus')\n $Assert.EndsWith($TargetObject, 'Name', @('db', 'web'), $True)\n}\nThe
FileHeaderassertion method checks a file for a comment header. When comparing the file header, the format of line comments are automatically detected by file extension. Single line comments are supported. Multi-line comments are not supported.The following parameters are accepted:
Prefix detection for line comments is supported with the following file extensions:
Reasons include:
Examples:
","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Assert/#filepath","title":"FilePath","text":"Rule 'FileHeader' {\n $Assert.FileHeader($TargetObject, 'FullName', @(\n 'Copyright (c) Microsoft Corporation.'\n 'Licensed under the MIT License.'\n ));\n}\nThe
FilePathassertion method checks the file exists. Checks use file system case-sensitivity rules.The following parameters are accepted:
Reasons include:
Examples:
","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Assert/#greater","title":"Greater","text":"Rule 'FilePath' {\n $Assert.FilePath($TargetObject, 'FullName', @('CHANGELOG.md'));\n $Assert.FilePath($TargetObject, 'FullName', @('LICENSE', 'LICENSE.txt'));\n $Assert.FilePath($TargetObject, 'FullName', @('CODE_OF_CONDUCT.md'));\n $Assert.FilePath($TargetObject, 'FullName', @('CONTRIBUTING.md'));\n $Assert.FilePath($TargetObject, 'FullName', @('SECURITY.md'));\n $Assert.FilePath($TargetObject, 'FullName', @('README.md'));\n $Assert.FilePath($TargetObject, 'FullName', @('.github/CODEOWNERS'));\n $Assert.FilePath($TargetObject, 'FullName', @('.github/PULL_REQUEST_TEMPLATE.md'));\n}\nThe
Greaterassertion method checks the field value is greater than the specified value. The field value can either be an integer, float, array, or string. When the field value is:The following parameters are accepted:
Reasons include:
Examples:
","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Assert/#greaterorequal","title":"GreaterOrEqual","text":"Rule 'Greater' {\n $Assert.Greater($TargetObject, 'value', 3)\n}\nThe
GreaterOrEqualassertion method checks the field value is greater or equal to the specified value. The field value can either be an integer, float, array, or string. When the field value is:The following parameters are accepted:
Reasons include:
Examples:
","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Assert/#hasdefaultvalue","title":"HasDefaultValue","text":"Rule 'GreaterOrEqual' {\n $Assert.GreaterOrEqual($TargetObject, 'value', 3)\n}\nThe
HasDefaultValueassertion method check that the field does not exist or the field value is set to the default value.The following parameters are accepted:
This assertion will pass if:
This assertion will fail if:
Reasons include:
Examples:
","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Assert/#hasfield","title":"HasField","text":"Rule 'HasDefaultValue' {\n $Assert.HasDefaultValue($TargetObject, 'Properties.osProfile.linuxConfiguration.provisionVMAgent', $True)\n}\nThe
HasFieldassertion method checks the object has any of the specified fields.The following parameters are accepted:
Reasons include:
Examples:
","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Assert/#hasfields","title":"HasFields","text":"Rule 'HasField' {\n $Assert.HasField($TargetObject, 'Name')\n $Assert.HasField($TargetObject, 'tag.Environment', $True)\n $Assert.HasField($TargetObject, @('tag.Environment', 'tag.Env'), $True)\n}\nThe
HasFieldsassertion method checks the object has all of the specified fields.The following parameters are accepted:
Reasons include:
Examples:
","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Assert/#hasfieldvalue","title":"HasFieldValue","text":"Rule 'HasFields' {\n $Assert.HasFields($TargetObject, 'Name')\n $Assert.HasFields($TargetObject, 'tag.Environment', $True)\n $Assert.HasFields($TargetObject, @('tag.Environment', 'tag.Env'), $True)\n}\nThe
HasFieldValueassertion method checks the field value of the object is not empty.A field value is empty if any of the following are true:
The following parameters are accepted:
Reasons include:
Examples:
","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Assert/#hasjsonschema","title":"HasJsonSchema","text":"Rule 'HasFieldValue' {\n $Assert.HasFieldValue($TargetObject, 'Name')\n $Assert.HasFieldValue($TargetObject, 'tag.Environment', 'production')\n}\nThe
HasJsonSchemaassertion method determines if the input object has a$schemaproperty defined. If the$schemaproperty is defined, it must not be empty and match one of the supplied schemas. If a trailing#is specified it is ignored from the$schemaproperty anduriparameter below.The following parameters are accepted:
Reasons include:
Examples:
","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Assert/#jsonschema","title":"JsonSchema","text":"Rule 'HasFieldValue' {\n $Assert.HasJsonSchema($TargetObject)\n $Assert.HasJsonSchema($TargetObject, \"http://json-schema.org/draft-07/schema`#\")\n $Assert.HasJsonSchema($TargetObject, \"https://json-schema.org/draft-07/schema\", $True)\n}\nThe
JsonSchemaassertion method compares the input object against a defined JSON schema.The following parameters are accepted:
Reasons include:
Examples:
","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Assert/#in","title":"In","text":"Rule 'JsonSchema' {\n $Assert.JsonSchema($TargetObject, 'tests/PSRule.Tests/FromFile.Json.schema.json')\n}\nThe
Inassertion method checks the field value is included in a set of values. The field value can either be an integer, float, array, or string. When the field value is an array, only one item must be included in the set.The following parameters are accepted:
Reasons include:
Examples:
","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Assert/#isarray","title":"IsArray","text":"Rule 'In' {\n $Assert.In($TargetObject, 'Sku.tier', @('PremiumV2', 'Premium', 'Standard'))\n $Assert.In($TargetObject, 'Sku.tier', @('PremiumV2', 'Premium', 'Standard'), $True)\n}\nThe
IsArrayassertion method checks the field value is an array type.The following parameters are accepted:
Reasons include:
Examples:
","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Assert/#isboolean","title":"IsBoolean","text":"Rule 'IsArray' {\n # Require Value1 to be an array\n $Assert.IsArray($TargetObject, 'Value1')\n}\nThe
IsBooleanassertion method checks the field value is a boolean type.The following parameters are accepted:
Reasons include:
Examples:
","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Assert/#isdatetime","title":"IsDateTime","text":"Rule 'IsBoolean' {\n # Require Value1 to be a boolean\n $Assert.IsBoolean($TargetObject, 'Value1')\n\n # Require Value1 to be a boolean or a boolean string\n $Assert.IsBoolean($TargetObject, 'Value1', $True)\n}\nThe
IsDateTimeassertion method checks the field value is a DateTime type.The following parameters are accepted:
Reasons include:
Examples:
","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Assert/#isinteger","title":"IsInteger","text":"Rule 'IsDateTime' {\n # Require Value1 to be a DateTime\n $Assert.IsDateTime($TargetObject, 'Value1')\n\n # Require Value1 to be a DateTime or a DateTime string\n $Assert.IsDateTime($TargetObject, 'Value1', $True)\n}\nThe
IsIntegerassertion method checks the field value is a integer type. The following types are considered integer typesint,long,byte.The following parameters are accepted:
Reasons include:
Examples:
","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Assert/#islower","title":"IsLower","text":"Rule 'IsInteger' {\n # Require Value1 to be an integer\n $Assert.IsInteger($TargetObject, 'Value1')\n\n # Require Value1 to be an integer or a integer string\n $Assert.IsInteger($TargetObject, 'Value1', $True)\n}\nThe
IsLowerassertion method checks the field value uses only lowercase characters. Non-letter characters are ignored by default and will pass.The following parameters are accepted:
Reasons include:
Examples:
","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Assert/#isnumeric","title":"IsNumeric","text":"Rule 'IsLower' {\n # Require Name to be lowercase\n $Assert.IsLower($TargetObject, 'Name')\n\n # Require Name to only contain lowercase letters\n $Assert.IsLower($TargetObject, 'Name', $True)\n}\nThe
IsNumericassertion method checks the field value is a numeric type. The following types are considered numeric typesint,long,float,byte,double.The following parameters are accepted:
Reasons include:
Examples:
","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Assert/#isstring","title":"IsString","text":"Rule 'IsNumeric' {\n # Require Value1 to be numeric\n $Assert.IsNumeric($TargetObject, 'Value1')\n\n # Require Value1 to be numeric or a numerical string\n $Assert.IsNumeric($TargetObject, 'Value1', $True)\n}\nThe
IsStringassertion method checks the field value is a string type.The following parameters are accepted:
Reasons include:
Examples:
","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Assert/#isupper","title":"IsUpper","text":"Rule 'IsString' {\n # Require Value1 to be a string\n $Assert.IsString($TargetObject, 'Value1')\n}\nThe
IsUpperassertion method checks the field value uses only uppercase characters. Non-letter characters are ignored by default and will pass.The following parameters are accepted:
Reasons include:
Examples:
","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Assert/#less","title":"Less","text":"Rule 'IsUpper' {\n # Require Name to be uppercase\n $Assert.IsUpper($TargetObject, 'Name')\n\n # Require Name to only contain uppercase letters\n $Assert.IsUpper($TargetObject, 'Name', $True)\n}\nThe
Lessassertion method checks the field value is less than the specified value. The field value can either be an integer, float, array, or string. When the field value is:The following parameters are accepted:
Reasons include:
Examples:
","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Assert/#lessorequal","title":"LessOrEqual","text":"Rule 'Less' {\n $Assert.Less($TargetObject, 'value', 3)\n}\nThe
LessOrEqualassertion method checks the field value is less or equal to the specified value. The field value can either be an integer, float, array, or string. When the field value is:The following parameters are accepted:
Reasons include:
Examples:
","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Assert/#like","title":"Like","text":"Rule 'LessOrEqual' {\n $Assert.LessOrEqual($TargetObject, 'value', 3)\n}\nThe
Likeassertion method checks the field value matches a specified pattern. Optionally a case-sensitive compare can be used, however case is ignored by default.The following parameters are accepted:
Reasons include:
Examples:
","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Assert/#match","title":"Match","text":"Rule 'Like' {\n $Assert.Like($TargetObject, 'ResourceGroupName', 'rg-*')\n $Assert.Like($TargetObject, 'Name', @('st*', 'diag*'), $True)\n}\nThe
Matchassertion method checks the field value matches a regular expression pattern.The following parameters are accepted:
Reasons include:
Examples:
","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Assert/#notcontains","title":"NotContains","text":"Rule 'Match' {\n $Assert.Match($TargetObject, 'value', '^[a-z]*$')\n $Assert.Match($TargetObject, 'value', '^[a-z]*$', $True)\n}\nThe
NotContainsassertion method checks the operand contains the specified string. This condition fails when any of the specified sub-strings are found. If the operand is an array of strings, this condition fails if any of the strings contain the specified string. Optionally a case-sensitive compare can be used, however case is ignored by default.The following parameters are accepted:
Reasons include:
Examples:
","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Assert/#notcount","title":"NotCount","text":"Rule 'NotContains' {\n $Assert.NotContains($TargetObject, 'ResourceGroupName', 'prod')\n $Assert.NotContains($TargetObject, 'Name', @('prod', 'test'), $True)\n}\nThe
NotCountassertion method checks the field value does not contain the specified number of items. The field value must be an array or collection.The following parameters are accepted:
Reasons include:
Examples:
","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Assert/#notendswith","title":"NotEndsWith","text":"Rule 'NotCount' {\n $Assert.NotCount($TargetObject, 'items', 2)\n}\nThe
NotEndsWithassertion method checks the operand ends with the specified suffix. This condition fails when any of the specified sub-strings are found at the end of the operand. If the operand is an array of strings, this condition fails if any of the strings ends with the specified suffix. Optionally a case-sensitive compare can be used, however case is ignored by default.The following parameters are accepted:
Reasons include:
Examples:
","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Assert/#nothasfield","title":"NotHasField","text":"Rule 'NotEndsWith' {\n $Assert.NotEndsWith($TargetObject, 'ResourceGroupName', 'eus')\n $Assert.NotEndsWith($TargetObject, 'Name', @('db', 'web'), $True)\n}\nThe
NotHasFieldassertion method checks the object does not have any of the specified fields.The following parameters are accepted:
Reasons include:
Examples:
","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Assert/#notin","title":"NotIn","text":"Rule 'NotHasField' {\n $Assert.NotHasField($TargetObject, 'Name')\n $Assert.NotHasField($TargetObject, 'tag.Environment', $True)\n $Assert.NotHasField($TargetObject, @('tag.Environment', 'tag.Env'), $True)\n}\nThe
NotInassertion method checks the field value is not in a set of values. The field value can either be an integer, array, float, or string. When the field value is an array, none of the items must be included in the set. If the field does not exist at all, it is not in the set and passes. To check the field exists combine this assertion method withHasFieldValue.The following parameters are accepted:
Reasons include:
Examples:
","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Assert/#notlike","title":"NotLike","text":"Rule 'In' {\n $Assert.NotIn($TargetObject, 'Sku.tier', @('Free', 'Shared', 'Basic'))\n $Assert.NotIn($TargetObject, 'Sku.tier', @('Free', 'Shared', 'Basic'), $True)\n}\nThe
NotLikeassertion method checks the field value matches a specified pattern. This condition fails when any of the specified patterns match the field value. Optionally a case-sensitive compare can be used, however case is ignored by default.The following parameters are accepted:
Reasons include:
Examples:
","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Assert/#notmatch","title":"NotMatch","text":"Rule 'NotLike' {\n $Assert.NotLike($TargetObject, 'ResourceGroupName', 'rg-*')\n $Assert.NotLike($TargetObject, 'Name', @('st*', 'diag*'), $True)\n}\nThe
NotMatchassertion method checks the field value does not match a regular expression pattern. If the field does not exist at all, it does not match and passes. To check the field exists combine this assertion method withHasFieldValue.The following parameters are accepted:
Reasons include:
Examples:
","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Assert/#notnull","title":"NotNull","text":"Rule 'NotMatch' {\n $Assert.NotMatch($TargetObject, 'value', '^[a-z]*$')\n $Assert.NotMatch($TargetObject, 'value', '^[a-z]*$', $True)\n}\nThe
NotNullassertion method checks the field value of the object is not null.The following parameters are accepted:
Reasons include:
Examples:
","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Assert/#notstartswith","title":"NotStartsWith","text":"Rule 'NotNull' {\n $Assert.NotNull($TargetObject, 'Name')\n $Assert.NotNull($TargetObject, 'tag.Environment')\n}\nThe
NotStartsWithassertion method checks the operand starts with the specified prefix. This condition fails when any of the specified sub-strings are found at the start of the operand. If the operand is an array of strings, this condition fails if any of the strings start with the specified prefix. Optionally a case-sensitive compare can be used, however case is ignored by default.The following parameters are accepted:
Reasons include:
Examples:
","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Assert/#notwithinpath","title":"NotWithinPath","text":"Rule 'NotStartsWith' {\n $Assert.NotStartsWith($TargetObject, 'ResourceGroupName', 'rg-')\n $Assert.NotStartsWith($TargetObject, 'Name', @('st', 'diag'), $True)\n}\nThe
NotWithinPathassertion method checks the file is not within a specified path. Checks use file system case-sensitivity rules by default.The following parameters are accepted:
Reasons include:
Examples:
","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Assert/#null","title":"Null","text":"Rule 'NotWithinPath' {\n # The file must not be within either policy/ or security/ sub-directories.\n $Assert.NotWithinPath($TargetObject, 'FullName', @('policy/', 'security/'));\n}\nThe
Nullassertion method checks the field value of the object is null.A field value is null if any of the following are true:
The following parameters are accepted:
Reasons include:
Examples:
","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Assert/#nullorempty","title":"NullOrEmpty","text":"Rule 'Null' {\n $Assert.Null($TargetObject, 'NotField')\n $Assert.Null($TargetObject, 'tag.NullField')\n}\nThe
NullOrEmptyassertion method checks the field value of the object is null or empty.A field value is null or empty if any of the following are true:
The following parameters are accepted:
Reasons include:
Examples:
","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Assert/#typeof","title":"TypeOf","text":"Rule 'NullOrEmpty' {\n $Assert.NullOrEmpty($TargetObject, 'Name')\n $Assert.NullOrEmpty($TargetObject, 'tag.Environment')\n}\nThe
TypeOfassertion method checks the field value is a specified type.The following parameters are accepted:
Reasons include:
Examples:
","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Assert/#setof","title":"SetOf","text":"Rule 'TypeOf' {\n # Require Value1 to be [int]\n $Assert.TypeOf($TargetObject, 'Value1', [int])\n\n # Require Value1 to be [int] or [long]\n $Assert.TypeOf($TargetObject, 'Value1', @([int], [long]))\n}\nThe
SetOfassertion method checks the field value only includes all of the specified values. The field value must be an array or collection. Specified values can be included in the field value in any order.The following parameters are accepted:
Reasons include:
Examples:
","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Assert/#startswith","title":"StartsWith","text":"Rule 'Subset' {\n $Assert.SetOf($TargetObject, 'zones', @('1', '2', '3'))\n}\nThe
StartsWithassertion method checks the operand starts with the specified prefix. If the operand is an array of strings, only one string must start with the specified prefix. Optionally a case-sensitive compare can be used, however case is ignored by default.The following parameters are accepted:
Reasons include:
Examples:
","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Assert/#subset","title":"Subset","text":"Rule 'StartsWith' {\n $Assert.StartsWith($TargetObject, 'ResourceGroupName', 'rg-')\n $Assert.StartsWith($TargetObject, 'Name', @('st', 'diag'), $True)\n}\nThe
Subsetassertion method checks the field value includes all of the specified values. The field value may also contain additional values that are not specified in thevaluesparameter. The field value must be an array or collection. Specified values can be included in the field value in any order.The following parameters are accepted:
Reasons include:
Examples:
","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Assert/#version","title":"Version","text":"Rule 'Subset' {\n $Assert.Subset($TargetObject, 'logs', @('cluster-autoscaler', 'kube-apiserver', 'kube-scheduler'), $True, $True)\n}\nThe
Versionassertion method checks the field value is a valid semantic version. A constraint can optionally be provided to require the semantic version to be within a range.The following parameters are accepted:
The following are supported constraints:
An empty, null or
*constraint matches all valid semantic versions.Multiple constraints can be joined together:
By example:
Handling for prerelease versions:
By example:
Reasons include:
Examples:
","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Assert/#withinpath","title":"WithinPath","text":"Rule 'ValidVersion' {\n $Assert.Version($TargetObject, 'version')\n}\n\nRule 'MinimumVersion' {\n $Assert.Version($TargetObject, 'version', '>=1.2.3')\n}\n\nRule 'MinimumVersionWithPrerelease' {\n $Assert.Version($TargetObject, 'version', '>=1.2.3-0', $True)\n}\n\nRule 'MinimumVersionWithFlag' {\n $Assert.Version($TargetObject, 'version', '@pre >=1.2.3-0')\n}\nThe
WithinPathassertion method checks if the file path is within a required path. Checks use file system case-sensitivity rules by default.The following parameters are accepted:
Reasons include:
Examples:
","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Assert/#advanced-usage","title":"Advanced usage","text":"Rule 'WithinPath' {\n # Require the file to be within either policy/ or security/ sub-directories.\n $Assert.WithinPath($TargetObject, 'FullName', @('policy/', 'security/'));\n}\nThe
AssertResultobject returned from assertion methods:The following properties are available:
The following methods are available:
Use of
Completeis optional, uncompleted results are automatically completed after the rule has executed. Uncompleted results may return reasons out of sequence.Using these advanced methods is not supported in rule script pre-conditions.
In this example,
Completeis used to find the first field with an empty value.Rule 'Assert.HasFieldValue' {\n $Assert.HasFieldValue($TargetObject, 'Name').Complete() -and\n $Assert.HasFieldValue($TargetObject, 'Type').Complete() -and\n $Assert.HasFieldValue($TargetObject, 'Value').Complete()\n}\nIn this example, the built-in reason is replaced with a custom reason, and immediately returned. The reason text is automatically formatted with any parameters provided.
Rule 'Assert.HasCustomValue' {\n $Assert.\n HasDefaultValue($TargetObject, 'value', 'test').\n Reason('The field {0} is using a non-default value: {1}', 'value', $TargetObject.value)\n\n # With localized string\n $Assert.\n HasDefaultValue($TargetObject, 'value', 'test').\n Reason($LocalizedData.NonDefaultValue, 'value', $TargetObject.value)\n}\nIn this example, the built-in reason has a path prefix added to any reasons.
","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Assert/#downstream-issues","title":"Downstream issues","text":"Rule 'Assert.ChildHasFieldValue' {\n $items = @($TargetObject.items)\n for ($i = 0; $i -lt $items.Length; $i++) {\n $Assert.HasFieldValue($items[$i], 'Name').PathPrefix(\"items[$i]\")\n }\n}\nBefore PSRule performs analysis external tools or rules modules may have already performed analysis. Issues identified by downstream tools can be consumed by PSRule using the
_PSRule.issueproperty. If a_PSRuleproperty exists withissuesub-property PSRule will consumeissueas an array of issues.Each issue has the following properties:
To get issues for an object use the
GetorAnymethods.# Get an array of all issues for the current object.\n$PSRule.Issue.Get();\n\n# Get an array of issues of a specific type.\n$PSRule.Issue.Get('CustomIssue');\n\n# Return true of any issues exist.\n$PSRule.Issue.Any();\n\n# Return true of any issues of a specific type exist.\n$PSRule.Issue.Any('CustomIssue');\nFor example:
","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Assert/#authoring-assertion-methods","title":"Authoring assertion methods","text":"# Synopsis: Fail if the object has any 'PSRule.Rules.Azure.Parameter.Insecure' issues.\nRule 'IssueReportTest' {\n $Assert.Create($PSRule.Issue.Get('PSRule.Rules.Azure.Parameter.Insecure'));\n}\nThe following built-in helper methods are provided for working with
$Assertwhen authoring new assertion methods:The following built-in helper methods are provided for aggregating assertion results:
For example:
","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Assert/#links","title":"Links","text":"Rule 'Assert.HasFieldValue' {\n $Assert.AllOf(\n $Assert.HasFieldValue($TargetObject, 'Name'),\n $Assert.HasFieldValue($TargetObject, 'Type'),\n $Assert.HasFieldValue($TargetObject, 'Value')\n )\n}\nDescribes using the badge API with PSRule.
"},{"location":"concepts/PSRule/en-US/about_PSRule_Badges/#description","title":"Description","text":"PSRule executes rules to validate an object from input. When processing input it may be necessary to perform custom actions before or after rules execute. Conventions provide an extensibility point that can be shipped with or external to standard rules. The badge API can be used to create badges within a convention.
"},{"location":"concepts/PSRule/en-US/about_PSRule_Badges/#using-the-api","title":"Using the API","text":"PSRule provides the
$PSRulebuilt-in variable that exposes the badge API. By using the$PSRule.Badges.Createmethod you can create a standard or custom badge.The create method provides the following overloads:
// Create a badge for the worst case of an analyzed object.\nIBadge Create(InvokeResult result);\n\n// Create a badge for the worst case of all analyzed objects.\nIBadge Create(IEnumerable<InvokeResult> result);\n\n// Create a custom badge.\nIBadge Create(string title, BadgeType type, string label);\nA badge once created can be read as a string or written to disk with the following methods:
"},{"location":"concepts/PSRule/en-US/about_PSRule_Badges/#defining-conventions","title":"Defining conventions","text":"// Get the badge as SVG text content.\nstring ToSvg();\n\n// Write the SVG badge content directly to disk.\nvoid ToFile(string path);\nTo define a convention, add a
Export-PSRuleConventionblock within a.Rule.ps1file. The.Rule.ps1must be in an included path or module with-Pathor-Module.The
Export-PSRuleConventionblock works similar to theRuleblock. Each convention must have a unique name. Currently the badge API support creating badges in the-Endblock.For example:
# Synopsis: A convention that generates a badge for an aggregate result.\nExport-PSRuleConvention 'Local.Aggregate' -End {\n $PSRule.Badges.Create($PSRule.Output).ToFile('out/badges/aggregate.svg');\n}\n
"},{"location":"concepts/PSRule/en-US/about_PSRule_Badges/#using-conventions","title":"Using conventions","text":"# Synopsis: A convention that generates a custom badge.\nExport-PSRuleConvention 'Local.CustomBadge' -End {\n $PSRule.Badges.Create('PSRule', [PSRule.Badges.BadgeType]::Success, 'OK').ToFile('out/badges/custom.svg');\n}\nA convention can be included by using the
-Conventionparameter when executing a PSRule cmdlet. Alternatively, conventions can be included with options. To use a convention specify the name of the convention by name. For example:
"},{"location":"concepts/PSRule/en-US/about_PSRule_Badges/#links","title":"Links","text":"Invoke-PSRule -Convention 'Local.Aggregate';\nDescribes usage of baselines within PSRule.
"},{"location":"concepts/PSRule/en-US/about_PSRule_Baseline/#description","title":"Description","text":"PSRule lets you define a baseline. A baseline includes a set of rule and configuration options that are used for evaluating objects.
The following baseline options can be configured:
Baseline options can be:
YAML baseline specs are saved within a YAML file with a
.Rule.yamlor.Rule.ymlextension, for exampleBaseline.Rule.yaml.JSON baseline specs are saved within a file with a
.Rule.jsonor.Rule.jsoncextension, for exampleBaseline.Rule.json. Use.jsoncto view JSON with Comments in Visual Studio Code.To define a YAML baseline spec use the following structure:
---\n# Synopsis: <synopsis>\napiVersion: github.com/microsoft/PSRule/v1\nkind: Baseline\nmetadata:\n name: <name>\n annotations: { }\nspec:\n # One or more baseline options\n binding: { }\n rule: { }\n configuration: { }\nFor example:
---\n# Synopsis: This is an example baseline\napiVersion: github.com/microsoft/PSRule/v1\nkind: Baseline\nmetadata:\n name: Baseline1\nspec:\n binding:\n field:\n id:\n - ResourceId\n targetName:\n - Name\n - ResourceName\n - ResourceGroupName\n targetType:\n - ResourceType\n rule:\n include:\n - Rule1\n - Rule2\n configuration:\n allowedLocations:\n - 'Australia East'\n - 'Australia South East'\n\n---\n# Synopsis: This is an example baseline\napiVersion: github.com/microsoft/PSRule/v1\nkind: Baseline\nmetadata:\n name: Baseline2\nspec:\n binding:\n targetName:\n - Name\n - ResourceName\n - ResourceGroupName\n targetType:\n - ResourceType\n rule:\n include:\n - Rule1\n - Rule3\n configuration:\n allowedLocations:\n - 'Australia East'\nTo define a JSON baseline spec use the following structure:
[\n {\n // Synopsis: <synopsis>\n \"apiVersion\": \"github.com/microsoft/PSRule/v1\",\n \"kind\": \"Baseline\",\n \"metadata\": {\n \"name\": \"<name>\",\n \"annotations\": {}\n },\n \"spec\": {\n \"binding\": {},\n \"rule\": {},\n \"configuration\": {}\n }\n }\n]\nFor example:
"},{"location":"concepts/PSRule/en-US/about_PSRule_Baseline/#baseline-scopes","title":"Baseline scopes","text":"[\n {\n // Synopsis: This is an example baseline\n \"apiVersion\": \"github.com/microsoft/PSRule/v1\",\n \"kind\": \"Baseline\",\n \"metadata\": {\n \"name\": \"Baseline1\"\n },\n \"spec\": {\n \"binding\": {\n \"field\": {\n \"id\": [\n \"ResourceId\"\n ]\n },\n \"targetName\": [\n \"Name\",\n \"ResourceName\",\n \"ResourceGroupName\"\n ],\n \"targetType\": [\n \"ResourceType\"\n ]\n },\n \"rule\": {\n \"include\": [\n \"Rule1\",\n \"Rule2\"\n ]\n },\n \"configuration\": {\n \"allowedLocations\": [\n \"Australia East\",\n \"Australia South East\"\n ]\n }\n }\n },\n {\n // Synopsis: This is an example baseline\n \"apiVersion\": \"github.com/microsoft/PSRule/v1\",\n \"kind\": \"Baseline\",\n \"metadata\": {\n \"name\": \"Baseline2\"\n },\n \"spec\": {\n \"binding\": {\n \"targetName\": [\n \"Name\",\n \"ResourceName\",\n \"ResourceGroupName\"\n ],\n \"targetType\": [\n \"ResourceType\"\n ]\n },\n \"rule\": {\n \"include\": [\n \"Rule1\",\n \"Rule3\"\n ]\n },\n \"configuration\": {\n \"allowedLocations\": [\n \"Australia East\"\n ]\n }\n }\n }\n]\nWhen baseline options are set, PSRule uses the following order to determine precedence.
After precedence is determined, baselines are merged and null values are ignored, such that:
"},{"location":"concepts/PSRule/en-US/about_PSRule_Baseline/#annotations","title":"Annotations","text":"Additional baseline annotations can be provided as key/ value pairs. Annotations can be used to provide additional information that is available in
Get-PSRuleBaselineoutput.The following reserved annotation exists:
YAML example:
---\n# Synopsis: This is an example baseline that is obsolete\napiVersion: github.com/microsoft/PSRule/v1\nkind: Baseline\nmetadata:\n name: ObsoleteBaseline\n annotations:\n obsolete: true\nspec: { }\nJSON example:
"},{"location":"concepts/PSRule/en-US/about_PSRule_Baseline/#examples","title":"Examples","text":""},{"location":"concepts/PSRule/en-US/about_PSRule_Baseline/#example-baselineruleyaml","title":"Example Baseline.Rule.yaml","text":"[\n {\n // Synopsis: This is an example baseline that is obsolete\n \"apiVersion\": \"github.com/microsoft/PSRule/v1\",\n \"kind\": \"Baseline\",\n \"metadata\": {\n \"name\": \"ObsoleteBaseline\",\n \"annotations\": {\n \"obsolete\": true\n }\n },\n \"spec\": {}\n }\n]\n
"},{"location":"concepts/PSRule/en-US/about_PSRule_Baseline/#example-baselinerulejson","title":"Example Baseline.Rule.json","text":"# Example Baseline.Rule.yaml\n\n---\n# Synopsis: This is an example baseline\napiVersion: github.com/microsoft/PSRule/v1\nkind: Baseline\nmetadata:\n name: TestBaseline1\nspec:\n binding:\n targetName:\n - AlternateName\n targetType:\n - kind\n rule:\n include:\n - 'WithBaseline'\n configuration:\n key1: value1\n\n---\n# Synopsis: This is an example baseline\napiVersion: github.com/microsoft/PSRule/v1\nkind: Baseline\nmetadata:\n name: TestBaseline2\nspec:\n binding:\n targetName:\n - AlternateName\n targetType:\n - kind\n rule:\n include:\n - 'WithBaseline'\n configuration:\n key1: value1\n
"},{"location":"concepts/PSRule/en-US/about_PSRule_Conventions/","title":"Conventions","text":"// Example Baseline.Rule.json\n\n[\n {\n // Synopsis: This is an example baseline\n \"apiVersion\": \"github.com/microsoft/PSRule/v1\",\n \"kind\": \"Baseline\",\n \"metadata\": {\n \"name\": \"TestBaseline1\"\n },\n \"spec\": {\n \"binding\": {\n \"targetName\": [\n \"AlternateName\"\n ],\n \"targetType\": [\n \"kind\"\n ]\n },\n \"rule\": {\n \"include\": [\n \"WithBaseline\"\n ]\n },\n \"configuration\": {\n \"key1\": \"value1\"\n }\n }\n },\n {\n // Synopsis: This is an example baseline\n \"apiVersion\": \"github.com/microsoft/PSRule/v1\",\n \"kind\": \"Baseline\",\n \"metadata\": {\n \"name\": \"TestBaseline2\"\n },\n \"spec\": {\n \"binding\": {\n \"targetName\": [\n \"AlternateName\"\n ],\n \"targetType\": [\n \"kind\"\n ]\n },\n \"rule\": {\n \"include\": [\n \"WithBaseline\"\n ]\n },\n \"configuration\": {\n \"key1\": \"value1\"\n }\n }\n }\n]\nDescribes PSRule Conventions including how to use and author them.
"},{"location":"concepts/PSRule/en-US/about_PSRule_Conventions/#description","title":"Description","text":"PSRule executes rules to validate an object from input. When processing input it may be necessary to perform custom actions before or after rules execute. Conventions provide an extensibility point that can be shipped with or external to standard rules. Each convention, hooks into one or more places within the pipeline.
"},{"location":"concepts/PSRule/en-US/about_PSRule_Conventions/#using-conventions","title":"Using conventions","text":"A convention can be included by using the
-Conventionparameter when executing a PSRule cmdlet. Alternatively, conventions can be included with options. To use a convention specify the name of the convention by name. For example:Invoke-PSRule -Convention 'ExampleConvention';\nIf multiple conventions are specified in an array, all are executed in they are specified. As a result, the convention specified last may override state set by earlier conventions.
"},{"location":"concepts/PSRule/en-US/about_PSRule_Conventions/#defining-conventions","title":"Defining conventions","text":"Assert-PSRule -Convention 'ExampleConvention1', 'ExampleConvention2';\nTo define a convention, add a
Export-PSRuleConventionblock within a.Rule.ps1file. The.Rule.ps1must be in an included path or module with-Pathor-Module.The
Export-PSRuleConventionblock works similar to theRuleblock. Each convention must have a unique name. For example:
"},{"location":"concepts/PSRule/en-US/about_PSRule_Conventions/#initialize-begin-process-end-blocks","title":"Initialize Begin Process End blocks","text":"# Synopsis: An example convention.\nExport-PSRuleConvention 'ExampleConvention' {\n # Add code here\n}\nConventions define four executable blocks
Initialize,Begin,Process,Endsimilar to a PowerShell function. Each block is injected in a different part of the pipeline as follows:Convention block limitations:
By default, the
Processblock used. For example:# Synopsis: The default { } executes the process block\nExport-PSRuleConvention 'ExampleConvention' {\n # Process block\n}\n\n# Synopsis: With optional -Process parameter name\nExport-PSRuleConvention 'ExampleConvention' -Process {\n # Process block\n}\nTo use
Initialize,Begin, orEndexplicitly add these blocks. For example:
"},{"location":"concepts/PSRule/en-US/about_PSRule_Conventions/#including-with-options","title":"Including with options","text":"Export-PSRuleConvention 'ExampleConvention' -Process {\n # Process block\n} -Begin {\n # Begin block\n} -End {\n # End block\n} -Initialize {\n # Initialize block\n}\nConventions can be included by name within options in addition to using the
ps-rule.yaml-Conventionparameter. To specify a convention within YAML options use the following:
"},{"location":"concepts/PSRule/en-US/about_PSRule_Conventions/#using-within-modules","title":"Using within modules","text":"convention:\n include:\n - 'ExampleConvention1'\n - 'ExampleConvention2'\nConventions can be shipped within a module using the same packaging and distribution process as rules. Additionally, conventions shipped within a module can be automatically included. By default, PSRule does not include conventions shipped within a module. To use a convention included in a module use the
-Conventionparameter or options configuration.A module can automatically include a convention by specifying the convention by name in module configuration. For example:
Config.Rule.yaml
"},{"location":"concepts/PSRule/en-US/about_PSRule_Conventions/#execution-order","title":"Execution order","text":"---\napiVersion: github.com/microsoft/PSRule/v1\nkind: ModuleConfig\nmetadata:\n name: ExampleModule\nspec:\n convention:\n include:\n - 'ExampleConvention1'\n - 'ExampleConvention2'\nConventions are executed in the order they are specified. This is true for
Initialize,Begin,Process, andEndblocks. i.e. In the following exampleExampleConvention1is execute beforeExampleConvention2.Assert-PSRule -Convention 'ExampleConvention1', 'ExampleConvention2';\nWhen conventions are specified from multiple locations PSRule orders conventions as follows:
Describes usage of documentation within PSRule.
"},{"location":"concepts/PSRule/en-US/about_PSRule_Docs/#description","title":"Description","text":"PSRule includes a built-in documentation system that provide culture specific help and metadata for resources. Documentation is composed of markdown files that can be optionally shipped with a module.
When markdown documentation is defined, this content will be used instead of inline synopsis comments. Markdown documentation is supported for rules and suppression groups.
"},{"location":"concepts/PSRule/en-US/about_PSRule_Docs/#getting-documentation","title":"Getting documentation","text":"To get documentation for a rule use the
Get-PSRuleHelpcmdlet.For example:
Get-PSRuleHelp <rule-name>\nEach rule can include the following documentation:
See cmdlet help for detailed information on the
"},{"location":"concepts/PSRule/en-US/about_PSRule_Docs/#online-help","title":"Online help","text":"Get-PSRuleHelpcmdlet.Rule documentation may optionally include a link to an online version. When included, the
-Onlineparameter can be used to open the online version in the default web browser.For example:
"},{"location":"concepts/PSRule/en-US/about_PSRule_Docs/#creating-documentation-for-rules","title":"Creating documentation for rules","text":"Get-PSRuleHelp <rule-name> -Online\nRule documentation is composed of markdown files, one per rule. When creating rules for more then one culture, a separate markdown file is created per rule per culture.
The markdown files for each rule is automatically discovered based on naming convention.
Markdown is saved in a file with the same filename as the rule name with the
.mdextension. The file name should match the same case exactly, with a lower case extension.As an example, the
storageAccounts.UseHttps.mdmarkdown file would be created.# Synopsis: Configure storage accounts to only accept encrypted traffic i.e. HTTPS/SMB\nRule 'storageAccounts.UseHttps' -If { ResourceType 'Microsoft.Storage/storageAccounts' } {\n Recommend 'Storage accounts should only allow secure traffic'\n\n $TargetObject.Properties.supportsHttpsTrafficOnly\n}\nThe markdown of each file uses following structure.
---\n{{ Annotations }}\n---\n\n# {{ Name of rule }}\n\n\n\n{{ A brief summary of the rule }}\n\n## Description\n\n{{ A detailed description of the rule }}\n\n## Recommendation\n\n{{ A detailed explanation of the steps required to pass the rule }}\n\n## Notes\n\n{{ Additional information or configuration options }}\n\n## Links\n\n{{ Links to external references }}\nOptionally, one or more annotations formatted as YAML key value pairs can be included. i.e.
severity: CriticalAdditional sections such as
"},{"location":"concepts/PSRule/en-US/about_PSRule_Docs/#creating-documentation-for-suppression-groups","title":"Creating documentation for suppression groups","text":"EXAMPLEScan be included although are not exposed withGet-PSRuleHelp.Suppression groups support documentation similar to rules that allows a synopsis to be defined. Other sections can be added to the markdown content, but are ignored. Set the synopsis in markdown to allow a culture specific message to be displayed.
The markdown of each file uses following structure.
"},{"location":"concepts/PSRule/en-US/about_PSRule_Docs/#storing-markdown-files","title":"Storing markdown files","text":"---\n{{ Annotations }}\n---\n\n# {{ Name of suppression group }}\n\n\n\n{{ A brief summary of the suppression group }}\nThe location PSRule uses to find markdown documentation depends on how the rules/ resources are packaged. In each case, documentation will be in a culture
/<culture>/specific subdirectory. Resources can be either shipped as part of a module, or standalone.The
"},{"location":"concepts/PSRule/en-US/about_PSRule_Docs/#links","title":"Links","text":"<culture>subdirectory will be the current culture that PowerShell is executed under. To determine the current culture use(Get-Culture).Name. Alternatively, the culture can set by using the-Cultureparameter of PSRule cmdlets.Describes PSRule expressions and how to use them.
","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Expressions/#description","title":"Description","text":"PSRule expressions are used within YAML-based rules or selectors to evaluate an object. Expressions are comprised of nested conditions, operators, and comparison properties.
The following conditions are available:
The following operators are available:
The following comparison properties are available:
The
allOfoperator is used to require all nested expressions to match. When any nested expression does not match,allOfdoes not match. This is similar to a logical and operation.Additionally sub-selectors can be used to modify the
allOfoperator. Sub-selectors allow filtering and looping through arrays of objects before theallOfoperator is applied. See sub-selectors for more information.Syntax:
allOf: <expression[]>\nFor example:
","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Expressions/#anyof","title":"AnyOf","text":"---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Rule\nmetadata:\n name: 'ExampleAllOf'\nspec:\n condition:\n allOf:\n # Both Name and Description must exist.\n - field: 'Name'\n exists: true\n - field: 'Description'\n exists: true\n\n---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Selector\nmetadata:\n name: 'ExampleAllOf'\nspec:\n if:\n allOf:\n # Both Name and Description must exist.\n - field: 'Name'\n exists: true\n - field: 'Description'\n exists: true\nThe
anyOfoperator is used to require one or more nested expressions to match. When any nested expression matches,allOfmatches. This is similar to a logical or operation.Additionally sub-selectors can be used to modify the
anyOfoperator. Sub-selectors allow filtering and looping through arrays of objects before theanyOfoperator is applied. See sub-selectors for more information.Syntax:
anyOf: <expression[]>\nFor example:
","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Expressions/#apiversion","title":"APIVersion","text":"---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Rule\nmetadata:\n name: 'ExampleAnyOf'\nspec:\n condition:\n anyOf:\n # Name and/ or AlternativeName must exist.\n - field: 'Name'\n exists: true\n - field: 'AlternativeName'\n exists: true\n\n---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Selector\nmetadata:\n name: 'ExampleAnyOf'\nspec:\n if:\n anyOf:\n # Name and/ or AlternativeName must exist.\n - field: 'Name'\n exists: true\n - field: 'AlternativeName'\n exists: true\nThe
apiVersioncondition determines if the operand is a valid date version. A constraint can optionally be provided to require the date version to be within a range. Supported version constraints for expression are the same as the$Assert.APIVersionassertion helper.Syntax:
apiVersion: <string>\nincludePrerelease: <bool>\nFor example:
","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Expressions/#contains","title":"Contains","text":"---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Rule\nmetadata:\n name: 'ExampleAPIVersion'\nspec:\n condition:\n field: 'engine.apiVersion'\n apiVersion: '>=2015-10-01'\n\n---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Selector\nmetadata:\n name: 'ExampleAnyAPIVersion'\nspec:\n if:\n field: 'engine.apiVersion'\n apiVersion: ''\n\n---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Selector\nmetadata:\n name: 'ExampleAPIVersionIncludingPrerelease'\nspec:\n if:\n field: 'engine.apiVersion'\n apiVersion: '>=2015-10-01'\n includePrerelease: true\nThe
containscondition can be used to determine if the operand contains a specified sub-string. One or more strings to compare can be specified.Syntax:
contains: <string | array>\ncaseSensitive: <boolean>\nconvert: <boolean>\nFor example:
","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Expressions/#count","title":"Count","text":"---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Rule\nmetadata:\n name: 'ExampleContains'\nspec:\n condition:\n anyOf:\n - field: 'url'\n contains: '/azure/'\n - field: 'url'\n contains:\n - 'github.io'\n - 'github.com'\n\n---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Selector\nmetadata:\n name: 'ExampleContains'\nspec:\n if:\n anyOf:\n - field: 'url'\n contains: '/azure/'\n - field: 'url'\n contains:\n - 'github.io'\n - 'github.com'\nThe
countcondition is used to determine if the operand contains a specified number of items.Syntax:
count: <int>\nFor example:
","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Expressions/#equals","title":"Equals","text":"---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Rule\nmetadata:\n name: 'ExampleCount'\nspec:\n condition:\n field: 'items'\n count: 2\n\n---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Selector\nmetadata:\n name: 'ExampleCount'\nspec:\n if:\n field: 'items'\n count: 2\nThe
equalscondition can be used to compare if the operand is equal to a supplied value.Syntax:
equals: <string | int | bool>\ncaseSensitive: <boolean>\nconvert: <boolean>\nFor example:
","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Expressions/#endswith","title":"EndsWith","text":"---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Rule\nmetadata:\n name: 'ExampleEquals'\nspec:\n condition:\n field: 'Name'\n equals: 'TargetObject1'\n\n---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Selector\nmetadata:\n name: 'ExampleEquals'\nspec:\n if:\n field: 'Name'\n equals: 'TargetObject1'\nThe
endsWithcondition can be used to determine if the operand ends with a specified string. One or more strings to compare can be specified.Syntax:
endsWith: <string | array>\ncaseSensitive: <boolean>\nconvert: <boolean>\nFor example:
","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Expressions/#exists","title":"Exists","text":"---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Rule\nmetadata:\n name: 'ExampleEndsWith'\nspec:\n condition:\n anyOf:\n - field: 'hostname'\n endsWith: '.com'\n - field: 'hostname'\n endsWith:\n - '.com.au'\n - '.com'\n\n---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Selector\nmetadata:\n name: 'ExampleEndsWith'\nspec:\n if:\n anyOf:\n - field: 'hostname'\n endsWith: '.com'\n - field: 'hostname'\n endsWith:\n - '.com.au'\n - '.com'\nThe
existscondition determines if the specified field exists.Syntax:
exists: <bool>\nFor example:
","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Expressions/#field","title":"Field","text":"---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Rule\nmetadata:\n name: 'ExampleExists'\nspec:\n condition:\n field: 'Name'\n exists: true\n\n---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Selector\nmetadata:\n name: 'ExampleExists'\nspec:\n if:\n field: 'Name'\n exists: true\nThe comparison property
fieldis used with a condition to determine field of the object to evaluate. A field can be:Syntax:
field: <string>\nFor example:
","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Expressions/#greater","title":"Greater","text":"---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Rule\nmetadata:\n name: 'ExampleField'\nspec:\n condition:\n field: 'Properties.securityRules[0].name'\n exists: true\n\n---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Selector\nmetadata:\n name: 'ExampleField'\nspec:\n if:\n field: 'Properties.securityRules[0].name'\n exists: true\nThe
greatercondition determines if the operand is greater than a supplied value. The field value can either be an integer, float, array, or string.When the field value is:
Syntax:
greater: <int>\nconvert: <boolean>\nFor example:
","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Expressions/#greaterorequals","title":"GreaterOrEquals","text":"---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Rule\nmetadata:\n name: 'ExampleGreater'\nspec:\n condition:\n field: 'Name'\n greater: 3\n\n---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Selector\nmetadata:\n name: 'ExampleGreater'\nspec:\n if:\n field: 'Name'\n greater: 3\nThe
greaterOrEqualscondition determines if the operand is greater or equal to the supplied value. The field value can either be an integer, float, array, or string.When the field value is:
Syntax:
greaterOrEquals: <int>\nconvert: <boolean>\nFor example:
","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Expressions/#hasdefault","title":"HasDefault","text":"---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Rule\nmetadata:\n name: 'ExampleGreaterOrEquals'\nspec:\n condition:\n field: 'Name'\n greaterOrEquals: 3\n\n---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Selector\nmetadata:\n name: 'ExampleGreaterOrEquals'\nspec:\n if:\n field: 'Name'\n greaterOrEquals: 3\nThe
hasDefaultcondition determines if the field exists that it is set to the specified value. If the field does not exist, the condition will returntrue.The following properties are accepted:
Syntax:
hasDefault: <string | int | bool>\ncaseSensitive: <bool>\nFor example:
","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Expressions/#hasschema","title":"HasSchema","text":"---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Rule\nmetadata:\n name: 'ExampleHasDefault'\nspec:\n condition:\n field: 'enabled'\n hasDefault: true\n\n---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Selector\nmetadata:\n name: 'ExampleHasDefault'\nspec:\n if:\n field: 'enabled'\n hasDefault: true\nThe
hasSchemacondition determines if the operand has a$schemaproperty defined. If the$schemaproperty is defined, it must match one of the specified schemas. If a trailing#is specified it is ignored.The following properties are accepted:
Syntax:
hasSchema: <array>\ncaseSensitive: <bool>\nignoreScheme: <bool>\nFor example:
","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Expressions/#hasvalue","title":"HasValue","text":"---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Rule\nmetadata:\n name: 'ExampleHasSchema'\nspec:\n condition:\n field: '.'\n hasSchema:\n - https://schema.management.azure.com/schemas/2019-04-01/deploymentParameters.json#\n\n---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Selector\nmetadata:\n name: 'ExampleHasSchema'\nspec:\n if:\n field: '.'\n hasSchema:\n - https://schema.management.azure.com/schemas/2019-04-01/deploymentParameters.json#\n - https://schema.management.azure.com/schemas/2015-01-01/deploymentParameters.json#\n ignoreScheme: true\n\n---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Selector\nmetadata:\n name: 'ExampleHasAnySchema'\nspec:\n if:\n field: '.'\n hasSchema: []\nThe
hasValuecondition determines if the field exists and has a non-empty value.Syntax:
hasValue: <bool>\nFor example:
","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Expressions/#in","title":"In","text":"---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Rule\nmetadata:\n name: 'ExampleHasValue'\nspec:\n condition:\n field: 'Name'\n hasValue: true\n\n---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Selector\nmetadata:\n name: 'ExampleHasValue'\nspec:\n if:\n field: 'Name'\n hasValue: true\nThe
incondition can be used to compare if a field contains one of the specified values.Syntax:
in: <array>\nFor example:
","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Expressions/#islower","title":"IsLower","text":"---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Rule\nmetadata:\n name: 'ExampleIn'\nspec:\n condition:\n field: 'Name'\n in:\n - 'Value1'\n - 'Value2'\n\n---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Selector\nmetadata:\n name: 'ExampleIn'\nspec:\n if:\n field: 'Name'\n in:\n - 'Value1'\n - 'Value2'\nThe
isLowercondition determines if the operand is a lowercase string.Syntax:
isLower: <bool>\nFor example:
","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Expressions/#isstring","title":"IsString","text":"---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Rule\nmetadata:\n name: 'ExampleIsLower'\nspec:\n condition:\n field: 'Name'\n isLower: true\n\n---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Selector\nmetadata:\n name: 'ExampleIsLower'\nspec:\n if:\n field: 'Name'\n isLower: true\nThe
isStringcondition determines if the operand is a string or other type.Syntax:
isString: <bool>\nFor example:
","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Expressions/#isarray","title":"IsArray","text":"---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Rule\nmetadata:\n name: 'ExampleIsString'\nspec:\n condition:\n field: 'Name'\n isString: true\n\n---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Selector\nmetadata:\n name: 'ExampleIsString'\nspec:\n if:\n field: 'Name'\n isString: true\nThe
isArraycondition determines if the operand is an array or other type.Syntax:
isArray: <bool>\nFor example:
","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Expressions/#isboolean","title":"IsBoolean","text":"---\n# Synopsis: Using isArray\napiVersion: github.com/microsoft/PSRule/v1\nkind: Selector\nmetadata:\n name: IsArrayExample\nspec:\n if:\n field: 'Value'\n isArray: true\nThe
isBooleancondition determines if the operand is a boolean or other type.isBoolean: <bool>\nconvert: <bool>\nFor example:
","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Expressions/#isdatetime","title":"IsDateTime","text":"---\n# Synopsis: Using isBoolean\napiVersion: github.com/microsoft/PSRule/v1\nkind: Selector\nmetadata:\n name: IsBooleanExample\nspec:\n if:\n field: 'Value'\n isBoolean: true\n\n---\n# Synopsis: Using isBoolean with conversion\napiVersion: github.com/microsoft/PSRule/v1\nkind: Selector\nmetadata:\n name: IsBooleanExampleWithConversion\nspec:\n if:\n field: 'Value'\n isBoolean: true\n convert: true\nThe
isDateTimecondition determines if the operand is a datetime or other type.isDateTime: <bool>\nconvert: <bool>\nFor example:
","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Expressions/#isinteger","title":"IsInteger","text":"---\n# Synopsis: Using isDateTime\napiVersion: github.com/microsoft/PSRule/v1\nkind: Selector\nmetadata:\n name: IsDateTimeExample\nspec:\n if:\n field: 'Value'\n isDateTime: true\n\n---\n# Synopsis: Using isDateTime with conversion\napiVersion: github.com/microsoft/PSRule/v1\nkind: Selector\nmetadata:\n name: IsDateTimeExampleWithConversion\nspec:\n if:\n field: 'Value'\n isDateTime: true\n convert: true\nThe
isIntegercondition determines if the operand is a an integer or other type. The following types are considered integer typesint,long,byte.isInteger: <bool>\nconvert: <bool>\nFor example:
","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Expressions/#isnumeric","title":"IsNumeric","text":"---\n# Synopsis: Using isInteger\napiVersion: github.com/microsoft/PSRule/v1\nkind: Selector\nmetadata:\n name: IsIntegerExample\nspec:\n if:\n field: 'Value'\n isInteger: true\n\n---\n# Synopsis: Using isInteger with conversion\napiVersion: github.com/microsoft/PSRule/v1\nkind: Selector\nmetadata:\n name: IsIntegerExampleWithConversion\nspec:\n if:\n field: 'Value'\n isInteger: true\n convert: true\nThe
isNumericcondition determines if the operand is a a numeric or other type. The following types are considered numeric typesint,long,float,byte,double.isNumeric: <bool>\nconvert: <bool>\nFor example:
","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Expressions/#isupper","title":"IsUpper","text":"---\n# Synopsis: Using isNumeric\napiVersion: github.com/microsoft/PSRule/v1\nkind: Selector\nmetadata:\n name: IsNumericExample\nspec:\n if:\n field: 'Value'\n isNumeric: true\n\n---\n# Synopsis: Using isNumeric with conversion\napiVersion: github.com/microsoft/PSRule/v1\nkind: Selector\nmetadata:\n name: IsNumercExampleWithConversion\nspec:\n if:\n field: 'Value'\n isNumeric: true\n convert: true\nThe
isUppercondition determines if the operand is an uppercase string.Syntax:
isUpper: <bool>\nFor example:
","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Expressions/#less","title":"Less","text":"---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Rule\nmetadata:\n name: 'ExampleIsUpper'\nspec:\n condition:\n field: 'Name'\n isUpper: true\n\n---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Selector\nmetadata:\n name: 'ExampleIsUpper'\nspec:\n if:\n field: 'Name'\n isUpper: true\nThe
lesscondition determines if the operand is less than a supplied value. The field value can either be an integer, float, array, or string.When the field value is:
Syntax:
less: <int>\nconvert: <boolean>\nFor example:
","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Expressions/#lessorequals","title":"LessOrEquals","text":"---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Rule\nmetadata:\n name: 'ExampleLess'\nspec:\n condition:\n field: 'Name'\n less: 3\n\n---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Selector\nmetadata:\n name: 'ExampleLess'\nspec:\n if:\n field: 'Name'\n less: 3\nThe
lessOrEqualscondition determines if the operand is less or equal to the supplied value. The field value can either be an integer, float, array, or string.When the field value is:
Syntax:
lessOrEquals: <int>\nconvert: <boolean>\nFor example:
","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Expressions/#like","title":"Like","text":"---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Rule\nmetadata:\n name: 'ExampleLessOrEquals'\nspec:\n condition:\n field: 'Name'\n lessOrEquals: 3\n\n---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Selector\nmetadata:\n name: 'ExampleLessOrEquals'\nspec:\n if:\n field: 'Name'\n lessOrEquals: 3\nThe
likecondition can be used to determine if the operand matches a wildcard pattern. One or more patterns to compare can be specified.Syntax:
like: <string | array>\ncaseSensitive: <boolean>\nconvert: <boolean>\nFor example:
","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Expressions/#match","title":"Match","text":"---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Rule\nmetadata:\n name: 'ExampleLike'\nspec:\n condition:\n anyOf:\n - field: 'url'\n like: 'http://*'\n - field: 'url'\n like:\n - 'http://*'\n - 'https://*'\n\n---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Selector\nmetadata:\n name: 'ExampleLike'\nspec:\n if:\n anyOf:\n - field: 'url'\n like: 'http://*'\n - field: 'url'\n like:\n - 'http://*'\n - 'https://*'\nThe
matchcondition can be used to compare if a field matches a supplied regular expression.Syntax:
match: <string>\ncaseSensitive: <boolean>\nFor example:
","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Expressions/#name","title":"Name","text":"---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Rule\nmetadata:\n name: 'ExampleMatch'\nspec:\n condition:\n field: 'Name'\n match: '$(abc|efg)$'\n\n---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Selector\nmetadata:\n name: 'ExampleMatch'\nspec:\n if:\n field: 'Name'\n match: '$(abc|efg)$'\nThe comparison property
nameis used with a condition to evaluate the target name of the object. Thenameproperty must be set to.. Any other value will cause the condition to evaluate tofalse.Syntax:
name: '.'\nFor example:
","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Expressions/#not","title":"Not","text":"---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Rule\nmetadata:\n name: 'ExampleName'\nspec:\n condition:\n name: '.'\n equals: 'TargetObject1'\n\n---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Selector\nmetadata:\n name: 'ExampleName'\nspec:\n if:\n name: '.'\n in:\n - 'TargetObject1'\n - 'TargetObject2'\nThe
anyoperator is used to invert the result of the nested expression. When a nested expression matches,notdoes not match. When a nested expression does not match,notmatches.Syntax:
not: <expression>\nFor example:
","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Expressions/#notcontains","title":"NotContains","text":"---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Rule\nmetadata:\n name: 'ExampleNot'\nspec:\n condition:\n not:\n # The AlternativeName field must not exist.\n field: 'AlternativeName'\n exists: true\n\n---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Selector\nmetadata:\n name: 'ExampleNot'\nspec:\n if:\n not:\n # The AlternativeName field must not exist.\n field: 'AlternativeName'\n exists: true\nThe
notContainscondition can be used to determine if the operand contains a specified sub-string. This condition fails when any of the specified sub-strings are found in the operand. One or more strings to compare can be specified.Syntax:
notContains: <string | array>\ncaseSensitive: <boolean>\nconvert: <boolean>\nFor example:
","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Expressions/#notcount","title":"NotCount","text":"---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Rule\nmetadata:\n name: 'ExampleNotContains'\nspec:\n condition:\n anyOf:\n - field: 'url'\n notContains: '/azure/'\n - field: 'url'\n notContains:\n - 'github.io'\n - 'github.com'\n\n---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Selector\nmetadata:\n name: 'ExampleNotContains'\nspec:\n if:\n anyOf:\n - field: 'url'\n notContains: '/azure/'\n - field: 'url'\n notContains:\n - 'github.io'\n - 'github.com'\nThe
notCountcondition is used to determine if the operand does not contain a specified number of items.Syntax:
notCount: <int>\nFor example:
","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Expressions/#notendswith","title":"NotEndsWith","text":"---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Rule\nmetadata:\n name: 'ExampleNotCount'\nspec:\n condition:\n field: 'items'\n notCount: 2\n\n---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Selector\nmetadata:\n name: 'ExampleNotCount'\nspec:\n if:\n field: 'items'\n notCount: 2\nThe
notEndsWithcondition can be used to determine if the operand ends with a specified string. This condition fails when any of the specified sub-strings are found at the end of the operand. One or more strings to compare can be specified.Syntax:
notEndsWith: <string | array>\ncaseSensitive: <boolean>\nconvert: <boolean>\nFor example:
","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Expressions/#notequals","title":"NotEquals","text":"---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Rule\nmetadata:\n name: 'ExampleNotEndsWith'\nspec:\n condition:\n anyOf:\n - field: 'hostname'\n notEndsWith: '.com'\n - field: 'hostname'\n notEndsWith:\n - '.com.au'\n - '.com'\n\n---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Selector\nmetadata:\n name: 'ExampleNotEndsWith'\nspec:\n if:\n anyOf:\n - field: 'hostname'\n notEndsWith: '.com'\n - field: 'hostname'\n notEndsWith:\n - '.com.au'\n - '.com'\nThe
notEqualscondition can be used to compare if a field is equal to a supplied value.Syntax:
notEquals: <string | int | bool>\ncaseSensitive: <boolean>\nconvert: <boolean>\nFor example:
","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Expressions/#notin","title":"NotIn","text":"---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Rule\nmetadata:\n name: 'ExampleNotEquals'\nspec:\n condition:\n field: 'Name'\n notEquals: 'TargetObject1'\n\n---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Selector\nmetadata:\n name: 'ExampleNotEquals'\nspec:\n if:\n field: 'Name'\n notEquals: 'TargetObject1'\nThe
notIncondition can be used to compare if a field does not contains one of the specified values.Syntax:
notIn: <array>\nFor example:
","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Expressions/#notlike","title":"NotLike","text":"---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Rule\nmetadata:\n name: 'ExampleNotIn'\nspec:\n condition:\n field: 'Name'\n notIn:\n - 'Value1'\n - 'Value2'\n\n---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Selector\nmetadata:\n name: 'ExampleNotIn'\nspec:\n if:\n field: 'Name'\n notIn:\n - 'Value1'\n - 'Value2'\nThe
notLikecondition can be used to determine if the operand matches a wildcard pattern. This condition fails when any of the specified patterns match the operand. One or more patterns to compare can be specified.Syntax:
notLike: <string | array>\ncaseSensitive: <boolean>\nconvert: <boolean>\nFor example:
","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Expressions/#notmatch","title":"NotMatch","text":"---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Rule\nmetadata:\n name: 'ExampleNotLike'\nspec:\n condition:\n anyOf:\n - field: 'url'\n notLike: 'http://*'\n - field: 'url'\n notLike:\n - 'http://'\n - 'https://'\n\n---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Selector\nmetadata:\n name: 'ExampleNotLike'\nspec:\n if:\n anyOf:\n - field: 'url'\n notLike: 'http://*'\n - field: 'url'\n notLike:\n - 'http://'\n - 'https://'\nThe
notMatchcondition can be used to compare if a field does not matches a supplied regular expression.Syntax:
notMatch: <string>\ncaseSensitive: <boolean>\nFor example:
","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Expressions/#notstartswith","title":"NotStartsWith","text":"---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Rule\nmetadata:\n name: 'ExampleNotMatch'\nspec:\n condition:\n field: 'Name'\n notMatch: '$(abc|efg)$'\n\n---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Selector\nmetadata:\n name: 'ExampleNotMatch'\nspec:\n if:\n field: 'Name'\n notMatch: '$(abc|efg)$'\nThe
notStartsWithcondition can be used to determine if the operand starts with a specified string. This condition fails when any of the specified sub-strings are found at the start of the operand. One or more strings to compare can be specified.Syntax:
notStartsWith: <string | array>\ncaseSensitive: <boolean>\nconvert: <boolean>\nFor example:
","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Expressions/#notwithinpath","title":"NotWithinPath","text":"---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Rule\nmetadata:\n name: 'ExampleNotStartsWith'\nspec:\n condition:\n anyOf:\n - field: 'url'\n notStartsWith: 'http'\n - field: 'url'\n notStartsWith:\n - 'http://'\n - 'https://'\n\n---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Selector\nmetadata:\n name: 'ExampleNotStartsWith'\nspec:\n if:\n anyOf:\n - field: 'url'\n notStartsWith: 'http'\n - field: 'url'\n notStartsWith:\n - 'http://'\n - 'https://'\nThe
notWithinPathcondition determines if a file path is not within a required path.If the path is not within the required path, the condition will return
true. If the path is within the required path, the condition will returnfalse.The following properties are accepted:
Syntax:
notWithinPath: <array>\ncaseSensitive: <boolean>\nFor example:
","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Expressions/#scope","title":"Scope","text":"---\n# Synopsis: Test notWithinPath with source\napiVersion: github.com/microsoft/PSRule/v1\nkind: Selector\nmetadata:\n name: YamlSourceNotWithinPath\nspec:\n if:\n source: 'Template'\n notWithinPath:\n - \"deployments/path/\"\n\n---\n# Synopsis: Test notWithinPath with source and case sensitive\napiVersion: github.com/microsoft/PSRule/v1\nkind: Selector\nmetadata:\n name: YamlSourceNotWithinPathCaseSensitive\nspec:\n if:\n source: 'Template'\n notWithinPath:\n - \"Deployments/Path/\"\n caseSensitive: true\nThe comparison property
scopeis used with a condition to evaluate any scopes assigned to the object. Thescopeproperty must be set to.. Any other value will cause the condition to evaluate tofalse.Syntax:
scope: '.'\nFor example:
","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Expressions/#setof","title":"SetOf","text":"---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Rule\nmetadata:\n name: 'ExampleScope'\nspec:\n condition:\n scope: '.'\n startsWith: '/'\n\n---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Selector\nmetadata:\n name: 'ExampleScope'\nspec:\n if:\n scope: '.'\n startsWith: '/'\nThe
setOfcondition can be used to determine if the operand is a set of specified values. Additionally the following properties are accepted:Syntax:
setOf: <array>\ncaseSensitive: <bool>\nFor example:
","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Expressions/#source","title":"Source","text":"---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Rule\nmetadata:\n name: 'ExampleSetOf'\nspec:\n condition:\n field: 'zones'\n setOf:\n - 1\n - 2\n - 3\n caseSensitive: false\n\n---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Selector\nmetadata:\n name: 'ExampleSetOf'\nspec:\n if:\n field: 'zones'\n setOf:\n - 1\n - 2\n - 3\n caseSensitive: false\nThe comparison property
sourceis used with a condition to expose the source path for the resource. Thesourceproperty can be set to any value. The default isfilewhen objects loaded from a file don't identify a source.Syntax:
source: 'file'\nFor example:
","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Expressions/#startswith","title":"StartsWith","text":"---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Selector\nmetadata:\n name: IgnoreTestFiles\nspec:\n if:\n source: 'file'\n withinPath: 'tests/PSRule.Tests/'\nThe
startsWithcondition can be used to determine if the operand starts with a specified string. One or more strings to compare can be specified.Syntax:
startsWith: <string | array>\ncaseSensitive: <boolean>\nconvert: <boolean>\nFor example:
","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Expressions/#subset","title":"Subset","text":"---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Rule\nmetadata:\n name: 'ExampleStartsWith'\nspec:\n condition:\n anyOf:\n - field: 'url'\n startsWith: 'http'\n - field: 'url'\n startsWith:\n - 'http://'\n - 'https://'\n\n---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Selector\nmetadata:\n name: 'ExampleStartsWith'\nspec:\n if:\n anyOf:\n - field: 'url'\n startsWith: 'http'\n - field: 'url'\n startsWith:\n - 'http://'\n - 'https://'\nThe
subsetcondition can be used to determine if the operand is a set of specified values. The following properties are accepted:Syntax:
subset: <array>\ncaseSensitive: <bool>\nunique: <bool>\nFor example:
","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Expressions/#type","title":"Type","text":"---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Rule\nmetadata:\n name: 'ExampleSubset'\nspec:\n condition:\n field: 'logs'\n subset:\n - 'cluster-autoscaler'\n - 'kube-apiserver'\n - 'kube-scheduler'\n caseSensitive: true\n unique: true\n\n---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Selector\nmetadata:\n name: 'ExampleSubset'\nspec:\n if:\n field: 'logs'\n subset:\n - 'cluster-autoscaler'\n - 'kube-apiserver'\n - 'kube-scheduler'\n caseSensitive: true\n unique: true\nThe comparison property
typeis used with a condition to evaluate the target type of the object. Thetypeproperty must be set to.. Any other value will cause the condition to evaluate tofalse.Syntax:
type: '.'\nFor example:
","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Expressions/#version","title":"Version","text":"---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Rule\nmetadata:\n name: 'ExampleType'\nspec:\n condition:\n type: '.'\n equals: 'CustomType'\n\n---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Selector\nmetadata:\n name: 'ExampleType'\nspec:\n if:\n type: '.'\n in:\n - 'Microsoft.Storage/storageAccounts'\n - 'Microsoft.Storage/storageAccounts/blobServices'\nThe
versioncondition determines if the operand is a valid semantic version. A constraint can optionally be provided to require the semantic version to be within a range. Supported version constraints for expression are the same as the$Assert.Versionassertion helper.Syntax:
version: <string>\nincludePrerelease: <bool>\nFor example:
","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Expressions/#withinpath","title":"WithinPath","text":"---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Rule\nmetadata:\n name: 'ExampleVersion'\nspec:\n condition:\n field: 'engine.version'\n version: '^1.2.3'\n\n---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Selector\nmetadata:\n name: 'ExampleAnyVersion'\nspec:\n if:\n field: 'engine.version'\n version: ''\n\n---\napiVersion: github.com/microsoft/PSRule/v1\nkind: Selector\nmetadata:\n name: 'ExampleVersionIncludingPrerelease'\nspec:\n if:\n field: 'engine.version'\n version: '>=1.5.0'\n includePrerelease: true\nThe
withinPathcondition determines if a file path is within a required path.If the path is within the required path, the condition will return
true. If the path is not within the required path, the condition will returnfalse.The following properties are accepted:
Syntax:
withinPath: <array>\ncaseSensitive: <boolean>\nFor example:
","tags":["language"]},{"location":"concepts/PSRule/en-US/about_PSRule_Expressions/#links","title":"Links","text":"---\n# Synopsis: Test withinPath with source\napiVersion: github.com/microsoft/PSRule/v1\nkind: Selector\nmetadata:\n name: YamlSourceWithinPath\nspec:\n if:\n source: 'Template'\n withinPath:\n - \"deployments/path/\"\n\n---\n# Synopsis: Test withinPath with source and case sensitive\napiVersion: github.com/microsoft/PSRule/v1\nkind: Selector\nmetadata:\n name: YamlSourceWithinPathCaseSensitive\nspec:\n if:\n source: 'Template'\n withinPath:\n - \"Deployments/Path/\"\n caseSensitive: true\nDescribes additional options that can be used during rule execution.
"},{"location":"concepts/PSRule/en-US/about_PSRule_Options/#description","title":"Description","text":"PSRule lets you use options when calling cmdlets such as
Invoke-PSRuleandTest-PSRuleTargetto change how rules are processed. This topic describes what options are available, when to and how to use them.The following workspace options are available for use:
Additionally the following baseline options can be included:
See about_PSRule_Baseline for more information on baseline options.
Options can be used with the following PSRule cmdlets:
Each of these cmdlets support:
When using a hashtable object
@{}, one or more options can be specified as keys using a dotted notation.For example:
$option = @{ 'Output.Format' = 'Yaml' };\nInvoke-PSRule -Path . -Option $option;\nInvoke-PSRule -Path . -Option @{ 'Output.Format' = 'Yaml' };\nThe above example shows how the
Output.Formatoption as a hashtable key can be used. Continue reading for a full list of options and how each can be used.Alternatively, options can be stored in a YAML formatted file and loaded from disk. Storing options as YAML allows different configurations to be loaded in a repeatable way instead of having to create an options object each time.
Options are stored as YAML properties using a lower camel case naming convention, for example:
output:\n format: Yaml\nThe
Set-PSRuleOptioncmdlet can be used to set options stored in YAML or the YAML file can be manually edited.Set-PSRuleOption -OutputFormat Yaml;\nBy default, PSRule will automatically look for a default YAML options file in the current working directory. Alternatively, you can specify a specific file path.
For example:
Invoke-PSRule -Option '.\\myconfig.yml';\nNew-PSRuleOption -Path '.\\myconfig.yaml';\nPSRule uses any of the following file names (in order) as the default YAML options file. If more than one of these files exist, the following order will be used to find the first match.
We recommend only using lowercase characters as shown above. This is because not all operating systems treat case in the same way.
Most options can be set using environment variables. When configuring environment variables we recommend that all capital letters are used. This is because environment variables are case-sensitive on some operating systems.
PSRule environment variables use a consistent naming pattern of
PSRULE_<PARENT>_<NAME>. Where<PARENT>is the parent class and<NAME>is the specific option. For example:When setting environment variables:
You can use a baseline group to provide a friendly name to an existing baseline. When you run PSRule you can opt to use the baseline group name as an alternative name for the baseline. To indicate a baseline group, prefix the group name with
@where you would use the name of a baseline.Baseline groups can be specified using:
# PowerShell: Using the BaselineGroup parameter\n$option = New-PSRuleOption -BaselineGroup @{ latest = 'YourBaseline' };\n# PowerShell: Using the Baseline.Group hashtable key\n$option = New-PSRuleOption -Option @{ 'Baseline.Group' = @{ latest = 'YourBaseline' } };\n# PowerShell: Using the BaselineGroup parameter to set YAML\nSet-PSRuleOption -BaselineGroup @{ latest = 'YourBaseline' };\n# YAML: Using the baseline/group property\nbaseline:\n group:\n latest: YourBaseline\n# Bash: Using environment variable\nexport PSRULE_BASELINE_GROUP='latest=YourBaseline'\n# GitHub Actions: Using environment variable\nenv:\n PSRULE_BASELINE_GROUP: 'latest=YourBaseline'\n
"},{"location":"concepts/PSRule/en-US/about_PSRule_Options/#bindingfield","title":"Binding.Field","text":"# Azure Pipelines: Using environment variable\nvariables:\n- name: PSRULE_BASELINE_GROUP\n value: 'latest=YourBaseline'\nWhen an object is passed from the pipeline, PSRule automatically extracts fields from object properties. PSRule provides standard fields such as
TargetNameandTargetType. In addition to standard fields, custom fields can be bound. Custom fields are available to rules and included in output.PSRule uses the following logic to determine which property should be used for binding:
Custom field bindings can be specified using:
# PowerShell: Using the BindingField parameter\n$option = New-PSRuleOption -BindingField @{ id = 'ResourceId', 'AlternativeId' };\n# PowerShell: Using the Binding.Field hashtable key\n$option = New-PSRuleOption -Option @{ 'Binding.Field' = @{ id = 'ResourceId', 'AlternativeId' } };\n# PowerShell: Using the BindingField parameter to set YAML\nSet-PSRuleOption -BindingField @{ id = 'ResourceId', 'AlternativeId' };\n
"},{"location":"concepts/PSRule/en-US/about_PSRule_Options/#bindingignorecase","title":"Binding.IgnoreCase","text":"# YAML: Using the binding/field property\nbinding:\n field:\n id:\n - ResourceId\n - AlternativeId\nWhen evaluating an object, PSRule extracts a few key properties from the object to help filter rules and display output results. The process of extract these key properties is called binding. The properties that PSRule uses for binding can be customized by providing a order list of alternative properties to use. See
Binding.TargetNameandBinding.TargetTypefor these options.This option can be specified using:
# PowerShell: Using the BindingIgnoreCase parameter\n$option = New-PSRuleOption -BindingIgnoreCase $False;\n# PowerShell: Using the Binding.IgnoreCase hashtable key\n$option = New-PSRuleOption -Option @{ 'Binding.IgnoreCase' = $False };\n# PowerShell: Using the BindingIgnoreCase parameter to set YAML\nSet-PSRuleOption -BindingIgnoreCase $False;\n# YAML: Using the binding/ignoreCase property\nbinding:\n ignoreCase: false\n# Bash: Using environment variable\nexport PSRULE_BINDING_IGNORECASE=false\n# GitHub Actions: Using environment variable\nenv:\n PSRULE_BINDING_IGNORECASE: false\n
"},{"location":"concepts/PSRule/en-US/about_PSRule_Options/#bindingnameseparator","title":"Binding.NameSeparator","text":"# Azure Pipelines: Using environment variable\nvariables:\n- name: PSRULE_BINDING_IGNORECASE\n value: false\nWhen an object is passed from the pipeline, PSRule assigns the object a TargetName. TargetName is used in output results to identify one object from another.
In cases where different types of objects share the same TargetName, this may become confusing. Using a qualified name, prefixes the TargetName with TargetType. i.e. TargetType/TargetName
To use a qualified name, see the
Binding.UseQualifiedNameoption.By default, PSRule uses
/to separate TargetType from TargetName. This option configures the separator that PSRule uses between the two components.This option can be specified using:
# PowerShell: Using the BindingNameSeparator parameter\n$option = New-PSRuleOption -BindingNameSeparator '::';\n# PowerShell: Using the Binding.NameSeparator hashtable key\n$option = New-PSRuleOption -Option @{ 'Binding.NameSeparator' = '::' };\n# PowerShell: Using the BindingNameSeparator parameter to set YAML\nSet-PSRuleOption -BindingNameSeparator '::';\n# YAML: Using the binding/nameSeparator property\nbinding:\n nameSeparator: '::'\n# Bash: Using environment variable\nexport PSRULE_BINDING_NAMESEPARATOR='::'\n# GitHub Actions: Using environment variable\nenv:\n PSRULE_BINDING_NAMESEPARATOR: '::'\n
"},{"location":"concepts/PSRule/en-US/about_PSRule_Options/#bindingprefertargetinfo","title":"Binding.PreferTargetInfo","text":"# Azure Pipelines: Using environment variable\nvariables:\n- name: PSRULE_BINDING_NAMESEPARATOR\n value: '::'\nSome built-in objects within PSRule perform automatic binding of TargetName and TargetType. These built-in objects provide their own target info.
When binding has been configured these values override automatic binding by default. This can occur when the built-in object uses one of the fields specified by the custom configuration. The common occurrences of this are on fields such as
NameandFullNamewhich are widely used. To prefer automatic binding when specified set this option to$True.This option can be specified using:
# PowerShell: Using the BindingPreferTargetInfo parameter\n$option = New-PSRuleOption -BindingPreferTargetInfo $True;\n# PowerShell: Using the Binding.PreferTargetInfo hashtable key\n$option = New-PSRuleOption -Option @{ 'Binding.PreferTargetInfo' = $True };\n# PowerShell: Using the BindingPreferTargetInfo parameter to set YAML\nSet-PSRuleOption -BindingPreferTargetInfo $True;\n# YAML: Using the binding/preferTargetInfo property\nbinding:\n preferTargetInfo: true\n# Bash: Using environment variable\nexport PSRULE_BINDING_PREFERTARGETINFO=false\n# GitHub Actions: Using environment variable\nenv:\n PSRULE_BINDING_PREFERTARGETINFO: false\n
"},{"location":"concepts/PSRule/en-US/about_PSRule_Options/#bindingtargetname","title":"Binding.TargetName","text":"# Azure Pipelines: Using environment variable\nvariables:\n- name: PSRULE_BINDING_PREFERTARGETINFO\n value: false\nWhen an object is passed from the pipeline, PSRule assigns the object a TargetName. TargetName is used in output results to identify one object from another. Many objects could be passed down the pipeline at the same time, so using a TargetName that is meaningful is important. TargetName is also used for advanced features such as rule suppression.
The value that PSRule uses for TargetName is configurable. PSRule uses the following logic to determine what TargetName should be used:
Custom property names to use for binding can be specified using:
# PowerShell: Using the TargetName parameter\n$option = New-PSRuleOption -TargetName 'ResourceName', 'AlternateName';\n# PowerShell: Using the Binding.TargetName hashtable key\n$option = New-PSRuleOption -Option @{ 'Binding.TargetName' = 'ResourceName', 'AlternateName' };\n# PowerShell: Using the TargetName parameter to set YAML\nSet-PSRuleOption -TargetName 'ResourceName', 'AlternateName';\n# YAML: Using the binding/targetName property\nbinding:\n targetName:\n - ResourceName\n - AlternateName\n# Bash: Using environment variable\nexport PSRULE_BINDING_TARGETNAME='ResourceName;AlternateName'\n# GitHub Actions: Using environment variable\nenv:\n PSRULE_BINDING_TARGETNAME: 'ResourceName;AlternateName'\n# Azure Pipelines: Using environment variable\nvariables:\n- name: PSRULE_BINDING_TARGETNAME\n value: 'ResourceName;AlternateName'\nTo specify a custom binding function use:
"},{"location":"concepts/PSRule/en-US/about_PSRule_Options/#bindingtargettype","title":"Binding.TargetType","text":"# Create a custom function that returns a TargetName string\n$bindFn = {\n param ($TargetObject)\n\n $otherName = $TargetObject.PSObject.Properties['OtherName'];\n if ($Null -eq $otherName) { return $Null }\n return $otherName.Value;\n}\n\n# Specify the binding function script block code to execute\n$option = New-PSRuleOption -BindTargetName $bindFn;\nWhen an object is passed from the pipeline, PSRule assigns the object a TargetType. TargetType is used to filter rules based on object type and appears in output results.
The value that PSRule uses for TargetType is configurable. PSRule uses the following logic to determine what TargetType should be used:
Custom property names to use for binding can be specified using:
# PowerShell: Using the TargetType parameter\n$option = New-PSRuleOption -TargetType 'ResourceType', 'kind';\n# PowerShell: Using the Binding.TargetType hashtable key\n$option = New-PSRuleOption -Option @{ 'Binding.TargetType' = 'ResourceType', 'kind' };\n# PowerShell: Using the TargetType parameter to set YAML\nSet-PSRuleOption -TargetType 'ResourceType', 'kind';\n# YAML: Using the binding/targetType property\nbinding:\n targetType:\n - ResourceType\n - kind\n# Bash: Using environment variable\nexport PSRULE_BINDING_TARGETTYPE='ResourceType;kind'\n# GitHub Actions: Using environment variable\nenv:\n PSRULE_BINDING_TARGETTYPE: 'ResourceType;kind'\n# Azure Pipelines: Using environment variable\nvariables:\n- name: PSRULE_BINDING_TARGETTYPE\n value: 'ResourceType;kind'\nTo specify a custom binding function use:
"},{"location":"concepts/PSRule/en-US/about_PSRule_Options/#bindingusequalifiedname","title":"Binding.UseQualifiedName","text":"# Create a custom function that returns a TargetType string\n$bindFn = {\n param ($TargetObject)\n\n $otherType = $TargetObject.PSObject.Properties['OtherType'];\n\n if ($otherType -eq $Null) {\n return $Null\n }\n\n return $otherType.Value;\n}\n\n# Specify the binding function script block code to execute\n$option = New-PSRuleOption -BindTargetType $bindFn;\nWhen an object is passed from the pipeline, PSRule assigns the object a TargetName. TargetName is used in output results to identify one object from another.
In cases where different types of objects share the same TargetName, this may become confusing. Using a qualified name, prefixes the TargetName with TargetType. i.e. TargetType/TargetName
This option determines if PSRule uses qualified or unqualified names (default).
By default, PSRule uses
/to separate TargetType from TargetName. SetBinding.NameSeparatorto change.This option can be specified using:
# PowerShell: Using the BindingUseQualifiedName parameter\n$option = New-PSRuleOption -BindingUseQualifiedName $True;\n# PowerShell: Using the Binding.UseQualifiedName hashtable key\n$option = New-PSRuleOption -Option @{ 'Binding.UseQualifiedName' = $True };\n# PowerShell: Using the BindingUseQualifiedName parameter to set YAML\nSet-PSRuleOption -BindingUseQualifiedName $True;\n# YAML: Using the binding/useQualifiedName property\nbinding:\n useQualifiedName: true\n# Bash: Using environment variable\nexport PSRULE_BINDING_USEQUALIFIEDNAME=false\n# GitHub Actions: Using environment variable\nenv:\n PSRULE_BINDING_USEQUALIFIEDNAME: false\n
"},{"location":"concepts/PSRule/en-US/about_PSRule_Options/#configuration","title":"Configuration","text":"# Azure Pipelines: Using environment variable\nvariables:\n- name: PSRULE_BINDING_USEQUALIFIEDNAME\n value: false\nConfigures a set of baseline configuration values that can be used in rule definitions. Configuration values can be overridden at different scopes.
This option can be specified using:
# PowerShell: Using the Configuration option with a hashtable\n$option = New-PSRuleOption -Configuration @{ LOCAL_APPSERVICEMININSTANCECOUNT = 2 };\n# YAML: Using the configuration property\nconfiguration:\n LOCAL_APPSERVICEMININSTANCECOUNT: 2\nConfiguration values can be specified using environment variables. To specify a configuration value, prefix the configuration value with
PSRULE_CONFIGURATION_.# Bash: Using environment variable\nexport PSRULE_CONFIGURATION_LOCAL_APPSERVICEMININSTANCECOUNT=2\n# GitHub Actions: Using environment variable\nenv:\n PSRULE_CONFIGURATION_LOCAL_APPSERVICEMININSTANCECOUNT: '2'\n
"},{"location":"concepts/PSRule/en-US/about_PSRule_Options/#conventioninclude","title":"Convention.Include","text":"# Azure Pipelines: Using environment variable\nvariables:\n- name: PSRULE_CONFIGURATION_LOCAL_APPSERVICEMININSTANCECOUNT\n value: '2'\nSpecifies conventions to execute when the pipeline run. Conventions are included by name and must be defined within files included in
-Pathor-Module.This option can be specified using:
# PowerShell: Using the Convention parameter\n$option = New-PSRuleOption -Convention 'Convention1', 'Convention2';\n# PowerShell: Using the Convention.Include hashtable key\n$option = New-PSRuleOption -Option @{ 'Convention.Include' = $True };\n# PowerShell: Using the Convention parameter to set YAML\nSet-PSRuleOption -Convention 'Convention1', 'Convention2';\n# YAML: Using the convention/include property\nconvention:\n include:\n - 'Convention1'\n - 'Convention2'\n# Bash: Using environment variable\nexport PSRULE_CONVENTION_INCLUDE='Convention1;Convention2'\n# GitHub Actions: Using environment variable\nenv:\n PSRULE_CONVENTION_INCLUDE: 'Convention1;Convention2'\n
"},{"location":"concepts/PSRule/en-US/about_PSRule_Options/#executionaliasreference","title":"Execution.AliasReference","text":"# Azure Pipelines: Using environment variable\nvariables:\n- name: PSRULE_CONVENTION_INCLUDE\n value: 'Convention1;Convention2'\nv2.9.0
Determines how to handle when an alias to a resource is used. By default, a warning is generated, however this behavior can be modified by this option.
The following preferences are available:
This option can be specified using:
# PowerShell: Using the ExecutionAliasReference parameter\n$option = New-PSRuleOption -ExecutionAliasReference 'Error';\n# PowerShell: Using the Execution.AliasReference hashtable key\n$option = New-PSRuleOption -Option @{ 'Execution.AliasReference' = 'Error' };\n# PowerShell: Using the ExecutionAliasReference parameter to set YAML\nSet-PSRuleOption -ExecutionAliasReference 'Error';\n# YAML: Using the execution/aliasReference property\nexecution:\n aliasReference: Error\n# Bash: Using environment variable\nexport PSRULE_EXECUTION_ALIASREFERENCE=Error\n# GitHub Actions: Using environment variable\nenv:\n PSRULE_EXECUTION_ALIASREFERENCE: Error\n
"},{"location":"concepts/PSRule/en-US/about_PSRule_Options/#executionduplicateresourceid","title":"Execution.DuplicateResourceId","text":"# Azure Pipelines: Using environment variable\nvariables:\n- name: PSRULE_EXECUTION_ALIASREFERENCE\n value: Error\nv2.4.0
Determines how to handle duplicate resources identifiers during execution. A duplicate resource identifier may exist if two resources are defined with the same name, ref, or alias. By default, an error is thrown, however this behavior can be modified by this option.
If this option is configured to
WarnorIgnoreonly the first resource will be used, however PSRule will continue to execute.The following preferences are available:
This option can be specified using:
# PowerShell: Using the DuplicateResourceId parameter\n$option = New-PSRuleOption -DuplicateResourceId 'Warn';\n# PowerShell: Using the Execution.DuplicateResourceId hashtable key\n$option = New-PSRuleOption -Option @{ 'Execution.DuplicateResourceId' = 'Warn' };\n# PowerShell: Using the DuplicateResourceId parameter to set YAML\nSet-PSRuleOption -DuplicateResourceId 'Warn';\n# YAML: Using the execution/duplicateResourceId property\nexecution:\n duplicateResourceId: Warn\n# Bash: Using environment variable\nexport PSRULE_EXECUTION_DUPLICATERESOURCEID=Warn\n# GitHub Actions: Using environment variable\nenv:\n PSRULE_EXECUTION_DUPLICATERESOURCEID: Warn\n
"},{"location":"concepts/PSRule/en-US/about_PSRule_Options/#executionhashalgorithm","title":"Execution.HashAlgorithm","text":"# Azure Pipelines: Using environment variable\nvariables:\n- name: PSRULE_EXECUTION_DUPLICATERESOURCEID\n value: Warn\nv3.0.0
Specifies the hashing algorithm used by the PSRule runtime. This hash algorithm is used when generating a resource identifier for an object that does not have a bound name.
By default, the SHA512 algorithm is used.
The following algorithms are available for use in PSRule:
This option can be specified using:
# PowerShell: Using the Execution.HashAlgorithm hashtable key\n$option = New-PSRuleOption -Option @{ 'Execution.HashAlgorithm' = 'SHA256' };\n# YAML: Using the execution/hashAlgorithm property\nexecution:\n hashAlgorithm: SHA256\n# Bash: Using environment variable\nexport PSRULE_EXECUTION_HASHALGORITHM=SHA256\n# GitHub Actions: Using environment variable\nenv:\n PSRULE_EXECUTION_HASHALGORITHM: SHA256\n
"},{"location":"concepts/PSRule/en-US/about_PSRule_Options/#executionlanguagemode","title":"Execution.LanguageMode","text":"# Azure Pipelines: Using environment variable\nvariables:\n- name: PSRULE_EXECUTION_HASHALGORITHM\n value: SHA256\nUnless PowerShell has been constrained, full language features of PowerShell are available to use within rule definitions. In locked down environments, a reduced set of language features may be desired.
When PSRule is executed in an environment configured for Device Guard, only constrained language features are available.
The following language modes are available for use in PSRule:
This option can be specified using:
# PowerShell: Using the Execution.LanguageMode hashtable key\n$option = New-PSRuleOption -Option @{ 'Execution.LanguageMode' = 'ConstrainedLanguage' };\n# YAML: Using the execution/languageMode property\nexecution:\n languageMode: ConstrainedLanguage\n# Bash: Using environment variable\nexport PSRULE_EXECUTION_LANGUAGEMODE=ConstrainedLanguage\n# GitHub Actions: Using environment variable\nenv:\n PSRULE_EXECUTION_LANGUAGEMODE: ConstrainedLanguage\n
"},{"location":"concepts/PSRule/en-US/about_PSRule_Options/#executioninvariantculture","title":"Execution.InvariantCulture","text":"# Azure Pipelines: Using environment variable\nvariables:\n- name: PSRULE_EXECUTION_LANGUAGEMODE\n value: ConstrainedLanguage\nv2.9.0
Determines how to report when an invariant culture is used. By default, a warning is generated, however this behavior can be modified by this option.
The following preferences are available:
This option can be specified using:
# PowerShell: Using the ExecutionInvariantCulture parameter\n$option = New-PSRuleOption -ExecutionInvariantCulture 'Error';\n# PowerShell: Using the Execution.InvariantCulture hashtable key\n$option = New-PSRuleOption -Option @{ 'Execution.InvariantCulture' = 'Error' };\n# PowerShell: Using the ExecutionInvariantCulture parameter to set YAML\nSet-PSRuleOption -ExecutionInvariantCulture 'Error';\n# YAML: Using the execution/invariantCulture property\nexecution:\n invariantCulture: Error\n# Bash: Using environment variable\nexport PSRULE_EXECUTION_INVARIANTCULTURE=Error\n# GitHub Actions: Using environment variable\nenv:\n PSRULE_EXECUTION_INVARIANTCULTURE: Error\n
"},{"location":"concepts/PSRule/en-US/about_PSRule_Options/#executioninitialsessionstate","title":"Execution.InitialSessionState","text":"# Azure Pipelines: Using environment variable\nvariables:\n- name: PSRULE_EXECUTION_INVARIANTCULTURE\n value: Error\nv2.5.0
Determines how the initial session state for executing PowerShell code is created.
The following preferences are available:
This option can be specified using:
# PowerShell: Using the InitialSessionState parameter\n$option = New-PSRuleOption -InitialSessionState 'Minimal';\n# PowerShell: Using the Execution.InitialSessionState hashtable key\n$option = New-PSRuleOption -Option @{ 'Execution.InitialSessionState' = 'Minimal' };\n# PowerShell: Using the InitialSessionState parameter to set YAML\nSet-PSRuleOption -InitialSessionState 'Minimal';\n# YAML: Using the execution/initialSessionState property\nexecution:\n initialSessionState: Minimal\n# Bash: Using environment variable\nexport PSRULE_EXECUTION_INITIALSESSIONSTATE=Minimal\n# GitHub Actions: Using environment variable\nenv:\n PSRULE_EXECUTION_INITIALSESSIONSTATE: Minimal\n
"},{"location":"concepts/PSRule/en-US/about_PSRule_Options/#executionrestrictscriptsource","title":"Execution.RestrictScriptSource","text":"# Azure Pipelines: Using environment variable\nvariables:\n- name: PSRULE_EXECUTION_INITIALSESSIONSTATE\n value: Minimal\nv3.0.0
Configures where to allow PowerShell language features (such as rules and conventions) to run from. In locked down environments, running PowerShell scripts from the workspace may not be allowed. Only run scripts from a trusted source.
This option does not affect YAML or JSON based rules and resources.
The following script source restrictions are available:
This option can be specified using:
# PowerShell: Using the RestrictScriptSource parameter\n$option = New-PSRuleOption -RestrictScriptSource 'ModuleOnly';\n# PowerShell: Using the Execution.RestrictScriptSource hashtable key\n$option = New-PSRuleOption -Option @{ 'Execution.RestrictScriptSource' = 'ModuleOnly' };\n# PowerShell: Using the RestrictScriptSource parameter to set YAML\nSet-PSRuleOption -RestrictScriptSource 'ModuleOnly';\n# YAML: Using the execution/restrictScriptSource property\nexecution:\n restrictScriptSource: ModuleOnly\n# Bash: Using environment variable\nexport PSRULE_EXECUTION_RESTRICTSCRIPTSOURCE=ModuleOnly\n# GitHub Actions: Using environment variable\nenv:\n PSRULE_EXECUTION_RESTRICTSCRIPTSOURCE: ModuleOnly\n
"},{"location":"concepts/PSRule/en-US/about_PSRule_Options/#executionruleinconclusive","title":"Execution.RuleInconclusive","text":"# Azure Pipelines: Using environment variable\nvariables:\n- name: PSRULE_EXECUTION_RESTRICTSCRIPTSOURCE\n value: ModuleOnly\nv2.9.0
Determines how to handle rules that generate inconclusive results. By default, a warning is generated, however this behavior can be modified by this option.
The following preferences are available:
This option can be specified using:
# PowerShell: Using the ExecutionRuleInconclusive parameter\n$option = New-PSRuleOption -ExecutionRuleInconclusive 'Error';\n# PowerShell: Using the Execution.RuleInconclusive hashtable key\n$option = New-PSRuleOption -Option @{ 'Execution.RuleInconclusive' = 'Error' };\n# PowerShell: Using the ExecutionRuleInconclusive parameter to set YAML\nSet-PSRuleOption -ExecutionRuleInconclusive 'Error';\n# YAML: Using the execution/ruleInconclusive property\nexecution:\n ruleInconclusive: Error\n# Bash: Using environment variable\nexport PSRULE_EXECUTION_RULEINCONCLUSIVE=Error\n# GitHub Actions: Using environment variable\nenv:\n PSRULE_EXECUTION_RULEINCONCLUSIVE: Error\n
"},{"location":"concepts/PSRule/en-US/about_PSRule_Options/#executionsuppressiongroupexpired","title":"Execution.SuppressionGroupExpired","text":"# Azure Pipelines: Using environment variable\nvariables:\n- name: PSRULE_EXECUTION_RULEINCONCLUSIVE\n value: Error\nv2.6.0
Determines how to handle expired suppression groups. Regardless of the value, an expired suppression group will be ignored. By default, a warning is generated, however this behavior can be modified by this option.
The following preferences are available:
This option can be specified using:
# PowerShell: Using the SuppressionGroupExpired parameter\n$option = New-PSRuleOption -SuppressionGroupExpired 'Error';\n# PowerShell: Using the Execution.SuppressionGroupExpired hashtable key\n$option = New-PSRuleOption -Option @{ 'Execution.SuppressionGroupExpired' = 'Error' };\n# PowerShell: Using the SuppressionGroupExpired parameter to set YAML\nSet-PSRuleOption -SuppressionGroupExpired 'Error';\n# YAML: Using the execution/suppressionGroupExpired property\nexecution:\n suppressionGroupExpired: Error\n# Bash: Using environment variable\nexport PSRULE_EXECUTION_SUPPRESSIONGROUPEXPIRED=Error\n# GitHub Actions: Using environment variable\nenv:\n PSRULE_EXECUTION_SUPPRESSIONGROUPEXPIRED: Error\n
"},{"location":"concepts/PSRule/en-US/about_PSRule_Options/#executionruleexcluded","title":"Execution.RuleExcluded","text":"# Azure Pipelines: Using environment variable\nvariables:\n- name: PSRULE_EXECUTION_SUPPRESSIONGROUPEXPIRED\n value: Error\nv2.8.0
Determines how to handle excluded rules. Regardless of the value, excluded rules are ignored. By default, a rule is excluded silently, however this behavior can be modified by this option.
The following preferences are available:
This option can be specified using:
# PowerShell: Using the ExecutionRuleExcluded parameter\n$option = New-PSRuleOption -ExecutionRuleExcluded 'Warn';\n# PowerShell: Using the Execution.RuleExcluded hashtable key\n$option = New-PSRuleOption -Option @{ 'Execution.RuleExcluded' = 'Warn' };\n# PowerShell: Using the ExecutionRuleExcluded parameter to set YAML\nSet-PSRuleOption -ExecutionRuleExcluded 'Warn';\n# YAML: Using the execution/ruleExcluded property\nexecution:\n ruleExcluded: Warn\n# Bash: Using environment variable\nexport PSRULE_EXECUTION_RULEEXCLUDED=Warn\n# GitHub Actions: Using environment variable\nenv:\n PSRULE_EXECUTION_RULEEXCLUDED: Warn\n
"},{"location":"concepts/PSRule/en-US/about_PSRule_Options/#executionrulesuppressed","title":"Execution.RuleSuppressed","text":"# Azure Pipelines: Using environment variable\nvariables:\n- name: PSRULE_EXECUTION_RULEEXCLUDED\n value: Warn\nv2.8.0
Determines how to handle suppressed rules. Regardless of the value, a suppressed rule is ignored. By default, a warning is generated, however this behavior can be modified by this option.
The following preferences are available:
# PowerShell: Using the ExecutionRuleSuppressed parameter\n$option = New-PSRuleOption -ExecutionRuleSuppressed 'Error';\n# PowerShell: Using the Execution.RuleSuppressed hashtable key\n$option = New-PSRuleOption -Option @{ 'Execution.RuleSuppressed' = 'Error' };\n# PowerShell: Using the ExecutionRuleSuppressed parameter to set YAML\nSet-PSRuleOption -ExecutionRuleSuppressed 'Error';\n# YAML: Using the execution/ruleSuppressed property\nexecution:\n ruleSuppressed: Error\n# Bash: Using environment variable\nexport PSRULE_EXECUTION_RULESUPPRESSED=Error\n# GitHub Actions: Using environment variable\nenv:\n PSRULE_EXECUTION_RULESUPPRESSED: Error\n
"},{"location":"concepts/PSRule/en-US/about_PSRule_Options/#executionunprocessedobject","title":"Execution.UnprocessedObject","text":"# Azure Pipelines: Using environment variable\nvariables:\n- name: PSRULE_EXECUTION_RULESUPPRESSED\n value: Error\nv2.9.0
Determines how to report objects that are not processed by any rule. By default, a warning is generated, however this behavior can be modified by this option.
The following preferences are available:
This option can be specified using:
# PowerShell: Using the ExecutionUnprocessedObject parameter\n$option = New-PSRuleOption -ExecutionUnprocessedObject 'Ignore';\n# PowerShell: Using the Execution.UnprocessedObject hashtable key\n$option = New-PSRuleOption -Option @{ 'Execution.UnprocessedObject' = 'Ignore' };\n# PowerShell: Using the ExecutionUnprocessedObject parameter to set YAML\nSet-PSRuleOption -ExecutionUnprocessedObject 'Ignore';\n# YAML: Using the execution/unprocessedObject property\nexecution:\n unprocessedObject: Ignore\n# Bash: Using environment variable\nexport PSRULE_EXECUTION_UNPROCESSEDOBJECT=Ignore\n# GitHub Actions: Using environment variable\nenv:\n PSRULE_EXECUTION_UNPROCESSEDOBJECT: Ignore\n
"},{"location":"concepts/PSRule/en-US/about_PSRule_Options/#includemodule","title":"Include.Module","text":"# Azure Pipelines: Using environment variable\nvariables:\n- name: PSRULE_EXECUTION_UNPROCESSEDOBJECT\n value: Ignore\nAutomatically include rules and resources from the specified module. To automatically import and include a module specify the module by name. The module must already be installed on the system.
When
$PSModuleAutoLoadingPreferenceis set to a value other thenAllthe module must be imported.This option is equivalent to using the
-Moduleparameter on PSRule cmdlets, with the following addition:This option can be specified using:
# PowerShell: Using the IncludeModule parameter\n$option = New-PSRuleOption -IncludeModule 'TestModule1', 'TestModule2';\n# PowerShell: Using the Include.Module hashtable key\n$option = New-PSRuleOption -Option @{ 'Include.Module' = 'TestModule1', 'TestModule2' };\n# PowerShell: Using the IncludeModule parameter to set YAML\nSet-PSRuleOption -IncludeModule 'TestModule1', 'TestModule2';\n# YAML: Using the include/module property\ninclude:\n module:\n - TestModule1\n# Bash: Using environment variable\nexport PSRULE_INCLUDE_MODULE=TestModule1;TestModule2\n# GitHub Actions: Using environment variable\nenv:\n PSRULE_INCLUDE_MODULE: TestModule1;TestModule2\n
"},{"location":"concepts/PSRule/en-US/about_PSRule_Options/#includepath","title":"Include.Path","text":"# Azure Pipelines: Using environment variable\nvariables:\n- name: PSRULE_INCLUDE_MODULE\n value: TestModule1;TestModule2\nAutomatically include rules and resources from the specified path. By default,
.ps-rule/is included.This option is equivalent to using the
-Pathparameter on PSRule cmdlets, with the following additions:This option can be specified using:
# PowerShell: Using the IncludePath parameter\n$option = New-PSRuleOption -IncludePath '.ps-rule/', 'custom-rules/';\n# PowerShell: Using the Include.Path hashtable key\n$option = New-PSRuleOption -Option @{ 'Include.Path' = '.ps-rule/', 'custom-rules/' };\n# PowerShell: Using the IncludePath parameter to set YAML\nSet-PSRuleOption -IncludePath '.ps-rule/', 'custom-rules/';\n# YAML: Using the include/path property\ninclude:\n path:\n - custom-rules/\n# Bash: Using environment variable\nexport PSRULE_INCLUDE_PATH=.ps-rule/;custom-rules/\n# GitHub Actions: Using environment variable\nenv:\n PSRULE_INCLUDE_PATH: .ps-rule/;custom-rules/\n
"},{"location":"concepts/PSRule/en-US/about_PSRule_Options/#inputformat","title":"Input.Format","text":"# Azure Pipelines: Using environment variable\nvariables:\n- name: PSRULE_INCLUDE_PATH\n value: .ps-rule/;custom-rules/\nConfigures the input format for when a string is passed in as a target object. This option determines if the target object is deserialized into an alternative form.
Use this option with
Assert-PSRule,Invoke-PSRuleorTest-PSRuleTarget. Set this option to eitherYaml,Json,Markdown,PowerShellDatato deserialize as a specific format. The-Formatparameter will override any value set in configuration.When the
-InputObjectparameter or pipeline input is used, strings are treated as plain text by default.FileInfoobjects for supported file formats will be deserialized based on file extension.When the
-InputPathparameter is used, supported file formats will be deserialized based on file extension. The-InputPathparameter can be used with a file path or URL.The following formats are available:
If the
Detectformat is used, the file extension will be used to automatically detect the format. When the file extension can not be determinedDetectis the same asNone.The
Markdownformat does not parse the whole markdown document. Specifically this format deserializes YAML front matter from the top of the document if any exists.The
Fileformat does not deserialize file contents. Each file is returned as an object. Files within.gitsub-directories are ignored. Path specs specified in.gitignoredirectly in the current working path are ignored. ARepositoryInfoobject is generated if the current working path if a.gitsub-directory is present. Additionally, PSRule performs automatic type binding for file objects, using the extension as the type. When files have no extension the whole file name is used.Detect uses the following file extensions:
This option can be specified using:
# PowerShell: Using the Format parameter\n$option = New-PSRuleOption -Format Yaml;\n# PowerShell: Using the Input.Format hashtable key\n$option = New-PSRuleOption -Option @{ 'Input.Format' = 'Yaml' };\n# PowerShell: Using the Format parameter to set YAML\nSet-PSRuleOption -Format Yaml;\n# YAML: Using the input/format property\ninput:\n format: Yaml\n# Bash: Using environment variable\nexport PSRULE_INPUT_FORMAT=Yaml\n# GitHub Actions: Using environment variable\nenv:\n PSRULE_INPUT_FORMAT: Yaml\n
"},{"location":"concepts/PSRule/en-US/about_PSRule_Options/#inputignoregitpath","title":"Input.IgnoreGitPath","text":"# Azure Pipelines: Using environment variable\nvariables:\n- name: PSRULE_INPUT_FORMAT\n value: Yaml\nWhen reading files from an input path, files within the
.gitsub-directory are ignored by default. Files stored within the.gitsub-directory are system repository files used by git. To read files stored within the.gitpath, set this option to$False.This option can be specified using:
# PowerShell: Using the InputIgnoreGitPath parameter\n$option = New-PSRuleOption -InputIgnoreGitPath $False;\n# PowerShell: Using the Input.IgnoreGitPath hashtable key\n$option = New-PSRuleOption -Option @{ 'Input.IgnoreGitPath' = $False };\n# PowerShell: Using the InputIgnoreGitPath parameter to set YAML\nSet-PSRuleOption -InputIgnoreGitPath $False;\n# YAML: Using the input/ignoreGitPath property\ninput:\n ignoreGitPath: false\n# Bash: Using environment variable\nexport PSRULE_INPUT_IGNOREGITPATH=false\n# GitHub Actions: Using environment variable\nenv:\n PSRULE_INPUT_IGNOREGITPATH: false\n
"},{"location":"concepts/PSRule/en-US/about_PSRule_Options/#inputignoreobjectsource","title":"Input.IgnoreObjectSource","text":"# Azure Pipelines: Using environment variable\nvariables:\n- name: PSRULE_INPUT_IGNOREGITPATH\n value: false\nBy default, objects read from file using
inputPathwill be skipped if the file path has been ignored. When set to true, additionally objects with a source path that has been ignored will be skipped. This will includeFileInfoobjects, and objects with a source set using the_PSRule.sourceproperty.File paths to ignore are set by
Input.PathIgnore,Input.IgnoreGitPath, andInput.IgnoreRepositoryCommon.This option can be specified using:
# PowerShell: Using the InputIgnoreObjectSource parameter\n$option = New-PSRuleOption -InputIgnoreObjectSource $True;\n# PowerShell: Using the Input.IgnoreObjectSource hashtable key\n$option = New-PSRuleOption -Option @{ 'Input.IgnoreObjectSource' = $True };\n# PowerShell: Using the InputIgnoreObjectSource parameter to set YAML\nSet-PSRuleOption -InputIgnoreObjectSource $True;\n# YAML: Using the input/ignoreObjectSource property\ninput:\n ignoreObjectSource: true\n# Bash: Using environment variable\nexport PSRULE_INPUT_IGNOREOBJECTSOURCE=true\n# GitHub Actions: Using environment variable\nenv:\n PSRULE_INPUT_IGNOREOBJECTSOURCE: true\n
"},{"location":"concepts/PSRule/en-US/about_PSRule_Options/#inputignorerepositorycommon","title":"Input.IgnoreRepositoryCommon","text":"# Azure Pipelines: Using environment variable\nvariables:\n- name: PSRULE_INPUT_IGNOREOBJECTSOURCE\n value: true\nWhen reading files from an input path, files are discovered recursively. A number of files are commonly found within a private and open-source repositories. In many cases these files are of no interest for analysis and should be ignored by rules. PSRule will ignore the following files by default:
To include these files, set this option to
$False. This option can be specified using:# PowerShell: Using the InputIgnoreRepositoryCommon parameter\n$option = New-PSRuleOption -InputIgnoreRepositoryCommon $False;\n# PowerShell: Using the Input.IgnoreRepositoryCommon hashtable key\n$option = New-PSRuleOption -Option @{ 'Input.IgnoreRepositoryCommon' = $False };\n# PowerShell: Using the InputIgnoreRepositoryCommon parameter to set YAML\nSet-PSRuleOption -InputIgnoreRepositoryCommon $False;\n# YAML: Using the input/ignoreRepositoryCommon property\ninput:\n ignoreRepositoryCommon: false\n# Bash: Using environment variable\nexport PSRULE_INPUT_IGNOREREPOSITORYCOMMON=false\n# GitHub Actions: Using environment variable\nenv:\n PSRULE_INPUT_IGNOREREPOSITORYCOMMON: false\n
"},{"location":"concepts/PSRule/en-US/about_PSRule_Options/#inputignoreunchangedpath","title":"Input.IgnoreUnchangedPath","text":"# Azure Pipelines: Using environment variable\nvariables:\n- name: PSRULE_INPUT_IGNOREREPOSITORYCOMMON\n value: false\nv2.5.0
By default, PSRule will process all files within an input path. For large repositories, this can result in a large number of files being processed. Additionally, for a pull request you may only be interested in files that have changed.
When set to
true, files that have not changed will be ignored. This option can be specified using:# PowerShell: Using the InputIgnoreUnchangedPath parameter\n$option = New-PSRuleOption -InputIgnoreUnchangedPath $True;\n# PowerShell: Using the Input.IgnoreUnchangedPath hashtable key\n$option = New-PSRuleOption -Option @{ 'Input.IgnoreUnchangedPath' = $True };\n# PowerShell: Using the InputIgnoreUnchangedPath parameter to set YAML\nSet-PSRuleOption -InputIgnoreUnchangedPath $True;\n# YAML: Using the input/ignoreUnchangedPath property\ninput:\n ignoreUnchangedPath: true\n# Bash: Using environment variable\nexport PSRULE_INPUT_IGNOREUNCHANGEDPATH=true\n# GitHub Actions: Using environment variable\nenv:\n PSRULE_INPUT_IGNOREUNCHANGEDPATH: true\n
"},{"location":"concepts/PSRule/en-US/about_PSRule_Options/#inputobjectpath","title":"Input.ObjectPath","text":"# Azure Pipelines: Using environment variable\nvariables:\n- name: PSRULE_INPUT_IGNOREUNCHANGEDPATH\n value: true\nThe object path to a property to use instead of the pipeline object.
By default, PSRule processes objects passed from the pipeline against selected rules. When this option is set, instead of evaluating the pipeline object, PSRule looks for a property of the pipeline object specified by
ObjectPathand uses that instead. If the property specified byObjectPathis a collection/ array, then each item is evaluated separately.If the property specified by
ObjectPathdoes not exist, PSRule skips the object.When using
Invoke-PSRule,Test-PSRuleTarget, andAssert-PSRulethe-ObjectPathparameter will override any value set in configuration.This option can be specified using:
# PowerShell: Using the ObjectPath parameter\n$option = New-PSRuleOption -ObjectPath 'items';\n# PowerShell: Using the Input.ObjectPath hashtable key\n$option = New-PSRuleOption -Option @{ 'Input.ObjectPath' = 'items' };\n# PowerShell: Using the ObjectPath parameter to set YAML\nSet-PSRuleOption -ObjectPath 'items';\n# YAML: Using the input/objectPath property\ninput:\n objectPath: items\n# Bash: Using environment variable\nexport PSRULE_INPUT_OBJECTPATH=items\n# GitHub Actions: Using environment variable\nenv:\n PSRULE_INPUT_OBJECTPATH: items\n
"},{"location":"concepts/PSRule/en-US/about_PSRule_Options/#inputpathignore","title":"Input.PathIgnore","text":"# Azure Pipelines: Using environment variable\nvariables:\n- name: PSRULE_INPUT_OBJECTPATH\n value: items\nIgnores input files that match the path spec when using
-InputPath. If specified, files that match the path spec will not be processed. By default, all files are processed.For example, ignoring file extensions:
input:\n pathIgnore:\n # Exclude files with these extensions\n - '*.md'\n - '*.png'\n # Exclude specific configuration files\n - 'bicepconfig.json'\nFor example, ignoring all files with exceptions:
input:\n pathIgnore:\n # Exclude all files\n - '*'\n # Only process deploy.bicep files\n - '!**/deploy.bicep'\nThis option can be specified using:
# PowerShell: Using the InputPathIgnore parameter\n$option = New-PSRuleOption -InputPathIgnore '*.Designer.cs';\n# PowerShell: Using the Input.PathIgnore hashtable key\n$option = New-PSRuleOption -Option @{ 'Input.PathIgnore' = '*.Designer.cs' };\n# PowerShell: Using the InputPathIgnore parameter to set YAML\nSet-PSRuleOption -InputPathIgnore '*.Designer.cs';\n# YAML: Using the input/pathIgnore property\ninput:\n pathIgnore:\n - '*.Designer.cs'\n# Bash: Using environment variable\nexport PSRULE_INPUT_PATHIGNORE=*.Designer.cs\n# GitHub Actions: Using environment variable\nenv:\n PSRULE_INPUT_PATHIGNORE: '*.Designer.cs'\n
"},{"location":"concepts/PSRule/en-US/about_PSRule_Options/#inputtargettype","title":"Input.TargetType","text":"# Azure Pipelines: Using environment variable\nvariables:\n- name: PSRULE_INPUT_PATHIGNORE\n value: '*.Designer.cs'\nFilters input objects by TargetType.
If specified, only objects with the specified TargetType are processed. Objects that do not match TargetType are ignored. If multiple values are specified, only one TargetType must match. This option is not case-sensitive.
By default, all objects are processed.
To change the field TargetType is bound to set the
Binding.TargetTypeoption.When using
Invoke-PSRule,Test-PSRuleTarget, andAssert-PSRulethe-TargetTypeparameter will override any value set in configuration.This option can be specified using:
# PowerShell: Using the InputTargetType parameter\n$option = New-PSRuleOption -InputTargetType 'virtualMachine', 'virtualNetwork';\n# PowerShell: Using the Input.TargetType hashtable key\n$option = New-PSRuleOption -Option @{ 'Input.TargetType' = 'virtualMachine', 'virtualNetwork' };\n# PowerShell: Using the InputTargetType parameter to set YAML\nSet-PSRuleOption -InputTargetType 'virtualMachine', 'virtualNetwork';\n# YAML: Using the input/targetType property\ninput:\n targetType:\n - virtualMachine\n# Bash: Using environment variable\nexport PSRULE_INPUT_TARGETTYPE=virtualMachine;virtualNetwork\n# GitHub Actions: Using environment variable\nenv:\n PSRULE_INPUT_TARGETTYPE: virtualMachine;virtualNetwork\n
"},{"location":"concepts/PSRule/en-US/about_PSRule_Options/#logginglimitdebug","title":"Logging.LimitDebug","text":"# Azure Pipelines: Using environment variable\nvariables:\n- name: PSRULE_INPUT_TARGETTYPE\n value: virtualMachine;virtualNetwork\nLimits debug messages to a list of named debug scopes.
When using the
-Debugswitch or preference variable, by default PSRule cmdlets log all debug output. When using debug output for debugging a specific rule, it may be helpful to limit debug message to a specific rule.To identify a rule to include in debug output use the rule name.
The following built-in scopes exist in addition to rule names:
This option can be specified using:
# PowerShell: Using the LoggingLimitDebug parameter\n$option = New-PSRuleOption -LoggingLimitDebug Rule1, Rule2;\n# PowerShell: Using the Logging.LimitDebug hashtable key\n$option = New-PSRuleOption -Option @{ 'Logging.LimitDebug' = Rule1, Rule2 };\n# PowerShell: Using the LoggingLimitDebug parameter to set YAML\nSet-PSRuleOption -LoggingLimitDebug Rule1, Rule2;\n
"},{"location":"concepts/PSRule/en-US/about_PSRule_Options/#logginglimitverbose","title":"Logging.LimitVerbose","text":"# YAML: Using the logging/limitDebug property\nlogging:\n limitDebug:\n - Rule1\n - Rule2\nLimits verbose messages to a list of named verbose scopes.
When using the
-Verboseswitch or preference variable, by default PSRule cmdlets log all verbose output. When using verbose output for troubleshooting a specific rule, it may be helpful to limit verbose messages to a specific rule.To identify a rule to include in verbose output use the rule name.
The following built-in scopes exist in addition to rule names:
This option can be specified using:
# PowerShell: Using the LoggingLimitVerbose parameter\n$option = New-PSRuleOption -LoggingLimitVerbose Rule1, Rule2;\n# PowerShell: Using the Logging.LimitVerbose hashtable key\n$option = New-PSRuleOption -Option @{ 'Logging.LimitVerbose' = Rule1, Rule2 };\n# PowerShell: Using the LoggingLimitVerbose parameter to set YAML\nSet-PSRuleOption -LoggingLimitVerbose Rule1, Rule2;\n
"},{"location":"concepts/PSRule/en-US/about_PSRule_Options/#loggingrulefail","title":"Logging.RuleFail","text":"# YAML: Using the logging/limitVerbose property\nlogging:\n limitVerbose:\n - Rule1\n - Rule2\nWhen an object fails a rule condition the results are written to output as a structured object marked with the outcome of Fail. If the rule executed successfully regardless of outcome no other informational messages are shown by default.
In some circumstances such as a continuous integration (CI) pipeline, it may be preferable to see informational messages or abort the CI process if one or more Fail outcomes are returned.
By settings this option, error, warning or information messages will be generated for each rule fail outcome in addition to structured output. By default, outcomes are not logged to an informational stream (i.e. None).
The following streams available:
This option can be specified using:
# PowerShell: Using the LoggingRuleFail parameter\n$option = New-PSRuleOption -LoggingRuleFail Error;\n# PowerShell: Using the Logging.RuleFail hashtable key\n$option = New-PSRuleOption -Option @{ 'Logging.RuleFail' = 'Error' };\n# PowerShell: Using the LoggingRuleFail parameter to set YAML\nSet-PSRuleOption -LoggingRuleFail Error;\n
"},{"location":"concepts/PSRule/en-US/about_PSRule_Options/#loggingrulepass","title":"Logging.RulePass","text":"# YAML: Using the logging/ruleFail property\nlogging:\n ruleFail: Error\nWhen an object passes a rule condition the results are written to output as a structured object marked with the outcome of Pass. If the rule executed successfully regardless of outcome no other informational messages are shown by default.
In some circumstances such as a continuous integration (CI) pipeline, it may be preferable to see informational messages.
By settings this option, error, warning or information messages will be generated for each rule pass outcome in addition to structured output. By default, outcomes are not logged to an informational stream (i.e. None).
The following streams available:
This option can be specified using:
# PowerShell: Using the LoggingRulePass parameter\n$option = New-PSRuleOption -LoggingRulePass Information;\n# PowerShell: Using the Logging.RulePass hashtable key\n$option = New-PSRuleOption -Option @{ 'Logging.RulePass' = 'Information' };\n# PowerShell: Using the LoggingRulePass parameter to set YAML\nSet-PSRuleOption -LoggingRulePass Information;\n
"},{"location":"concepts/PSRule/en-US/about_PSRule_Options/#outputas","title":"Output.As","text":"# YAML: Using the logging/rulePass property\nlogging:\n rulePass: Information\nConfigures the type of results to produce.
This option only applies to
Invoke-PSRuleandAssert-PSRule.Invoke-PSRuleandAssert-PSRulealso include a-Asparameter to set this option at runtime. If specified, the-Asparameter take precedence, over this option.The following options are available:
This option can be specified using:
# PowerShell: Using the OutputAs parameter\n$option = New-PSRuleOption -OutputAs Summary;\n# PowerShell: Using the Output.As hashtable key\n$option = New-PSRuleOption -Option @{ 'Output.As' = 'Summary' };\n# PowerShell: Using the OutputAs parameter to set YAML\nSet-PSRuleOption -OutputAs Summary;\n# YAML: Using the output/as property\noutput:\n as: Summary\n# Bash: Using environment variable\nexport PSRULE_OUTPUT_AS=Summary\n# GitHub Actions: Using environment variable\nenv:\n PSRULE_OUTPUT_AS: Summary\n
"},{"location":"concepts/PSRule/en-US/about_PSRule_Options/#outputbanner","title":"Output.Banner","text":"# Azure Pipelines: Using environment variable\nvariables:\n- name: PSRULE_OUTPUT_AS\n value: Summary\nThe information displayed for PSRule banner. This option is only applicable when using
Assert-PSRulecmdlet.The following information can be shown or hidden by configuring this option.
Additionally the following rollup options exist:
This option can be configured using one of the named values described above. Alternatively, this value can be configured by specifying a bit mask as an integer. For example
6would showSource, andSupportLinks.This option can be specified using:
# PowerShell: Using the OutputBanner parameter\n$option = New-PSRuleOption -OutputBanner Minimal;\n# PowerShell: Using the Output.Banner hashtable key\n$option = New-PSRuleOption -Option @{ 'Output.Banner' = 'Minimal' };\n# PowerShell: Using the OutputBanner parameter to set YAML\nSet-PSRuleOption -OutputBanner Minimal;\n# YAML: Using the output/banner property\noutput:\n banner: Minimal\n# Bash: Using environment variable\nexport PSRULE_OUTPUT_BANNER=Minimal\n# GitHub Actions: Using environment variable\nenv:\n PSRULE_OUTPUT_BANNER: Minimal\n
"},{"location":"concepts/PSRule/en-US/about_PSRule_Options/#outputculture","title":"Output.Culture","text":"# Azure Pipelines: Using environment variable\nvariables:\n- name: PSRULE_OUTPUT_BANNER\n value: Minimal\nSpecified the name of one or more cultures to use for generating output. When multiple cultures are specified, the first matching culture will be used. If a culture is not specified, PSRule will use the current PowerShell culture.
PSRule cmdlets also include a
-Cultureparameter to set this option at runtime. If specified, the-Cultureparameter take precedence, over this option.To get a list of cultures use the
Get-Culture -ListAvailablecmdlet.This option can be specified using:
# PowerShell: Using the OutputCulture parameter\n$option = New-PSRuleOption -OutputCulture 'en-AU';\n# PowerShell: Using the Output.Culture hashtable key\n$option = New-PSRuleOption -Option @{ 'Output.Culture' = 'en-AU' };\n# PowerShell: Using the OutputCulture parameter to set YAML\nSet-PSRuleOption -OutputCulture 'en-AU', 'en-US';\n# YAML: Using the output/culture property\noutput:\n culture: [ 'en-AU', 'en-US' ]\n# Bash: Using environment variable\nexport PSRULE_OUTPUT_CULTURE=en-AU;en-US\n# GitHub Actions: Using environment variable\nenv:\n PSRULE_OUTPUT_CULTURE: en-AU;en-US\n
"},{"location":"concepts/PSRule/en-US/about_PSRule_Options/#outputencoding","title":"Output.Encoding","text":"# Azure Pipelines: Using environment variable\nvariables:\n- name: PSRULE_OUTPUT_CULTURE\n value: en-AU;en-US\nConfigures the encoding used when output is written to file. This option has no affect when
Output.Pathis not set.The following encoding options are available:
This option can be specified using:
# PowerShell: Using the OutputEncoding parameter\n$option = New-PSRuleOption -OutputEncoding UTF8;\n# PowerShell: Using the Output.Format hashtable key\n$option = New-PSRuleOption -Option @{ 'Output.Encoding' = 'UTF8' };\n# PowerShell: Using the OutputEncoding parameter to set YAML\nSet-PSRuleOption -OutputEncoding UTF8;\n# YAML: Using the output/encoding property\noutput:\n encoding: UTF8\n# Bash: Using environment variable\nexport PSRULE_OUTPUT_ENCODING=UTF8\n# GitHub Actions: Using environment variable\nenv:\n PSRULE_OUTPUT_ENCODING: UTF8\n
"},{"location":"concepts/PSRule/en-US/about_PSRule_Options/#outputfooter","title":"Output.Footer","text":"# Azure Pipelines: Using environment variable\nvariables:\n- name: PSRULE_OUTPUT_ENCODING\n value: UTF8\nThe information displayed for PSRule footer. This option is only applicable when using
Assert-PSRulecmdlet.The following information can be shown or hidden by configuring this option.
Additionally the following rollup options exist:
This option can be configured using one of the named values described above. Alternatively, this value can be configured by specifying a bit mask as an integer. For example
3would showRunInfo, andRuleCount.This option can be specified using:
# PowerShell: Using the OutputFooter parameter\n$option = New-PSRuleOption -OutputFooter RuleCount;\n# PowerShell: Using the Output.Footer hashtable key\n$option = New-PSRuleOption -Option @{ 'Output.Footer' = 'RuleCount' };\n# PowerShell: Using the OutputFooter parameter to set YAML\nSet-PSRuleOption -OutputFooter RuleCount;\n# YAML: Using the output/footer property\noutput:\n footer: RuleCount\n# Bash: Using environment variable\nexport PSRULE_OUTPUT_FOOTER=RuleCount\n# GitHub Actions: Using environment variable\nenv:\n PSRULE_OUTPUT_FOOTER: RuleCount\n
"},{"location":"concepts/PSRule/en-US/about_PSRule_Options/#outputformat","title":"Output.Format","text":"# Azure Pipelines: Using environment variable\nvariables:\n- name: PSRULE_OUTPUT_FOOTER\n value: RuleCount\nConfigures the format that results will be presented in. This option applies to
Invoke-PSRule,Assert-PSRule,Get-PSRuleandGet-PSRuleBaseline. This options is ignored by other cmdlets.The following format options are available:
The Wide format is ignored by
Assert-PSRule.Get-PSRuleonly acceptsNone,Wide,YamlandJson. Usage of other formats are treated asNone.The
Get-PSRuleBaselinecmdlet only acceptsNoneorYaml. TheExport-PSRuleBaselinecmdlet only acceptsYaml.This option can be specified using:
# PowerShell: Using the OutputFormat parameter\n$option = New-PSRuleOption -OutputFormat Yaml;\n# PowerShell: Using the Output.Format hashtable key\n$option = New-PSRuleOption -Option @{ 'Output.Format' = 'Yaml' };\n# PowerShell: Using the OutputFormat parameter to set YAML\nSet-PSRuleOption -OutputFormat Yaml;\n# YAML: Using the output/format property\noutput:\n format: Yaml\n# Bash: Using environment variable\nexport PSRULE_OUTPUT_FORMAT=Yaml\n# GitHub Actions: Using environment variable\nenv:\n PSRULE_OUTPUT_FORMAT: Yaml\n
"},{"location":"concepts/PSRule/en-US/about_PSRule_Options/#outputoutcome","title":"Output.Outcome","text":"# Azure Pipelines: Using environment variable\nvariables:\n- name: PSRULE_OUTPUT_FORMAT\n value: Yaml\nFilters output to include results with the specified outcome. The following outcome options are available:
Additionally the following rollup options exist:
This option can be specified using:
# PowerShell: Using the OutputOutcome parameter\n$option = New-PSRuleOption -OutputOutcome Fail;\n# PowerShell: Using the Output.Outcome hashtable key\n$option = New-PSRuleOption -Option @{ 'Output.Outcome' = 'Fail' };\n# PowerShell: Using the OutputOutcome parameter to set YAML\nSet-PSRuleOption -OutputOutcome Fail;\n# YAML: Using the output/outcome property\noutput:\n outcome: 'Fail'\n# Bash: Using environment variable\nexport PSRULE_OUTPUT_OUTCOME=Fail\n# GitHub Actions: Using environment variable\nenv:\n PSRULE_OUTPUT_OUTCOME: Fail\n
"},{"location":"concepts/PSRule/en-US/about_PSRule_Options/#outputpath","title":"Output.Path","text":"# Azure Pipelines: Using environment variable\nvariables:\n- name: PSRULE_OUTPUT_OUTCOME\n value: Fail\nSpecifies the output file path to write results. Directories along the file path will automatically be created if they do not exist.
This option only applies to
Invoke-PSRule.Invoke-PSRulealso includes a parameter-OutputPathto set this option at runtime. If specified, the-OutputPathparameter take precedence, over this option.Syntax:
output:\n path: string\nDefault:
output:\n path: null\nThis option can be specified using:
# PowerShell: Using the OutputPath parameter\n$option = New-PSRuleOption -OutputPath 'out/results.yaml';\n# PowerShell: Using the Output.Path hashtable key\n$option = New-PSRuleOption -Option @{ 'Output.Path' = 'out/results.yaml' };\n# PowerShell: Using the OutputPath parameter to set YAML\nSet-PSRuleOption -OutputPath 'out/results.yaml';\n# YAML: Using the output/path property\noutput:\n path: 'out/results.yaml'\n# Bash: Using environment variable\nexport PSRULE_OUTPUT_PATH=out/results.yaml\n# GitHub Actions: Using environment variable\nenv:\n PSRULE_OUTPUT_PATH: out/results.yaml\n
"},{"location":"concepts/PSRule/en-US/about_PSRule_Options/#outputsarifproblemsonly","title":"Output.SarifProblemsOnly","text":"# Azure Pipelines: Using environment variable\nvariables:\n- name: PSRULE_OUTPUT_PATH\n value: out/results.yaml\nDetermines if SARIF output only includes rules with fail or error outcomes. By default, only rules with fail or error outcomes are included for compatibility with external tools. To include rules with pass outcomes, set this option to
false. This option only applies when the output format isSarif.Syntax:
output:\n sarifProblemsOnly: boolean\nDefault:
output:\n sarifProblemsOnly: true\nThis option can be specified using:
# PowerShell: Using the OutputSarifProblemsOnly parameter\n$option = New-PSRuleOption -OutputSarifProblemsOnly $False;\n# PowerShell: Using the Output.SarifProblemsOnly hashtable key\n$option = New-PSRuleOption -Option @{ 'Output.SarifProblemsOnly' = $False };\n# PowerShell: Using the OutputSarifProblemsOnly parameter to set YAML\nSet-PSRuleOption -OutputSarifProblemsOnly $False;\n# YAML: Using the output/sarifProblemsOnly property\noutput:\n sarifProblemsOnly: false\n# Bash: Using environment variable\nexport PSRULE_OUTPUT_SARIFPROBLEMSONLY=false\n# GitHub Actions: Using environment variable\nenv:\n PSRULE_OUTPUT_SARIFPROBLEMSONLY: false\n
"},{"location":"concepts/PSRule/en-US/about_PSRule_Options/#outputstyle","title":"Output.Style","text":"# Azure Pipelines: Using environment variable\nvariables:\n- name: PSRULE_OUTPUT_SARIFPROBLEMSONLY\n value: false\nConfigures the style that results will be presented in.
This option only applies to output generated from
Assert-PSRule.Assert-PSRulealso include a parameter-Styleto set this option at runtime. If specified, the-Styleparameter takes precedence, over this option.The following styles are available:
Detect uses the following logic:
Syntax:
output:\n style: string\nDefault:
output:\n style: Detect\nThis option can be specified using:
# PowerShell: Using the OutputStyle parameter\n$option = New-PSRuleOption -OutputStyle AzurePipelines;\n# PowerShell: Using the Output.Style hashtable key\n$option = New-PSRuleOption -Option @{ 'Output.Style' = 'AzurePipelines' };\n# PowerShell: Using the OutputStyle parameter to set YAML\nSet-PSRuleOption -OutputFormat AzurePipelines;\n# YAML: Using the output/style property\noutput:\n style: AzurePipelines\n# Bash: Using environment variable\nexport PSRULE_OUTPUT_STYLE=AzurePipelines\n# GitHub Actions: Using environment variable\nenv:\n PSRULE_OUTPUT_STYLE: AzurePipelines\n
"},{"location":"concepts/PSRule/en-US/about_PSRule_Options/#outputjobsummarypath","title":"Output.JobSummaryPath","text":"# Azure Pipelines: Using environment variable\nvariables:\n- name: PSRULE_OUTPUT_STYLE\n value: AzurePipelines\nv2.6.0
Configures the file path a job summary will be written to when using
Assert-PSRule. A job summary is a markdown file that summarizes the results of a job. When not specified, a job summary will not be generated.Syntax:
output:\n jobSummaryPath: string\nDefault:
output:\n jobSummaryPath: null\nThis option can be specified using:
# PowerShell: Using the OutputJobSummaryPath parameter\n$option = New-PSRuleOption -OutputJobSummaryPath 'reports/summary.md';\n# PowerShell: Using the Output.JobSummaryPath hashtable key\n$option = New-PSRuleOption -Option @{ 'Output.JobSummaryPath' = 'reports/summary.md' };\n# PowerShell: Using the OutputJobSummaryPath parameter to set YAML\nSet-PSRuleOption -OutputJobSummaryPath 'reports/summary.md';\n# YAML: Using the output/jobSummaryPath property\noutput:\n jobSummaryPath: 'reports/summary.md'\n# Bash: Using environment variable\nexport PSRULE_OUTPUT_JOBSUMMARYPATH='reports/summary.md'\n# PowerShell: Using environment variable\n$env:PSRULE_OUTPUT_JOBSUMMARYPATH = 'reports/summary.md';\n# GitHub Actions: Using environment variable\nenv:\n PSRULE_OUTPUT_JOBSUMMARYPATH: reports/summary.md\n
"},{"location":"concepts/PSRule/en-US/about_PSRule_Options/#outputjsonindent","title":"Output.JsonIndent","text":"# Azure Pipelines: Using environment variable\nvariables:\n- name: PSRULE_OUTPUT_JOBSUMMARYPATH\n value: reports/summary.md\nConfigures the number of spaces to indent JSON properties and elements. The default number of spaces is 0.
This option applies to output generated from
-OutputFormat JsonforGet-PSRuleandInvoke-PSRule. This option also applies to output generated from-OutputPathforAssert-PSRule.The range of indentation accepts a minimum of 0 (machine first) spaces and a maximum of 4 spaces.
This option can be specified using:
# PowerShell: Using the OutputJsonIndent parameter\n$option = New-PSRuleOption -OutputJsonIndent 2;\n# PowerShell: Using the Output.JsonIndent hashtable key\n$option = New-PSRuleOption -Option @{ 'Output.JsonIndent' = 2 };\n# PowerShell: Using the OutputJsonIndent parameter to set YAML\nSet-PSRuleOption -OutputJsonIndent 2;\n# YAML: Using the output/jsonIndent property\noutput:\n jsonIndent: 2\n# Bash: Using environment variable\nexport PSRULE_OUTPUT_JSONINDENT=2\n# PowerShell: Using environment variable\n$env:PSRULE_OUTPUT_JSONINDENT = 2;\n# GitHub Actions: Using environment variable\nenv:\n PSRULE_OUTPUT_JSONINDENT: 2\n
"},{"location":"concepts/PSRule/en-US/about_PSRule_Options/#repositorybaseref","title":"Repository.BaseRef","text":"# Azure Pipelines: Using environment variable\nvariables:\n- name: PSRULE_OUTPUT_JSONINDENT\n value: 2\nThis option is used for specify the base branch for pull requests. When evaluating changes files only PSRule uses this option for comparison with the current branch. By default, the base ref is detected from environment variables set by the build system.
This option can be specified using:
# PowerShell: Using the RepositoryBaseRef parameter\n$option = New-PSRuleOption -RepositoryBaseRef 'main';\n# PowerShell: Using the Repository.BaseRef hashtable key\n$option = New-PSRuleOption -Option @{ 'Repository.BaseRef' = 'main' };\n# PowerShell: Using the RepositoryBaseRef parameter to set YAML\nSet-PSRuleOption -RepositoryBaseRef 'main';\n# YAML: Using the repository/baseRef property\nrepository:\n baseRef: main\n# Bash: Using environment variable\nexport PSRULE_REPOSITORY_BASEREF='main'\n
"},{"location":"concepts/PSRule/en-US/about_PSRule_Options/#repositoryurl","title":"Repository.Url","text":"# PowerShell: Using environment variable\n$env:PSRULE_REPOSITORY_BASEREF = 'main';\nThis option can be configured to set the repository URL reported in output. By default, the repository URL is detected from environment variables set by the build system.
This option can be specified using:
# PowerShell: Using the RepositoryUrl parameter\n$option = New-PSRuleOption -RepositoryUrl 'https://github.com/microsoft/PSRule';\n# PowerShell: Using the Repository.Url hashtable key\n$option = New-PSRuleOption -Option @{ 'Repository.Url' = 'https://github.com/microsoft/PSRule' };\n# PowerShell: Using the RepositoryUrl parameter to set YAML\nSet-PSRuleOption -RepositoryUrl 'https://github.com/microsoft/PSRule';\n# YAML: Using the repository/url property\nrepository:\n url: 'https://github.com/microsoft/PSRule'\n# Bash: Using environment variable\nexport PSRULE_REPOSITORY_URL='https://github.com/microsoft/PSRule'\n
"},{"location":"concepts/PSRule/en-US/about_PSRule_Options/#requires","title":"Requires","text":"# PowerShell: Using environment variable\n$env:PSRULE_REPOSITORY_URL = 'https://github.com/microsoft/PSRule';\nSpecifies module version constraints for running PSRule. When set PSRule will error if a module version is used that does not satisfy the requirements. The format for version constraints are the same as the
Versionassertion method. See [about_PSRule_Assert] for more information.Module version constraints a not enforced prior to PSRule v0.19.0.
The version constraint for a rule module is enforced when the module is included with
-Module. A version constraint does not require a rule module to be included. Use theInclude.Moduleoption to automatically include a rule module.This option can be specified using:
# PowerShell: Using the Requires.module hashtable key\n$option = New-PSRuleOption -Option @{ 'Requires.PSRule' = '>=1.0.0' };\n# YAML: Using the requires property\nrequires:\n PSRule: '>=1.0.0' # Require v1.0.0 or greater.\n PSRule.Rules.Azure: '>=1.0.0' # Require v1.0.0 or greater.\n PSRule.Rules.CAF: '@pre >=0.1.0' # Require stable or pre-releases v0.1.0 or greater.\nThis option can be configured using environment variables. To specify a module version constraint, prefix the module name with
PSRULE_REQUIRES_. When the module name includes a dot (.) use an underscore (_) instead.# Bash: Using environment variable\nexport PSRULE_REQUIRES_PSRULE='>=1.0.0'\nexport PSRULE_REQUIRES_PSRULE_RULES_AZURE='>=1.0.0'\nexport PSRULE_REQUIRES_PSRULE_RULES_CAF='@pre >=0.1.0'\n# GitHub Actions: Using environment variable\nenv:\n PSRULE_REQUIRES_PSRULE: '>=1.0.0'\n PSRULE_REQUIRES_PSRULE_RULES_AZURE: '>=1.0.0'\n PSRULE_REQUIRES_PSRULE_RULES_CAF: '@pre >=0.1.0'\n
"},{"location":"concepts/PSRule/en-US/about_PSRule_Options/#rulebaseline","title":"Rule.Baseline","text":"# Azure Pipelines: Using environment variable\nvariables:\n- name: PSRULE_REQUIRES_PSRULE\n value: '>=1.0.0'\n- name: PSRULE_REQUIRES_PSRULE_RULES_AZURE\n value: '>=1.0.0'\n- name: PSRULE_REQUIRES_PSRULE_RULES_CAF\n value: '@pre >=0.1.0'\nThe name of a default baseline to use for the module. Currently this option can only be set within a module configuration resource.
For example:
"},{"location":"concepts/PSRule/en-US/about_PSRule_Options/#ruleinclude","title":"Rule.Include","text":"---\n# Synopsis: Example module configuration for Enterprise.Rules module.\napiVersion: github.com/microsoft/PSRule/v1\nkind: ModuleConfig\nmetadata:\n name: Enterprise.Rules\nspec:\n rule:\n baseline: Enterprise.Baseline1\nThe name of specific rules to evaluate. If this option is not specified all rules in search paths will be evaluated.
This option can be overridden at runtime by using the
-Namecmdlet parameter.This option can be specified using:
# PowerShell: Using the Rule.Include hashtable key\n$option = New-PSRuleOption -Option @{ 'Rule.Include' = 'Rule1','Rule2' };\n# YAML: Using the rule/include property\nrule:\n include:\n - Rule1\n - Rule2\n# Bash: Using environment variable\nexport PSRULE_RULE_INCLUDE='Rule1;Rule2'\n# GitHub Actions: Using environment variable\nenv:\n PSRULE_RULE_INCLUDE: 'Rule1;Rule2'\n
"},{"location":"concepts/PSRule/en-US/about_PSRule_Options/#ruleincludelocal","title":"Rule.IncludeLocal","text":"# Azure Pipelines: Using environment variable\nvariables:\n- name: PSRULE_RULE_INCLUDE\n value: 'Rule1;Rule2'\nAutomatically include all local rules in the search path unless they have been explicitly excluded. This option will include local rules even when they do not match
Rule.IncludeorRule.Tagfilters. By default, local rules will be filtered withRule.IncludeandRule.Tagfilters.This option is useful when you want to include local rules not included in a baseline.
This option can be specified using:
# PowerShell: Using the RuleIncludeLocal parameter\n$option = New-PSRuleOption -RuleIncludeLocal $True;\n# PowerShell: Using the Rule.IncludeLocal hashtable key\n$option = New-PSRuleOption -Option @{ 'Rule.IncludeLocal' = $True };\n# PowerShell: Using the RuleIncludeLocal parameter to set YAML\nSet-PSRuleOption -RuleIncludeLocal $True;\n# YAML: Using the rule/includeLocal property\nrule:\n includeLocal: true\n# Bash: Using environment variable\nexport PSRULE_RULE_INCLUDELOCAL=true\n# GitHub Actions: Using environment variable\nenv:\n PSRULE_RULE_INCLUDELOCAL: true\n
"},{"location":"concepts/PSRule/en-US/about_PSRule_Options/#ruleexclude","title":"Rule.Exclude","text":"# Azure Pipelines: Using environment variable\nvariables:\n- name: PSRULE_RULE_INCLUDELOCAL\n value: true\nThe name of specific rules to exclude from being evaluated. This will exclude rules specified by
Rule.Includeor discovered from a search path.This option can be specified using:
# PowerShell: Using the Rule.Exclude hashtable key\n$option = New-PSRuleOption -Option @{ 'Rule.Exclude' = 'Rule3','Rule4' };\n# YAML: Using the rule/exclude property\nrule:\n exclude:\n - Rule3\n - Rule4\n# Bash: Using environment variable\nexport PSRULE_RULE_EXCLUDE='Rule3;Rule4'\n# GitHub Actions: Using environment variable\nenv:\n PSRULE_RULE_EXCLUDE: 'Rule3;Rule4'\n
"},{"location":"concepts/PSRule/en-US/about_PSRule_Options/#ruletag","title":"Rule.Tag","text":"# Azure Pipelines: Using environment variable\nvariables:\n- name: PSRULE_RULE_EXCLUDE\n value: 'Rule3;Rule4'\nA set of required key value pairs (tags) that rules must have applied to them to be included.
Multiple values can be specified for the same tag. When multiple values are used, only one must match.
This option can be overridden at runtime by using the
-Tagcmdlet parameter.This option can be specified using:
# PowerShell: Using the Rule.Tag hashtable key\n$option = New-PSRuleOption -Option @{ 'Rule.Tag' = @{ severity = 'Critical','Warning' } };\n# YAML: Using the rule/tag property\nrule:\n tag:\n severity: Critical\n# YAML: Using the rule/tag property, with multiple values\nrule:\n tag:\n severity:\n - Critical\n - Warning\nIn the example above, rules must have a tag of
"},{"location":"concepts/PSRule/en-US/about_PSRule_Options/#suppression","title":"Suppression","text":"severityset to eitherCriticalorWarningto be included.In certain circumstances it may be necessary to exclude or suppress rules from processing objects that are in a known failed state.
PSRule allows objects to be suppressed for a rule by TargetName. Objects that are suppressed are not processed by the rule at all but will continue to be processed by other rules.
Rule suppression complements pre-filtering and pre-conditions.
This option can be specified using:
# PowerShell: Using the SuppressTargetName option with a hashtable\n$option = New-PSRuleOption -SuppressTargetName @{ 'storageAccounts.UseHttps' = 'TestObject1', 'TestObject3' };\n# YAML: Using the suppression property\nsuppression:\n storageAccounts.UseHttps:\n targetName:\n - TestObject1\n - TestObject3\nIn both of the above examples,
TestObject1andTestObject3have been suppressed from being processed by a rule namedstorageAccounts.UseHttps.When to use rule suppression:
When not to use rule suppression:
An example of pre-filtering:
# Define objects to validate\n$items = @();\n$items += [PSCustomObject]@{ Name = 'Fridge'; Type = 'Equipment'; Category = 'White goods'; };\n$items += [PSCustomObject]@{ Name = 'Apple'; Type = 'Food'; Category = 'Produce'; };\n$items += [PSCustomObject]@{ Name = 'Carrot'; Type = 'Food'; Category = 'Produce'; };\n\n# Example of pre-filtering, only food items are sent to Invoke-PSRule\n$items | Where-Object { $_.Type -eq 'Food' } | Invoke-PSRule;\nAn example of pre-conditions:
"},{"location":"concepts/PSRule/en-US/about_PSRule_Options/#examples","title":"Examples","text":""},{"location":"concepts/PSRule/en-US/about_PSRule_Options/#example-ps-ruleyaml","title":"Example ps-rule.yaml","text":"# A rule with a pre-condition to only process produce\nRule 'isFruit' -If { $TargetObject.Category -eq 'Produce' } {\n # Condition to determine if the object is fruit\n $TargetObject.Name -in 'Apple', 'Orange', 'Pear'\n}\n
"},{"location":"concepts/PSRule/en-US/about_PSRule_Options/#default-ps-ruleyaml","title":"Default ps-rule.yaml","text":"#\n# PSRule example configuration\n#\n\n# Configures the repository\nrepository:\n url: https://github.com/microsoft/PSRule\n baseRef: main\n\n# Configure required module versions\nrequires:\n PSRule.Rules.Azure: '>=1.1.0'\n\n# Configure convention options\nconvention:\n include:\n - 'Convention1'\n\n# Configure execution options\nexecution:\n hashAlgorithm: SHA256\n duplicateResourceId: Warn\n languageMode: ConstrainedLanguage\n suppressionGroupExpired: Error\n restrictScriptSource: ModuleOnly\n\n# Configure include options\ninclude:\n module:\n - 'PSRule.Rules.Azure'\n path: [ ]\n\n# Configures input options\ninput:\n format: Yaml\n ignoreGitPath: false\n ignoreObjectSource: true\n ignoreRepositoryCommon: false\n ignoreUnchangedPath: true\n objectPath: items\n pathIgnore:\n - '*.Designer.cs'\n targetType:\n - Microsoft.Compute/virtualMachines\n - Microsoft.Network/virtualNetworks\n\n# Configures outcome logging options\nlogging:\n limitDebug:\n - Rule1\n - Rule2\n limitVerbose:\n - Rule1\n - Rule2\n ruleFail: Error\n rulePass: Information\n\noutput:\n as: Summary\n banner: Minimal\n culture:\n - en-US\n encoding: UTF8\n footer: RuleCount\n format: Json\n jobSummaryPath: reports/summary.md\n outcome: Fail\n sarifProblemsOnly: false\n style: GitHubActions\n\n# Configure rule suppression\nsuppression:\n storageAccounts.UseHttps:\n targetName:\n - TestObject1\n - TestObject3\n\n# Configure baseline options\nbinding:\n field:\n id:\n - ResourceId\n - AlternativeId\n ignoreCase: false\n nameSeparator: '::'\n preferTargetInfo: true\n targetName:\n - ResourceName\n - AlternateName\n targetType:\n - ResourceType\n - kind\n useQualifiedName: true\n\nconfiguration:\n appServiceMinInstanceCount: 2\n\nrule:\n include:\n - rule1\n - rule2\n includeLocal: true\n exclude:\n - rule3\n - rule4\n tag:\n severity:\n - Critical\n - Warning\n
"},{"location":"concepts/PSRule/en-US/about_PSRule_Options/#links","title":"Links","text":"#\n# PSRule defaults\n#\n\n# Note: Only properties that differ from the default values need to be specified.\n\n# Configure required module versions\nrequires: { }\n\n# Configure convention options\nconvention:\n include: [ ]\n\n# Configure execution options\nexecution:\n hashAlgorithm: SHA512\n aliasReference: Warn\n duplicateResourceId: Error\n invariantCulture: Warn\n languageMode: FullLanguage\n initialSessionState: BuiltIn\n restrictScriptSource: Unrestricted\n ruleInconclusive: Warn\n ruleSuppressed: Warn\n suppressionGroupExpired: Warn\n unprocessedObject: Warn\n\n# Configure include options\ninclude:\n module: [ ]\n path:\n - '.ps-rule/'\n\n# Configures input options\ninput:\n format: Detect\n ignoreGitPath: true\n ignoreObjectSource: false\n ignoreRepositoryCommon: true\n ignoreUnchangedPath: false\n objectPath: null\n pathIgnore: [ ]\n targetType: [ ]\n\n# Configures outcome logging options\nlogging:\n limitDebug: [ ]\n limitVerbose: [ ]\n ruleFail: None\n rulePass: None\n\noutput:\n as: Detail\n banner: Default\n culture: [ ]\n encoding: Default\n footer: Default\n format: None\n jobSummaryPath: null\n outcome: Processed\n sarifProblemsOnly: true\n style: Detect\n\n# Configure rule suppression\nsuppression: { }\n\n# Configure baseline options\nbinding:\n field: { }\n ignoreCase: true\n nameSeparator: '/'\n preferTargetInfo: false\n targetName:\n - TargetName\n - Name\n targetType:\n - PSObject.TypeNames[0]\n useQualifiedName: false\n\nconfiguration: { }\n\nrule:\n include: [ ]\n includeLocal: false\n exclude: [ ]\n tag: { }\nDescribes PSRule rules including how to use and author them.
"},{"location":"concepts/PSRule/en-US/about_PSRule_Rules/#description","title":"Description","text":"PSRule executes rules to validate an object from input either from a file or PowerShell pipeline. The PowerShell pipeline only available when running PSRule directly. PSRule can also be run from a continuous integration (CI) pipeline or Visual Studio Code. When using these methods, the PowerShell pipeline is not available.
To evaluate an object PSRule can use rules defined in script or YAML.
When using script rules:
To learn more about assertion helpers see about_PSRule_Assert.
When using YAML rules:
To learn more about YAML-based expressions see about_PSRule_Expressions.
"},{"location":"concepts/PSRule/en-US/about_PSRule_Rules/#using-pre-conditions","title":"Using pre-conditions","text":"Pre-conditions are used to determine if a rule should be executed. While pre-conditions are not required for each rule, it is a good practice to define them. If a rule does not specify a pre-condition it may be executed against an object it does not expect.
Pre-conditions come in three forms:
Different forms of pre-conditions can be combined. When combining pre-conditions, different forms must be all true (logical AND). i.e. Script AND Type AND Selector must be all be true for the rule to be executed.
Multiple Type and Selector pre-conditions can be specified. If multiple Type and Selector pre-conditions are specified, only one must be true (logical OR).
For example:
# Synopsis: An example script rule with pre-conditions.\nRule 'ScriptRule' -If { $True } -Type 'CustomType1', 'CustomType2' -With 'Selector.1', 'Selector.2' {\n # Rule condition\n}\n---\n# Synopsis: An example YAML rule with pre-conditions.\napiVersion: github.com/microsoft/PSRule/v1\nkind: Rule\nmetadata:\n name: 'YamlRule'\nspec:\n type:\n - 'CustomType1'\n - 'CustomType2'\n with:\n - 'Selector.1'\n - 'Selector.2'\n condition: { }\n[\n {\n // Synopsis: An example YAML rule with pre-conditions.\n \"apiVersion\": \"github.com/microsoft/PSRule/v1\",\n \"kind\": \"Rule\",\n \"metadata\": {\n \"name\": \"YamlRule\"\n },\n \"spec\": {\n \"type\": [\n \"CustomType1\",\n \"CustomType2\"\n ],\n \"with\": [\n \"Selector.1\",\n \"Selector.2\"\n ],\n \"condition\": {}\n }\n }\n]\nPre-conditions are evaluated in the following order: Selector, Type, then Script.
"},{"location":"concepts/PSRule/en-US/about_PSRule_Rules/#defining-script-rules","title":"Defining script rules","text":"To define a script rule use the
Rulekeyword followed by a name and a pair of squiggly brackets{. Within the{ }one or more conditions can be used. Script rule must be defined within.Rule.ps1files. Multiple rules can be defined in a single file by creating multipleRuleblocks. Rule blocks can not be nested within each other.Within the
Ruleblock, define one or more conditions to determine pass or fail of the rule.Syntax:
Rule [-Name] <string> [-Tag <hashtable>] [-When <string[]>] [-Type <string[]>] [-If <scriptBlock>] [-DependsOn <string[]>] [-Configure <hashtable>] [-ErrorAction <ActionPreference>] [-Body] {\n ...\n}\nExample:
"},{"location":"concepts/PSRule/en-US/about_PSRule_Rules/#defining-yaml-rules","title":"Defining YAML rules","text":"# Synopsis: Use a Standard load-balancer with AKS clusters.\nRule 'Azure.AKS.StandardLB' -Type 'Microsoft.ContainerService/managedClusters' -Tag @{ release = 'GA'; ruleSet = '2020_06' } {\n $Assert.HasFieldValue($TargetObject, 'Properties.networkProfile.loadBalancerSku', 'standard');\n}\nTo define a YAML rule use the
Ruleresource in a YAML file. Each rule must be defined within a.Rule.yamlfile following a standard schema. Multiple rules can be defined in a single YAML file by separating each rule with a---.Within the
Ruleresource, theconditionproperty specifies conditions to pass or fail the rule.Syntax:
---\n# Synopsis: {{ Synopsis }}\napiVersion: github.com/microsoft/PSRule/v1\nkind: Rule\nmetadata:\n name: '{{ Name }}'\n tags: { }\nspec:\n type: [ ]\n with: [ ]\n condition: { }\nExample:
"},{"location":"concepts/PSRule/en-US/about_PSRule_Rules/#defining-json-rules","title":"Defining JSON rules","text":"---\n# Synopsis: Use a Standard load-balancer with AKS clusters.\napiVersion: github.com/microsoft/PSRule/v1\nkind: Rule\nmetadata:\n name: 'Azure.AKS.StandardLB'\n tags:\n release: 'GA'\n ruleSet: '2020_06'\nspec:\n type:\n - Microsoft.ContainerService/managedClusters\n condition:\n field: 'Properties.networkProfile.loadBalancerSku'\n equals: 'standard'\nTo define a JSON rule use the
Ruleresource in a JSON file. Each rule must be defined within a.Rule.jsoncfile following a standard schema. One or more rules can be defined in a single JSON array separating each rule in a JSON object.Within the
Ruleresource, theconditionproperty specifies conditions to pass or fail the rule.Rules can also be defined within
.jsonfiles. We recommend using.jsoncto view JSON with Comments in Visual Studio Code.Syntax:
[\n {\n // Synopsis: {{ Synopsis }}\n \"apiVersion\": \"github.com/microsoft/PSRule/v1\",\n \"kind\": \"Rule\",\n \"metadata\": {\n \"name\": \"{{ Name }}\",\n \"tags\": {}\n },\n \"spec\": {\n \"type\": [],\n \"with\": [],\n \"condition\": {}\n }\n }\n]\nExample:
"},{"location":"concepts/PSRule/en-US/about_PSRule_Rules/#links","title":"Links","text":"[\n {\n // Synopsis: Use a Standard load-balancer with AKS clusters.\n \"apiVersion\": \"github.com/microsoft/PSRule/v1\",\n \"kind\": \"Rule\",\n \"metadata\": {\n \"name\": \"Azure.AKS.StandardLB\",\n \"tags\": {\n \"release\": \"GA\",\n \"ruleSet\": \"2020_06\"\n }\n },\n \"spec\": {\n \"type\": [\n \"Microsoft.ContainerService/managedClusters\"\n ],\n \"condition\": {\n \"field\": \"Properties.networkProfile.loadBalancerSku\",\n \"equals\": \"standard\"\n }\n }\n }\n]\nDescribes PSRule Selectors including how to use and author them.
"},{"location":"concepts/PSRule/en-US/about_PSRule_Selectors/#description","title":"Description","text":"PSRule executes rules to validate an object from input. When evaluating an object from input, PSRule can use selectors to perform complex matches of an object.
The following conditions are available:
The following operators are available:
The following comparison properties are available:
To learn more about conditions, operators, and properties see about_PSRule_Expressions.
Currently the following limitations apply:
Selectors can be referenced by name as a rule pre-condition by using the
-Withparameter. For example:Rule 'RuleWithSelector' -With 'BasicSelector' {\n # Rule condition\n}\nSelector pre-conditions can be used together with type and script block pre-conditions. If one or more selector pre-conditions are used, they are evaluated before type or script block pre-conditions.
"},{"location":"concepts/PSRule/en-US/about_PSRule_Selectors/#defining-selectors","title":"Defining selectors","text":"Selectors can be defined with either YAML or JSON format, and can be included with a module or standalone
.Rule.yamlor.Rule.jsoncfile. In either case, define a selector within a file ending with the.Rule.yamlor.Rule.jsoncextension. A selector can be defined side-by-side with other resources such as baselines or module configurations.Selectors can also be defined within
.jsonfiles. We recommend using.jsoncto view JSON with Comments in Visual Studio Code.Use the following template to define a selector:
---\n# Synopsis: {{ Synopsis }}\napiVersion: github.com/microsoft/PSRule/v1\nkind: Selector\nmetadata:\n name: '{{ Name }}'\nspec:\n if: { }\n[\n {\n // Synopsis: {{ Synopsis }}\n \"apiVersion\": \"github.com/microsoft/PSRule/v1\",\n \"kind\": \"Selector\",\n \"metadata\": {\n \"name\": \"{{ Name }}\"\n },\n \"spec\": {\n \"if\": {}\n }\n }\n]\nWithin the
"},{"location":"concepts/PSRule/en-US/about_PSRule_Selectors/#examples","title":"Examples","text":""},{"location":"concepts/PSRule/en-US/about_PSRule_Selectors/#example-selectorsruleyaml","title":"Example Selectors.Rule.yaml","text":"ifobject, one or more conditions or logical operators can be used.
"},{"location":"concepts/PSRule/en-US/about_PSRule_Selectors/#example-selectorsrulejsonc","title":"Example Selectors.Rule.jsonc","text":"# Example Selectors.Rule.yaml\n---\n# Synopsis: Require the CustomValue field.\napiVersion: github.com/microsoft/PSRule/v1\nkind: Selector\nmetadata:\n name: RequireCustomValue\nspec:\n if:\n field: 'CustomValue'\n exists: true\n\n---\n# Synopsis: Require a Name or AlternativeName.\napiVersion: github.com/microsoft/PSRule/v1\nkind: Selector\nmetadata:\n name: RequireName\nspec:\n if:\n anyOf:\n - field: 'AlternateName'\n exists: true\n - field: 'Name'\n exists: true\n\n---\n# Synopsis: Require a specific CustomValue\napiVersion: github.com/microsoft/PSRule/v1\nkind: Selector\nmetadata:\n name: RequireSpecificCustomValue\nspec:\n if:\n field: 'CustomValue'\n in:\n - 'Value1'\n - 'Value2'\n
"},{"location":"concepts/PSRule/en-US/about_PSRule_Selectors/#links","title":"Links","text":"// Example Selectors.Rule.jsonc\n[\n {\n // Synopsis: Require the CustomValue field.\n \"apiVersion\": \"github.com/microsoft/PSRule/v1\",\n \"kind\": \"Selector\",\n \"metadata\": {\n \"name\": \"RequireCustomValue\"\n },\n \"spec\": {\n \"if\": {\n \"field\": \"CustomValue\",\n \"exists\": true\n }\n }\n },\n {\n // Synopsis: Require a Name or AlternativeName.\n \"apiVersion\": \"github.com/microsoft/PSRule/v1\",\n \"kind\": \"Selector\",\n \"metadata\": {\n \"name\": \"RequireName\"\n },\n \"spec\": {\n \"if\": {\n \"anyOf\": [\n {\n \"field\": \"AlternateName\",\n \"exists\": true\n },\n {\n \"field\": \"Name\",\n \"exists\": true\n }\n ]\n }\n }\n },\n {\n // Synopsis: Require a specific CustomValue\n \"apiVersion\": \"github.com/microsoft/PSRule/v1\",\n \"kind\": \"Selector\",\n \"metadata\": {\n \"name\": \"RequireSpecificCustomValue\"\n },\n \"spec\": {\n \"if\": {\n \"field\": \"CustomValue\",\n \"in\": [\n \"Value1\",\n \"Value2\"\n ]\n }\n }\n }\n]\nDescribes PSRule Suppression Groups including how to use and author them.
"},{"location":"concepts/PSRule/en-US/about_PSRule_SuppressionGroups/#description","title":"Description","text":"PSRule executes rules to validate an object from input. When an evaluating each object, PSRule can use suppression groups to suppress rules based on a condition. Suppression groups use a Selector to determine if the rule is suppressed.
"},{"location":"concepts/PSRule/en-US/about_PSRule_SuppressionGroups/#defining-suppression-groups","title":"Defining suppression groups","text":"Suppression groups can be defined using either YAML or JSON format. A suppression group can be in a standalone file or included in a module. Define suppression groups in
.Rule.yamlor.Rule.jsoncfiles. Each suppression group may be defined individually or side-by-side with resources such as rules or baselines.Suppression groups can also be defined within
.jsonfiles. We recommend using.jsoncto view JSON with Comments in Visual Studio Code.Use the following template to define a suppression group:
---\n# Synopsis: {{ Synopsis }}\napiVersion: github.com/microsoft/PSRule/v1\nkind: SuppressionGroup\nmetadata:\n name: '{{ Name }}'\nspec:\n expiresOn: null\n rule: []\n if: { }\n[\n {\n // Synopsis: {{ Synopsis }}\n \"apiVersion\": \"github.com/microsoft/PSRule/v1\",\n \"kind\": \"SuppressionGroup\",\n \"metadata\": {\n \"name\": \"{{ Name }}\"\n },\n \"spec\": {\n \"expiresOn\": null,\n \"rule\": [],\n \"if\": {}\n }\n }\n]\nSet the
synopsisto describe the justification for the suppression. Within therulearray, one or more rule names can be used. If no rules are specified, suppression will occur for all rules. Within theifobject, one or more conditions or logical operators can be used. When theifcondition istruethe object will be suppressed for the current rule.Optionally, an expiry can be set using the
"},{"location":"concepts/PSRule/en-US/about_PSRule_SuppressionGroups/#documentation","title":"Documentation","text":"expiresOnproperty. When the expiry date is reached, the suppression will no longer be applied. To configure an expiry, set a RFC3339 (ISO 8601) formatted date time using the formatyyyy-MM-ddTHH:mm:ssZ.Suppression groups can be configured with a synopsis. When set, the synopsis will be included in output for any suppression warnings that are shown. The synopsis helps provide justification for the suppression, in a short single line message. To set the synopsis, include a comment above the suppression group
apiVersionproperty.Alternatively, a localized synopsis can be provided in a separate markdown file. See about_PSRule_Docs for details.
Some examples of a suppression group synopsis include:
"},{"location":"concepts/PSRule/en-US/about_PSRule_SuppressionGroups/#example-suppressiongroupsrulejsonc","title":"Example SuppressionGroups.Rule.jsonc","text":"# Example SuppressionGroups.Rule.yaml\n\n---\n# Synopsis: Ignore test objects by name.\napiVersion: github.com/microsoft/PSRule/v1\nkind: SuppressionGroup\nmetadata:\n name: SuppressWithTargetName\nspec:\n rule:\n - 'FromFile1'\n - 'FromFile2'\n if:\n name: '.'\n in:\n - 'TestObject1'\n - 'TestObject2'\n\n---\n# Synopsis: Ignore test objects by type.\napiVersion: github.com/microsoft/PSRule/v1\nkind: SuppressionGroup\nmetadata:\n name: SuppressWithTestType\nspec:\n expiresOn: '2030-01-01T00:00:00Z'\n rule:\n - 'FromFile3'\n - 'FromFile5'\n if:\n type: '.'\n equals: 'TestType'\n
"},{"location":"concepts/PSRule/en-US/about_PSRule_SuppressionGroups/#links","title":"Links","text":"// Example SuppressionGroups.Rule.jsonc\n[\n {\n // Synopsis: Ignore test objects by name.\n \"apiVersion\": \"github.com/microsoft/PSRule/v1\",\n \"kind\": \"SuppressionGroup\",\n \"metadata\": {\n \"name\": \"SuppressWithTargetName\"\n },\n \"spec\": {\n \"rule\": [\n \"FromFile1\",\n \"FromFile2\"\n ],\n \"if\": {\n \"name\": \".\",\n \"in\": [\n \"TestObject1\",\n \"TestObject2\"\n ]\n }\n }\n },\n {\n // Synopsis: Ignore test objects by type.\n \"apiVersion\": \"github.com/microsoft/PSRule/v1\",\n \"kind\": \"SuppressionGroup\",\n \"metadata\": {\n \"name\": \"SuppressWithTestType\"\n },\n \"spec\": {\n \"expiresOn\": \"2030-01-01T00:00:00Z\",\n \"rule\": [\n \"FromFile3\",\n \"FromFile5\"\n ],\n \"if\": {\n \"type\": \".\",\n \"equals\": \"TestType\"\n }\n }\n }\n]\nDescribes the automatic variables that can be used within PSRule rule definitions.
"},{"location":"concepts/PSRule/en-US/about_PSRule_Variables/#description","title":"Description","text":"PSRule lets you define rules using PowerShell blocks. A rule is defined within script files by using the
rulekeyword.Within a rule definition, PSRule exposes a number of automatic variables that can be read to assist with rule execution. Overwriting these variables or variable properties is not supported.
These variables are only available while
Invoke-PSRuleis executing.The following variables are available for use:
An assertion helper with methods to evaluate objects. The
$Assertobject provides a set of built-in methods and provides a consistent variable for extension.Each
$Assertmethod returns anAssertResultobject that contains the result of the condition.The following built-in assertion methods are provided:
The
$Assertvariable can only be used within a rule definition block.For detailed information on the assertion helper see about_PSRule_Assert.
Syntax:
$Assert\nExamples:
"},{"location":"concepts/PSRule/en-US/about_PSRule_Variables/#configuration","title":"Configuration","text":"# Synopsis: Determine if $TargetObject is valid against the provided schema\nRule 'UseJsonSchema' {\n $Assert.JsonSchema($TargetObject, 'schemas/PSRule-options.schema.json')\n}\nA dynamic object with properties names that map to configuration values set in the baseline.
When accessing configuration:
The following helper methods are available:
Syntax:
$Configuration.<configurationKey>\n$Configuration.GetStringValues(<configurationKey>)\nExamples:
"},{"location":"concepts/PSRule/en-US/about_PSRule_Variables/#localizeddata","title":"LocalizedData","text":"# Synopsis: This rule uses a threshold stored as $Configuration.appServiceMinInstanceCount\nRule 'appServicePlan.MinInstanceCount' -If { $TargetObject.ResourceType -eq 'Microsoft.Web/serverfarms' } {\n $TargetObject.Sku.capacity -ge $Configuration.appServiceMinInstanceCount\n} -Configure @{ appServiceMinInstanceCount = 2 }\nA dynamic object with properties names that map to localized data messages in a
.psd1file.When using localized data, PSRule loads localized strings as a hashtable from
PSRule-rules.psd1.The following logic is used to locate
PSRule-rules.psd1:When accessing localized data:
Syntax:
$LocalizedData.<messageName>\nExamples:
# Data for rules stored in PSRule-rules.psd1\n@{\n WithLocalizedDataMessage = 'LocalizedMessage for en-ZZ. Format={0}.'\n}\n# Synopsis: Use -f to generate a formatted localized warning\nRule 'WithLocalizedData' {\n Write-Warning -Message ($LocalizedData.WithLocalizedDataMessage -f $TargetObject.Type)\n}\nThis rule returns a warning message similar to:
"},{"location":"concepts/PSRule/en-US/about_PSRule_Variables/#psrule","title":"PSRule","text":"LocalizedMessage for en-ZZ. Format=TestType.\nAn object representing the current context during execution.
The following properties are available for read access:
The following properties are available for read/ write access:
To bind fields that already exist on the target object use custom binding and
Binding.Field. Use custom data to store data that must be calculated during rule execution.The following helper methods are available:
The file format is detected based on the same file formats as the option
Input.Format. i.e. Yaml, Json, Markdown, and PowerShell Data.Syntax:
$PSRule\nExamples:
# Synopsis: This rule determines if the target object matches the naming convention\nRule 'NamingConvention' {\n $PSRule.TargetName.ToLower() -ceq $PSRule.TargetName\n}\n
"},{"location":"concepts/PSRule/en-US/about_PSRule_Variables/#rule","title":"Rule","text":"# Synopsis: Use allowed environment tags\nRule 'CustomData' {\n Recommend 'Environment must be set to an allowed value'\n Within 'Tags.environment' 'production', 'test', 'development'\n\n if ($TargetObject.Tags.environment -in 'prod') {\n $PSRule.Data['targetEnvironment'] = 'production'\n }\n elseif ($TargetObject.Tags.environment -in 'dev', 'develop') {\n $PSRule.Data['targetEnvironment'] = 'development'\n }\n elseif ($TargetObject.Tags.environment -in 'tst', 'testing') {\n $PSRule.Data['targetEnvironment'] = 'test'\n }\n}\nAn object representing the current rule during execution.
The following properties are available for read access:
Syntax:
$Rule\nExamples:
"},{"location":"concepts/PSRule/en-US/about_PSRule_Variables/#targetobject","title":"TargetObject","text":"# Synopsis: This rule determines if the target object matches the naming convention\nRule 'resource.NamingConvention' {\n $PSRule.TargetName.ToLower() -ceq $PSRule.TargetName\n}\nThe value of the pipeline object currently being processed.
$TargetObjectis set by using the-InputObjectparameter ofInvoke-PSRule.When more than one input object is set, each object will be processed sequentially.
Syntax:
$TargetObject\nExamples:
"},{"location":"concepts/PSRule/en-US/about_PSRule_Variables/#links","title":"Links","text":"# Synopsis: Check that sku capacity is set to at least 2\nRule 'HasMinInstances' {\n $TargetObject.Sku.capacity -ge 2\n}\nAbstract
PSRule provides a command-line interface (CLI) to run rules and analyze results. This article describes the commands available in the CLI.
For details on installing the PSRule CLI, see Install PSRule.
"},{"location":"concepts/cli/#commands","title":"Commands","text":"The following commands are available in the CLI:
--version","text":"Show the version information for PSRule.
For example:
"},{"location":"concepts/cli/#global-options","title":"Global options","text":"ps-rule --version\nThe following global options can be used with any command:
"},{"location":"concepts/cli/#-option","title":"--option","text":"Specifies the path to an options file. By default, the CLI will look for a file named
"},{"location":"concepts/cli/#-h-help","title":"ps-rule.yamlin the current directory.-?|-h|--help","text":"Display help and usage information for the PSRule CLI and commands. To display help for a specific command, use
--helpwith the command name.For example:
"},{"location":"concepts/cli/#-verbose","title":"ps-rule run --help\n--verbose","text":"Display verbose output for the selected command.
"},{"location":"concepts/cli/#-debug","title":"--debug","text":"Display debug output for the selected command.
"},{"location":"concepts/cli/module/","title":"ps-rule module","text":"Abstract
Use the
"},{"location":"concepts/cli/module/#usage","title":"Usage","text":"PSRule CLI command-linemodulecommand to manage or restore modules tracked by the module lock file and configured options. (ps-rule.lock.json). The module lock file, provides consistent module versions across multiple machines and environments. For more information, see Lock file.ps-rule module [subcommand] [options]\nTo use the
modulecommand, choose one of the available subcommands:module init","text":"Initialize a new lock file based on existing options. Using this command, the module lock file is created or updated.
If
ps-rule.yamloption are configured to included module (Include.Modules), these a automatically added to the lock file. Any required version constraints set by theRequiresoption are taken into consideration.Optional parameters:
For example:
PSRule CLI command-lineps-rule module init\nFor example, force the creation of a new lock file, even if one already exists:
PSRule CLI command-line
"},{"location":"concepts/cli/module/#module-list","title":"ps-rule module init --force\nmodule list","text":"List any module and the installed versions from the lock file.
"},{"location":"concepts/cli/module/#module-add","title":"module add","text":"Add one or more modules to the module lock file. If the lock file does not exist, it is created.
By default, the latest stable version of the module is added. Any required version constraints set by the
Requiresoption are taken into consideration.To use a specific module version, use the
--versionargument.Optional parameters:
For example:
PSRule CLI command-lineps-rule module add PSRule.Rules.Azure\nFor example, a specific version of the module is added:
PSRule CLI command-line
"},{"location":"concepts/cli/module/#module-remove","title":"ps-rule module add PSRule.Rules.Azure --version 1.32.1\nmodule remove","text":"Remove one or more modules from the lock file.
For example:
PSRule CLI command-line
"},{"location":"concepts/cli/module/#module-restore","title":"ps-rule module remove PSRule.Rules.Azure\nmodule restore","text":"Restore modules from the module lock file (
ps-rule.lock.json) and configured options.Optional parameters:
For example:
PSRule CLI command-lineps-rule module restore\nFor example, force restore of all modules:
PSRule CLI command-line
"},{"location":"concepts/cli/module/#module-upgrade","title":"ps-rule module restore --force\nmodule upgrade","text":"Upgrade to the latest versions any modules within the lock file.
For example:
PSRule CLI command-line
"},{"location":"concepts/cli/module/#next-steps","title":"Next steps","text":"ps-rule module upgrade\nFor more information on the module lock file, see Lock file.
To find out more about the commands available with the PSRule CLI, see PSRule CLI.
"},{"location":"concepts/cli/run/","title":"ps-rule run","text":"Abstract
Use the
"},{"location":"concepts/cli/run/#usage","title":"Usage","text":"PSRule CLI command-lineruncommand to run rules against an input path and output the results.
"},{"location":"concepts/cli/run/#options","title":"Options","text":""},{"location":"concepts/cli/run/#-input-path-f","title":"ps-rule run [options]\n--input-path|-f","text":"The file or directory path to search for input file to use during a run. By default, this is the current working path.
"},{"location":"concepts/cli/run/#-module-m","title":"--module|-m","text":"The name of one or more modules that contain rules or resources to use during a run.
"},{"location":"concepts/cli/run/#-baseline","title":"--baseline","text":"The name of a specific baseline to use. Currently, only a single baseline can be used during a run.
"},{"location":"concepts/cli/run/#-outcome","title":"--outcome","text":"Specifies the rule results to show in output. By default,
Pass/Fail/Errorresults are shown.Allows filtering of results by outcome. The supported values are:
To specify multiple values, specify the parameter multiple times. For example:
"},{"location":"concepts/cli/run/#-output-o","title":"--outcome Pass --Outcome Fail.--output|-o","text":"Specifies the format to use when outputting results.
"},{"location":"concepts/cli/run/#-output-path","title":"--output-path","text":"Specifies a path to write results to.
"},{"location":"concepts/cli/run/#next-steps","title":"Next steps","text":"To find out more about the commands available with the PSRule CLI, see PSRule CLI.
"},{"location":"expressions/functions/","title":"Functions","text":"Abstract
Functions are an advanced language feature specific to YAML and JSON expressions. That extend the language to allow for more complex use cases with expressions. Functions don't apply to script expressions because PowerShell already has rich support for complex manipulation.
Experimental
Functions are a work in progress and subject to change. We hope to add more functions, broader support, and more detailed documentation in the future. Join or start a discussion to let us know how we can improve this feature going forward.
Functions cover two (2) main scenarios:
It may be necessary to perform minor transformation before evaluating a condition.
Currently functions are only supported on a subset of conditions. The conditions that are supported are:
"},{"location":"expressions/functions/#recommended-content","title":"Recommended content","text":"---\n# Synopsis: An expression function example.\napiVersion: github.com/microsoft/PSRule/v1\nkind: Selector\nmetadata:\n name: Yaml.Fn.Example1\nspec:\n if:\n value:\n $:\n substring:\n path: name\n length: 7\n equals: TestObj\n\n---\n# Synopsis: An expression function example.\napiVersion: github.com/microsoft/PSRule/v1\nkind: Selector\nmetadata:\n name: Yaml.Fn.Example2\nspec:\n if:\n value:\n $:\n configuration: 'ConfigArray'\n count: 5\n\n---\n# Synopsis: An expression function example.\napiVersion: github.com/microsoft/PSRule/v1\nkind: Selector\nmetadata:\n name: Yaml.Fn.Example3\nspec:\n if:\n value:\n $:\n boolean: true\n equals: true\n\n---\n# Synopsis: An expression function example.\napiVersion: github.com/microsoft/PSRule/v1\nkind: Selector\nmetadata:\n name: Yaml.Fn.Example4\nspec:\n if:\n value:\n $:\n concat:\n - path: name\n - string: '-'\n - path: name\n equals: TestObject1-TestObject1\n\n---\n# Synopsis: An expression function example.\napiVersion: github.com/microsoft/PSRule/v1\nkind: Selector\nmetadata:\n name: Yaml.Fn.Example5\nspec:\n if:\n value:\n $:\n integer: 6\n greater: 5\n\n---\n# Synopsis: An expression function example.\napiVersion: github.com/microsoft/PSRule/v1\nkind: Selector\nmetadata:\n name: Yaml.Fn.Example6\nspec:\n if:\n value: TestObject1-TestObject1\n equals:\n $:\n concat:\n - path: name\n - string: '-'\n - path: name\nAbstract
This topic covers sub-selectors which are a PSRule language feature specific to YAML and JSON expressions. They are useful for filtering out objects that you do not want to evaluate. Sub-selectors don't apply to script expressions because PowerShell already has rich support for filtering.
Experimental
Sub-selectors are a work in progress and subject to change. We hope to add broader support, and more detailed documentation in the future. Join or start a discussion to let us know how we can improve this feature going forward.
Sub-selectors cover two (2) main scenarios:
PSRule can process many different types of objects. Rules however, are normally written to test a specific property or type of object. So it is important that rules only run on objects that you want to evaluate. Pre-condition sub-selectors are one way you can determine if a rule should be run.
To use a sub-selector as a pre-condition, use the
whereproperty, directly under thespec. The expressions in the sub-selector follow the same form that you can use in rules.For example:
YAMLJSON---\n# Synopsis: A rule with a sub-selector precondition.\napiVersion: github.com/microsoft/PSRule/v1\nkind: Rule\nmetadata:\n name: Yaml.Subselector.Precondition\nspec:\n where:\n field: 'kind'\n equals: 'api'\n condition:\n field: resources\n count: 10\n{\n // Synopsis: A rule with a sub-selector precondition.\n \"apiVersion\": \"github.com/microsoft/PSRule/v1\",\n \"kind\": \"Rule\",\n \"metadata\": {\n \"name\": \"Json.Subselector.Precondition\"\n },\n \"spec\": {\n \"where\": {\n \"field\": \"kind\",\n \"equals\": \"api\"\n },\n \"condition\": {\n \"field\": \"resources\",\n \"count\": 10\n }\n }\n}\nIn the example:
The rule does not run if the:
Tip
Other types of pre-conditions also exist that allow you to filter based on type or by a shared selector.
"},{"location":"expressions/sub-selectors/#object-filter","title":"Object filter","text":"When you are evaluating an object, you can use sub-selectors to limit the condition. This is helpful when dealing with properties that are a list of items. Properties that contain a list of items may contain a sub-set of items that you want to evaluate.
For example, the object may look like this:
YAMLJSONname: app1\ntype: Microsoft.Web/sites\nresources:\n- name: web\n type: Microsoft.Web/sites/config\n properties:\n detailedErrorLoggingEnabled: true\n{\n \"name\": \"app1\",\n \"type\": \"Microsoft.Web/sites\",\n \"resources\": [\n {\n \"name\": \"web\",\n \"type\": \"Microsoft.Web/sites/config\",\n \"properties\": {\n \"detailedErrorLoggingEnabled\": true\n }\n }\n ]\n}\nA rule to test if any sub-resources with the
YAMLJSONdetailedErrorLoggingEnabledset totrueexist might look like this:---\n# Synopsis: A rule with a sub-selector filter.\napiVersion: github.com/microsoft/PSRule/v1\nkind: Rule\nmetadata:\n name: Yaml.Subselector.Filter\nspec:\n condition:\n field: resources\n where:\n type: '.'\n equals: 'Microsoft.Web/sites/config'\n allOf:\n - field: properties.detailedErrorLoggingEnabled\n equals: true\n{\n // Synopsis: A rule with a sub-selector filter.\n \"apiVersion\": \"github.com/microsoft/PSRule/v1\",\n \"kind\": \"Rule\",\n \"metadata\": {\n \"name\": \"Json.Subselector.Filter\"\n },\n \"spec\": {\n \"condition\": {\n \"field\": \"resources\",\n \"where\": {\n \"type\": \".\",\n \"equals\": \"Microsoft.Web/sites/config\"\n },\n \"allOf\": [\n {\n \"field\": \"properties.detailedErrorLoggingEnabled\",\n \"equals\": true\n }\n ]\n }\n }\n}\nIn the example:
Given the example, is important to understand what happens by default if:
In either of these two cases, the sub-selector will return
falseand fail the rule. The rule fails because there is no secondary conditions that could be used instead.If this was not the desired behavior, you could:
For example:
YAMLJSON---\n# Synopsis: A rule with a sub-selector filter.\napiVersion: github.com/microsoft/PSRule/v1\nkind: Rule\nmetadata:\n name: Yaml.Subselector.FilterOr\nspec:\n condition:\n anyOf:\n\n - field: resources\n where:\n type: '.'\n equals: 'Microsoft.Web/sites/config'\n allOf:\n - field: properties.detailedErrorLoggingEnabled\n equals: true\n\n - field: resources\n exists: false\n{\n // Synopsis: A rule with a sub-selector filter.\n \"apiVersion\": \"github.com/microsoft/PSRule/v1\",\n \"kind\": \"Rule\",\n \"metadata\": {\n \"name\": \"Json.Subselector.FilterOr\"\n },\n \"spec\": {\n \"condition\": {\n \"anyOf\": [\n {\n \"field\": \"resources\",\n \"where\": {\n \"type\": \".\",\n \"equals\": \"Microsoft.Web/sites/config\"\n },\n \"allOf\": [\n {\n \"field\": \"properties.detailedErrorLoggingEnabled\",\n \"equals\": true\n }\n ]\n },\n {\n \"field\": \"resources\",\n \"exists\": false\n }\n ]\n }\n }\n}\nIn the example:
When iterating over a list of items, you may want to determine how many items must match. A quantifier determines how many items in the list match. Matching items must be:
Supported quantifiers are:
For example:
YAMLJSON---\n# Synopsis: A rule with a sub-selector quantifier.\napiVersion: github.com/microsoft/PSRule/v1\nkind: Rule\nmetadata:\n name: Yaml.Subselector.Quantifier\nspec:\n condition:\n field: resources\n where:\n type: '.'\n equals: 'Microsoft.Web/sites/config'\n greaterOrEqual: 1\n allOf:\n - field: properties.detailedErrorLoggingEnabled\n equals: true\n{\n // Synopsis: A rule with a sub-selector quantifier.\n \"apiVersion\": \"github.com/microsoft/PSRule/v1\",\n \"kind\": \"Rule\",\n \"metadata\": {\n \"name\": \"Json.Subselector.Quantifier\"\n },\n \"spec\": {\n \"condition\": {\n \"field\": \"resources\",\n \"where\": {\n \"type\": \".\",\n \"equals\": \"Microsoft.Web/sites/config\"\n },\n \"greaterOrEqual\": 1,\n \"allOf\": [\n {\n \"field\": \"properties.detailedErrorLoggingEnabled\",\n \"equals\": true\n }\n ]\n }\n }\n}\nIn the example:
Describes the language keywords that can be used within PSRule rule definitions.
"},{"location":"keywords/PSRule/en-US/about_PSRule_Keywords/#description","title":"Description","text":"PSRule lets you define rules using PowerShell blocks. To define a rule use the
Rulekeyword.The following are the built-in keywords that can be used within a rule definition:
A subset of built-in keywords can be used within script preconditions:
A
Ruledefinition describes an individual business rule that will be executed against each input object. Input objects can be passed on the PowerShell pipeline or supplied from file.To define a Rule use the
Rulekeyword followed by a name and a pair of squiggly brackets{. Within the{ }one or more conditions can be used.Conditions determine if the input object either Pass or Fail the rule.
Syntax:
Rule [-Name] <string> [-Ref <string>] [-Alias <string[]>] [-Tag <hashtable>] [-When <string[]>] [-Type <string[]>] [-If <scriptBlock>] [-DependsOn <string[]>] [-Configure <hashtable>] [-ErrorAction <ActionPreference>] [-Body] {\n ...\n}\nA condition is any valid PowerShell that return either
$Trueor$False. Optionally, PSRule keywords can be used to help build out conditions quickly. When a rule contains more then one condition, all must return$Truefor the rule to Pass. If any one condition returns$Falsethe rule has failed.The following restrictions apply:
Examples:
# Synopsis: This rule checks for the presence of a name field\nRule 'NameMustExist' {\n Exists 'Name'\n}\n# Synopsis: This rule checks that the title field is valid, when the rule NameMustExist is successful\nRule 'TitleIsValid' -DependsOn 'NameMustExist' {\n Within 'Title' 'Mr', 'Miss', 'Mrs', 'Ms'\n}\n# Synopsis: This rule uses a threshold stored as $Configuration.minInstanceCount\nRule 'HasMinInstances' {\n $TargetObject.Sku.capacity -ge $Configuration.minInstanceCount\n} -Configure @{ minInstanceCount = 2 }\n
"},{"location":"keywords/PSRule/en-US/about_PSRule_Keywords/#exists","title":"Exists","text":"# Synopsis: This rule still passes because errors are ignored\nRule 'WithRuleErrorActionIgnore' -ErrorAction Ignore {\n Write-Error 'Some error';\n $True;\n}\nThe
Existsassertion is used within aRuledefinition to assert that a field or property must exist on the pipeline object.Syntax:
Exists [-Field] <string[]> [-CaseSensitive] [-Not] [-All] [-Reason <string>] [-InputObject <PSObject>]\nExamples:
# Synopsis: Checks for the presence of a name property\nRule 'nameMustExist' {\n Exists 'Name'\n}\n# Synopsis: Checks for the presence of name nested under the metadata property\nRule 'nameMustExist' {\n Exists 'metadata.name'\n}\n# Synopsis: Checks for the presence of name nested under the metadata property\nRule 'nameMustExist' {\n $TargetObject.metadata | Exists 'name'\n}\n# Synopsis: Checks that the NotName property does not exist\nRule 'NotNameMustNotExist' {\n Exists -Not 'NotName'\n}\n# Synopsis: Checks one of Name or AlternativeName properties exist\nRule 'EitherMustExist' {\n Exists 'Name', 'AlternativeName'\n}\n# Synopsis: Checks that both Name and Type properties exist\nRule 'AllMustExist' {\n Exists 'Name', 'Type' -All\n}\nOutput:
If any the specified fields exists then
Existswill return$True, otherwise$False.If
-Notis used, then if any of the fields exist thenExistswill return$Falseotherwise$True.If
"},{"location":"keywords/PSRule/en-US/about_PSRule_Keywords/#match","title":"Match","text":"-Allis used, then then all of the fields must exist, or not with the-Notswitch. If all fields exist thenExistswill return$True, otherwise$False. If-Notis used with-All, if all of the fields existExistswill return$Falseotherwise$True.The
Matchassertion is used within aRuledefinition to assert that the value of a field or property from pipeline data must match one or more regular expressions. To optionally perform a case sensitive match use the-CaseSensitiveswitch, otherwise a case insensitive match will be used.Syntax:
Match [-Field] <string> [-Expression] <string[]> [-CaseSensitive] [-Not] [-Reason <string>] [-InputObject <PSObject>]\nExamples:
# Synopsis: Check that PhoneNumber is complete and formatted correctly\nRule 'validatePhoneNumber' {\n Match 'PhoneNumber' '^(\\+61|0)([0-9] {0,1}){8}[0-9]$'\n}\nOutput:
If any of the specified regular expressions match the field value then
Matchreturns$True, otherwise$False.When
"},{"location":"keywords/PSRule/en-US/about_PSRule_Keywords/#within","title":"Within","text":"-Notis used, if any of the regular expressions match the field value withMatchreturn$False, otherwise$True.The
Withinassertion is used within aRuledefinition to assert that the value of a field or property from pipeline data must equal an item from a supplied list of allowed values. To optionally perform a case sensitive match use the-CaseSensitiveswitch, otherwise a case insensitive match will be used.Syntax:
Within [-Field] <string> [-Not] [-Like] [-Value] <PSObject[]> [-CaseSensitive] [-Reason <string>] [-InputObject <PSObject>]\nExamples:
# Synopsis: Ensure that the title field has one of the allowed values\nRule 'validateTitle' {\n Within 'Title' 'Mr', 'Miss', 'Mrs', 'Ms'\n}\n# Synopsis: Ensure that the title field is not one of the specified values\nRule 'validateTitle' {\n Within 'Title' -Not 'Mr', 'Sir'\n}\n# Synopsis: Ensure that the title field has one of the allowed values\nRule 'validateTitle' {\n Within 'Title' -Like 'Mr', 'M*s'\n}\nOutput:
If any of the values match the field value then
Withinreturns$True, otherwise$False.When
-Notis used, if any of the values match the field value withWithinreturn$False, otherwise$True.When
"},{"location":"keywords/PSRule/en-US/about_PSRule_Keywords/#allof","title":"AllOf","text":"-Likeis used, the field value is matched against one or more wildcard expressions.The
AllOfassertion is used within aRuledefinition to aggregate the result of assertions within a pair of squiggly brackets{ }.AllOfis functionally equivalent to a binary and, where when all of the contained assertions return$True,AllOfwill return$True.Syntax:
AllOf [-Body] {\n <assertion>\n [<assertion>]\n ...\n}\nExamples:
# Synopsis: The Name field must exist and have a value of either John or Jane\nRule 'nameCheck' {\n AllOf {\n Exists 'Name'\n Within 'Name' 'John', 'Jane'\n }\n}\nOutput:
If all of the assertions return
"},{"location":"keywords/PSRule/en-US/about_PSRule_Keywords/#anyof","title":"AnyOf","text":"$TrueAllOf will return$True, otherwise$False.The
AnyOfassertion is used within aRuledefinition to aggregate the result of assertions within a pair of squiggly brackets{ }.AnyOfis functionally equivalent to a binary or, where if any of the contained assertions returns$True,AnyOfwill return$True.Syntax:
AnyOf [-Body] {\n <assertion>\n [<assertion>]\n ...\n}\nExamples:
# Synopsis: The Last or Surname field must exist\nRule 'personCheck' {\n AnyOf {\n Exists 'Last'\n Exists 'Surname'\n }\n}\nOutput:
If any of the assertions return
"},{"location":"keywords/PSRule/en-US/about_PSRule_Keywords/#typeof","title":"TypeOf","text":"$TrueAnyOf will return$True, otherwise$False.The
TypeOfassertion is used within aRuledefinition to evaluate if the pipeline object matches one or more of the supplied type names.Syntax:
TypeOf [-TypeName] <string[]> [-Reason <string>] [-InputObject <PSObject>]\nExamples:
# Synopsis: The object must be a hashtable\nRule 'objectType' {\n TypeOf 'System.Collections.Hashtable'\n}\nOutput:
If any the specified type names match the pipeline object then TypeOf will return
"},{"location":"keywords/PSRule/en-US/about_PSRule_Keywords/#reason","title":"Reason","text":"$True, otherwise$False.The
Reasonkeyword is used within aRuledefinition to provide a message that indicates the reason the rule failed. The reason is included in detailed results.A reason is only included when the rule fails or errors. The outcomes
PassandNonedo not include reason.Use this keyword when you want to implement custom logic. Built-in keywords including
Exists,Match,WithinandTypeOfautomatically include a reason when they fail.Syntax:
Reason [-Text] <string>\nExamples:
# Synopsis: Provide reason the rule failed\nRule 'objectRecommend' {\n Reason 'A minimum of two (2) instances are required'\n $TargetObject.count -ge 2\n}\nOutput:
None.
"},{"location":"keywords/PSRule/en-US/about_PSRule_Keywords/#recommend","title":"Recommend","text":"The
Recommendkeyword is used within aRuledefinition to provide a recommendation to resolve the issue and pass the rule. This may include manual steps to change that state of the object or the desired state accessed by the rule.The recommendation can only be set once per rule. Each object will use the same recommendation.
Syntax:
Recommend [-Text] <string>\nExamples:
# Synopsis: Provide recommendation to resolve the issue\nRule 'objectRecommend' {\n Recommend 'Use at least two (2) instances'\n $TargetObject.count -ge 2\n}\nOutput:
None.
"},{"location":"keywords/PSRule/en-US/about_PSRule_Keywords/#examples","title":"Examples","text":"
"},{"location":"keywords/PSRule/en-US/about_PSRule_Keywords/#links","title":"Links","text":"# Synopsis: App Service Plan has multiple instances\nRule 'appServicePlan.MinInstanceCount' -If { $TargetObject.ResourceType -eq 'Microsoft.Web/serverfarms' } {\n Recommend 'Use at least two (2) instances'\n\n $TargetObject.Sku.capacity -ge 2\n}\nYou can use PSRule to create tests for PowerShell objects piped to PSRule for validation. Each test is called a rule.
PSRule allows you to write rules using YAML, JSON, or PowerShell. Regardless of the format you choose, any combination of YAML, JSON, or PowerShell rules can be used together.
Abstract
This topic covers how to create a rule using YAML, JSON, and PowerShell by example. In this quickstart, will be using native PowerShell objects. For an example of reading objects from disk, continue reading Testing infrastructure.
"},{"location":"quickstart/standalone-rule/#prerequisites","title":"Prerequisites","text":"For this quickstart, PSRule must be installed locally on MacOS, Linux, or Windows. To install PSRule locally, open PowerShell and run the following
PowerShellInstall-Modulecommand. If you don't have PowerShell installed, complete Installing PowerShell first.Install-Module -Name 'PSRule' -Repository PSGallery -Scope CurrentUser\nTip
PowerShell is installed by default on Windows. If these instructions don't work for you, your administrator may have restricted how PowerShell can be used in your environment. You or your administrator may be able to install PSRule for all users as a local administrator. See Getting the modules for instructions on how to do this.
Tip
To make you editing experience even better, consider installing the Visual Studio Code extension.
"},{"location":"quickstart/standalone-rule/#scenario-test-for-image-files","title":"Scenario - Test for image files","text":"In our quickstart scenario, we have been tasked with creating a rule to test for image files. When a file ending with the
.jpgor.pngextension is found the rule should fail.We will be using the following PowerShell code to get a list of files.
PowerShell$pathToSearch = $Env:HOME;\n$files = Get-ChildItem -Path $pathToSearch -File -Recurse;\nInfo
The path to search
"},{"location":"quickstart/standalone-rule/#define-the-file-type-rule","title":"Define the file type rule","text":"$Env:HOMEdefaults to the current user's home directory. This directory is used so this quickstart works on Windows and Linux operating systems. Feel free to update this path to a more suitable directory on your local machine.Before an object can be tested with PSRule, one or more rules must be defined. Each rule is defined in a file named with the suffix
.Rule.yaml,.Rule.jsonc, or.Rule.ps1. Multiple rules can be defined in a single file.A rule that fail on files with
YAMLJSONPowerShell.jpgor.pngextensions is shown in YAML, JSON, and PowerShell formats. You only need to choose one format, however you can choose to create all three to try out each format.Create the
YAMLFileType.Rule.yamlfile with the following contents. This file can be created in Visual Studio Code or any text editor. Make a note of the location you saveFileType.Rule.yaml.---\n# Synopsis: Image files are not permitted.\napiVersion: github.com/microsoft/PSRule/v1\nkind: Rule\nmetadata:\n name: Yaml.FileType\nspec:\n type:\n - System.IO.FileInfo\n condition:\n field: Extension\n notIn:\n - .jpg\n - .png\nCreate the
JSONFileType.Rule.jsoncfile with the following contents. This file can be created in Visual Studio Code or any text editor. Make a note of the location you saveFileType.Rule.jsonc.[\n {\n // Synopsis: Image files are not permitted.\n \"apiVersion\": \"github.com/microsoft/PSRule/v1\",\n \"kind\": \"Rule\",\n \"metadata\": {\n \"name\": \"Json.FileType\"\n },\n \"spec\": {\n \"type\": [\n \"System.IO.FileInfo\"\n ],\n \"condition\": {\n \"field\": \"Extension\",\n \"notIn\": [\n \".jpg\",\n \".png\"\n ]\n }\n }\n }\n]\nCreate the
PowerShellFileType.Rule.ps1file with the following contents. This file can be created in Visual Studio Code, Windows PowerShell ISE, or any text editor. Make a note of the location you saveFileType.Rule.ps1.# Synopsis: Image files are not permitted.\nRule 'PS.FileType' -Type 'System.IO.FileInfo' {\n $Assert.NotIn($TargetObject, 'Extension', @('.jpg', '.png'))\n}\nYou can test the rule by using the
PowerShellInvoke-PSRulecommand. For example:$pathToSearch = $Env:HOME;\n$files = Get-ChildItem -Path $pathToSearch -File -Recurse;\n\n# The path to the rule file. Update this to the location of your saved file.\n$rulePath = 'C:\\temp\\FileType.Rule.ps1'\n# Or the directory can be used to find all rules in the path:\n# $rulePath = 'C:\\temp\\'\n\n# Test the rule\n$files | Invoke-PSRule -Path $rulePath\nAfter running
Invoke-PSRuleyou will get output which includes all files in the pathToSeach. Files with a.jpgor.pngextension should have the outcome ofFail. All other files should report an outcome ofPass.For example:
OutputTargetName: main.html\n\nRuleName Outcome Recommendation\n-------- ------- --------------\nYaml.FileType Pass Image files are not permitted.\n\n TargetName: favicon.png\n\nRuleName Outcome Recommendation\n-------- ------- --------------\nYaml.FileType Fail Image files are not permitted.\nTip
v2.0.0
In our quickstart scenario, we have been tasked to:
We will be using the following PowerShell code to get a list of local services.
PowerShell$services = Get-Service\nNote
This scenario is designed for Windows clients. The PowerShell cmdlet
"},{"location":"quickstart/standalone-rule/#define-a-selector","title":"Define a selector","text":"Get-Serviceis only available on Windows.A selector can be used to filter a list of all services to only services that are set to start automatically. Selectors use YAML or JSON expressions and are similar to rules in many ways. A selector determines if the rule will be run or skipped.
Create the
YAMLService.Rule.yamlfile with the following contents. This file can be created in Visual Studio Code or any text editor. Make a note of the location you saveService.Rule.yaml.---\n# Synopsis: Find services with an automatic start type.\napiVersion: github.com/microsoft/PSRule/v1\nkind: Selector\nmetadata:\n name: Yaml.IsAutomaticService\nspec:\n if:\n field: StartType\n startsWith: Automatic\n convert: true\nCreate the
JSONService.Rule.jsoncfile with the following contents. This file can be created in Visual Studio Code or any text editor. Make a note of the location you saveService.Rule.jsonc.[\n {\n // Synopsis: Find services with an automatic start type.\n \"apiVersion\": \"github.com/microsoft/PSRule/v1\",\n \"kind\": \"Selector\",\n \"metadata\": {\n \"name\": \"Json.IsAutomaticService\"\n },\n \"spec\": {\n \"if\": {\n \"field\": \"StartType\",\n \"startsWith\": \"Automatic\",\n \"convert\": true\n }\n }\n }\n]\nSimilar to the selector, the
YAMLJSONPowerShellStatusfield will be tested to determine if the service isRunning.Append the following contents to the existing
YAMLService.Rule.yamlfile.---\n# Synopsis: Automatic services should be running.\napiVersion: github.com/microsoft/PSRule/v1\nkind: Rule\nmetadata:\n name: Yaml.ServiceStarted\nspec:\n with:\n - Yaml.IsAutomaticService\n condition:\n field: Status\n equals: Running\n convert: true\nUpdate the contents of
JSONService.Rule.jsoncto the following.[\n {\n // Synopsis: Find services with an automatic start type.\n \"apiVersion\": \"github.com/microsoft/PSRule/v1\",\n \"kind\": \"Selector\",\n \"metadata\": {\n \"name\": \"Json.IsAutomaticService\"\n },\n \"spec\": {\n \"if\": {\n \"field\": \"StartType\",\n \"startsWith\": \"Automatic\",\n \"convert\": true\n }\n }\n },\n {\n // Synopsis: Automatic services should be running.\n \"apiVersion\": \"github.com/microsoft/PSRule/v1\",\n \"kind\": \"Rule\",\n \"metadata\": {\n \"name\": \"Json.ServiceStarted\"\n },\n \"spec\": {\n \"with\": [\n \"Json.IsAutomaticService\"\n ],\n \"condition\": {\n \"field\": \"Status\",\n \"equals\": \"Running\",\n \"convert\": true\n }\n }\n }\n]\nCreate the
PowerShellService.Rule.ps1file with the following contents. This file can be created in Visual Studio Code, Windows PowerShell ISE, or any text editor. Make a note of the location you saveService.Rule.ps1.# Synopsis: Automatic services should be running.\nRule 'PS.ServiceStarted' -With 'Yaml.IsAutomaticService' {\n $status = $TargetObject.Status.ToString()\n $Assert.HasFieldValue($status, '.', 'Running')\n}\nYou can test the rule with service object by using the
PowerShellInvoke-PSRulecommand. For example:$services = Get-Service\n\n# The directory path to the rule file. Update this to the location of your saved file.\n$rulePath = 'C:\\temp\\'\n\n# Test the rule\n$services | Invoke-PSRule -Path $rulePath\nAfter running
Invoke-PSRuleyou will get output which include for services that start automatically. Services that areRunningshould pass whereas other stopped services should fail. For manual or disabled services a warning will be generated indicating that no matching rules were found.For example:
OutputTargetName: edgeupdate\n\nRuleName Outcome Recommendation\n-------- ------- --------------\nPS.ServiceStarted Fail Automatic services should be running.\nYaml.ServiceStarted Fail Automatic services should be running.\nJson.ServiceStarted Fail Automatic services should be running.\n\n\n TargetName: EventLog\n\nRuleName Outcome Recommendation\n-------- ------- --------------\nPS.ServiceStarted Pass Automatic services should be running.\nYaml.ServiceStarted Pass Automatic services should be running.\nJson.ServiceStarted Pass Automatic services should be running.\n\nWARNING: Target object 'TermService' has not been processed because no matching rules were found.\nTip
You can disable the warning by setting Execution.UnprocessedObject option. Alternatively you can ignore all warnings by using the
"},{"location":"scenarios/","title":"Getting started with PSRule","text":""},{"location":"scenarios/#define-a-rule","title":"Define a rule","text":"-WarningAction SilentlyContinueparameter.To define a rule, use a
Ruleblock saved to a file with the.Rule.ps1extension.Rule 'NameOfRule' {\n # Rule conditions\n}\nWithin the body of the rule provide one or more conditions. A condition is valid PowerShell that results in
$Trueor$False.For example:
Rule 'isFruit' {\n # Condition to determine if the object is fruit\n $TargetObject.Name -in 'Apple', 'Orange', 'Pear'\n}\nAn optional result message can be added to by using the
Recommendkeyword.Rule 'isFruit' {\n # An recommendation to display in output\n Recommend 'Fruit is only Apple, Orange and Pear'\n\n # Condition to determine if the object is fruit\n $TargetObject.Name -in 'Apple', 'Orange', 'Pear'\n}\nThe rule is saved to a file named
"},{"location":"scenarios/#execute-a-rule","title":"Execute a rule","text":"isFruit.Rule.ps1file. One or more rules can be defined within a single file.To execute the rule use
Invoke-PSRule.For example:
# Define objects to validate\n$items = @();\n$items += [PSCustomObject]@{ Name = 'Fridge' };\n$items += [PSCustomObject]@{ Name = 'Apple' };\n\n# Validate each item using rules saved in current working path\n$items | Invoke-PSRule;\nThe output of this example is:
"},{"location":"scenarios/#additional-options","title":"Additional options","text":"TargetName: Fridge\n\nRuleName Outcome Recommendation\n-------- ------- --------------\nisFruit Fail Fruit is only Apple, Orange and Pear\n\n\n TargetName: Apple\n\nRuleName Outcome Recommendation\n-------- ------- --------------\nisFruit Pass Fruit is only Apple, Orange and Pear\nTo 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\n$items | Invoke-PSRule -Outcome Fail;\nFor a summary of results for each rule use
Invoke-PSRule -As Summary.For example:
# Show rule summary\n$items | Invoke-PSRule -As Summary;\nThe output of this example is:
RuleName Pass Fail Outcome\n-------- ---- ---- -------\nisFruit 1 1 Fail\nAn optional failure reason can be added to the rule block by using the
Reasonkeyword.Rule 'isFruit' {\n # An recommendation to display in output\n Recommend 'Fruit is only Apple, Orange and Pear'\n\n # An failure reason to display for non-fruit\n Reason \"$($PSRule.TargetName) is not fruit.\"\n\n # Condition to determine if the object is fruit\n $TargetObject.Name -in 'Apple', 'Orange', 'Pear'\n}\nTo include the reason with output use
Invoke-PSRule -OutputFormat Wide.For example:
# Show failure reason for failing results\n$items | Invoke-PSRule -OutputFormat Wide;\nThe output of this example is:
TargetName: Fridge\n\nRuleName Outcome Reason Recommendation\n-------- ------- ------ --------------\nisFruit Fail Fridge is not fruit. Fruit is only Apple, Orange and Pear\n\n\n TargetName: Apple\n\nRuleName Outcome Reason Recommendation\n-------- ------- ------ --------------\nisFruit Pass Fruit is only Apple, Orange and Pear\nThe final rule is saved to
"},{"location":"scenarios/#scenarios","title":"Scenarios","text":"isFruit.Rule.ps1.For walk through examples of PSRule usage see:
PSRule makes it easy to validate Infrastructure as Code (IaC) such as Azure resources. For example, Azure resources can be validated to match an internal standard or baseline.
Note
A pre-built module to validate Azure resources already exists. This scenario demonstrates the process and features of PSRule for illustration purposes.
Consider using or contributing these pre-built rule modules instead:
This scenario covers the following:
In this scenario we will use a JSON file:
To generate a similar
resources.jsonfile of your own, the use following command.# Get all resources using the Az modules. Alternatively use Get-AzureRmResource if using AzureRm modules.\n# This command also requires authentication with Connect-AzAccount or Connect-AzureRmAccount\nGet-AzResource -ExpandProperties | ConvertTo-Json -Depth 10 | Set-Content -path .\\resources.json;\nFor this example we ran this command:
"},{"location":"scenarios/azure-resources/azure-resources/#define-rules","title":"Define rules","text":"Get-AzResource -ExpandProperties | ConvertTo-Json -Depth 10 | Set-Content -path docs/scenarios/azure-resources/resources.json;\nTo validate our Azure resources we need to define some rules. Rules are defined by using the
Rulekeyword in a file ending with the.Rule.ps1extension.So start we are going to define a
storageAccounts.UseHttpsrule, which will validate that Azure Storage resources have a Secure Transfer Required enabled.In the example below:
"},{"location":"scenarios/azure-resources/azure-resources/#set-rule-condition","title":"Set rule condition","text":"# Synopsis: Configure storage accounts to only accept encrypted traffic i.e. HTTPS/SMB\nRule 'storageAccounts.UseHttps' {\n # Rule conditions go here\n}\nConditions can be any valid PowerShell expression that results in a
$Trueor$False, just like anIfstatement, but without specifically requiring theIfkeyword to be used.Several PSRule keywords such as
ExistsandAllOfcan supplement PowerShell to quickly build out rules that are easy to read.In
resources.jsonone of our example storage accounts has a propertyProperties.supportsHttpsTrafficOnlyas shown below, which will be how our rule will pass$Trueor fail$FalseAzure resources that we throw at it.{\n \"Name\": \"storage\",\n \"ResourceName\": \"storage\",\n \"ResourceType\": \"Microsoft.Storage/storageAccounts\",\n \"Kind\": \"Storage\",\n \"ResourceGroupName\": \"test-rg\",\n \"Location\": \"eastus2\",\n \"Properties\": {\n \"supportsHttpsTrafficOnly\": false\n }\n}\nIn the example below:
"},{"location":"scenarios/azure-resources/azure-resources/#add-rule-recommendation","title":"Add rule recommendation","text":"# Synopsis: Configure storage accounts to only accept encrypted traffic i.e. HTTPS/SMB\nRule 'storageAccounts.UseHttps' {\n # This property returns true or false, so nothing more needs to be done\n $TargetObject.Properties.supportsHttpsTrafficOnly\n\n # Alternatively this could be written as:\n # $TargetObject.Properties.supportsHttpsTrafficOnly -eq $True\n}\nAdditionally to provide feedback to the person or process running the rules, we can use the
Recommendkeyword to set a message that appears in results.If a recommend message is not provided the synopsis will be used instead.
In the example below:
"},{"location":"scenarios/azure-resources/azure-resources/#filter-with-preconditions","title":"Filter with preconditions","text":"# Synopsis: Configure storage accounts to only accept encrypted traffic i.e. HTTPS/SMB\nRule 'storageAccounts.UseHttps' {\n Recommend 'Storage accounts should only allow secure traffic'\n\n $TargetObject.Properties.supportsHttpsTrafficOnly\n}\nSo far our rule works for a Storage Account, but there are many type of resources that could be returned by calling
Get-AzResource. Most of these resources won't have theProperties.supportsHttpsTrafficOnlyproperty, and if it did, it may use different configuration options instead of justtrueandfalse. This is where preconditions help out.Preconditions can be specified by using the
-Ifparameter when defining a rule. When the rule is executed, if the precondition is$Truethen the rule is processed, otherwise it is skipped.In the example below:
# Synopsis: Configure storage accounts to only accept encrypted traffic i.e. HTTPS/SMB\nRule 'storageAccounts.UseHttps' -If { $TargetObject.ResourceType -eq 'Microsoft.Storage/storageAccounts' } {\n Recommend 'Storage accounts should only allow secure traffic'\n\n $TargetObject.Properties.supportsHttpsTrafficOnly\n}\nSkipped rules have the outcome
"},{"location":"scenarios/azure-resources/azure-resources/#execute-rules","title":"Execute rules","text":"Noneand are not included in output by default. To include skipped rules use the-Outcome Allparameter.With a rule defined, the next step is to execute it. To execute rules, pipe the target object to
Invoke-PSRule.For example:
# Read resources in from file\n$resources = Get-Content -Path .\\resources.json | ConvertFrom-Json;\n\n# Process resources\n$resources | Invoke-PSRule;\nPSRule natively supports reading from YAML and JSON files so this command-line can be simplified to:
Invoke-PSRule -InputPath .\\resources.json;\nYou will notice, we didn't specify the rule. By default PSRule will look for any
.Rule.ps1files in the current working path.Invoke-PSRulesupports-Path,-Nameand-Tagparameters that can be used to specify the path to look for rules in or filter rules if you want to run a subset of the rules.For this example we ran these commands:
Invoke-PSRule -Path docs/scenarios/azure-resources -InputPath docs/scenarios/azure-resources/resources.json;\nOur output looked like this:
TargetName: storage\n\nRuleName Outcome Recommendation\n-------- ------- --------------\nstorageAccounts.UseHttps Fail Storage accounts should only allow secure traffic\nIn our case
"},{"location":"scenarios/azure-resources/azure-resources/#define-helper-functions","title":"Define helper functions","text":"storageAccounts.UseHttpsreturns aFailoutcome because our storage account hassupportsHttpsTrafficOnly=false, which is exactly what should happen.Using helper functions is completely optional and not required in many cases. However, you may prefer to use helper functions when rule conditions or preconditions are complex and hard to understand.
To use helper functions use a
functionblock within a file with a.Rule.ps1extension. Any code within.Rule.ps1files called byInvoke-PSRulewill be executed, however to make it available for use within a rule, a global scope modifier must be used.For functions this is done by prefixing the function name with
global:.For example:
function global:NameOfFunction {\n # Function body\n}\nIn our example, we are going to define a
ResourceTypefunction in a file namedcommon.Rule.ps1. This function will be used by preconditions to check the type of Azure resource.# A custom function to filter by resource type\nfunction global:ResourceType {\n param (\n [String]$ResourceType\n )\n\n process {\n return $TargetObject.ResourceType -eq $ResourceType;\n }\n}\nUpdating our existing
storageAccounts.UseHttpsrule, our rule definition becomes:
"},{"location":"scenarios/azure-resources/azure-resources/#more-information","title":"More information","text":"# Synopsis: Configure storage accounts to only accept encrypted traffic i.e. HTTPS/SMB\nRule 'storageAccounts.UseHttps' -If { ResourceType 'Microsoft.Storage/storageAccounts' } {\n Recommend 'Storage accounts should only allow secure traffic'\n\n $TargetObject.Properties.supportsHttpsTrafficOnly\n}\nThis is an example of how PSRule can be used to validate tags on Azure resources to match an internal tagging standard.
This scenario covers the following:
In this scenario we will use a JSON file:
To generate a similar file of your own, the use following command.
# Get all resources using the Az modules. Alternatively use Get-AzureRmResource if using AzureRm modules.\n# This command also requires authentication with Connect-AzAccount or Connect-AzureRmAccount\nGet-AzResource -ExpandProperties | ConvertTo-Json -Depth 10 | Set-Content -Path .\\resources.json;\nFor this example, we ran this command:
"},{"location":"scenarios/azure-tags/azure-tags/#define-rules","title":"Define rules","text":"Get-AzResource -ExpandProperties | ConvertTo-Json -Depth 10 | Set-Content -Path docs/scenarios/azure-resources/resources.json;\nTo validate our Azure resources, we need to define some rules. Rules are defined by using the
Rulekeyword in a file ending with the.Rule.ps1extension.Our business rules for Azure resource tagging can be defined with the following dot points:
To start we are going to define an
environmentTagrule, which will ensure that the environment tag exists and that the value only uses allowed values.In the example below:
"},{"location":"scenarios/azure-tags/azure-tags/#check-that-tag-exists","title":"Check that tag exists","text":"# Synopsis: Resource must have environment tag\nRule 'environmentTag' {\n # Rule conditions go here\n}\nConditions can be any valid PowerShell expression that results in a
$Trueor$False, just like anIfstatement, but without specifically requiring theIfkeyword to be used.In
resources.jsonone of our example storage accounts has theTagsproperty as shown below, this is how Azure Resource Manager stores tags for a resource. We will use this property as the basis of our rules to determine if the resource is tagged and what the tag value is.{\n \"Name\": \"storage\",\n \"ResourceName\": \"storage\",\n \"ResourceType\": \"Microsoft.Storage/storageAccounts\",\n \"Tags\": {\n \"role\": \"deployment\",\n \"environment\": \"production\"\n }\n}\nPSRule also defines several additional keywords to supplement PowerShell. These additional keywords help to create readable rules that can be built out quickly.
In the example below:
"},{"location":"scenarios/azure-tags/azure-tags/#tag-uses-only-allowed-values","title":"Tag uses only allowed values","text":"# Synopsis: Resource must have environment tag\nRule 'environmentTag' {\n Exists 'Tags.environment' -CaseSensitive\n}\nIn our scenario, we have three environments that our environment tag could be set to. In the next example we will ensure that only allowed environment values are used.
In the example below:
# Synopsis: Resource must have environment tag\nRule 'environmentTag' {\n Exists 'Tags.environment' -CaseSensitive\n Within 'Tags.environment' 'production', 'test', 'development' -CaseSensitive\n}\nAlternatively, instead of using the
Withinkeyword the-cinoperator could be used.Withinprovides additional verbose logging, however either syntax is valid.In the example below:
"},{"location":"scenarios/azure-tags/azure-tags/#tag-value-matches-regular-expression","title":"Tag value matches regular expression","text":"# Synopsis: Resource must have environment tag\nRule 'environmentTag' {\n Exists 'Tags.environment' -CaseSensitive\n $TargetObject.Tags.environment -cin 'production', 'test', 'development'\n}\nFor our second rule (
costCentreTag), the costCentre tag value must be 5 numbers. We can validate this by using a regular expression.In the example below:
# Synopsis: Resource must have costCentre tag\nRule 'costCentreTag' {\n Exists 'Tags.costCentre' -CaseSensitive\n Match 'Tags.costCentre' '^([1-9][0-9]{4})$'\n}\nAn alternative way to write the rule would be to use the
-matchoperator instead of theMatchkeyword. Like theWithinkeyword, theMatchkeyword provides additional verbose logging that the-matchoperator does not provide.In the example below:
"},{"location":"scenarios/azure-tags/azure-tags/#use-business-unit-name-from-configuration","title":"Use business unit name from configuration","text":"# Synopsis: Resource must have costCentre tag\nRule 'costCentreTag' {\n Exists 'Tags.costCentre' -CaseSensitive\n $TargetObject.Tags.costCentre -match '^([1-9][0-9]{4})$'\n}\nFor our third rule (
businessUnitTag), the businessUnit must match a valid business unit. A list of business units will be referenced from configuration instead of hard coded in the rule.Configuration can be used within rule definitions by defining configuration in a YAML file then using the automatic variable
$Configuration.In the example below:
An extract from azureTags.Rule.ps1:
# Synopsis: Resource must have businessUnit tag\nRule 'businessUnitTag' {\n Exists 'Tags.businessUnit' -CaseSensitive\n Within 'Tags.businessUnit' $Configuration.allowedBusinessUnits\n}\nAn extract from ps-rule.yaml:
"},{"location":"scenarios/azure-tags/azure-tags/#execute-rules","title":"Execute rules","text":"# Configure business units that are allowed\nconfiguration:\n allowedBusinessUnits:\n - 'IT Operations'\n - 'Finance'\n - 'HR'\nWith a rule defined, the next step is to execute it. To execute rules, pipe the target object to
Invoke-PSRule.For example:
# Read resources in from file\n$resources = Get-Content -Path .\\resources.json | ConvertFrom-Json;\n\n# Evaluate each resource against tagging rules\n$resources | Invoke-PSRule -Option .\\ps-rule.yaml;\nThe
ps-rule.yamlwill automatically discovered if it exists in the current working path (i.e..\\ps-rule.yaml). Alternatively it can be specified with the-Optionparameter as show above.PSRule natively supports reading from YAML and JSON files so this command-line can be simplified to:
# Evaluate each resource against tagging rules\nInvoke-PSRule -InputPath .\\resources.json;\nYou will notice, we didn't specify the rule. By default PSRule will look for any
.Rule.ps1files in the current working path.Invoke-PSRulesupports-Path,-Nameand-Tagparameters that can be used to specify the path to look for rules in or filter rules if you want to run a subset of the rules.The
-Optionparameter allows us to specify a specific YAML configuration file to use.For this example, we ran these commands:
# Evaluate each resource against tagging rules\nInvoke-PSRule -Path docs/scenarios/azure-tags -InputPath docs/scenarios/azure-tags/resources.json -Outcome Fail -Option docs/scenarios/azure-tags/ps-rule.yaml;\nOur output looked like this:
TargetName: storage\n\nRuleName Outcome Recommendation\n-------- ------- --------------\ncostCentreTag Fail Resource must have costCentre tag\nbusinessUnitTag Fail Resource must have businessUnit tag\n\n\n TargetName: web-app\n\nRuleName Outcome Recommendation\n-------- ------- --------------\nenvironmentTag Fail Resource must have environment tag\ncostCentreTag Fail Resource must have costCentre tag\n\n\n TargetName: web-app/staging\n\nRuleName Outcome Recommendation\n-------- ------- --------------\nenvironmentTag Fail Resource must have environment tag\ncostCentreTag Fail Resource must have costCentre tag\nAny resources that don't follow the tagging standard are reported with an outcome of
"},{"location":"scenarios/azure-tags/azure-tags/#more-information","title":"More information","text":"Fail.
| Method | Mean | Error | StdDev | Median | Gen 0 | Gen 1 | Gen 2 | Allocated | |------------------------- |-----------:|----------:|----------:|-----------:|-----------:|------:|------:|------------:| | Invoke | 111.140 ms | 2.1935 ms | 4.5786 ms | 109.312 ms | 8200.0000 | - | - | 16839.42 KB | | InvokeIf | 117.141 ms | 2.2703 ms | 2.2298 ms | 116.398 ms | 9600.0000 | - | - | 19980.62 KB | | InvokeType | 108.648 ms | 0.7983 ms | 0.7467 ms | 108.584 ms | 8200.0000 | - | - | 16870.67 KB | | InvokeSummary | 107.300 ms | 0.8612 ms | 0.8056 ms | 107.115 ms | 8000.0000 | - | - | 16784.76 KB | | Get | 9.003 ms | 0.0643 ms | 0.0602 ms | 9.010 ms | 140.6250 | - | - | 307.96 KB | | GetHelp | 8.902 ms | 0.0831 ms | 0.0649 ms | 8.899 ms | 140.6250 | - | - | 306.34 KB | | Within | 179.522 ms | 1.5483 ms | 1.4483 ms | 179.981 ms | 15666.6667 | - | - | 32400.38 KB | | WithinBulk | 247.883 ms | 2.6279 ms | 2.1944 ms | 248.124 ms | 28500.0000 | - | - | 59306.73 KB | | WithinLike | 238.815 ms | 2.5538 ms | 1.9939 ms | 239.245 ms | 29333.3333 | - | - | 60580.58 KB | | DefaultTargetNameBinding | 2.124 ms | 0.0214 ms | 0.0200 ms | 2.129 ms | 85.9375 | - | - | 179.69 KB | | CustomTargetNameBinding | 2.463 ms | 0.0483 ms | 0.0452 ms | 2.458 ms | 179.6875 | - | - | 375 KB | | NestedTargetNameBinding | 2.433 ms | 0.0370 ms | 0.0328 ms | 2.420 ms | 179.6875 | - | - | 375 KB |"},{"location":"scenarios/benchmark/results-v0.19.0/","title":"Results v0.19.0","text":"BenchmarkDotNet=v0.12.1, OS=Windows 10.0.18363.778 (1909/November2018Update/19H2)\nIntel Core i7-6600U CPU 2.60GHz (Skylake), 1 CPU, 4 logical and 2 physical cores\n.NET Core SDK=3.1.201\n [Host] : .NET Core 2.1.17 (CoreCLR 4.6.28619.01, CoreFX 4.6.28619.01), X64 RyuJIT\n DefaultJob : .NET Core 2.1.17 (CoreCLR 4.6.28619.01, CoreFX 4.6.28619.01), X64 RyuJIT\n
| Method | Mean | Error | StdDev | Gen 0 | Gen 1 | Gen 2 | Allocated | |------------------------- |-------------:|------------:|------------:|-----------:|---------:|------:|------------:| | Invoke | 40,943.5 \u03bcs | 581.23 \u03bcs | 515.25 \u03bcs | 4000.0000 | 500.0000 | - | 16452.28 KB | | InvokeIf | 42,806.0 \u03bcs | 477.29 \u03bcs | 423.11 \u03bcs | 4500.0000 | 500.0000 | - | 18703.12 KB | | InvokeType | 40,470.1 \u03bcs | 484.16 \u03bcs | 429.19 \u03bcs | 4000.0000 | 538.4615 | - | 16452.27 KB | | InvokeSummary | 39,768.8 \u03bcs | 462.14 \u03bcs | 385.91 \u03bcs | 4000.0000 | 153.8462 | - | 16397.82 KB | | Get | 11,145.4 \u03bcs | 402.59 \u03bcs | 1,187.03 \u03bcs | 46.8750 | - | - | 252.11 KB | | GetHelp | 10,169.1 \u03bcs | 625.02 \u03bcs | 1,842.88 \u03bcs | 46.8750 | - | - | 250.51 KB | | Within | 78,993.5 \u03bcs | 799.51 \u03bcs | 667.63 \u03bcs | 8000.0000 | 400.0000 | - | 32791.83 KB | | WithinBulk | 118,800.8 \u03bcs | 1,637.36 \u03bcs | 1,531.59 \u03bcs | 14333.3333 | 333.3333 | - | 59817.29 KB | | WithinLike | 106,796.3 \u03bcs | 2,067.20 \u03bcs | 2,538.71 \u03bcs | 11333.3333 | - | - | 47311.07 KB | | DefaultTargetNameBinding | 698.2 \u03bcs | 7.51 \u03bcs | 7.02 \u03bcs | 38.0859 | - | - | 156.25 KB | | CustomTargetNameBinding | 884.7 \u03bcs | 7.11 \u03bcs | 6.65 \u03bcs | 85.9375 | - | - | 351.56 KB | | NestedTargetNameBinding | 883.9 \u03bcs | 14.44 \u03bcs | 12.80 \u03bcs | 85.9375 | - | - | 351.56 KB |"},{"location":"scenarios/benchmark/results-v0.20.0/","title":"Results v0.20.0","text":"BenchmarkDotNet=v0.12.1, OS=Windows 10.0.19041.450 (2004/?/20H1)\nIntel Core i7-1065G7 CPU 1.30GHz, 1 CPU, 8 logical and 4 physical cores\n.NET Core SDK=3.1.401\n [Host] : .NET Core 3.1.7 (CoreCLR 4.700.20.36602, CoreFX 4.700.20.37001), X64 RyuJIT\n DefaultJob : .NET Core 3.1.7 (CoreCLR 4.700.20.36602, CoreFX 4.700.20.37001), X64 RyuJIT\n
| Method | Mean | Error | StdDev | Gen 0 | Gen 1 | Gen 2 | Allocated | |------------------------- |-------------:|------------:|------------:|-----------:|----------:|------:|------------:| | Invoke | 42,162.8 \u03bcs | 827.36 \u03bcs | 1,263.47 \u03bcs | 3833.3333 | - | - | 15952 KB | | InvokeIf | 45,646.4 \u03bcs | 912.31 \u03bcs | 1,924.38 \u03bcs | 4416.6667 | 416.6667 | - | 18202.98 KB | | InvokeType | 41,825.5 \u03bcs | 810.73 \u03bcs | 901.12 \u03bcs | 3833.3333 | - | - | 15952 KB | | InvokeSummary | 41,133.3 \u03bcs | 777.97 \u03bcs | 895.91 \u03bcs | 3833.3333 | 500.0000 | - | 15897.56 KB | | Get | 10,054.3 \u03bcs | 396.83 \u03bcs | 1,170.07 \u03bcs | 46.8750 | - | - | 252.11 KB | | GetHelp | 10,581.4 \u03bcs | 448.15 \u03bcs | 1,321.38 \u03bcs | 46.8750 | - | - | 250.51 KB | | Within | 81,215.1 \u03bcs | 1,532.85 \u03bcs | 1,433.83 \u03bcs | 7750.0000 | 250.0000 | - | 32290.62 KB | | WithinBulk | 123,301.6 \u03bcs | 2,451.51 \u03bcs | 3,958.73 \u03bcs | 14000.0000 | 1000.0000 | - | 59317.29 KB | | WithinLike | 109,738.9 \u03bcs | 1,933.95 \u03bcs | 1,809.02 \u03bcs | 11333.3333 | 1000.0000 | - | 46811.07 KB | | DefaultTargetNameBinding | 696.0 \u03bcs | 12.06 \u03bcs | 10.69 \u03bcs | 38.0859 | - | - | 156.25 KB | | CustomTargetNameBinding | 845.6 \u03bcs | 11.75 \u03bcs | 10.42 \u03bcs | 85.9375 | - | - | 351.56 KB | | NestedTargetNameBinding | 856.0 \u03bcs | 12.29 \u03bcs | 10.90 \u03bcs | 85.9375 | - | - | 351.56 KB |"},{"location":"scenarios/benchmark/results-v0.21.0/","title":"Results v0.21.0","text":"BenchmarkDotNet=v0.12.1, OS=Windows 10.0.19041.450 (2004/?/20H1)\nIntel Core i7-1065G7 CPU 1.30GHz, 1 CPU, 8 logical and 4 physical cores\n.NET Core SDK=3.1.401\n [Host] : .NET Core 3.1.7 (CoreCLR 4.700.20.36602, CoreFX 4.700.20.37001), X64 RyuJIT\n DefaultJob : .NET Core 3.1.7 (CoreCLR 4.700.20.36602, CoreFX 4.700.20.37001), X64 RyuJIT\n
| Method | Mean | Error | StdDev | Gen 0 | Gen 1 | Gen 2 | Allocated | |------------------------- |-------------:|------------:|------------:|-----------:|---------:|------:|------------:| | Invoke | 41,409.3 \u03bcs | 743.11 \u03bcs | 1,089.24 \u03bcs | 3916.6667 | 500.0000 | - | 16124.02 KB | | InvokeIf | 43,138.3 \u03bcs | 510.44 \u03bcs | 426.24 \u03bcs | 4416.6667 | 83.3333 | - | 18374.86 KB | | InvokeType | 41,511.3 \u03bcs | 703.93 \u03bcs | 963.55 \u03bcs | 3923.0769 | 230.7692 | - | 16144.62 KB | | InvokeSummary | 40,319.9 \u03bcs | 795.95 \u03bcs | 705.59 \u03bcs | 3900.0000 | 500.0000 | - | 16124.26 KB | | Get | 9,873.7 \u03bcs | 392.08 \u03bcs | 1,149.89 \u03bcs | 46.8750 | - | - | 253.44 KB | | GetHelp | 9,943.1 \u03bcs | 406.36 \u03bcs | 1,198.17 \u03bcs | 46.8750 | - | - | 251.84 KB | | Within | 76,627.6 \u03bcs | 1,527.91 \u03bcs | 1,759.54 \u03bcs | 7800.0000 | - | - | 32460.47 KB | | WithinBulk | 115,374.0 \u03bcs | 2,279.41 \u03bcs | 3,269.07 \u03bcs | 14333.3333 | - | - | 59488.54 KB | | WithinLike | 102,684.3 \u03bcs | 1,482.11 \u03bcs | 1,313.85 \u03bcs | 11500.0000 | 750.0000 | - | 46983.1 KB | | DefaultTargetNameBinding | 673.8 \u03bcs | 4.27 \u03bcs | 3.79 \u03bcs | 38.0859 | - | - | 156.25 KB | | CustomTargetNameBinding | 888.9 \u03bcs | 15.31 \u03bcs | 12.78 \u03bcs | 85.9375 | - | - | 351.56 KB | | NestedTargetNameBinding | 901.3 \u03bcs | 9.04 \u03bcs | 8.01 \u03bcs | 85.9375 | - | - | 351.56 KB |"},{"location":"scenarios/benchmark/results-v0.22.0/","title":"Results v0.22.0","text":"BenchmarkDotNet=v0.12.1, OS=Windows 10.0.19042\nIntel Core i7-1065G7 CPU 1.30GHz, 1 CPU, 8 logical and 4 physical cores\n.NET Core SDK=3.1.403\n [Host] : .NET Core 3.1.9 (CoreCLR 4.700.20.47201, CoreFX 4.700.20.47203), X64 RyuJIT\n DefaultJob : .NET Core 3.1.9 (CoreCLR 4.700.20.47201, CoreFX 4.700.20.47203), X64 RyuJIT\n
| Method | Mean | Error | StdDev | Gen 0 | Gen 1 | Gen 2 | Allocated | |------------------------- |-------------:|------------:|------------:|-----------:|---------:|------:|------------:| | Invoke | 40,804.1 \u03bcs | 656.89 \u03bcs | 614.45 \u03bcs | 3916.6667 | 500.0000 | - | 16124.02 KB | | InvokeIf | 42,768.8 \u03bcs | 843.79 \u03bcs | 704.61 \u03bcs | 4461.5385 | 76.9231 | - | 18374.92 KB | | InvokeType | 40,487.0 \u03bcs | 609.33 \u03bcs | 1,034.69 \u03bcs | 3923.0769 | 538.4615 | - | 16124.02 KB | | InvokeSummary | 40,403.1 \u03bcs | 806.53 \u03bcs | 714.97 \u03bcs | 3923.0769 | 538.4615 | - | 16124.26 KB | | Assert | 41,551.0 \u03bcs | 684.23 \u03bcs | 640.03 \u03bcs | 4000.0000 | 153.8462 | - | 16538.36 KB | | Get | 10,180.9 \u03bcs | 402.29 \u03bcs | 1,186.17 \u03bcs | 46.8750 | - | - | 231.12 KB | | GetHelp | 9,941.1 \u03bcs | 409.65 \u03bcs | 1,207.87 \u03bcs | 46.8750 | - | - | 229.52 KB | | Within | 75,818.3 \u03bcs | 1,504.74 \u03bcs | 2,297.90 \u03bcs | 7800.0000 | 600.0000 | - | 32468.28 KB | | WithinBulk | 112,731.0 \u03bcs | 1,239.66 \u03bcs | 1,035.17 \u03bcs | 14333.3333 | 666.6667 | - | 59496.35 KB | | WithinLike | 101,227.7 \u03bcs | 1,990.03 \u03bcs | 2,854.05 \u03bcs | 11333.3333 | - | - | 46623.62 KB | | DefaultTargetNameBinding | 654.3 \u03bcs | 10.46 \u03bcs | 9.78 \u03bcs | 38.0859 | - | - | 156.25 KB | | CustomTargetNameBinding | 854.3 \u03bcs | 16.30 \u03bcs | 15.25 \u03bcs | 85.9375 | - | - | 351.56 KB | | NestedTargetNameBinding | 945.7 \u03bcs | 18.78 \u03bcs | 19.29 \u03bcs | 85.9375 | - | - | 351.57 KB | | AssertHasFieldValue | 1,036.2 \u03bcs | 13.63 \u03bcs | 12.08 \u03bcs | 121.0938 | - | - | 500 KB |"},{"location":"scenarios/benchmark/results-v0.3.0/","title":"Results v0.3.0","text":"BenchmarkDotNet=v0.12.1, OS=Windows 10.0.19042\nIntel Core i7-1065G7 CPU 1.30GHz, 1 CPU, 8 logical and 4 physical cores\n.NET Core SDK=3.1.403\n [Host] : .NET Core 3.1.9 (CoreCLR 4.700.20.47201, CoreFX 4.700.20.47203), X64 RyuJIT\n DefaultJob : .NET Core 3.1.9 (CoreCLR 4.700.20.47201, CoreFX 4.700.20.47203), X64 RyuJIT\n
| Method | Mean | Error | StdDev | Gen 0/1k Op | Gen 1/1k Op | Gen 2/1k Op | Allocated Memory/Op | |-------------- |-----------:|----------:|----------:|------------:|------------:|------------:|--------------------:| | Invoke | 117.257 ms | 2.1959 ms | 2.1567 ms | 8400.0000 | 400.0000 | - | 17355.83 KB | | InvokeIf | 128.418 ms | 3.0122 ms | 3.8095 ms | 9750.0000 | 500.0000 | - | 20301.73 KB | | InvokeSummary | 116.479 ms | 1.9241 ms | 1.7998 ms | 8400.0000 | - | - | 17301.03 KB | | Get | 8.921 ms | 0.0864 ms | 0.0766 ms | 93.7500 | - | - | 203.82 KB |"},{"location":"scenarios/benchmark/results-v1.0.1/","title":"Results v1.0.1","text":"BenchmarkDotNet=v0.11.3, OS=Windows 10.0.17763.195 (1809/October2018Update/Redstone5)\nIntel Core i7-6600U CPU 2.60GHz (Skylake), 1 CPU, 4 logical and 2 physical cores\n.NET Core SDK=2.2.100\n [Host] : .NET Core 2.1.6 (CoreCLR 4.6.27019.06, CoreFX 4.6.27019.05), 64bit RyuJIT\n DefaultJob : .NET Core 2.1.6 (CoreCLR 4.6.27019.06, CoreFX 4.6.27019.05), 64bit RyuJIT\n
| Method | Mean | Error | StdDev | Median | Gen 0 | Gen 1 | Gen 2 | Allocated | |------------------------- |-------------:|------------:|------------:|-------------:|-----------:|---------:|------:|------------:| | Invoke | 39,343.5 \u03bcs | 781.08 \u03bcs | 835.75 \u03bcs | 39,287.2 \u03bcs | 3923.0769 | 538.4615 | - | 16124.02 KB | | InvokeIf | 41,264.0 \u03bcs | 545.97 \u03bcs | 483.99 \u03bcs | 41,148.4 \u03bcs | 4461.5385 | 76.9231 | - | 18374.92 KB | | InvokeType | 39,514.4 \u03bcs | 755.90 \u03bcs | 670.09 \u03bcs | 39,343.8 \u03bcs | 3923.0769 | 538.4615 | - | 16124.02 KB | | InvokeSummary | 39,251.4 \u03bcs | 605.30 \u03bcs | 566.20 \u03bcs | 39,143.5 \u03bcs | 3916.6667 | 500.0000 | - | 16124.26 KB | | Assert | 40,662.2 \u03bcs | 776.24 \u03bcs | 688.12 \u03bcs | 40,589.9 \u03bcs | 4000.0000 | 333.3333 | - | 16538.53 KB | | Get | 8,570.8 \u03bcs | 429.97 \u03bcs | 1,267.78 \u03bcs | 8,872.7 \u03bcs | 46.8750 | - | - | 231.12 KB | | GetHelp | 9,235.4 \u03bcs | 295.56 \u03bcs | 871.45 \u03bcs | 9,238.7 \u03bcs | 46.8750 | - | - | 229.52 KB | | Within | 75,171.4 \u03bcs | 744.98 \u03bcs | 660.41 \u03bcs | 75,223.5 \u03bcs | 7750.0000 | 750.0000 | - | 32468.28 KB | | WithinBulk | 110,726.9 \u03bcs | 2,142.74 \u03bcs | 2,200.44 \u03bcs | 109,801.1 \u03bcs | 14500.0000 | 500.0000 | - | 59496.51 KB | | WithinLike | 101,989.2 \u03bcs | 2,007.91 \u03bcs | 4,056.09 \u03bcs | 100,288.9 \u03bcs | 11250.0000 | - | - | 46623.25 KB | | DefaultTargetNameBinding | 626.0 \u03bcs | 11.49 \u03bcs | 10.75 \u03bcs | 622.9 \u03bcs | 38.0859 | - | - | 156.25 KB | | CustomTargetNameBinding | 796.3 \u03bcs | 7.48 \u03bcs | 7.00 \u03bcs | 797.0 \u03bcs | 85.9375 | - | - | 351.56 KB | | NestedTargetNameBinding | 806.1 \u03bcs | 12.12 \u03bcs | 10.12 \u03bcs | 805.3 \u03bcs | 85.9375 | - | - | 351.56 KB | | AssertHasFieldValue | 900.6 \u03bcs | 14.51 \u03bcs | 12.87 \u03bcs | 901.2 \u03bcs | 122.0703 | - | - | 500 KB |"},{"location":"scenarios/benchmark/results-v1.1.0/","title":"Results v1.1.0","text":"BenchmarkDotNet=v0.12.1, OS=Windows 10.0.19042\nIntel Core i7-1065G7 CPU 1.30GHz, 1 CPU, 8 logical and 4 physical cores\n.NET Core SDK=5.0.102\n [Host] : .NET Core 3.1.11 (CoreCLR 4.700.20.56602, CoreFX 4.700.20.56604), X64 RyuJIT\n DefaultJob : .NET Core 3.1.11 (CoreCLR 4.700.20.56602, CoreFX 4.700.20.56604), X64 RyuJIT\n
| Method | Mean | Error | StdDev | Gen 0 | Gen 1 | Gen 2 | Allocated | |------------------------- |-------------:|------------:|------------:|-----------:|---------:|------:|------------:| | Invoke | 40,327.3 \u03bcs | 801.24 \u03bcs | 1,013.31 \u03bcs | 3923.0769 | 538.4615 | - | 16124.02 KB | | InvokeIf | 42,943.9 \u03bcs | 849.72 \u03bcs | 1,396.11 \u03bcs | 4461.5385 | 76.9231 | - | 18374.92 KB | | InvokeType | 40,880.7 \u03bcs | 783.51 \u03bcs | 1,452.28 \u03bcs | 3900.0000 | - | - | 16149.45 KB | | InvokeSummary | 39,101.4 \u03bcs | 431.56 \u03bcs | 336.93 \u03bcs | 3916.6667 | 500.0000 | - | 16124.26 KB | | Assert | 41,917.1 \u03bcs | 831.37 \u03bcs | 1,192.33 \u03bcs | 4076.9231 | 461.5385 | - | 16780.81 KB | | Get | 9,643.0 \u03bcs | 428.32 \u03bcs | 1,262.91 \u03bcs | 54.6875 | 7.8125 | - | 231.12 KB | | GetHelp | 9,271.5 \u03bcs | 372.94 \u03bcs | 1,099.63 \u03bcs | 46.8750 | - | - | 229.52 KB | | Within | 76,020.5 \u03bcs | 954.22 \u03bcs | 744.99 \u03bcs | 7800.0000 | 600.0000 | - | 32468.65 KB | | WithinBulk | 112,135.7 \u03bcs | 2,189.72 \u03bcs | 2,342.97 \u03bcs | 14500.0000 | 500.0000 | - | 59499.77 KB | | WithinLike | 101,928.4 \u03bcs | 1,952.97 \u03bcs | 2,398.43 \u03bcs | 11333.3333 | - | - | 46623.57 KB | | DefaultTargetNameBinding | 655.6 \u03bcs | 13.11 \u03bcs | 25.87 \u03bcs | 38.0859 | - | - | 156.25 KB | | CustomTargetNameBinding | 822.1 \u03bcs | 16.06 \u03bcs | 19.11 \u03bcs | 85.9375 | - | - | 351.56 KB | | NestedTargetNameBinding | 878.9 \u03bcs | 16.63 \u03bcs | 17.08 \u03bcs | 85.9375 | - | - | 351.56 KB | | AssertHasFieldValue | 923.2 \u03bcs | 17.81 \u03bcs | 19.05 \u03bcs | 122.0703 | 0.9766 | - | 500.26 KB |"},{"location":"scenarios/benchmark/results-v1.10.0/","title":"Results v1.10.0","text":"BenchmarkDotNet=v0.12.1, OS=Windows 10.0.19042\nIntel Core i7-1065G7 CPU 1.30GHz, 1 CPU, 8 logical and 4 physical cores\n.NET Core SDK=5.0.103\n [Host] : .NET Core 3.1.12 (CoreCLR 4.700.21.6504, CoreFX 4.700.21.6905), X64 RyuJIT\n DefaultJob : .NET Core 3.1.12 (CoreCLR 4.700.21.6504, CoreFX 4.700.21.6905), X64 RyuJIT\n
| Method | Mean | Error | StdDev | Gen 0 | Gen 1 | Allocated | |------------------------- |-------------:|------------:|------------:|-----------:|----------:|----------:| | Invoke | 50,742.5 \u03bcs | 908.47 \u03bcs | 709.27 \u03bcs | 4100.0000 | 400.0000 | 17,758 KB | | InvokeIf | 53,048.6 \u03bcs | 698.34 \u03bcs | 619.06 \u03bcs | 4500.0000 | 200.0000 | 20,008 KB | | InvokeType | 50,575.6 \u03bcs | 794.27 \u03bcs | 663.25 \u03bcs | 4000.0000 | 200.0000 | 17,760 KB | | InvokeSummary | 50,449.0 \u03bcs | 698.80 \u03bcs | 619.47 \u03bcs | 4100.0000 | 400.0000 | 17,758 KB | | Assert | 52,152.6 \u03bcs | 765.95 \u03bcs | 678.99 \u03bcs | 4200.0000 | 300.0000 | 18,462 KB | | Get | 5,793.8 \u03bcs | 86.70 \u03bcs | 81.10 \u03bcs | 78.1250 | - | 364 KB | | GetHelp | 5,799.6 \u03bcs | 76.72 \u03bcs | 71.77 \u03bcs | 85.9375 | 7.8125 | 364 KB | | Within | 89,538.2 \u03bcs | 1,754.26 \u03bcs | 1,555.11 \u03bcs | 8000.0000 | 1000.0000 | 34,102 KB | | WithinBulk | 128,126.9 \u03bcs | 1,928.80 \u03bcs | 1,709.83 \u03bcs | 14666.6667 | 1333.3333 | 61,131 KB | | WithinLike | 112,174.1 \u03bcs | 1,132.30 \u03bcs | 1,003.76 \u03bcs | 11666.6667 | 1666.6667 | 48,258 KB | | DefaultTargetNameBinding | 695.6 \u03bcs | 13.57 \u03bcs | 14.52 \u03bcs | 38.0859 | - | 156 KB | | CustomTargetNameBinding | 851.0 \u03bcs | 10.35 \u03bcs | 8.64 \u03bcs | 85.9375 | - | 352 KB | | NestedTargetNameBinding | 961.5 \u03bcs | 17.83 \u03bcs | 15.80 \u03bcs | 85.9375 | - | 352 KB | | AssertHasFieldValue | 3,033.5 \u03bcs | 60.15 \u03bcs | 66.85 \u03bcs | 253.9063 | 7.8125 | 1,040 KB |"},{"location":"scenarios/benchmark/results-v1.11.0/","title":"Results v1.11.0","text":"BenchmarkDotNet=v0.13.1, OS=Windows 10.0.22000\nIntel Core i7-1065G7 CPU 1.30GHz, 1 CPU, 8 logical and 4 physical cores\n.NET SDK=5.0.404\n [Host] : .NET Core 3.1.22 (CoreCLR 4.700.21.56803, CoreFX 4.700.21.57101), X64 RyuJIT\n DefaultJob : .NET Core 3.1.22 (CoreCLR 4.700.21.56803, CoreFX 4.700.21.57101), X64 RyuJIT\n
| Method | Mean | Error | StdDev | Gen 0 | Gen 1 | Allocated | |------------------------- |-------------:|------------:|------------:|-----------:|----------:|----------:| | Invoke | 50,529.4 \u03bcs | 1,006.40 \u03bcs | 941.38 \u03bcs | 4000.0000 | 444.4444 | 17,758 KB | | InvokeIf | 51,974.4 \u03bcs | 667.26 \u03bcs | 591.51 \u03bcs | 4500.0000 | 200.0000 | 20,008 KB | | InvokeType | 49,901.2 \u03bcs | 679.83 \u03bcs | 567.69 \u03bcs | 4000.0000 | 363.6364 | 17,758 KB | | InvokeSummary | 51,198.9 \u03bcs | 862.22 \u03bcs | 922.57 \u03bcs | 4000.0000 | 363.6364 | 17,758 KB | | Assert | 52,136.6 \u03bcs | 588.93 \u03bcs | 550.88 \u03bcs | 4100.0000 | 300.0000 | 18,461 KB | | Get | 5,710.0 \u03bcs | 111.69 \u03bcs | 104.47 \u03bcs | 85.9375 | 7.8125 | 364 KB | | GetHelp | 5,777.4 \u03bcs | 97.83 \u03bcs | 91.51 \u03bcs | 85.9375 | 7.8125 | 364 KB | | Within | 88,106.3 \u03bcs | 1,752.66 \u03bcs | 1,799.86 \u03bcs | 8000.0000 | 1000.0000 | 34,102 KB | | WithinBulk | 125,319.9 \u03bcs | 2,303.80 \u03bcs | 2,154.98 \u03bcs | 14666.6667 | 1000.0000 | 61,133 KB | | WithinLike | 115,376.3 \u03bcs | 1,866.04 \u03bcs | 1,654.20 \u03bcs | 11666.6667 | 1666.6667 | 48,258 KB | | DefaultTargetNameBinding | 669.5 \u03bcs | 6.52 \u03bcs | 6.10 \u03bcs | 38.0859 | - | 156 KB | | CustomTargetNameBinding | 837.6 \u03bcs | 6.70 \u03bcs | 6.27 \u03bcs | 85.9375 | - | 352 KB | | NestedTargetNameBinding | 854.1 \u03bcs | 9.50 \u03bcs | 7.42 \u03bcs | 85.9375 | - | 352 KB | | AssertHasFieldValue | 2,967.0 \u03bcs | 38.88 \u03bcs | 34.47 \u03bcs | 253.9063 | 7.8125 | 1,040 KB |"},{"location":"scenarios/benchmark/results-v2.0.0/","title":"Results v2.0.0","text":"BenchmarkDotNet=v0.13.1, OS=Windows 10.0.22000\nIntel Core i7-1065G7 CPU 1.30GHz, 1 CPU, 8 logical and 4 physical cores\n.NET SDK=5.0.404\n [Host] : .NET Core 3.1.22 (CoreCLR 4.700.21.56803, CoreFX 4.700.21.57101), X64 RyuJIT\n DefaultJob : .NET Core 3.1.22 (CoreCLR 4.700.21.56803, CoreFX 4.700.21.57101), X64 RyuJIT\n
| Method | Mean | Error | StdDev | Median | Gen 0 | Gen 1 | Allocated | |------------------------- |-----------------:|----------------:|-----------------:|-----------------:|-----------:|----------:|----------:| | Invoke | 71,586,583.6 ns | 4,077,161.43 ns | 11,957,608.68 ns | 71,526,200.0 ns | 4200.0000 | 600.0000 | 17,703 KB | | InvokeIf | 59,661,136.5 ns | 1,161,506.18 ns | 1,192,781.33 ns | 59,397,680.0 ns | 4400.0000 | 400.0000 | 19,954 KB | | InvokeType | 55,089,186.0 ns | 1,045,769.22 ns | 1,989,684.63 ns | 54,242,620.0 ns | 4300.0000 | 500.0000 | 17,703 KB | | InvokeSummary | 55,371,580.7 ns | 1,271,559.50 ns | 3,586,456.14 ns | 53,815,745.0 ns | 4300.0000 | 500.0000 | 17,704 KB | | Assert | 56,146,053.8 ns | 1,122,221.08 ns | 3,053,085.20 ns | 54,841,105.0 ns | 4500.0000 | 600.0000 | 18,407 KB | | Get | 5,701,341.2 ns | 110,332.76 ns | 158,235.95 ns | 5,665,673.8 ns | 78.1250 | 7.8125 | 365 KB | | GetHelp | 5,750,066.9 ns | 113,595.72 ns | 170,024.73 ns | 5,720,298.0 ns | 85.9375 | 7.8125 | 366 KB | | Within | 99,151,338.5 ns | 2,136,858.10 ns | 6,165,324.21 ns | 97,015,516.7 ns | 8333.3333 | 1333.3333 | 34,142 KB | | WithinBulk | 147,062,385.7 ns | 2,633,709.47 ns | 2,334,714.85 ns | 146,838,450.0 ns | 14000.0000 | 3000.0000 | 61,169 KB | | WithinLike | 120,988,346.7 ns | 2,099,294.17 ns | 1,963,681.06 ns | 120,963,000.0 ns | 11666.6667 | 1666.6667 | 48,297 KB | | DefaultTargetNameBinding | 731,969.9 ns | 13,918.54 ns | 36,422.40 ns | 714,067.8 ns | 38.0859 | - | 156 KB | | CustomTargetNameBinding | 1,052,297.9 ns | 44,284.38 ns | 125,627.41 ns | 1,022,416.2 ns | 85.9375 | - | 352 KB | | NestedTargetNameBinding | 916,580.7 ns | 24,378.48 ns | 71,497.85 ns | 903,449.3 ns | 85.9375 | - | 352 KB | | AssertHasFieldValue | 3,082,706.1 ns | 61,644.86 ns | 68,518.10 ns | 3,058,487.1 ns | 234.3750 | - | 962 KB | | PathTokenize | 846.6 ns | 16.52 ns | 23.69 ns | 842.4 ns | 0.2632 | - | 1 KB | | PathExpressionBuild | 548.3 ns | 10.14 ns | 11.68 ns | 547.1 ns | 0.3500 | - | 1 KB | | PathExpressionGet | 356,089.5 ns | 7,027.54 ns | 11,348.18 ns | 351,085.5 ns | 17.0898 | - | 70 KB |"},{"location":"scenarios/containers/container-execution/","title":"Using PSRule from a Container","text":"BenchmarkDotNet=v0.13.1, OS=Windows 10.0.22000\nIntel Core i7-1065G7 CPU 1.30GHz, 1 CPU, 8 logical and 4 physical cores\n.NET SDK=6.0.400\n [Host] : .NET Core 3.1.28 (CoreCLR 4.700.22.36202, CoreFX 4.700.22.36301), X64 RyuJIT\n DefaultJob : .NET Core 3.1.28 (CoreCLR 4.700.22.36202, CoreFX 4.700.22.36301), X64 RyuJIT\nDepending on your development or CI/CD process for your environment you may desire to use PSRules to validate your Infrastructure as Code (IaC) from a container. This document shows how you can use a simple container based on the mcr.microsoft.com/powershell image from Microsoft.
In this tutorial we are going to use a simple Ubuntu based PowerShell image to validate an ARM template. We will do this by creating a dockerfile to describe and create a container image that we can then run. When we run the container we will use a volume mount to share our ARM template and test code for the container to then execute the PSRule for Azure against our ARM template and output the results.
"},{"location":"scenarios/containers/container-execution/#creating-the-image","title":"Creating the image","text":"Creating an image ready to run PSRules first requires a dockerfile. The below example will use the latest PowerShell image released and install the
DockerfilePSRuleandPSRule.Rules.Azuremodules.# Copyright (c) Microsoft Corporation.\n# Licensed under the MIT License.\n\nFROM mcr.microsoft.com/powershell:7.2-ubuntu-22.04\nSHELL [\"pwsh\", \"-command\"]\n\nRUN Install-Module -Name 'PSRule','PSRule.Rules.Azure' -Force\nThe below docker command can be used to create the image locally.
docker build --tag psrule:latest .\nNote
While fine for an example, it is common to always reference a container by a version number and not the
"},{"location":"scenarios/containers/container-execution/#create-your-test-script","title":"Create your test script","text":"latesttag. Using thelatesttag may lead to unexpected behavior as version changes occur.Create a new directory and add a new file named
validate-files.ps1. This file will run the PSRule test for us on our new container image. Add the below code to the file.# Copyright (c) Microsoft Corporation.\n# Licensed under the MIT License.\n\n<#\n .SYNOPSIS\n Create a PSRule AzRuleTemplate data file and run the PSRule.Rules.Azure module rules against the output.\n#>\n\nGet-AzRuleTemplateLink \"$PSScriptRoot/template\" | Export-AzRuleTemplateData -OutputPath \"$PSScriptRoot/out\"\n\nAssert-PSRule -InputPath \"$PSScriptRoot/out/\" -Module 'PSRule.Rules.Azure' -As Summary\nAlso, within the new directory add another directory named
template. Add any ARM template you would like to test in this directory. For a starting point you can get a template from Azure Quickstart Templates.Your directory should now look like the below.
"},{"location":"scenarios/containers/container-execution/#run-psrules-in-the-container","title":"Run PSRules in the container","text":"- Directory \n |--> validate-files.ps1\n |--> template\n |--> ARM template...\nNow we are ready to go! Run the below docker command to test the ARM template.
docker run -it --rm -v $PWD/:/src psrule:latest pwsh -file /src/validate-files.ps1\nThis command runs the container and the PSRule tests by mounting the directory to the
/srcpath and then executing thevalidate-files.ps1script.Note
The volume mount option expects your current working directory to be the new directory created. You can change this to an absolute or relative path if desired.
"},{"location":"scenarios/containers/container-execution/#clean-up","title":"Clean up","text":"When you are ready to clean up the container image you can do so with the below command.
"},{"location":"scenarios/kubernetes-resources/kubernetes-resources/","title":"Kubernetes resource validation example","text":"docker image rm psrule\nThis is an example of how PSRule can be used to validate Kubernetes resources to match an internal metadata and configuration standard.
Note
A pre-built module to validate Kubernetes resources already exists. This scenario demonstrates the process and features of PSRule for illustration purposes.
Consider using or contributing these pre-built rule modules instead:
This scenario covers the following:
In this scenario we will use a YAML file:
To validate our Kubernetes resources, we need to define some rules. Rules are defined by using the
Rulekeyword in a file ending with the.Rule.ps1extension.Our business rules for configuration Kubernetes resources can be defined with the following dot points:
In the example below:
"},{"location":"scenarios/kubernetes-resources/kubernetes-resources/#check-that-the-label-exists","title":"Check that the label exists","text":"# Synopsis: Must have the app.kubernetes.io/name label\nRule 'metadata.Name' {\n # Rule conditions go here\n}\nIn the next step, we define one or more conditions.
Conditions can be:
PSRule includes several convenience keywords such as
AllOf,AnyOf,Exists,Match,TypeOfandWithinthat make conditions faster to define, easier to understand and troubleshoot. However, use of these keywords is optional.In the example below:
# Synopsis: Must have the app.kubernetes.io/name label\nRule 'metadata.Name' {\n Exists \"metadata.labels.'app.kubernetes.io/name'\"\n}\nWe have also defined something similar for the version and component labels.
In the example below:
"},{"location":"scenarios/kubernetes-resources/kubernetes-resources/#use-custom-binding","title":"Use custom binding","text":"# Synopsis: Must have the app.kubernetes.io/version label\nRule 'metadata.Version' {\n Exists 'metadata.labels.''app.kubernetes.io/version'''\n}\n\n# Synopsis: Must have the app.kubernetes.io/component label\nRule 'metadata.Component' {\n Exists 'metadata.labels.''app.kubernetes.io/component'''\n Within 'metadata.labels.''app.kubernetes.io/component''' 'web', 'api', 'database', 'gateway' -CaseSensitive\n}\nBefore processing rules, PSRule binds
TargetNameandTargetTypeproperties to the pipeline object. These properties are used for filtering and displaying results.The default properties that PSRule binds are different from how Kubernetes resources are structured. Kubernetes uses:
The default bindings can be updated by providing custom property names or a custom script. To change binding property names set the
Binding.TargetNameandBinding.TargetTypeconfiguration options.The following example shows how to set the options using a YAML configuration file:
binding:\n targetName:\n - metadata.name\n targetType:\n - kind\nThese options can be set in the file
.\\ps-rule.yamlto be automatically loaded at when PSRule cmdlets are called. To set these configuration options either edit the file manually or use the following command.# Set options in ps-rule.yaml\nSet-PSRuleOption -TargetName 'metadata.Name' -TargetType 'kind';\nAlternatively, these options can be set at runtime using the hashtable syntax.
# Save options to a variable\n$option = New-PSRuleOption -TargetName 'metadata.Name' -TargetType 'kind';\nThese options will be passed to
"},{"location":"scenarios/kubernetes-resources/kubernetes-resources/#define-preconditions","title":"Define preconditions","text":"Invoke-PSRuleusing the-Optionparameter in a later step.Currently the
metadata.Namerule defined in a previous step will be executed for any type of object. Kubernetes has many types of built-in resource such as Services, Deployments, Namespaces, Pods and ClusterRoles.By defining a precondition, we can ensure that the rule is only processed for Services or Deployments to match our business rules.
PSRule supports two types of preconditions, either type (
-Type) or script block (-If).Preconditions are evaluated once per rule for each object.
In the example below:
# Synopsis: Must have the app.kubernetes.io/name label\nRule 'metadata.Name' -Type 'Deployment', 'Service' {\n Exists \"metadata.labels.'app.kubernetes.io/name'\"\n}\nUsing a type precondition satisfies our business rules and will deliver faster performance then using a script block. An example using a script block precondition is also shown below.
"},{"location":"scenarios/kubernetes-resources/kubernetes-resources/#complete-remaining-rules","title":"Complete remaining rules","text":"# Synopsis: Must have the app.kubernetes.io/name label\nRule 'metadata.Name' -If { $TargetObject.kind -eq 'Deployment' -or $TargetObject.kind -eq 'Service' } {\n Exists \"metadata.labels.'app.kubernetes.io/name'\"\n}\nThe remaining rule definitions from our defined business rules are included below. Each follows a similar pattern and builds on the previous sections.
In the example below:
"},{"location":"scenarios/kubernetes-resources/kubernetes-resources/#execute-rules","title":"Execute rules","text":"# Synopsis: Deployments use a minimum of 2 replicas\nRule 'deployment.HasMinimumReplicas' -Type 'Deployment' {\n Exists 'spec.replicas'\n $TargetObject.spec.replicas -ge 2\n}\n\n# Synopsis: Deployments use specific tags\nRule 'deployment.NotLatestImage' -Type 'Deployment' {\n foreach ($container in $TargetObject.spec.template.spec.containers) {\n $container.image -like '*:*' -and\n $container.image -notlike '*:latest'\n }\n}\n\n# Synopsis: Resource requirements are set for each container\nRule 'deployment.ResourcesSet' -Type 'Deployment' {\n foreach ($container in $TargetObject.spec.template.spec.containers) {\n $container | Exists 'resources.requests.cpu'\n $container | Exists 'resources.requests.memory'\n $container | Exists 'resources.limits.cpu'\n $container | Exists 'resources.limits.memory'\n }\n}\nWith some rules defined, the next step is to execute them. For this example, we'll use
Invoke-PSRuleto get the result for each rule. TheTest-PSRuleTargetcmdlet can be used if only a true or false is required.In our example we are using the YAML format to store Kubernetes resources. PSRule has built-in support for YAML so we can import these files directly from disk or process output from a command such as
kubectl.In the examples below:
# Validate resources from file\nInvoke-PSRule -InputPath resources.yaml;\n# Validate resources directly from kubectl output\nkubectl get services -o yaml | Out-String | Invoke-PSRule -Format Yaml -ObjectPath items;\nFor this example, we limited the output to failed results with the following command:
# Validate resources from file\nInvoke-PSRule -Path docs/scenarios/kubernetes-resources -InputPath docs/scenarios/kubernetes-resources/resources.yaml -Option docs/scenarios/kubernetes-resources/ps-rule.yaml -Outcome Fail;\nThe resulting output is:
"},{"location":"scenarios/kubernetes-resources/kubernetes-resources/#more-information","title":"More information","text":"TargetName: app1-cache\n\nRuleName Outcome Recommendation\n-------- ------- --------------\ndeployment.HasMinimumReplicas Fail Deployments use a minimum of 2 replicas\ndeployment.NotLatestImage Fail Deployments use specific tags\ndeployment.ResourcesSet Fail Resource requirements are set for each container\n\n\n TargetName: app1-cache-service\n\nRuleName Outcome Recommendation\n-------- ------- --------------\nmetadata.Name Fail Must have the app.kubernetes.io/name label\nmetadata.Version Fail Must have the app.kubernetes.io/version label\nmetadata.Component Fail Must have the app.kubernetes.io/component label\n\n\n TargetName: app1-ui\n\nRuleName Outcome Recommendation\n-------- ------- --------------\nmetadata.Version Fail Must have the app.kubernetes.io/version label\nPSRule supports several features that make it easy to a continuous integration (CI) pipeline. When added to a pipeline, PSRule can validate files, template and objects dynamically.
This scenario covers the following:
Typically, PSRule is not pre-installed on CI worker nodes and must be installed. If your CI pipeline runs on a persistent virtual machine that you control, consider pre-installing PSRule. The following examples focus on installing PSRule dynamically during execution of the pipeline. Which is suitable for cloud-based CI worker nodes.
To install PSRule within a CI pipeline execute the
Install-ModulePowerShell cmdlet.In the example below:
Install-Module -Name PSRule -Scope CurrentUser -Force;\nIn some cases, installing NuGet and PowerShellGet may be required to connect to the PowerShell Gallery. The NuGet package provider can be installed using the
Install-PackageProviderPowerShell cmdlet.Install-PackageProvider -Name NuGet -Scope CurrentUser -Force;\nInstall-Module PowerShellGet -MinimumVersion '2.2.1' -Scope CurrentUser -Force -AllowClobber;\nThe example below includes both steps together with checks:
if ($Null -eq (Get-PackageProvider -Name NuGet -ErrorAction SilentlyContinue)) {\n Install-PackageProvider -Name NuGet -Scope CurrentUser -Force;\n}\n\nif ($Null -eq (Get-InstalledModule -Name PowerShellGet -MinimumVersion '2.2.1' -ErrorAction Ignore)) {\n Install-Module PowerShellGet -MinimumVersion '2.2.1' -Scope CurrentUser -Force -AllowClobber;\n}\nif ($Null -eq (Get-InstalledModule -Name PSRule -MinimumVersion '2.1.0' -ErrorAction SilentlyContinue)) {\n Install-Module -Name PSRule -Scope CurrentUser -MinimumVersion '2.1.0' -Force;\n}\nSee the change log for the latest version.
"},{"location":"scenarios/validation-pipeline/validation-pipeline/#validating-objects","title":"Validating objects","text":"To validate objects use
Invoke-PSRule,Assert-PSRuleorTest-PSRuleTarget. In a CI pipeline,Assert-PSRuleis recommended.Assert-PSRuleoutputs preformatted results ideal for use within a CI pipeline.For rules within the same source control repository, put rules in the
.ps-ruledirectory. A directory.ps-rulein the repository root, is used by convention.In the following example, objects are validated against rules from the
./.ps-rule/directory:$items | Assert-PSRule -Path './.ps-rule/'\nExample output:
-> ObjectFromFile.psd1 : System.IO.FileInfo\n\n [PASS] File.Header\n [PASS] File.Encoding\n [WARN] Target object 'ObjectFromFile.yaml' has not been processed because no matching rules were found.\n [WARN] Target object 'ObjectFromNestedFile.yaml' has not been processed because no matching rules were found.\n [WARN] Target object 'Baseline.Rule.yaml' has not been processed because no matching rules were found.\n\n -> FromFile.Rule.ps1 : System.IO.FileInfo\n\n [FAIL] File.Header\n [PASS] File.Encoding\nIn the next example, objects from file are validated against pre-defined rules from a module:
"},{"location":"scenarios/validation-pipeline/validation-pipeline/#formatting-output","title":"Formatting output","text":"Assert-PSRule -InputPath .\\resources-*.json -Module PSRule.Rules.Azure;\nWhen executing a CI pipeline, feedback on any validation failures is important. The
Assert-PSRulecmdlet provides easy to read formatted output instead of PowerShell objects.Additionally,
Assert-PSRulesupports styling formatted output for Azure Pipelines and GitHub Actions. Use the-Style AzurePipelinesor-Style GitHubActionsparameter to style output.For example:
"},{"location":"scenarios/validation-pipeline/validation-pipeline/#failing-the-pipeline","title":"Failing the pipeline","text":"$items | Assert-PSRule -Path './.ps-rule/' -Style AzurePipelines;\nWhen using PSRule within a CI pipeline, a failed rule should stop the pipeline. When using
Assert-PSRuleif any rules fail, an error will be generated.Assert-PSRule : One or more rules reported failure.\nAt line:1 char:10\n+ $items | Assert-PSRule -Path ./.ps-rule/\n+ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n+ CategoryInfo : InvalidData: (:) [Assert-PSRule], FailPipelineException\n+ FullyQualifiedErrorId : PSRule.Fail,Assert-PSRule\nA single PowerShell error is typically enough to stop a CI pipeline. If you are using a different configuration additionally
-ErrorAction Stopcan be used.For example:
$items | Assert-PSRule -Path './.ps-rule/' -ErrorAction Stop;\nUsing
-ErrorAction Stopwill stop the current script and return an exit code of 1.To continue running the current script but return an exit code, use:
"},{"location":"scenarios/validation-pipeline/validation-pipeline/#generating-nunit-output","title":"Generating NUnit output","text":"try {\n $items | Assert-PSRule -Path './.ps-rule/' -ErrorAction Stop;\n}\ncatch {\n $Host.SetShouldExit(1);\n}\nNUnit is a popular unit test framework for .NET. NUnit generates a test report format that is widely interpreted by CI systems. While PSRule does not use NUnit directly, it support outputting validation results in the NUnit3 format. Using a common format allows integration with any system that supports the NUnit3 for publishing test results.
To generate an NUnit report:
$items | Assert-PSRule -Path './.ps-rule/' -OutputFormat NUnit3 -OutputPath reports/rule-report.xml;\nThe output path will be created if it does not exist.
"},{"location":"scenarios/validation-pipeline/validation-pipeline/#publishing-nunit-report-with-azure-devops","title":"Publishing NUnit report with Azure DevOps","text":"With Azure DevOps, an NUnit report can be published using Publish Test Results task.
An example YAML snippet is included below:
"},{"location":"scenarios/validation-pipeline/validation-pipeline/#complete-example","title":"Complete example","text":"# PSRule results\n- task: PublishTestResults@2\n displayName: 'Publish PSRule results'\n inputs:\n testRunTitle: 'PSRule'\n testRunner: NUnit\n testResultsFiles: 'reports/rule-report.xml'\n mergeTestResults: true\n publishRunAttachments: true\n condition: succeededOrFailed()\nPutting each of these steps together.
"},{"location":"scenarios/validation-pipeline/validation-pipeline/#install-dependencies","title":"Install dependencies","text":"
"},{"location":"scenarios/validation-pipeline/validation-pipeline/#validate-files","title":"Validate files","text":"# Install dependencies for connecting to PowerShell Gallery\nif ($Null -eq (Get-PackageProvider -Name NuGet -ErrorAction SilentlyContinue)) {\n Install-PackageProvider -Name NuGet -Force -Scope CurrentUser;\n}\n\nif ($Null -eq (Get-InstalledModule -Name PowerShellGet -MinimumVersion '2.2.1' -ErrorAction SilentlyContinue)) {\n Install-Module PowerShellGet -MinimumVersion '2.2.1' -Scope CurrentUser -Force -AllowClobber;\n}\n
"},{"location":"scenarios/validation-pipeline/validation-pipeline/#azure-devops-pipeline","title":"Azure DevOps Pipeline","text":"# Install PSRule module\nif ($Null -eq (Get-InstalledModule -Name PSRule -MinimumVersion '2.1.0' -ErrorAction SilentlyContinue)) {\n Install-Module -Name PSRule -Scope CurrentUser -MinimumVersion '2.1.0' -Force;\n}\n\n# Validate files\n$assertParams = @{\n Path = './.ps-rule/'\n Style = 'AzurePipelines'\n OutputFormat = 'NUnit3'\n OutputPath = 'reports/rule-report.xml'\n}\n$items = Get-ChildItem -Recurse -Path .\\src\\,.\\tests\\ -Include *.ps1,*.psd1,*.psm1,*.yaml;\n$items | Assert-PSRule $assertParams -ErrorAction Stop;\n
"},{"location":"scenarios/validation-pipeline/validation-pipeline/#additional-options","title":"Additional options","text":""},{"location":"scenarios/validation-pipeline/validation-pipeline/#using-invoke-build","title":"Using Invoke-Build","text":"steps:\n\n# Install dependencies\n- powershell: ./pipeline-deps.ps1\n displayName: 'Install dependencies'\n\n# Validate templates\n- powershell: ./validate-files.ps1\n displayName: 'Validate files'\n\n# Publish pipeline results\n- task: PublishTestResults@2\n displayName: 'Publish PSRule results'\n inputs:\n testRunTitle: 'PSRule'\n testRunner: NUnit\n testResultsFiles: 'reports/rule-report.xml'\n mergeTestResults: true\n publishRunAttachments: true\n condition: succeededOrFailed()\nInvoke-Build is a build automation cmdlet that can be installed from the PowerShell Gallery by installing the InvokeBuild module. Within Invoke-Build, each build process is broken into tasks.
The following example shows an example of using PSRule with Invoke-Build tasks.
# Synopsis: Install PSRule\ntask PSRule {\n if ($Null -eq (Get-InstalledModule -Name PSRule -MinimumVersion '2.1.0' -ErrorAction SilentlyContinue)) {\n Install-Module -Name PSRule -Scope CurrentUser -MinimumVersion '2.1.0' -Force;\n }\n}\n\n# Synopsis: Validate files\ntask ValidateFiles PSRule, {\n $assertParams = @{\n Path = './.ps-rule/'\n Style = 'AzurePipelines'\n OutputFormat = 'NUnit3'\n OutputPath = 'reports/rule-report.xml'\n }\n $items = Get-ChildItem -Recurse -Path .\\src\\,.\\tests\\ -Include *.ps1,*.psd1,*.psm1,*.yaml;\n $items | Assert-PSRule @assertParams -ErrorAction Stop;\n}\n\n# Synopsis: Run all build tasks\ntask Build ValidateFiles\n
"},{"location":"scenarios/validation-pipeline/validation-pipeline/#calling-from-pester","title":"Calling from Pester","text":"Invoke-Build Build;\nPester is a unit test framework for PowerShell that can be installed from the PowerShell Gallery.
Typically, Pester unit tests are built for a particular pipeline. PSRule can complement Pester unit tests by providing dynamic and sharable rules that are easy to reuse. By using
-Ifor-Typepre-conditions, rules can dynamically provide validation for a range of use cases.When calling PSRule from Pester use
Invoke-PSRuleinstead ofAssert-PSRule.Invoke-PSRulereturns validation result objects that can be tested by PesterShouldconditions.Additionally, the
Logging.RuleFailoption can be included to generate an error message for each failing rule.For example:
"},{"location":"scenarios/validation-pipeline/validation-pipeline/#more-information","title":"More information","text":"Describe 'Azure' {\n Context 'Resource templates' {\n It 'Use content rules' {\n $invokeParams = @{\n Path = './.ps-rule/'\n OutputFormat = 'NUnit3'\n OutputPath = 'reports/rule-report.xml'\n }\n $items = Get-ChildItem -Recurse -Path .\\src\\,.\\tests\\ -Include *.ps1,*.psd1,*.psm1,*.yaml;\n Invoke-PSRule @invokeParams -Outcome Fail,Error | Should -BeNullOrEmpty;\n }\n }\n}\nThis document is intended as a working technical specification for PSRule.
"},{"location":"specs/design-spec/#what-is-psrule","title":"What is PSRule?","text":"PSRule is an engine, shipped as a PowerShell module designed to validate infrastructure as code (IaC). Additionally, PSRule can validate any PowerShell object, allowing almost any custom scenario to be supported.
PSRule natively supports common infrastructure code artifacts with the following file formats:
While some infrastructure as code languages implement their own custom language, many support output into a standard artifact format. i.e.
"},{"location":"specs/design-spec/#project-objectives","title":"Project objectives","text":"terraform show -jsonPSRule is rooted in PowerShell. This provides significant benefits and flexibility including:
To ensure these benefits remain, the following must be true:
PowerShell offers complete flexibility to build simple to complex rules. However, rule authors may be unfamiliar with PowerShell. Authoring rules in YAML or JSON with a defined schema will allow additional options for basic rules.
"},{"location":"specs/design-spec/#concepts","title":"Concepts","text":""},{"location":"specs/design-spec/#rule-definitions","title":"Rule definitions","text":"Rule definitions or rules are defined using PowerShell. Rules can be created in a PowerShell script file with the
.Rule.ps1extension. Rule files can be created and used individually or bundled as a module.Each rule:
For example:
Rule 'NameOfRule' {\n # <Rule conditions>\n}\n
"},{"location":"specs/design-spec/#psrule-engine","title":"PSRule engine","text":"# Synopsis: Configure storage accounts to only accept encrypted traffic i.e. HTTPS/SMB\nRule 'StorageAccounts.UseHttps' -Type 'Microsoft.Storage/storageAccounts' {\n $TargetObject.Properties.supportsHttpsTrafficOnly -eq $True\n}\nDistributed as a PowerShell module, all source code is included within this repository. This included cmdlets and an execution sandbox where rules are evaluated. PSRule is designed to be self contained, requiring only PowerShell to run.
By itself PSRule doesn't implement any specific rules. Custom rules can be defined and evaluated from PowerShell script files. Reusable rules can be distributed using PowerShell modules. Use PowerShellGet to install modules from public and private sources.
PSRule extends PowerShell with domain specific language (DSL) keywords, cmdlets, and automatic variables. These language features are only available within the sandbox. Stubs are exported from PSRule module to provide command completion during authoring.
In additional to rules, a number of resources can be used within PSRule. Resources are defined in YAML files with the
.Rule.yamlfile extension. You can create one or many resource within a single.Rule.yamlfile.PSRule supports the following resources:
A special
"},{"location":"specs/design-spec/#keywords-and-variables","title":"Keywords and variables","text":"ModuleConfigresource can also be defined to configure defaults for a module.TBA
"},{"location":"specs/design-spec/#baselines","title":"Baselines","text":"A baseline is a resource defined in YAML that determines which rules to run for a given scenario. One or more baselines can be included in a
.Rule.yamlfile. Baselines can be created individually or bundled in a module.Common use cases where baselines are helpful include:
Execution within PSRule occurs within a pipeline. The PSRule pipeline is similar to PowerShell and contains a
begin,process, andendstage.Three execution pipelines exist,
Invoke,Assert, orTest. Differences between each of these pipeline is minimal and mostly deals with how output is presented.The execution sandbox is implemented using PowerShell runspaces. Runspaces are a PowerShell feature which enable partial isolation within a PowerShell process.
PSRule uses two discrete runspaces:
Input and output are proxied between the two discrete runspaces to maintain runspace separation. This separation allows rules to be executed without polluting the state of the parent runspace.
"},{"location":"specs/design-spec/#rule-evaluation","title":"Rule evaluation","text":"TBA
"},{"location":"specs/design-spec/#configuration","title":"Configuration","text":"PSRule has built-in support for configuration of the engine and rules. Configuration can be set by:
Configuration of the PSRule engine is referred to as options. Each option changes the default that PSRule uses during execution. The supported options that can be configured for PSRule are described in the about_PSRule_Options topic.
"},{"location":"specs/design-spec/#rule-configuration","title":"Rule configuration","text":"Separately, rules can optionally define configuration that can skip or change the rule conditions. Rule configuration is a key/ value pair.
"},{"location":"specs/design-spec/#integration","title":"Integration","text":"TBA
"},{"location":"specs/function-spec/","title":"PSRule function expressions spec (draft)","text":"This is a spec for implementing function expressions in PSRule v2.
"},{"location":"specs/function-spec/#synopsis","title":"Synopsis","text":"Functions are available to handle complex conditions within YAML and JSON expressions.
"},{"location":"specs/function-spec/#schema-driven","title":"Schema driven","text":"While functions allow handing for complex use cases, they should still remain schema driven. A schema driven design allows auto-completion and validation during authoring in a broad set of tools.
"},{"location":"specs/function-spec/#syntax","title":"Syntax","text":"Functions can be used within YAML and JSON expressions by using the
$object property. For example:
"},{"location":"specs/option-spec/","title":"PSRule options spec (draft)","text":"---\n# Synopsis: An expression function example.\napiVersion: github.com/microsoft/PSRule/v1\nkind: Selector\nmetadata:\n name: Yaml.Fn.Example1\nspec:\n if:\n value:\n $:\n substring:\n path: name\n length: 3\n equals: abc\nThis is a spec for implementing options in PSRule v2.
"},{"location":"specs/option-spec/#synopsis","title":"Synopsis","text":"When executing resources options is often required to control the specific behaviour. In additional, many of these cases are scoped to the module being used.
The following scopes exist:
- Engine features: