Setup Azure Monitor logs#

When analyzing Azure resources, you may want to capture the results of each analysis run. Azure Monitor provides a central storage location for log data through Log Analytics workspaces. Centrally storing PSRule results enables the following scenarios:

Auditing and reporting — Report on analysis pass or failures.
- Use Azure Monitor workbooks or custom queries to perform analysis and display results.
- Perform security analysis within Microsoft Azure Sentinel your a scalable, cloud-native SIEM. Alternatively, export log data from Log Analytics for ingestion into a third-party SIEM.
Send notifications using alerts — Trigger alerts to send notifications.
Integration with other workflows — Configure alerts and action groups to trigger integration.

Abstract

This topic covers setting up PSRule to log rule results into a Log Analytics workspace.

Logging into a Log Analytics workspace#

Logging of PSRule results into a workspace is done using the PSRule for Azure Monitor module. PSRule for Azure Monitor extends the PSRule pipeline to import results into the specified workspace.

Once configured, PSRule will log results into the PSRule_CL custom log table of the chosen workspace.

Info

Integration between PSRule and Azure Monitor is done by means of a convention. Conventions extend the pipeline to be able to upload results after rules have run.

Setting environment variables#

PSRule for Azure Monitor requires a Log Analytics workspace to import results into. To configure the workspace to import results to the following environment variables must be set.

PSRULE_CONFIGURATION_MONITOR_WORKSPACE_ID - The unique ID (GUID) for the workspace to import results.
PSRULE_CONFIGURATION_MONITOR_WORKSPACE_KEY - Either the primary or secondary key of the workspace.

How to set these environment variables is covered in the next section for GitHub Actions and Azure Pipelines.

Tip

Both the workspace ID and keys can be found under the Agents management settings of the workspace.

Configuring your pipeline#

The convention that imports PSRule analysis results is not executed by default. To enable, reference the Monitor.LogAnalytics.Import convention in your analysis pipeline.

With GitHub Actions#

GitHub Action

Import analysis results into Azure Monitor with GitHub Actions by:

Using the PSRule.Monitor module.
Referencing the Monitor.LogAnalytics.Import convention.
Configure secrets for MONITOR_WORKSPACE_ID and MONITOR_WORKSPACE_KEY.

StablePre-release

Install the latest stable module versions.

- name: Analyze Azure template files
  uses: microsoft/ps-rule@v2.9.0
  with:
    modules: PSRule.Rules.Azure,PSRule.Monitor
    conventions: Monitor.LogAnalytics.Import
  env:
    # Define environment variables using GitHub encrypted secrets
    PSRULE_CONFIGURATION_MONITOR_WORKSPACE_ID: ${{ secrets.MONITOR_WORKSPACE_ID }}
    PSRULE_CONFIGURATION_MONITOR_WORKSPACE_KEY: ${{ secrets.MONITOR_WORKSPACE_KEY }}

Install the latest stable or pre-release module versions.

- name: Analyze Azure template files
  uses: microsoft/ps-rule@v2.9.0
  with:
    modules: PSRule.Rules.Azure,PSRule.Monitor
    conventions: Monitor.LogAnalytics.Import
    prerelease: true
  env:
    # Define environment variables using GitHub encrypted secrets
    PSRULE_CONFIGURATION_MONITOR_WORKSPACE_ID: ${{ secrets.MONITOR_WORKSPACE_ID }}
    PSRULE_CONFIGURATION_MONITOR_WORKSPACE_KEY: ${{ secrets.MONITOR_WORKSPACE_KEY }}

Important

Environment variables can be configured in the workflow or from a secret. To keep MONITOR_WORKSPACE_KEY secure, use an encrypted secret.

With Azure Pipelines#

Extension

Import analysis results into Azure Monitor with Azure Pipelines by:

Installing the PSRule extension, then using the ps-rule-assert task in pipeline steps.
Using the PSRule.Monitor module.
Referencing the Monitor.LogAnalytics.Import convention.
Configure variables for MONITORWORKSPACEID and MONITORWORKSPACEKEY.

StablePre-release

Install the latest stable module versions.

- task: ps-rule-assert@2
  displayName: Analyze Azure template files
  inputs:
    modules: PSRule.Rules.Azure,PSRule.Monitor
    conventions: Monitor.LogAnalytics.Import
  env:
    # Define environment variables within Azure Pipelines
    PSRULE_CONFIGURATION_MONITOR_WORKSPACE_ID: $(MONITORWORKSPACEID)
    PSRULE_CONFIGURATION_MONITOR_WORKSPACE_KEY: $(MONITORWORKSPACEKEY)

Install the latest stable or pre-release module versions.

- task: ps-rule-install@2
  displayName: Install PSRule for Azure (pre-release)
  inputs:
    module: PSRule.Rules.Azure
    prerelease: true

- task: ps-rule-install@2
  displayName: Install PSRule for Azure Monitor (pre-release)
  inputs:
    module: PSRule.Monitor
    prerelease: true

- task: ps-rule-assert@2
  displayName: Analyze Azure template files
  inputs:
    modules: PSRule.Rules.Azure,PSRule.Monitor
    conventions: Monitor.LogAnalytics.Import
  env:
    # Define environment variables within Azure Pipelines
    PSRULE_CONFIGURATION_MONITOR_WORKSPACE_ID: $(MONITORWORKSPACEID)
    PSRULE_CONFIGURATION_MONITOR_WORKSPACE_KEY: $(MONITORWORKSPACEKEY)

Important

Variables can be configured in YAML, on the pipeline, or referenced from a defined variable group. To keep MONITORWORKSPACEKEY secure, use a variable group linked to an Azure Key Vault.

Samples#

Continue reading for some sample resources you can try once this integration is setup Azure Monitor integration.

Log Analytics Queries#

Results with annotations#

Kusto

// Show extended info
PSRule_CL
| where TimeGenerated > ago(30d)
| extend Pillar = tostring(parse_json(Annotations_s).pillar)
| extend Link = tostring(parse_json(Annotations_s).["online version"])

Summarize results by run#

Kusto

// Group by run
PSRule_CL
| where TimeGenerated > ago(30d)
| summarize Pass=countif(Outcome_s == "Pass"), Fail=countif(Outcome_s  == "Fail") by RunId_s

Querying The Data#

Once the results have been published to the Log Analytics workspace, they can be queried by executing results against the PSRule_CL table (under Custom Logs). For more information on how to write Log Analytics querys, review the Log Analytics tutortial.

Workbook#

Workbook

A sample Azure Monitor Workbook is available in the PSRule for Azure GitHub repository. This workbook can be imported directly into Azure Monitor and used as a foundation to build from. Review the Workbook creation tutorial for instructions on how to work with the sample Workbook.