Skip to content

Baselines#

Describes usage of baselines within PSRule.

Description#

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:

  • 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.yaml or ps-rule.json.
    • Only a single baseline can be specified.
    • See about_PSRule_Options for details on using this method.

Baseline specs#

YAML baseline specs are saved within a YAML file with a .Rule.yaml or .Rule.yml extension, for example Baseline.Rule.yaml.

JSON baseline specs are saved within a file with a .Rule.json or .Rule.jsonc extension, for example Baseline.Rule.json. Use .jsonc to view JSON with Comments in Visual Studio Code.

To define a YAML baseline spec use the following structure:

---
# Synopsis: <synopsis>
apiVersion: github.com/microsoft/PSRule/v1
kind: Baseline
metadata:
  name: <name>
  annotations: { }
spec:
  # One or more baseline options
  rule: { }
  configuration: { }

For example:

---
# Synopsis: This is an example baseline
apiVersion: github.com/microsoft/PSRule/v1
kind: Baseline
metadata:
  name: Baseline1
spec:
  rule:
    include:
    - Rule1
    - Rule2
  configuration:
    allowedLocations:
    - 'Australia East'
    - 'Australia South East'

---
# Synopsis: This is an example baseline
apiVersion: github.com/microsoft/PSRule/v1
kind: Baseline
metadata:
  name: Baseline2
spec:
  rule:
    include:
    - Rule1
    - Rule3
  configuration:
    allowedLocations:
    - 'Australia East'

To define a JSON baseline spec use the following structure:

[
  {
    // Synopsis: <synopsis>
    "apiVersion": "github.com/microsoft/PSRule/v1",
    "kind": "Baseline",
    "metadata": {
      "name": "<name>",
      "annotations": {}
    },
    "spec": {
      "rule": {},
      "configuration": {}
    }
  }
]

For example:

[
  {
    // Synopsis: This is an example baseline
    "apiVersion": "github.com/microsoft/PSRule/v1",
    "kind": "Baseline",
    "metadata": {
      "name": "Baseline1"
    },
    "spec": {
      "rule": {
        "include": [
          "Rule1",
          "Rule2"
        ]
      },
      "configuration": {
        "allowedLocations": [
          "Australia East",
          "Australia South East"
        ]
      }
    }
  },
  {
    // Synopsis: This is an example baseline
    "apiVersion": "github.com/microsoft/PSRule/v1",
    "kind": "Baseline",
    "metadata": {
      "name": "Baseline2"
    },
    "spec": {
      "rule": {
        "include": [
          "Rule1",
          "Rule3"
        ]
      },
      "configuration": {
        "allowedLocations": [
          "Australia East"
        ]
      }
    }
  }
]

Baseline scopes#

When baseline options are set, PSRule uses the following order to determine precedence.

  1. Parameter - -Name and -Tag.
  2. Explicit - A named baseline specified with -Baseline.
  3. Workspace - Included in ps-rule.yaml or specified on the command line with -Option.
  4. Module - A baseline object included in a .Rule.yaml or .Rule.json file.

After precedence is determined, baselines are merged and null values are ignored, such that:

Annotations#

Additional baseline annotations can be provided as key/ value pairs. Annotations can be used to provide additional information that is available in Get-PSRuleBaseline output.

The following reserved annotation exists:

  • obsolete - Marks the baseline as obsolete when set to true. PSRule will generate a warning when an obsolete baseline is used.

YAML example:

---
# Synopsis: This is an example baseline that is obsolete
apiVersion: github.com/microsoft/PSRule/v1
kind: Baseline
metadata:
  name: ObsoleteBaseline
  annotations:
    obsolete: true
spec: { }

JSON example:

[
  {
    // Synopsis: This is an example baseline that is obsolete
    "apiVersion": "github.com/microsoft/PSRule/v1",
    "kind": "Baseline",
    "metadata": {
      "name": "ObsoleteBaseline",
      "annotations": {
        "obsolete": true
      }
    },
    "spec": {}
  }
]

Examples#

Example Baseline.Rule.yaml#

# Example Baseline.Rule.yaml

---
# Synopsis: This is an example baseline
apiVersion: github.com/microsoft/PSRule/v1
kind: Baseline
metadata:
  name: TestBaseline1
spec:
  rule:
    include:
    - 'WithBaseline'
  configuration:
    key1: value1

---
# Synopsis: This is an example baseline
apiVersion: github.com/microsoft/PSRule/v1
kind: Baseline
metadata:
  name: TestBaseline2
spec:
  rule:
    include:
    - 'WithBaseline'
  configuration:
    key1: value1

Example Baseline.Rule.json#

// Example Baseline.Rule.json

[
  {
    // Synopsis: This is an example baseline
    "apiVersion": "github.com/microsoft/PSRule/v1",
    "kind": "Baseline",
    "metadata": {
      "name": "TestBaseline1"
    },
    "spec": {
      "rule": {
        "include": [
          "WithBaseline"
        ]
      },
      "configuration": {
        "key1": "value1"
      }
    }
  },
  {
    // Synopsis: This is an example baseline
    "apiVersion": "github.com/microsoft/PSRule/v1",
    "kind": "Baseline",
    "metadata": {
      "name": "TestBaseline2"
    },
    "spec": {
      "rule": {
        "include": [
          "WithBaseline"
        ]
      },
      "configuration": {
        "key1": "value1"
      }
    }
  }
]

Comments