Analysis output#

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.

Setting the output format#

The output format can be configuring by setting the Output.Format option to one the following:

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.

Tip

To write output to a file, also set the Output.Path option to the file path to save.

GitHub ActionsAzure PipelinesPowerShellOptions file

# Analyze and save results
- name: Analyze repository
  uses: microsoft/ps-rule@v2.9.0
  with:
    outputFormat: Sarif
    outputPath: reports/ps-rule-results.sarif

# Analyze and save results
- task: ps-rule-assert@2
  displayName: Analyze repository
  inputs:
    inputType: repository
    outputFormat: Sarif
    outputPath: reports/ps-rule-results.sarif

Invoke-PSRule

Invoke-PSRule -OutputFormat Sarif -OutputPath reports/ps-rule-results.sarif

Assert-PSRule

Assert-PSRule -OutputFormat Sarif -OutputPath reports/ps-rule-results.sarif

ps-rule.yaml

output:
  format: 'Sarif'
  path: reports/ps-rule-results.sarif

Formatting as YAML#

When using the YAML output format, results a serialized as YAML. Two spaces are used to indent properties of objects.

Example output

- data: {}
  info:
    displayName: Local.PS.RequireTLS
    name: Local.PS.RequireTLS
    synopsis: An example rule to require TLS.
  level: Error
  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: 16b0534165ffb5279beeb1672a251fc1ff3124b6
  source:
  - file: C:\Dev\Workspace\PSRule\docs\authoring\writing-rules\settings.json
    line: 2
    position: 11
    type: File
  targetName: 1fe7c0f476b11301402d5017d87424c36ff085a8
  targetType: app1
  time: 0

Formatting as JSON#

When using the JSON output format, results are serialized as JSON. By default, no indentation is used.

Example output

[{"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}]

Configuring JSON indentation#

v1.8.0

The number of spaces used to indent properties and elements is configurable between 0 to 4 spaces. By default, no indentation is used.

Example output with 2 spaces

[
  {
    "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": "3afadfed32e57f5283ad71c1aa496da822ff0c84",
    "source": [
      {
        "file": "C:\\Dev\\Workspace\\PSRule\\docs\\authoring\\writing-rules\\settings.json",
        "line": 2,
        "position": 11,
        "type": "File"
      }
    ],
    "targetName": "1fe7c0f476b11301402d5017d87424c36ff085a8",
    "targetType": "app1",
    "time": 0
  }
]

Formatting as CSV#

The 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	Description
`RuleName`	The name of the rule.
`TargetName`	The name of the object that was analyzed.
`TargetType`	The type of the object that was analyzed.
`Outcome`	The outcome of the analysis, such as `Pass` or `Fail`.
`OutcomeReason`	An additional reason for the outcome such as `Inconclusive`.
`Synopsis`	A short description of the rule.
`Recommendation`	The recommendation of the rule.

For summary output, the following columns are used:

Column	Description
`RuleName`	The name of the rule.
`Pass`	The number of objects that passed.
`Fail`	The number of objects that failed.
`Outcome`	The worst case outcome of the analysis, such as `Pass` or `Fail`.
`Synopsis`	A short description of the rule.
`Recommendation`	The recommendation of the rule.

Example output

RuleName,TargetName,TargetType,Outcome,OutcomeReason,Synopsis,Recommendation
"Local.PS.RequireTLS","1fe7c0f476b11301402d5017d87424c36ff085a8","app1","Fail","Processed","An example rule to require TLS.",
"Local.YAML.RequireTLS","1fe7c0f476b11301402d5017d87424c36ff085a8","app1","Fail","Processed","An example rule to require TLS.",
"Local.JSON.RequireTLS","1fe7c0f476b11301402d5017d87424c36ff085a8","app1","Fail","Processed","An example rule to require TLS.",

Formatting as SARIF#

v2.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.

GitHub code scanning alerts#

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:

Create a GitHub Actions workflow.
Add a step using the microsoft/ps-rule action.
- Configure the outputFormat and outputPath parameters.
Add a step using the github/codeql-action/upload-sarif action.
- Configure the sarif_file parameter to the same file path specified in outputPath.

Example .github/workflows/analyze.yaml

name: Analyze
on:
  push:
    branches: [ main ]
  schedule:
  - cron: '24 22 * * 0' # At 10:24 PM, on Sunday each week
  workflow_dispatch:

jobs:
  oss:
    name: Analyze with PSRule
    runs-on: ubuntu-latest
    permissions:
      contents: read
      security-events: write
    steps:

    - name: Checkout
      uses: actions/checkout@v4

    - name: Run PSRule analysis
      uses: microsoft/ps-rule@v2.9.0
      with:
        outputFormat: Sarif
        outputPath: reports/ps-rule-results.sarif

    - name: Upload results to security tab
      uses: github/codeql-action/upload-sarif@v3
      with:
        sarif_file: reports/ps-rule-results.sarif

Azure DevOps scans tab#

SARIF 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.

Verifying configuration#

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.

Analysis output#

Setting the output format#

Formatting as YAML#

Formatting as JSON#

Configuring JSON indentation#

Formatting as CSV#

Formatting as SARIF#

GitHub code scanning alerts#

Azure DevOps scans tab#

Verifying configuration#

Comments