Added support for baseline groups #1541

.vscode/settings.json

@@ -57,6 +57,9 @@
       "document"
     ]
   },
+  "[markdown]": {
+    "editor.formatOnSave": false
+  },
   "[powershell]": {
     "editor.formatOnSave": false,
     "editor.tabSize": 4

README.md

@@ -281,6 +281,7 @@ The following conceptual topics exist in the `PSRule` module:
   - [WithinPath](https://microsoft.github.io/PSRule/v2/concepts/PSRule/en-US/about_PSRule_Expressions/#withinpath)
   - [Version](https://microsoft.github.io/PSRule/v2/concepts/PSRule/en-US/about_PSRule_Expressions/#version)
 - [Options](https://aka.ms/ps-rule/options)
+  - [Baseline.Group](https://aka.ms/ps-rule/options#baselinegroup)
   - [Binding.Field](https://aka.ms/ps-rule/options#bindingfield)
   - [Binding.IgnoreCase](https://aka.ms/ps-rule/options#bindingignorecase)
   - [Binding.NameSeparator](https://aka.ms/ps-rule/options#bindingnameseparator)

docs/CHANGELOG-v2.md

@@ -19,6 +19,8 @@ See [upgrade notes][1] for helpful information when upgrading from previous vers
 
 **Experimental features**:
 
+- Baseline groups allow you to use a friendly name to reference baselines.
+  See [baselines][6] for more information.
 - Functions within YAML and JSON expressions can be used to perform manipulation prior to testing a condition.
   See [functions][3] for more information.
 - Sub-selectors within YAML and JSON expressions can be used to filter rules and list properties.
@@ -29,11 +31,19 @@ See [upgrade notes][1] for helpful information when upgrading from previous vers
   [3]: expressions/functions.md
   [4]: expressions/sub-selectors.md
   [5]: creating-your-pipeline.md#processing-changed-files-only
+  [6]: concepts/baselines.md
 
 ## Unreleased
 
 What's changed since pre-release v2.9.0-B0033:
 
+- New features:
+  - **Experimental**: Added support for baseline groups by @BernieWhite.
+    [#1541](https://github.com/microsoft/PSRule/issues/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][6] for more information.
 - Engineering:
   - Bump Microsoft.NET.Test.Sdk to v17.6.1.
     [#1540](https://github.com/microsoft/PSRule/pull/1540)

docs/commands/PSRule/en-US/New-PSRuleOption.md

@@ -18,10 +18,10 @@ Create options to configure PSRule execution.
 ```text
 New-PSRuleOption [[-Path] <String>] [-Configuration <ConfigurationOption>]
  [-SuppressTargetName <SuppressionOption>] [-BindTargetName <BindTargetName[]>]
- [-BindTargetType <BindTargetName[]>] [-BindingIgnoreCase <Boolean>] [-BindingField <Hashtable>]
- [-BindingNameSeparator <String>] [-BindingPreferTargetInfo <Boolean>] [-TargetName <String[]>]
- [-TargetType <String[]>] [-BindingUseQualifiedName <Boolean>] [-Convention <String[]>]
- [-AliasReferenceWarning <Boolean>] [-DuplicateResourceId <ExecutionActionPreference>]
+ [-BindTargetType <BindTargetName[]>] [-BaselineGroup <Hashtable>] [-BindingIgnoreCase <Boolean>]
+ [-BindingField <Hashtable>] [-BindingNameSeparator <String>] [-BindingPreferTargetInfo <Boolean>]
+ [-TargetName <String[]>] [-TargetType <String[]>] [-BindingUseQualifiedName <Boolean>]
+ [-Convention <String[]>] [-AliasReferenceWarning <Boolean>] [-DuplicateResourceId <ExecutionActionPreference>]
  [-InconclusiveWarning <Boolean>] [-InvariantCultureWarning <Boolean>] [-InitialSessionState <SessionState>]
  [-NotProcessedWarning <Boolean>] [-SuppressedRuleWarning <Boolean>]
  [-SuppressionGroupExpired <ExecutionActionPreference>] [-ExecutionRuleExcluded <ExecutionActionPreference>]
@@ -46,10 +46,10 @@ New-PSRuleOption [[-Path] <String>] [-Configuration <ConfigurationOption>]
 ```text
 New-PSRuleOption [-Option] <PSRuleOption> [-Configuration <ConfigurationOption>]
  [-SuppressTargetName <SuppressionOption>] [-BindTargetName <BindTargetName[]>]
- [-BindTargetType <BindTargetName[]>] [-BindingIgnoreCase <Boolean>] [-BindingField <Hashtable>]
- [-BindingNameSeparator <String>] [-BindingPreferTargetInfo <Boolean>] [-TargetName <String[]>]
- [-TargetType <String[]>] [-BindingUseQualifiedName <Boolean>] [-Convention <String[]>]
- [-AliasReferenceWarning <Boolean>] [-DuplicateResourceId <ExecutionActionPreference>]
+ [-BindTargetType <BindTargetName[]>] [-BaselineGroup <Hashtable>] [-BindingIgnoreCase <Boolean>]
+ [-BindingField <Hashtable>] [-BindingNameSeparator <String>] [-BindingPreferTargetInfo <Boolean>]
+ [-TargetName <String[]>] [-TargetType <String[]>] [-BindingUseQualifiedName <Boolean>]
+ [-Convention <String[]>] [-AliasReferenceWarning <Boolean>] [-DuplicateResourceId <ExecutionActionPreference>]
  [-InconclusiveWarning <Boolean>] [-InvariantCultureWarning <Boolean>] [-InitialSessionState <SessionState>]
  [-NotProcessedWarning <Boolean>] [-SuppressedRuleWarning <Boolean>]
  [-SuppressionGroupExpired <ExecutionActionPreference>] [-ExecutionRuleExcluded <ExecutionActionPreference>]
@@ -73,14 +73,15 @@ New-PSRuleOption [-Option] <PSRuleOption> [-Configuration <ConfigurationOption>]
 
 ```text
 New-PSRuleOption [-Default] [-Configuration <ConfigurationOption>] [-SuppressTargetName <SuppressionOption>]
- [-BindTargetName <BindTargetName[]>] [-BindTargetType <BindTargetName[]>] [-BindingIgnoreCase <Boolean>]
- [-BindingField <Hashtable>] [-BindingNameSeparator <String>] [-BindingPreferTargetInfo <Boolean>]
- [-TargetName <String[]>] [-TargetType <String[]>] [-BindingUseQualifiedName <Boolean>]
- [-Convention <String[]>] [-AliasReferenceWarning <Boolean>] [-DuplicateResourceId <ExecutionActionPreference>]
- [-InconclusiveWarning <Boolean>] [-InvariantCultureWarning <Boolean>] [-InitialSessionState <SessionState>]
- [-NotProcessedWarning <Boolean>] [-SuppressedRuleWarning <Boolean>]
- [-SuppressionGroupExpired <ExecutionActionPreference>] [-ExecutionRuleExcluded <ExecutionActionPreference>]
- [-ExecutionRuleSuppressed <ExecutionActionPreference>] [-ExecutionAliasReference <ExecutionActionPreference>]
+ [-BindTargetName <BindTargetName[]>] [-BindTargetType <BindTargetName[]>] [-BaselineGroup <Hashtable>]
+ [-BindingIgnoreCase <Boolean>] [-BindingField <Hashtable>] [-BindingNameSeparator <String>]
+ [-BindingPreferTargetInfo <Boolean>] [-TargetName <String[]>] [-TargetType <String[]>]
+ [-BindingUseQualifiedName <Boolean>] [-Convention <String[]>] [-AliasReferenceWarning <Boolean>]
+ [-DuplicateResourceId <ExecutionActionPreference>] [-InconclusiveWarning <Boolean>]
+ [-InvariantCultureWarning <Boolean>] [-InitialSessionState <SessionState>] [-NotProcessedWarning <Boolean>]
+ [-SuppressedRuleWarning <Boolean>] [-SuppressionGroupExpired <ExecutionActionPreference>]
+ [-ExecutionRuleExcluded <ExecutionActionPreference>] [-ExecutionRuleSuppressed <ExecutionActionPreference>]
+ [-ExecutionAliasReference <ExecutionActionPreference>]
  [-ExecutionRuleInconclusive <ExecutionActionPreference>]
  [-ExecutionInvariantCulture <ExecutionActionPreference>]
  [-ExecutionUnprocessedObject <ExecutionActionPreference>] [-IncludeModule <String[]>]
@@ -259,6 +260,24 @@ Accept pipeline input: False
 Accept wildcard characters: False
 ```
 
+### -BaselineGroup
+
+Sets the option `Baseline.Group`.
+The option `Baseline.Group` allows a named group of baselines to be defined and later referenced.
+See about_PSRule_Options for more information.
+
+```yaml
+Type: Hashtable
+Parameter Sets: (All)
+Aliases:
+
+Required: False
+Position: Named
+Default value: None
+Accept pipeline input: False
+Accept wildcard characters: False
+```
+
 ### -BindTargetType
 
 Configures a custom function to use to bind TargetType of an object.

docs/commands/PSRule/en-US/Set-PSRuleOption.md

@@ -15,14 +15,14 @@ Sets options that configure PSRule execution.
 
 ```text
 Set-PSRuleOption [[-Path] <String>] [-Option <PSRuleOption>] [-PassThru] [-Force] [-AllowClobber]
- [-BindingIgnoreCase <Boolean>] [-BindingField <Hashtable>] [-BindingNameSeparator <String>]
- [-BindingPreferTargetInfo <Boolean>] [-TargetName <String[]>] [-TargetType <String[]>]
- [-BindingUseQualifiedName <Boolean>] [-Convention <String[]>] [-AliasReferenceWarning <Boolean>]
- [-DuplicateResourceId <ExecutionActionPreference>] [-InconclusiveWarning <Boolean>]
- [-InvariantCultureWarning <Boolean>] [-InitialSessionState <SessionState>] [-NotProcessedWarning <Boolean>]
- [-SuppressedRuleWarning <Boolean>] [-SuppressionGroupExpired <ExecutionActionPreference>]
- [-ExecutionRuleExcluded <ExecutionActionPreference>] [-ExecutionRuleSuppressed <ExecutionActionPreference>]
- [-ExecutionAliasReference <ExecutionActionPreference>]
+ [-BaselineGroup <Hashtable>] [-BindingIgnoreCase <Boolean>] [-BindingField <Hashtable>]
+ [-BindingNameSeparator <String>] [-BindingPreferTargetInfo <Boolean>] [-TargetName <String[]>]
+ [-TargetType <String[]>] [-BindingUseQualifiedName <Boolean>] [-Convention <String[]>]
+ [-AliasReferenceWarning <Boolean>] [-DuplicateResourceId <ExecutionActionPreference>]
+ [-InconclusiveWarning <Boolean>] [-InvariantCultureWarning <Boolean>] [-InitialSessionState <SessionState>]
+ [-NotProcessedWarning <Boolean>] [-SuppressedRuleWarning <Boolean>]
+ [-SuppressionGroupExpired <ExecutionActionPreference>] [-ExecutionRuleExcluded <ExecutionActionPreference>]
+ [-ExecutionRuleSuppressed <ExecutionActionPreference>] [-ExecutionAliasReference <ExecutionActionPreference>]
  [-ExecutionRuleInconclusive <ExecutionActionPreference>]
  [-ExecutionInvariantCulture <ExecutionActionPreference>]
  [-ExecutionUnprocessedObject <ExecutionActionPreference>] [-IncludeModule <String[]>]
@@ -155,6 +155,24 @@ Accept pipeline input: False
 Accept wildcard characters: False
 ```
 
+### -BaselineGroup
+
+Sets the option `Baseline.Group`.
+The option `Baseline.Group` allows a named group of baselines to be defined and later referenced.
+See about_PSRule_Options for more information.
+
+```yaml
+Type: Hashtable
+Parameter Sets: (All)
+Aliases:
+
+Required: False
+Position: Named
+Default value: None
+Accept pipeline input: False
+Accept wildcard characters: False
+```
+
 ### -BindingIgnoreCase
 
 Sets the option `Binding.IgnoreCase`.

docs/concepts/PSRule/en-US/about_PSRule_Options.md

@@ -13,6 +13,7 @@ This topic describes what options are available, when to and how to use them.
 
 The following workspace options are available for use:
 
+- [Baseline.Group](#baselinegroup)
 - [Convention.Include](#conventioninclude)
 - [Execution.AliasReference](#executionaliasreference)
 - [Execution.AliasReferenceWarning](#executionaliasreferencewarning)
@@ -169,6 +170,54 @@ Boolean values are case-insensitive.
 - String array values can specify multiple items by using a semi-colon separator.
 For example `PSRULE_INPUT_TARGETTYPE` could be set to `virtualMachine;virtualNetwork`.
 
+### Baseline.Group
+
+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
+# PowerShell: Using the BaselineGroup parameter
+$option = New-PSRuleOption -BaselineGroup @{ latest = 'YourBaseline' };
+```
+
+```powershell
+# PowerShell: Using the Baseline.Group hashtable key
+$option = New-PSRuleOption -Option @{ 'Baseline.Group' = @{ latest = 'YourBaseline' } };
+```
+
+```powershell
+# PowerShell: Using the BaselineGroup parameter to set YAML
+Set-PSRuleOption -BaselineGroup @{ latest = 'YourBaseline' };
+```
+
+```yaml
+# YAML: Using the baseline/group property
+baseline:
+  group:
+    latest: YourBaseline
+```
+
+```bash
+# Bash: Using environment variable
+export PSRULE_BASELINE_GROUP='latest=YourBaseline'
+```
+
+```yaml
+# GitHub Actions: Using environment variable
+env:
+  PSRULE_BASELINE_GROUP: 'latest=YourBaseline'
+```
+
+```yaml
+# Azure Pipelines: Using environment variable
+variables:
+- name: PSRULE_BASELINE_GROUP
+  value: 'latest=YourBaseline'
+```
+
 ### Binding.Field
 
 When an object is passed from the pipeline, PSRule automatically extracts fields from object properties.

docs/concepts/baselines.md

@@ -0,0 +1,80 @@
+# Baselines
+
+!!! 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:
+
+- **Rules** — 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** — A baseline allows you to run any included rules with a predefined configuration by name.
+
+## Defining baselines
+
+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][1] reference.
+
+  [1]: ./PSRule/en-US/about_PSRule_Baseline.md
+
+## Baseline groups
+
+:octicons-milestone-24: 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][2] 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 disucssion][3] 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 `latest` and `preview` are defined:
+
+```yaml title="ps-rule.yaml"
+baseline:
+  group:
+    latest: PSRule.Rules.Azure\Azure.GA_2023_03
+    preview: PSRule.Rules.Azure\Azure.Preview_2023_03
+```
+
+- The `latest` baseline group is set to `Azure.GA_2023_03` within the `PSRule.Rules.Azure` module.
+- The `preview` baseline group is set to `Azure.Preview_2023_03` within the `PSRule.Rules.Azure` module.
+
+To use the baseline group, prefix the group name with `@` when running PSRule.
+For example:
+
+=== "GitHub Actions"
+
+    ```yaml
+    - name: Run PSRule
+      uses: microsoft/[email protected]
+      with:
+        modules: 'PSRule.Rules.Azure'
+        baseline: '@latest'
+    ```
+
+=== "Azure Pipelines"
+
+    ```yaml
+    - task: ps-rule-assert@2
+      displayName: Run PSRule
+      inputs:
+        modules: 'PSRule.Rules.Azure'
+        baseline: '@latest'
+    ```
+
+=== "Generic with PowerShell"
+
+    ```powershell
+    Assert-PSRule -InputPath '.' -Baseline '@latest' -Module PSRule.Rules.Azure -Format File;
+    ```
+
+  [2]: ./PSRule/en-US/about_PSRule_Options.md#baselinegroup
+  [3]: https://github.com/microsoft/PSRule/discussions

docs/troubleshooting.md

@@ -88,3 +88,22 @@ Choose to use one or the other.
 If you have a specific use case your would like to enable, please start a [discussion][3].
 
   [3]: https://github.com/microsoft/PSRule/discussions
+
+## PSR0003 - The specified baseline group is not known
+
+!!! 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][4] option.
+
+  [4]: https://aka.ms/ps-rule/options#baselinegroup
+
+## PSR0004 - The specified resource is not known
+
+!!! 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.

mkdocs.yml

@@ -61,6 +61,7 @@ nav:
           - Kubernetes resource validation example: scenarios/kubernetes-resources/kubernetes-resources.md
           - Using PSRule from a Container: scenarios/containers/container-execution.md
       - Concepts:
+          - Baselines: concepts/baselines.md
           - Functions: expressions/functions.md
           - Grouping rules: concepts/grouping-rules.md
           - Sub-selectors: expressions/sub-selectors.md