microsoft / PSRule.Monitor

Log PSRule analysis results to Azure Monitor.

PSRule for Azure Monitor

Log PSRule analysis results to Azure Monitor.

Support

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

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

If you have any problems with the PSRule engine, please check the project GitHub issues page instead.

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

Getting the module

This project requires the PSRule PowerShell module. For detail on installation and dependencies see install.

You can download and install these modules from the PowerShell Gallery.

Module	Description	Downloads / instructions
PSRule.Monitor	Log PSRule analysis results to Azure Monitor.	latest / instructions

Getting started

Upload results with PSRule convention

A convention can be used to upload the results of a PSRule analysis to Azure Monitor. To use the convention:

• Install the PSRule.Monitor module from the PowerShell Gallery.
• Include the PSRule.Monitor module. This can be set in PSRule options or specified at runtime as a parameter.
• Reference Monitor.LogAnalytics.Import convention. This can be set in PSRule options or specified at runtime as a parameter.

For example:

include:
  module:
  - 'PSRule.Monitor'

convention:
  include:
  - 'Monitor.LogAnalytics.Import

When using the convention a Log Analytics workspace must be specified. This can be done by setting the following environment variables:

• PSRULE_CONFIGURATION_MONITOR_WORKSPACE_ID - Containing the Log Analytics workspace ID.
• PSRULE_CONFIGURATION_MONITOR_WORKSPACE_KEY - Containing either the primary or secondary key to the workspace. This value is sensitive and should be stored securely. To protect this value, avoid storing it in source control.

For example:

# PowerShell: Setting environment variable
$Env:PSRULE_CONFIGURATION_MONITOR_WORKSPACE_ID = '00000000-0000-0000-0000-000000000000'
$Env:PSRULE_CONFIGURATION_MONITOR_WORKSPACE_KEY = Get-Secret -Name 'WORKSPACE_KEY' -AsPlainText

# GitHub Actions: Setting environment variable with microsoft/ps-rule action
- name: Run PSRule analysis
  uses: microsoft/ps-rule@main
  env:
    PSRULE_CONFIGURATION_MONITOR_WORKSPACE_ID: 00000000-0000-0000-0000-000000000000
    PSRULE_CONFIGURATION_MONITOR_WORKSPACE_KEY: ${{ secrets.WORKSPACE_KEY }}

# Azure Pipelines: Setting environment variable with ps-rule-assert task
- task: ps-rule-assert@0
  displayName: Run PSRule analysis
  inputs:
    inputType: repository
  env:
    PSRULE_CONFIGURATION_MONITOR_WORKSPACE_ID: 00000000-0000-0000-0000-000000000000
    PSRULE_CONFIGURATION_MONITOR_WORKSPACE_KEY: $(WORKSPACE_KEY)

Upload results with PowerShell

To upload results from PSRule to Azure Monitor, use the Send-PSRuleMonitorRecord cmdlet. Results can by piped directly from Invoke-PSRule or stored and piped from a variable.

The Send-PSRuleMonitorRecord cmdlet requires a Log Analytics workspace to send data to. A workspace can be specified by using the -WorkspaceId and -SharedKey parameters.

For example:

$data | Invoke-PSRule | Send-PSRuleMonitorRecord -WorkspaceId <workspaceId> -SharedKey <primaryKey>;

The following example shows using analysis results from a pre-built module:

$results = Invoke-PSRule -InputPath .\*.json -Module 'PSRule.Rules.Azure';
$results | Send-PSRuleMonitorRecord -WorkspaceId <workspaceId> -SharedKey <primaryKey>;

Querying logs from Azure Monitor

By default, PSRule results are stored in the PSRule_CL table. The results can be queries from the Log Analytics workspace using Kusto.

The following query returns all rule records from the last hour that failed:

PSRule_CL
| where Outcome_s == "Fail" and TimeGenerated > ago(1h)

To query these results from PowerShell use:

Invoke-AzOperationalInsightsQuery -WorkspaceId <workspaceId> -Query 'PSRule_CL | where Outcome_s == "Fail" and TimeGenerated > ago(1h)'

Language reference

Commands

The following commands exist in the PSRule.Monitor module:

• Send-PSRuleMonitorRecord - Send analysis results from PSRule to Azure Monitor.

Changes and versioning

Modules in this repository will use the semantic versioning model to declare breaking changes from v1.0.0. Prior to v1.0.0, breaking changes may be introduced in minor (0.x.0) version increments. For a list of module changes please see the change log.

Pre-release module versions are created on major commits and can be installed from the PowerShell Gallery. Pre-release versions should be considered experimental. Modules and change log details for pre-releases will be removed as standard releases are made available.

Contributing

This project welcomes contributions and suggestions. If you are ready to contribute, please visit the contribution guide.

Code of Conduct

This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact [e-mail] with any additional questions or comments.

Maintainers

• Bernie White

License

This project is licensed under the MIT License.